Skip to contents

# Census query & extract subsets

Source: `vignettes/census_query_extract.Rmd`
`census_query_extract.Rmd`

Goal: demonstrate the ability to query subsets of the Census based upon user-defined obs/var metadata, and extract those slices into in-memory data structures for further analysis.

NOTE: all examples in this vignette assume that sufficient memory exists on the host machine to store query results. In fact, we will increase the memory available to `tiledbsoma` as we open the Census. There are other notebooks which provide examples for out-of-core processing.

    ctx <- tiledbsoma::SOMATileDBContext$new(
      config = c("soma.init_buffer_bytes" = "1073741824")
    )
    census <- cellxgene.census::open_soma(tiledbsoma_ctx = ctx)

The Census includes SOMA Experiments for both human and mouse. These experiments can be queried based upon metadata values (eg, tissue type), and the query result can be extracted into a variety of formats.

Basic idea:

- define per-axis (i.e., obs, var) query criteria
- specify the experiment and measurement name to be queried
- specify the column names you want as part of the results
- and read the query result into an in-memory format.

This utilizes the SOMA `value_filter` query language. Keep in mind that the results must fit into memory, so it is best to define a selective query and only fetch those axis metadata columns which are necessary.

The `cellxgene.census` package includes a convenience function to extract a slice of the Census and read into a Seurat object. This function accepts a variety of arguments, including:

- the organism to slice
- the per-axis slice criteria
- the columns to fetch and include in the Seurat metadata

For more complex query scenarios, there is an advanced query API demonstrated in other vignettes.

    obs_query <- tiledbsoma::SOMAAxisQuery$new(value_filter = "tissue_ontology_term_id=='UBERON:0002048' && sex_ontology_term_id=='PATO:0000383' && cell_type_ontology_term_id == 'CL:0000499'")
    adata <- cellxgene.census::get_seurat(census, "Homo sapiens", obs_query = obs_query)
    #> Warning: No reductions found
    #> Warning: No graphs found in 'obsp'
    print(adata)
    #> An object of class Seurat
    #> 60664 features across 40118 samples within 1 assay
    #> Active assay: RNA (60664 features, 0 variable features)

    # You can also query on both axis. This example adds a var-axis query for a handful of genes, and queries the mouse experiment.
    obs_query <- tiledbsoma::SOMAAxisQuery$new(value_filter = "tissue == 'brain'")
    var_query <- tiledbsoma::SOMAAxisQuery$new(value_filter = "feature_name %in% c('Gm16259', 'Dcaf5', 'Gm53058')")
    adata <- cellxgene.census::get_seurat(
      census,
      "Mus musculus",
      obs_query = obs_query,
      obs_column_names = c("tissue", "cell_type", "sex"),
      var_query = var_query
    )
    #> Warning: No reductions found
    #> Warning: No graphs found in 'obsp'
    print(adata)
    #> An object of class Seurat
    #> 3 features across 133674 samples within 1 assay
    #> Active assay: RNA (3 features, 0 variable features)