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.