Discovery and retrieval
Martin Morgan
Roswell Park Comprehensive Cancer CenterMartin.Morgan@RoswellPark.org Source:
vignettes/a_using_cellxgenedp.Rmd
a_using_cellxgenedp.RmdAbstract
The CELLxGENE data portal (https://cellxgene.cziscience.com/) provides a graphical user interface to collections of single-cell sequence data processed in standard ways to ‘count matrix’ summaries. The cellxgenedp package provides an alternative, R-based inteface, allowing flexible data discovery, viewing, and retrieval.
NOTE: The interface to CELLxGENE has changed; versions of cellxgenedp prior to 1.4.1 / 1.5.2 will cease to work when CELLxGENE removes the previous interface. See the vignette section ‘API changes’ for additional details.
Installation and use
This package is available in Bioconductor version 3.15 and later. The following code installs cellxgenedp from Bioconductor
if (!"BiocManager" %in% rownames(installed.packages()))
install.packages("BiocManager", repos = "https://CRAN.R-project.org")
BiocManager::install("cellxgenedp")Alternatively, install the ‘development’ version from GitHub (see GitHub.io for current documentation)
if (!"remotes" %in% rownames(installed.packages()))
install.packages("remotes", repos = "https://CRAN.R-project.org")
remotes::install_github("mtmorgan/cellxgenedp")To also install additional packages required for this vignette, use
pkgs <- c("tidyr", "zellkonverter", "SingleCellExperiment", "HDF5Array")
required_pkgs <- pkgs[!pkgs %in% rownames(installed.packages())]
BiocManager::install(required_pkgs)Load the package into your current R session. We make extensive use of the dplyr packages, and at the end of the vignette use SingleCellExperiment and zellkonverter, so load those as well.
library(zellkonverter)
library(SingleCellExperiment) # load early to avoid masking dplyr::count()
library(dplyr)
library(cellxgenedp)
cxg() Provides a ‘shiny’ interface
The following sections outline how to use the cellxgenedp package in
an R script; most functionality is also available in the
cxg() shiny application, providing an easy way to identify,
download, and visualize one or several datasets. Start the app
cxg()choose a project on the first tab, and a dataset for visualization, or one or more datasets for download!
Collections, datasets and files
Retrieve metadata about resources available at the cellxgene data
portal using db():
db <- db()Printing the db object provides a brief overview of the
available data, as well as hints, in the form of functions like
collections(), for further exploration.
db## cellxgene_db
## number of collections(): 235
## number of datasets(): 1488
## number of files(): 2723The portal organizes data hierarchically, with ‘collections’ (research studies, approximately), ‘datasets’, and ‘files’. Discover data using the corresponding functions.
collections(db)## # A tibble: 235 × 18
## collection_id collection_version_id collection_url consortia contact_email
## <chr> <chr> <chr> <list> <chr>
## 1 4828d33d-fb26-4… 3892863c-7057-4a32-a… https://cellx… <chr [1]> anna.molofsk…
## 2 48259aa8-f168-4… 67e75752-53dd-4aec-9… https://cellx… <lgl [1]> wtk22@cam.ac…
## 3 6e067060-f7e4-4… 37be1b6a-2d00-4b28-a… https://cellx… <lgl [1]> William.Zach…
## 4 1ca90a2d-2943-4… 1cb67a11-55b0-4416-9… https://cellx… <chr [2]> edl@allenins…
## 5 31937775-0602-4… e79f335e-ff6b-4c01-8… https://cellx… <lgl [1]> weallen@fas.…
## 6 34f12de7-c5e5-4… 375b0e1c-19d6-42b9-a… https://cellx… <chr [1]> ganier.clari…
## 7 48d354f5-a5ca-4… 8216eda1-79ae-4faf-9… https://cellx… <chr [1]> Nathan.Salom…
## 8 28e9d721-6816-4… c152fcf5-a85a-46c4-9… https://cellx… <lgl [1]> Tom_Mariani@…
## 9 9c8808ce-1138-4… e3c1e670-8e51-499f-a… https://cellx… <lgl [1]> ebutcher@sta…
## 10 37f1f46d-6dfa-4… 731ffc35-11c3-4236-8… https://cellx… <lgl [1]> ecker@salk.e…
## # ℹ 225 more rows
## # ℹ 13 more variables: contact_name <chr>, curator_name <chr>,
## # description <chr>, doi <chr>, links <list>, name <chr>,
## # publisher_metadata <list>, revising_in <lgl>, revision_of <lgl>,
## # visibility <chr>, created_at <date>, published_at <date>, revised_at <date>
datasets(db)## # A tibble: 1,488 × 33
## dataset_id dataset_version_id collection_id donor_id assay batch_condition
## <chr> <chr> <chr> <list> <list> <list>
## 1 5dec4249-84… dea35fd3-c576-4ca… 4828d33d-fb2… <chr> <list> <lgl [1]>
## 2 be35c935-ee… 15248da6-b817-403… 48259aa8-f16… <chr> <list> <chr [1]>
## 3 975e13b6-be… b2c407a9-4915-4d1… 48259aa8-f16… <chr> <list> <chr [1]>
## 4 55003f67-c4… c769bb55-b211-46a… 48259aa8-f16… <chr> <list> <lgl [1]>
## 5 24ec2dc5-35… 872b9ff1-86e9-4a7… 48259aa8-f16… <chr> <list> <chr [1]>
## 6 0ba636a1-47… 5a611776-aae0-41b… 48259aa8-f16… <chr> <list> <chr [1]>
## 7 2e877cd3-55… 5596ac91-b10e-4d8… 6e067060-f7e… <chr> <list> <lgl [1]>
## 8 fc0ceb80-d2… f94214e6-b6af-4ed… 1ca90a2d-294… <chr> <list> <chr [1]>
## 9 f67f2cfa-ba… 2cc3894f-09be-4af… 1ca90a2d-294… <chr> <list> <chr [1]>
## 10 eec3e37d-ed… cb6f7da3-3c1d-449… 1ca90a2d-294… <chr> <list> <chr [1]>
## # ℹ 1,478 more rows
## # ℹ 27 more variables: cell_count <int>, cell_type <list>, citation <chr>,
## # default_embedding <chr>, development_stage <list>, disease <list>,
## # embeddings <list>, explorer_url <chr>, feature_biotype <list>,
## # feature_count <int>, feature_reference <list>, is_primary_data <list>,
## # mean_genes_per_cell <dbl>, organism <list>, primary_cell_count <int>,
## # raw_data_location <chr>, schema_version <chr>, …
files(db)## # A tibble: 2,723 × 4
## dataset_id filesize filetype url
## <chr> <dbl> <chr> <chr>
## 1 5dec4249-8459-4df0-8998-37193135754c 239645451 H5AD https://datasets.c…
## 2 5dec4249-8459-4df0-8998-37193135754c 241723366 RDS https://datasets.c…
## 3 be35c935-ee4f-475c-9d3c-97630d59a735 3555862131 H5AD https://datasets.c…
## 4 be35c935-ee4f-475c-9d3c-97630d59a735 3390479178 RDS https://datasets.c…
## 5 975e13b6-bec1-4eed-b46a-9be1f1357373 4584229094 H5AD https://datasets.c…
## 6 975e13b6-bec1-4eed-b46a-9be1f1357373 4527013199 RDS https://datasets.c…
## 7 55003f67-c494-46f1-83fb-902745646379 19350133095 H5AD https://datasets.c…
## 8 24ec2dc5-3573-4d66-a9e1-25b7dcf43e27 151629100 H5AD https://datasets.c…
## 9 24ec2dc5-3573-4d66-a9e1-25b7dcf43e27 132974054 RDS https://datasets.c…
## 10 0ba636a1-4754-4786-a8be-7ab3cf760fd6 8493125588 H5AD https://datasets.c…
## # ℹ 2,713 more rowsEach of these resources has a unique primary identifier (e.g.,
file_id) as well as an identifier describing the
relationship of the resource to other components of the database (e.g.,
dataset_id). These identifiers can be used to ‘join’
information across tables.
Using dplyr to navigate data
A collection may have several datasets, and datasets may have several files. For instance, here is the collection with the most datasets
We can find out about this collection by joining with the
collections() table.
left_join(
collection_with_most_datasets |> select(collection_id),
collections(db),
by = "collection_id"
) |> glimpse()## Rows: 1
## Columns: 18
## $ collection_id <chr> "283d65eb-dd53-496d-adb7-7570c7caa443"
## $ collection_version_id <chr> "c4fb2c3d-960f-4845-9033-f0e758d3f059"
## $ collection_url <chr> "https://cellxgene.cziscience.com/collections/28…
## $ consortia <list> <"BRAIN Initiative", "CZI Single-Cell Biology">
## $ contact_email <chr> "kimberly.siletti@ki.se"
## $ contact_name <chr> "Kimberly Siletti"
## $ curator_name <chr> "James Chaffer"
## $ description <chr> "First draft atlas of human brain transcriptomic…
## $ doi <chr> "10.1126/science.add7046"
## $ links <list> [["", "RAW_DATA", "http://data.nemoarchive.org/b…
## $ name <chr> "Human Brain Cell Atlas v1.0"
## $ publisher_metadata <list> [[["Siletti", "Kimberly"], ["Hodge", "Rebecca"]…
## $ revising_in <lgl> NA
## $ revision_of <lgl> NA
## $ visibility <chr> "PUBLIC"
## $ created_at <date> 2024-06-09
## $ published_at <date> 2022-12-09
## $ revised_at <date> 2024-06-12We can take a similar strategy to identify all datasets belonging to this collection
left_join(
collection_with_most_datasets |> select(collection_id),
datasets(db),
by = "collection_id"
)## # A tibble: 138 × 33
## collection_id dataset_id dataset_version_id donor_id assay batch_condition
## <chr> <chr> <chr> <list> <list> <list>
## 1 283d65eb-dd53-… ff7d15fa-… 61ee7a9e-216b-411… <chr> <list> <chr [1]>
## 2 283d65eb-dd53-… fe1a73ab-… 6cc6a9b9-d53a-4b2… <chr> <list> <chr [1]>
## 3 283d65eb-dd53-… fbf173f9-… cf701447-cfdd-40f… <chr> <list> <chr [1]>
## 4 283d65eb-dd53-… fa554686-… 83b8522d-f362-4ac… <chr> <list> <chr [1]>
## 5 283d65eb-dd53-… f9034091-… 8faf8f5a-284a-4b2… <chr> <list> <chr [1]>
## 6 283d65eb-dd53-… f8dda921-… 821fa877-c2b1-488… <chr> <list> <chr [1]>
## 7 283d65eb-dd53-… f7d003d4-… f86dbeff-36bf-403… <chr> <list> <chr [1]>
## 8 283d65eb-dd53-… f6d9f2ad-… 7d5e92ed-87fa-4e8… <chr> <list> <chr [1]>
## 9 283d65eb-dd53-… f5a04dff-… 0eb52059-c5a4-4b6… <chr> <list> <chr [1]>
## 10 283d65eb-dd53-… f502c312-… 443f8b59-a15d-4d2… <chr> <list> <chr [1]>
## # ℹ 128 more rows
## # ℹ 27 more variables: cell_count <int>, cell_type <list>, citation <chr>,
## # default_embedding <chr>, development_stage <list>, disease <list>,
## # embeddings <list>, explorer_url <chr>, feature_biotype <list>,
## # feature_count <int>, feature_reference <list>, is_primary_data <list>,
## # mean_genes_per_cell <dbl>, organism <list>, primary_cell_count <int>,
## # raw_data_location <chr>, schema_version <chr>, …
facets() provides information on ‘levels’ present in
specific columns
Notice that some columns are ‘lists’ rather than atomic vectors like ‘character’ or ‘integer’.
## # A tibble: 1,488 × 16
## donor_id assay batch_condition cell_type development_stage disease
## <list> <list> <list> <list> <list> <list>
## 1 <chr [4]> <list [1]> <lgl [1]> <list [1]> <list [1]> <list>
## 2 <chr [55]> <list [1]> <chr [1]> <list [8]> <list [33]> <list>
## 3 <chr [55]> <list [1]> <chr [1]> <list [5]> <list [33]> <list>
## 4 <chr [286]> <list [3]> <lgl [1]> <list [26]> <list [43]> <list>
## 5 <chr [55]> <list [1]> <chr [1]> <list [15]> <list [33]> <list>
## 6 <chr [55]> <list [1]> <chr [1]> <list [11]> <list [33]> <list>
## 7 <chr [13]> <list [1]> <lgl [1]> <list [16]> <list [1]> <list>
## 8 <chr [79]> <list [2]> <chr [1]> <list [1]> <list [21]> <list>
## 9 <chr [89]> <list [2]> <chr [1]> <list [1]> <list [24]> <list>
## 10 <chr [89]> <list [2]> <chr [1]> <list [1]> <list [24]> <list>
## # ℹ 1,478 more rows
## # ℹ 10 more variables: embeddings <list>, feature_biotype <list>,
## # feature_reference <list>, is_primary_data <list>, organism <list>,
## # self_reported_ethnicity <list>, sex <list>, spatial <list>,
## # suspension_type <list>, tissue <list>This indicates that at least some of the datasets had more than one
type of assay, cell_type, etc. The
facets() function provides a convenient way of discovering
possible levels of each column, e.g., assay,
organism, self_reported_ethnicity, or
sex, and the number of datasets with each label.
facets(db, "assay")## # A tibble: 40 × 4
## facet label ontology_term_id n
## <chr> <chr> <chr> <int>
## 1 assay 10x 3' v3 EFO:0009922 686
## 2 assay 10x 3' v2 EFO:0009899 299
## 3 assay Slide-seqV2 EFO:0030062 223
## 4 assay Visium Spatial Gene Expression EFO:0010961 220
## 5 assay 10x 5' v1 EFO:0011025 100
## 6 assay Smart-seq2 EFO:0008931 69
## 7 assay 10x multiome EFO:0030059 68
## 8 assay sci-RNA-seq EFO:0010550 33
## 9 assay 10x 5' v2 EFO:0009900 32
## 10 assay 10x 5' transcription profiling EFO:0030004 23
## # ℹ 30 more rows
facets(db, "self_reported_ethnicity")## # A tibble: 34 × 4
## facet label ontology_term_id n
## <chr> <chr> <chr> <int>
## 1 self_reported_ethnicity European HANCESTRO:0005 588
## 2 self_reported_ethnicity unknown unknown 563
## 3 self_reported_ethnicity na na 408
## 4 self_reported_ethnicity Asian HANCESTRO:0008 153
## 5 self_reported_ethnicity African American HANCESTRO:0568 67
## 6 self_reported_ethnicity Hispanic or Latin American HANCESTRO:0014 67
## 7 self_reported_ethnicity Native American,Hispanic or L… HANCESTRO:0013,… 50
## 8 self_reported_ethnicity African American or Afro-Cari… HANCESTRO:0016 32
## 9 self_reported_ethnicity Greater Middle Eastern (Midd… HANCESTRO:0015 23
## 10 self_reported_ethnicity African HANCESTRO:0010 20
## # ℹ 24 more rows
facets(db, "sex")## # A tibble: 3 × 4
## facet label ontology_term_id n
## <chr> <chr> <chr> <int>
## 1 sex male PATO:0000384 1128
## 2 sex female PATO:0000383 861
## 3 sex unknown unknown 229Filtering faceted columns
Suppose we were interested in finding datasets from the 10x 3’ v3
assay (ontology_term_id of EFO:0009922)
containing individuals of African American ethnicity, and female sex.
Use the facets_filter() utility function to filter data
sets as needed
african_american_female <-
datasets(db) |>
filter(
facets_filter(assay, "ontology_term_id", "EFO:0009922"),
facets_filter(self_reported_ethnicity, "label", "African American"),
facets_filter(sex, "label", "female")
)Use nrow(african_american_female) to find the number of
datasets satisfying our criteria. It looks like there are up to
## # A tibble: 1 × 1
## total_cell_count
## <int>
## 1 5189408cells sequenced (each dataset may contain cells from several
ethnicities, as well as males or individuals of unknown gender, so we do
not know the actual number of cells available without downloading
files). Use left_join to identify the corresponding
collections:
## collections
left_join(
african_american_female |> select(collection_id) |> distinct(),
collections(db),
by = "collection_id"
)## # A tibble: 17 × 18
## collection_id collection_version_id collection_url consortia contact_email
## <chr> <chr> <chr> <list> <chr>
## 1 c9706a92-0e5f-4… fc466248-8bbb-488a-a… https://cellx… <chr [1]> hnakshat@iup…
## 2 72d37bc9-76cc-4… 5dc098de-6cd2-4ece-9… https://cellx… <chr [1]> m.sepp@zmbh.…
## 3 62e8f058-9c37-4… 0584f8f1-8ae2-4994-b… https://cellx… <chr [1]> chanj3@mskcc…
## 4 b9fc3d70-5a72-4… 1e29c67b-fd93-4ac2-8… https://cellx… <chr [1]> bruce.aronow…
## 5 b953c942-f5d8-4… 7127c92b-9ab2-45fe-9… https://cellx… <lgl [1]> icobos@stanf…
## 6 71f4bccf-53d4-4… 9b96b3b8-0905-470a-9… https://cellx… <chr [1]> kevinmbyrd@g…
## 7 6b701826-37bb-4… 6d374eb7-9c2c-4a69-8… https://cellx… <chr [1]> astreets@ber…
## 8 380ade76-e561-4… f6fd9136-ec9d-489a-a… https://cellx… <chr [1]> mengjiechen@…
## 9 f17b9205-f61f-4… 84167598-bb57-4165-8… https://cellx… <chr [1]> genevieve.ko…
## 10 3c4f0970-7614-4… e8667df5-84ca-443d-b… https://cellx… <lgl [1]> alexmascensi…
## 11 bcb61471-2a44-4… 51121545-a925-4d1e-a… https://cellx… <chr [3]> info@kpmp.org
## 12 625f6bf4-2f33-4… 418239cf-e0c0-42dc-b… https://cellx… <chr [1]> a5wang@healt…
## 13 e1fa9900-3fc9-4… 04b9f7c0-8963-4a20-8… https://cellx… <lgl [1]> j.ma@yale.edu
## 14 a98b828a-622a-4… 0ea9212d-9359-4d57-a… https://cellx… <chr [1]> markusbi@med…
## 15 4195ab4c-20bd-4… 6ede7b1a-87a8-4b7e-b… https://cellx… <chr [1]> nnavin@mdand…
## 16 cec4ef8e-1e70-4… 8171af2d-710f-462a-b… https://cellx… <lgl [1]> Ryan.Logan@u…
## 17 0f528c8a-a25c-4… 9fbe55ac-be5c-4487-a… https://cellx… <chr [3]> info@kpmp.org
## # ℹ 13 more variables: contact_name <chr>, curator_name <chr>,
## # description <chr>, doi <chr>, links <list>, name <chr>,
## # publisher_metadata <list>, revising_in <lgl>, revision_of <lgl>,
## # visibility <chr>, created_at <date>, published_at <date>, revised_at <date>Publication and other external data
Many collections include publication information and other external
data. This information is available in the return value of
collections(), but the helper function
publisher_metadata(), authors(), and
links() may facilitate access.
Suppose one is interested in the publication “A single-cell atlas of the healthy breast tissues reveals clinically relevant clusters of breast epithelial cells”. Discover it in the collections
title_of_interest <- paste(
"A single-cell atlas of the healthy breast tissues reveals clinically",
"relevant clusters of breast epithelial cells"
)
collection_of_interest <-
collections(db) |>
dplyr::filter(startsWith(name, title_of_interest))
collection_of_interest |>
glimpse()## Rows: 1
## Columns: 18
## $ collection_id <chr> "c9706a92-0e5f-46c1-96d8-20e42467f287"
## $ collection_version_id <chr> "fc466248-8bbb-488a-a9bd-a4f38b7b2eb3"
## $ collection_url <chr> "https://cellxgene.cziscience.com/collections/c9…
## $ consortia <list> "CZI Single-Cell Biology"
## $ contact_email <chr> "hnakshat@iupui.edu"
## $ contact_name <chr> "Harikrishna Nakshatri"
## $ curator_name <chr> "Jennifer Yu-Sheng Chien"
## $ description <chr> "Single-cell RNA sequencing (scRNA-seq) is an ev…
## $ doi <chr> "10.1016/j.xcrm.2021.100219"
## $ links <list> [["", "RAW_DATA", "https://explore.data.humancel…
## $ name <chr> "A single-cell atlas of the healthy breast tiss…
## $ publisher_metadata <list> [[["Bhat-Nakshatri", "Poornima"], ["Gao", "Hongy…
## $ revising_in <lgl> NA
## $ revision_of <lgl> NA
## $ visibility <chr> "PUBLIC"
## $ created_at <date> 2024-08-14
## $ published_at <date> 2021-03-25
## $ revised_at <date> 2024-08-19Use the collection_id to extract publisher metadata
(including a DOI if available) and author information
collection_id_of_interest <- pull(collection_of_interest, "collection_id")
publisher_metadata(db) |>
filter(collection_id == collection_id_of_interest) |>
glimpse()## Rows: 1
## Columns: 9
## $ collection_id <chr> "c9706a92-0e5f-46c1-96d8-20e42467f287"
## $ name <chr> "A single-cell atlas of the healthy breast tissues rev…
## $ is_preprint <lgl> FALSE
## $ journal <chr> "Cell Reports Medicine"
## $ published_at <date> 2021-03-01
## $ published_year <int> 2021
## $ published_month <int> 3
## $ published_day <int> 1
## $ doi <chr> NA## # A tibble: 12 × 4
## collection_id family given consortium
## <chr> <chr> <chr> <chr>
## 1 c9706a92-0e5f-46c1-96d8-20e42467f287 Bhat-Nakshatri Poornima NA
## 2 c9706a92-0e5f-46c1-96d8-20e42467f287 Gao Hongyu NA
## 3 c9706a92-0e5f-46c1-96d8-20e42467f287 Sheng Liu NA
## 4 c9706a92-0e5f-46c1-96d8-20e42467f287 McGuire Patrick C. NA
## 5 c9706a92-0e5f-46c1-96d8-20e42467f287 Xuei Xiaoling NA
## 6 c9706a92-0e5f-46c1-96d8-20e42467f287 Wan Jun NA
## 7 c9706a92-0e5f-46c1-96d8-20e42467f287 Liu Yunlong NA
## 8 c9706a92-0e5f-46c1-96d8-20e42467f287 Althouse Sandra K. NA
## 9 c9706a92-0e5f-46c1-96d8-20e42467f287 Colter Austyn NA
## 10 c9706a92-0e5f-46c1-96d8-20e42467f287 Sandusky George NA
## 11 c9706a92-0e5f-46c1-96d8-20e42467f287 Storniolo Anna Maria NA
## 12 c9706a92-0e5f-46c1-96d8-20e42467f287 Nakshatri Harikrishna NACollections may have links to additional external data, in this case
a DOI and two links to RAW_DATA.
external_links <- links(db)
external_links## # A tibble: 855 × 4
## collection_id link_name link_type link_url
## <chr> <chr> <chr> <chr>
## 1 4828d33d-fb26-42e7-bf36-18293b0eec85 NA LAB_WEBS… https:/…
## 2 4828d33d-fb26-42e7-bf36-18293b0eec85 GSE173173 RAW_DATA https:/…
## 3 4828d33d-fb26-42e7-bf36-18293b0eec85 NA DATA_SOU… https:/…
## 4 48259aa8-f168-4bf5-b797-af8e88da6637 trained CellTypist l… OTHER https:/…
## 5 48259aa8-f168-4bf5-b797-af8e88da6637 NA OTHER https:/…
## 6 48259aa8-f168-4bf5-b797-af8e88da6637 E-MTAB-13664 RAW_DATA https:/…
## 7 6e067060-f7e4-466c-86f3-ec3dd33c0381 NA RAW_DATA https:/…
## 8 6e067060-f7e4-466c-86f3-ec3dd33c0381 Images OTHER https:/…
## 9 6e067060-f7e4-466c-86f3-ec3dd33c0381 LungMAP ShinyCell OTHER http://…
## 10 6e067060-f7e4-466c-86f3-ec3dd33c0381 LungMAP Portal OTHER http://…
## # ℹ 845 more rows
external_links |>
count(link_type)## # A tibble: 5 × 2
## link_type n
## <chr> <int>
## 1 DATA_SOURCE 55
## 2 LAB_WEBSITE 44
## 3 OTHER 374
## 4 PROTOCOL 48
## 5 RAW_DATA 334
external_links |>
filter(collection_id == collection_id_of_interest)## # A tibble: 2 × 4
## collection_id link_name link_type link_url
## <chr> <chr> <chr> <chr>
## 1 c9706a92-0e5f-46c1-96d8-20e42467f287 NA RAW_DATA https://explore.data…
## 2 c9706a92-0e5f-46c1-96d8-20e42467f287 NA RAW_DATA https://www.ncbi.nlm…Conversely, knowledge of a DOI, etc., can be used to discover details of the corresponding collection.
doi_of_interest <- "https://doi.org/10.1016/j.stem.2018.12.011"
links(db) |>
filter(link_url == doi_of_interest) |>
left_join(collections(db), by = "collection_id") |>
glimpse()## Rows: 1
## Columns: 21
## $ collection_id <chr> "b1a879f6-5638-48d3-8f64-f6592c1b1561"
## $ link_name <chr> "PSC-ATO protocol"
## $ link_type <chr> "PROTOCOL"
## $ link_url <chr> "https://doi.org/10.1016/j.stem.2018.12.011"
## $ collection_version_id <chr> "47c7b727-cdb8-4d5f-8dbf-107197c7acb5"
## $ collection_url <chr> "https://cellxgene.cziscience.com/collections/b1…
## $ consortia <list> <"CZI Single-Cell Biology", "Wellcome HCA Strate…
## $ contact_email <chr> "st9@sanger.ac.uk"
## $ contact_name <chr> "Sarah Teichmann"
## $ curator_name <chr> "Batuhan Cakir"
## $ description <chr> "Single-cell genomics studies have decoded the i…
## $ doi <chr> "10.1126/science.abo0510"
## $ links <list> [["scVI Models", "DATA_SOURCE", "https://develop…
## $ name <chr> "Mapping the developing human immune system acro…
## $ publisher_metadata <list> [[["Suo", "Chenqu"], ["Dann", "Emma"], ["Goh", "…
## $ revising_in <lgl> NA
## $ revision_of <lgl> NA
## $ visibility <chr> "PUBLIC"
## $ created_at <date> 2024-06-09
## $ published_at <date> 2022-10-04
## $ revised_at <date> 2024-06-12Visualizing data in cellxgene
Visualization is straight-forward once dataset_id is
available. For example, to visualize the first dataset in
african_american_female, use
african_american_female |>
## use criteria to identify a single dataset (here just the
## 'first' dataset), then visualize
slice(1) |>
datasets_visualize()Visualization is an interactive process, so
datasets_visualize() will only open up to 5 browser tabs
per call.
File download and use
Datasets usually contain H5AD (files produced by the
python AnnData module), and Rds (serialized files produced
by the R Seurat package). The Rds files may be
unreadable if the version of Seurat used to create the file is different
from the version used to read the file. We therefore focus on the
H5AD files.
For illustration, we find all files associated with studies with African American females
download one of our selected files.
selected_files <-
left_join(
african_american_female |> select(dataset_id),
files(db),
by = "dataset_id"
)And then choose a single dataset and its H5AD file for download
local_file <-
selected_files |>
filter(
dataset_id == "de985818-285f-4f59-9dbd-d74968fddba3",
filetype == "H5AD"
) |>
files_download(dry.run = FALSE)
basename(local_file)## [1] "f72aae6e-c997-484c-bffd-6d09e41ef9a4.h5ad"These are downloaded to a local cache (use the internal function
cellxgenedp:::.cellxgenedb_cache_path() for the location of
the cache), so the process is only time-consuming the first time.
H5AD files can be converted to R /
Bioconductor objects using the zellkonverter
package.
h5ad <- readH5AD(local_file, use_hdf5 = TRUE, reader = "R")
h5ad## class: SingleCellExperiment
## dim: 33159 31696
## metadata(5): citation default_embedding schema_reference schema_version
## title
## assays(1): X
## rownames(33159): ENSG00000243485 ENSG00000237613 ... ENSG00000277475
## ENSG00000268674
## rowData names(5): feature_is_filtered feature_name feature_reference
## feature_biotype feature_length
## colnames(31696): CMGpool_AAACCCAAGGACAACC CMGpool_AAACCCACAATCTCTT ...
## K109064_TTTGTTGGTTGCATCA K109064_TTTGTTGGTTGGACCC
## colData names(45): mapped_reference_annotation donor_id ...
## development_stage observation_joinid
## reducedDimNames(3): X_pca X_tsne X_umap
## mainExpName: NULL
## altExpNames(0):The SingleCellExperiment object is a matrix-like object
with rows corresponding to genes and columns to cells. Thus we can
easily explore the cells present in the data.
## # A tibble: 7 × 3
## sex donor_id n
## <fct> <fct> <int>
## 1 female D1 2303
## 2 female D2 864
## 3 female D3 2517
## 4 female D4 1771
## 5 female D5 2244
## 6 female D11 7454
## 7 female pooled [D9,D7,D8,D10,D6] 14543Next steps
The Orchestrating
Single-Cell Analysis with Bioconductor online resource provides an
excellent introduction to analysis and visualization of single-cell data
in R / Bioconductor. Extensive opportunities for
working with AnnData objects in R but using the native python
interface are briefly described in, e.g., ?AnnData2SCE help
page of zellkonverter.
The hca package provides programmatic access to the Human Cell Atlas data portal, allowing retrieval of primary as well as derived single-cell data files.
API changes
Data access provided by CELLxGENE has changed to a new ‘Discover’ API. The main functionality of the cellxgenedp package has not changed, but specific columns have been removed, replaced or added, as follows:
- Removed:
access_type,data_submission_policy_version - Replaced:
updated_atreplaced withrevised_at - Added:
collection_version_id,collection_url,doi,revising_in,revision_of
- Removed:
is_valid,processing_status,published,revision,created_at - Replaced:
dataset_deploymentsreplaced withexplorer_url,namereplaced withtitle,updated_atreplaced withrevised_at - Added:
dataset_version_id,batch_condition,x_approximate_distribution
- Removed:
file_id,filename,s3_uri,user_submitted,created_at,updated_at - Added:
filesize,url
Session info
## R version 4.4.1 (2024-06-14)
## Platform: x86_64-pc-linux-gnu
## Running under: Ubuntu 22.04.4 LTS
##
## Matrix products: default
## BLAS: /usr/lib/x86_64-linux-gnu/openblas-pthread/libblas.so.3
## LAPACK: /usr/lib/x86_64-linux-gnu/openblas-pthread/libopenblasp-r0.3.20.so; LAPACK version 3.10.0
##
## locale:
## [1] LC_CTYPE=C.UTF-8 LC_NUMERIC=C LC_TIME=C.UTF-8
## [4] LC_COLLATE=C.UTF-8 LC_MONETARY=C.UTF-8 LC_MESSAGES=C.UTF-8
## [7] LC_PAPER=C.UTF-8 LC_NAME=C LC_ADDRESS=C
## [10] LC_TELEPHONE=C LC_MEASUREMENT=C.UTF-8 LC_IDENTIFICATION=C
##
## time zone: UTC
## tzcode source: system (glibc)
##
## attached base packages:
## [1] stats4 stats graphics grDevices utils datasets methods
## [8] base
##
## other attached packages:
## [1] cellxgenedp_1.9.1 dplyr_1.1.4
## [3] SingleCellExperiment_1.26.0 SummarizedExperiment_1.34.0
## [5] Biobase_2.64.0 GenomicRanges_1.56.1
## [7] GenomeInfoDb_1.40.1 IRanges_2.38.1
## [9] S4Vectors_0.42.1 BiocGenerics_0.50.0
## [11] MatrixGenerics_1.16.0 matrixStats_1.4.1
## [13] zellkonverter_1.14.1 BiocStyle_2.32.1
##
## loaded via a namespace (and not attached):
## [1] tidyselect_1.2.1 filelock_1.0.3 fastmap_1.2.0
## [4] promises_1.3.0 digest_0.6.37 mime_0.12
## [7] lifecycle_1.0.4 magrittr_2.0.3 compiler_4.4.1
## [10] rlang_1.1.4 sass_0.4.9 tools_4.4.1
## [13] utf8_1.2.4 yaml_2.3.10 knitr_1.48
## [16] S4Arrays_1.4.1 htmlwidgets_1.6.4 curl_5.2.2
## [19] reticulate_1.39.0 DelayedArray_0.30.1 abind_1.4-5
## [22] HDF5Array_1.32.1 withr_3.0.1 desc_1.4.3
## [25] grid_4.4.1 fansi_1.0.6 xtable_1.8-4
## [28] Rhdf5lib_1.26.0 cli_3.6.3 rmarkdown_2.28
## [31] crayon_1.5.3 ragg_1.3.2 generics_0.1.3
## [34] httr_1.4.7 cachem_1.1.0 rhdf5_2.48.0
## [37] zlibbioc_1.50.0 parallel_4.4.1 BiocManager_1.30.25
## [40] XVector_0.44.0 basilisk_1.16.0 vctrs_0.6.5
## [43] Matrix_1.7-0 jsonlite_1.8.8 dir.expiry_1.12.0
## [46] bookdown_0.40 systemfonts_1.1.0 jquerylib_0.1.4
## [49] glue_1.7.0 pkgdown_2.1.0 DT_0.33
## [52] later_1.3.2 UCSC.utils_1.0.0 tibble_3.2.1
## [55] pillar_1.9.0 basilisk.utils_1.16.0 htmltools_0.5.8.1
## [58] rhdf5filters_1.16.0 GenomeInfoDbData_1.2.12 R6_2.5.1
## [61] textshaping_0.4.0 evaluate_0.24.0 shiny_1.9.1
## [64] lattice_0.22-6 png_0.1-8 httpuv_1.6.15
## [67] bslib_0.8.0 rjsoncons_1.3.1 Rcpp_1.0.13
## [70] SparseArray_1.4.8 xfun_0.47 fs_1.6.4
## [73] pkgconfig_2.0.3