Registry / data / tiledbsoma

tiledbsoma

JSON →
library2.3.0pypypiunverified

TileDB-SOMA is a Python API for efficient storage and retrieval of single-cell biological data, building on the TileDB embedded array database. It implements the SOMA (Single Object for Multi-omic Access) specification, enabling scalable, language-agnostic access to annotated matrices. The library receives regular updates, typically with minor releases every 1-2 months.

pip install tiledbsoma
INSTALL
IMPORT
SIG · TILEDBSOMA
T
tiledbsoma
datapythonv2.3.0
Install
31.1s avg
Import
3122ms
Disk
1024MB
Pass rate
5/ 10
Env Coverage5 / 10
glibc
3.9–3.13
musl
3.9–3.13
Install & Compatibility
Where this runs
tested against v2.3.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.10–3.910 runs
build_error
glibc
py 3.10–3.910 runs
installs and imports cleanly · install 31.1s · import 3.122s · 942MB
1024MB installed
● package 1024MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

soma
✓ import tiledbsoma as soma
The idiomatic import for the main API.
DataFrame
✓ from tiledbsoma import DataFrame
✗ from tiledbsoma.soma import DataFrame
Top-level symbols are directly available from `tiledbsoma`.
Collection
✓ from tiledbsoma import Collection
✗ from tiledbsoma.collection import Collection
Top-level symbols are directly available from `tiledbsoma`.

This quickstart demonstrates how to create a simple SOMA DataFrame, write Pandas data to it with a PyArrow schema, and then read the data back. This covers the fundamental create, write, and read operations for a basic SOMA object.

import tiledbsoma as soma import os import pandas as pd import pyarrow as pa # Define a path for the SOMA object soma_path = "./my_soma_df_quickstart" # Clean up if it exists if os.path.exists(soma_path): soma.delete(soma_path) # Create a SOMA DataFrame with soma.DataFrame.create( soma_path, schema=pa.schema([ pa.field("gene_id", pa.string()), pa.field("feature_val", pa.float32()), ]), index_column_names=["gene_id"], ) as sdf: # Prepare data data = pd.DataFrame({ "gene_id": ["geneA", "geneB", "geneC"], "feature_val": [1.1, 2.2, 3.3] }) # Write data sdf.write(data) print(f"SOMA DataFrame created at: {soma_path}") # Read data back with soma.DataFrame.open(soma_path) as sdf_read: read_df = sdf_read.read().concat().to_pandas() print("\nRead DataFrame:") print(read_df) # Clean up soma.delete(soma_path) print(f"\nCleaned up {soma_path}")
Debug
Known issues
breakingUsers who ingested BPCells data with versions 2.1.0 or 2.1.1 must re-ingest with version 2.1.2 or later to ensure data correctness.
fix
Upgrade to TileDB-SOMA 2.1.2 or newer and re-ingest any BPCells data created with versions 2.1.0 or 2.1.1.
affects: 2.1.0, 2.1.1
deprecatedSupport for MacOS Intel is being deprecated.
fix
Users on MacOS Intel systems should consider migrating to Apple Silicon (M-series) for continued support and optimal performance. Future versions may drop support entirely.
affects: >=2.2.0
gotchaSOMA object paths must be unique for creation. Attempting to create an object at an existing path will raise an error.
fix
Before creating a new SOMA object, ensure the path does not exist, or explicitly delete the existing object using `soma.delete(path)` if overwriting is intended.
affects: All versions
gotchaSchema definition is critical. Data written to SOMA objects must conform to the defined PyArrow schema. Type mismatches can lead to errors.
fix
Carefully define your `pyarrow.Schema` when creating SOMA objects. Ensure the `dtype` of your input data (e.g., Pandas DataFrame) is compatible with the PyArrow types in the schema.
affects: All versions
Upgrade
Version history
2.3.0latest on PyPI · released Jan 27, 2026
Audit
Dependencies
tiledb-pyrequiredCore dependency for TileDB array storage backend.
numpyrequiredFundamental package for numerical computation.
pandasrequiredData manipulation and analysis, common for data ingestion/retrieval.
pyarrowrequiredUsed for defining SOMA object schemas and data interchange.
anndatarequiredPrimary integration target for single-cell data.
Agent activity
14 hits · last 30 days
node
12
OpenAI (training)
1
Resources
tiledbsoma — pip install tiledbsoma · libregistry