Skip to contents

Census Datasets example

Source: vignettes/census_datasets.Rmd
census_datasets.Rmd

Goal: demonstrate basic use of the census_datasets data frame.

Each Cell Census contains a top-level data frame itemizing the datasets contained therein. You can read this SOMADataFrame into an Arrow Table:

census <- cellxgene.census::open_soma()
census_datasets <- census$get("census_info")$get("datasets")$read()
print(census_datasets)
#> Table
#> 529 rows x 8 columns
#> $soma_joinid <int64 not null>
#> $collection_id <large_string not null>
#> $collection_name <large_string not null>
#> $collection_doi <large_string not null>
#> $dataset_id <large_string not null>
#> $dataset_title <large_string not null>
#> $dataset_h5ad_path <large_string not null>
#> $dataset_total_cell_count <int64 not null>

and then an R data frame:

census_datasets <- as.data.frame(census_datasets)
print(census_datasets[, c(
  "dataset_id",
  "dataset_title",
  "dataset_total_cell_count"
)], n = 5)
#> # A tibble: 529 × 3
#>   dataset_id                           dataset_title                     datas…¹
#>   <chr>                                <chr>                               <int>
#> 1 f512b8b6-369d-4a85-a695-116e0806857f Skin                                68036
#> 2 36c867a7-be10-4e69-9b39-5de12b0af6da Ileum                               32458
#> 3 58b01044-c5e5-4b0f-8a2d-6ebf951e01ff A scRNA-seq atlas of immune cell…  130908
#> 4 456e8b9b-f872-488b-871d-94534090a865 Single-cell atlas of peripheral …   44721
#> 5 d8da613f-e681-4c69-b463-e94f5e66847f A molecular single-cell lung atl…  116313
#> # … with 524 more rows, and abbreviated variable name ¹​dataset_total_cell_count

The sum of cell counts across all datasets should match the number of cells across all SOMA experiments (human, mouse).

census_data <- census$get("census_data")
all_experiments <- lapply(census_data$to_list(), function(it) census_data$get(it$name))
print(all_experiments)
#> $homo_sapiens
#> <SOMAExperiment>
#>   uri: s3://cellxgene-data-public/cell-census/2023-04-10/soma/census_data/homo_sapiens 
#>   arrays: obs* 
#>   groups: ms* 
#> 
#> $mus_musculus
#> <SOMAExperiment>
#>   uri: s3://cellxgene-data-public/cell-census/2023-04-10/soma/census_data/mus_musculus 
#>   arrays: obs* 
#>   groups: ms*
experiments_total_cells <- sum(sapply(all_experiments, function(it) {
  nrow(it$obs$read(column_names = c("soma_joinid")))
}))
print(paste("Found", experiments_total_cells, "cells in all experiments."))
#> [1] "Found 49972919 cells in all experiments."
print(paste(
  "Found", sum(as.vector(census_datasets$dataset_total_cell_count)),
  "cells in all datasets."
))
#> [1] "Found 49972919 cells in all datasets."

Let’s pick one dataset to slice out of the census, and turn into a Seurat in-memory object. (This requires the Seurat package to have been installed beforehand.)

census_datasets[census_datasets$dataset_id == "0bd1a1de-3aee-40e0-b2ec-86c7a30c7149", ]
#> # A tibble: 1 × 8
#>   soma_joinid collection_id      colle…¹ colle…² datas…³ datas…⁴ datas…⁵ datas…⁶
#>         <int> <chr>              <chr>   <chr>   <chr>   <chr>   <chr>     <int>
#> 1         197 0b9d8a04-bb9d-44d… Tabula… 10.103… 0bd1a1… Bone m… 0bd1a1…   40220
#> # … with abbreviated variable names ¹​collection_name, ²​collection_doi,
#> #   ³​dataset_id, ⁴​dataset_title, ⁵​dataset_h5ad_path, ⁶​dataset_total_cell_count

Create a query on the mouse experiment, “RNA” measurement, for the dataset_id.

obs_query <- tiledbsoma::SOMAAxisQuery$new(
  value_filter = "dataset_id == '0bd1a1de-3aee-40e0-b2ec-86c7a30c7149'"
)
expt_query <- tiledbsoma::SOMAExperimentAxisQuery$new(
  census_data$get("mus_musculus"), "RNA",
  obs_query = obs_query
)
dataset_seurat <- expt_query$to_seurat(c(counts = "raw"))
#> Warning: No reductions found
#> Warning: No graphs found in 'obsp'
print(dataset_seurat)
#> An object of class Seurat 
#> 52392 features across 40220 samples within 1 assay 
#> Active assay: RNA (52392 features, 0 variable features)

You can also use the cellxgene.census::get_source_h5ad_uri() API to fetch a URI pointing to the H5AD associated with this dataset_id. This is the same H5AD you can download from the CELLxGENE Portal, and may contain additional data-submitter provided information which was not included in the Cell Census.

The “locator” returned by this API will include a URI and additional information that may be necessary to use the URI (eg, the S3 region).

cellxgene.census::get_source_h5ad_uri("0bd1a1de-3aee-40e0-b2ec-86c7a30c7149")
#> $uri
#> [1] "s3://cellxgene-data-public/cell-census/2023-04-10/h5ads/0bd1a1de-3aee-40e0-b2ec-86c7a30c7149.h5ad"
#> 
#> $s3_region
#> [1] "us-west-2"

The cellxgene.census::download_source_h5ad() API downloads the H5AD to a local file, which can then be used in R using SeuratDisk’s anndata converter.