Quickstart

Learn how to install the TileDB-SOMA API to start working with SOMA experiments containing single-cell data.

How to run this tutorial

We recommend running this tutorial, as well as the other various tutorials in the Tutorials section, inside TileDB Cloud. This will allow you to quickly experiment avoiding all the installation and deployment hassles. Sign up for the free tier, spin up a TileDB Cloud notebook with a Python or R kernel, and follow the tutorial instructions.

This tutorial will cover basic access of a public single-cell dataset (available on the TileDB Cloud Marketplace) with TileDB-SOMA in Python and R, as well as the integrations with AnnData and Seurat.

You will use an example dataset generated by the Tabula Sapiens consortium, which contains nearly 265,000 immune cells. The original H5AD data file was downloaded from Figshare and converted to a SOMA experiment, which is available on TileDB Cloud.

Data from a single-cell study stored in TileDB-SOMA is called a SOMA experiment. Each SOMA experiment contains various data elements, including the assay measurements, annotations, and derived results, all organized into a well-defined on-disk format.

To access a SOMA experiment, you need to know its URI, which points to its physical location locally, a remote object store (e.g., Amazon S3), or TileDB Cloud. This example uses a SOMA experiment located on S3 that has been registered on TileDB Cloud.

Python
R

EXPERIMENT_URI = "tiledb://TileDB-Inc/tabula-sapiens-immune"

experiment_uri <- "tiledb://TileDB-Inc/tabula-sapiens-immune"

Import the necessary libraries.

Python
R

import tiledbsoma
import tiledbsoma.io

tiledbsoma.show_package_versions()

tiledbsoma.__version__              1.11.3
TileDB-Py version                   0.29.0
TileDB core version (tiledb)        2.23.0
TileDB core version (libtiledbsoma) 2.23.0
python version                      3.11.9.final.0
OS version                          Linux 6.8.0-1009-aws

library(tiledb)
library(tiledbsoma)
suppressPackageStartupMessages(library(Seurat))

show_package_versions()

tiledbsoma:    1.11.3
tiledb-r:      0.27.0
tiledb core:   2.23.0
libtiledbsoma: 2.23.0
R:             R version 4.3.3 (2024-02-29)
OS:            Debian GNU/Linux 11 (bullseye)

Open the SOMA experiment in read mode to view its structure and metadata.

Python
R

experiment = tiledbsoma.Experiment.open(EXPERIMENT_URI)
experiment

<Experiment 'tiledb://TileDB-Inc/tabula-sapiens-immune' (open for 'r') (2 items)
    'ms': 'tiledb://TileDB-Inc/e19ed185-3710-4542-be4f-a82ce8418fd6' (unopened)
    'obs': 'tiledb://TileDB-Inc/e11d2d07-ab5a-41aa-9408-378802cd4890' (unopened)>

experiment <- SOMAExperimentOpen(experiment_uri)
experiment

<SOMAExperiment>
  uri: tiledb://TileDB-Inc/tabula-sapiens-immune 
  arrays: obs* 
  groups: ms*

Each data component within a SOMA experiment is stored hierarchically, with the top-level collection containing obs, a TileDB array containing observation-level metadata, and ms, a sub-collection containing one or more SOMA measurements.

Tip

Learn more about the SOMA data model in the Foundation section.

Any of these elements can be accessed directly, such as obs as shown below.

Python
R

experiment.obs

<DataFrame 'tiledb://TileDB-Inc/e11d2d07-ab5a-41aa-9408-378802cd4890' (open for 'r')>

experiment$obs

<SOMADataFrame>
  uri: tiledb://TileDB-Inc/e11d2d07-ab5a-41aa-9408-378802cd4890 
  dimensions: soma_joinid 
  attributes: cell_id, organ_tissue, method, donor, anatomical_information, n_counts_UMIs, ...

Once you have accessed the component of interest, you can load its data into memory for further analysis.

Python
R

experiment.obs.read().concat().to_pandas()

	soma_joinid	cell_id	organ_tissue	method	donor	anatomical_information	n_counts_UMIs	n_genes	cell_ontology_class	free_annotation	manually_annotated	compartment	gender
0	0	AAACCCACACTCCTGT_TSP6_Liver_NA_10X_1_1	Liver	10X	TSP6	nan	7633.0	2259	macrophage	Monocyte/Macrophage	True	immune	male
1	1	AAACGAAGTACCAGAG_TSP6_Liver_NA_10X_1_1	Liver	10X	TSP6	nan	2858.0	1152	monocyte	Monocyte	True	immune	male
2	2	AAAGAACAGCCTCTTC_TSP6_Liver_NA_10X_1_1	Liver	10X	TSP6	nan	10395.0	2598	macrophage	Monocyte/Macrophage	True	immune	male
3	3	AAAGAACGTAGCACAG_TSP6_Liver_NA_10X_1_1	Liver	10X	TSP6	nan	6610.0	2125	liver dendritic cell	Dendritic cell	True	immune	male
4	4	AAAGAACGTTTCTTAC_TSP6_Liver_NA_10X_1_1	Liver	10X	TSP6	nan	9387.0	2345	macrophage	Monocyte/Macrophage	True	immune	male
...	...	...	...	...	...	...	...	...	...	...	...	...	...
264819	264819	TSP2_Vasculature_aorta_SS2_B113343_B133091_Imm...	Vasculature	smartseq2	TSP2	aorta	37347.0	395	macrophage	macrophage	True	immune	female
264820	264820	TSP2_Vasculature_aorta_SS2_B113343_B133091_Imm...	Vasculature	smartseq2	TSP2	aorta	111047.0	769	macrophage	macrophage	True	immune	female
264821	264821	TSP2_Vasculature_aorta_SS2_B113343_B133091_Imm...	Vasculature	smartseq2	TSP2	aorta	140634.0	2468	macrophage	macrophage	True	immune	female
264822	264822	TSP2_Vasculature_aorta_SS2_B113343_B133091_Imm...	Vasculature	smartseq2	TSP2	aorta	176268.0	2700	macrophage	macrophage	True	immune	female
264823	264823	TSP2_Vasculature_aorta_SS2_B113343_B133091_Imm...	Vasculature	smartseq2	TSP2	aorta	69025.0	982	t cell	t cell	True	immune	female

264824 rows × 13 columns

experiment$obs$read()$concat()$to_data_frame()

A tibble: 264824 x 13
soma_joinid	cell_id	organ_tissue	method	donor	anatomical_information	n_counts_UMIs	n_genes	cell_ontology_class	free_annotation	manually_annotated	compartment	gender
<int>	<chr>	<fct>	<fct>	<fct>	<fct>	<dbl>	<int>	<fct>	<fct>	<lgl>	<fct>	<fct>
0	AAACCCACACTCCTGT_TSP6_Liver_NA_10X_1_1	Liver	10X	TSP6	nan	7633	2259	macrophage	Monocyte/Macrophage	TRUE	immune	male
1	AAACGAAGTACCAGAG_TSP6_Liver_NA_10X_1_1	Liver	10X	TSP6	nan	2858	1152	monocyte	Monocyte	TRUE	immune	male
2	AAAGAACAGCCTCTTC_TSP6_Liver_NA_10X_1_1	Liver	10X	TSP6	nan	10395	2598	macrophage	Monocyte/Macrophage	TRUE	immune	male
3	AAAGAACGTAGCACAG_TSP6_Liver_NA_10X_1_1	Liver	10X	TSP6	nan	6610	2125	liver dendritic cell	Dendritic cell	TRUE	immune	male
4	AAAGAACGTTTCTTAC_TSP6_Liver_NA_10X_1_1	Liver	10X	TSP6	nan	9387	2345	macrophage	Monocyte/Macrophage	TRUE	immune	male
...	...	...	...	...	...	...	...	...	...	...	...	...
264819	TSP2_Vasculature_aorta_SS2_B113343_B133091_Immune_P5_S365	Vasculature	smartseq2	TSP2	aorta	37347	395	macrophage	macrophage	TRUE	immune	female
264820	TSP2_Vasculature_aorta_SS2_B113343_B133091_Immune_P6_S366	Vasculature	smartseq2	TSP2	aorta	111047	769	macrophage	macrophage	TRUE	immune	female
264821	TSP2_Vasculature_aorta_SS2_B113343_B133091_Immune_P7_S367	Vasculature	smartseq2	TSP2	aorta	140634	2468	macrophage	macrophage	TRUE	immune	female
264822	TSP2_Vasculature_aorta_SS2_B113343_B133091_Immune_P8_S368	Vasculature	smartseq2	TSP2	aorta	176268	2700	macrophage	macrophage	TRUE	immune	female
264823	TSP2_Vasculature_aorta_SS2_B113343_B133091_Immune_P9_S369	Vasculature	smartseq2	TSP2	aorta	69025	982	t cell	t cell	TRUE	immune	female

Tip

Visit the Data Access tutorial to learn about performing iterated reads, applying filters, sub-selecting columns, and in-memory formats for further analysis.

You can select and extract data from a SOMA experiment by performing an axis query to filter the data based on observation or variable metadata. For example, you can filter the experiment to retrieve only data for macrophage cells and genes with highly variable expression levels:

Python
R

query = experiment.axis_query(
    measurement_name="RNA",
    obs_query=tiledbsoma.AxisQuery(value_filter="cell_ontology_class == 'monocyte'"),
    var_query=tiledbsoma.AxisQuery(value_filter="highly_variable == True"),
)

query <- experiment$axis_query(
  measurement_name = "RNA",
  obs_query = SOMAAxisQuery$new(
    value_filter = "cell_ontology_class == 'monocyte'"
  ),
  var_query = SOMAAxisQuery$new(
    value_filter = "highly_variable == True"
  )
)

Similar to the experiment object, the query object allows access to any data component within a SOMA experiment. However, unlike the experiment, a query loads into memory only the data matching the filtering criteria specified in the axis_query(). This makes it possible to access and analyze specific slices of data from a larger dataset.

Additionally, the query object provides methods to read multiple components of the experiment into memory as objects compatible with popular single-cell analysis toolkits.

Python
R

This will create an AnnData object containing the filtered expression data, cell metadata, and feature metadata. Any derived results (e.g., embeddings) can also be loaded into the AnnData object.

query.to_anndata(X_name="data")

AnnData object with n_obs × n_vars = 12514 × 2435
    obs: 'soma_joinid', 'cell_id', 'organ_tissue', 'method', 'donor', 'anatomical_information', 'n_counts_UMIs', 'n_genes', 'cell_ontology_class', 'free_annotation', 'manually_annotated', 'compartment', 'gender'
    var: 'soma_joinid', 'var_id', 'gene_symbol', 'feature_type', 'ensemblid', 'highly_variable', 'means', 'dispersions', 'dispersions_norm', 'mean', 'std'

Remember to always close the query object when you are done with it.

query.close()

This will create a Seurat object containing the filtered expression data, cell metadata, and feature metadata. Any derived results (e.g., embeddings) can also be included in the Seurat object. Here, the obsm_layers arg is used to include the UMAP embeddings.

query$to_seurat(
  X_layers = c(data = "data"),
  obs_index = "cell_id",
  var_index = "var_id",
  obsm_layers = "X_umap"
)

An object of class Seurat 
2435 features across 12514 samples within 1 assay 
Active assay: RNA (2435 features, 0 variable features)
 1 layer present: data
 1 dimensional reduction calculated: umap

Finally, the SOMA experiment class acts as a context manager, which needs to be closed to release the underlying resources.

Python
R

experiment.close()

experiment$close()

Congratulations! You have successfully installed the TileDB-SOMA API and used it to access and query a single-cell dataset stored as a SOMA experiment.

Next steps

Learn more about the TileDB-SOMA data model and APIs in the Foundation section.
Explore the Tutorials to dive deeper into the TileDB-SOMA APIs.