cellxgene_census.open_soma

cellxgene_census.open_soma(*, census_version: str | None = 'stable', mirror: str | None = None, uri: str | None = None, tiledb_config: dict[str, Any] | None = None, context: SOMATileDBContext | None = None) → Collection

Open the Census by version or URI.

Parameters:

• census_version – The version of the Census, e.g. "latest" or "stable". Defaults to "stable".

• mirror – The mirror used to retrieve the Census. If not specified, a suitable mirror will be chosen automatically.

• uri – The URI containing the Census SOMA objects. If specified, will take precedence over census_version parameter.

• tiledb_config – A dictionary of TileDB configuration parameters that will be used to open the SOMA object. Optional, defaults to None. If specified, the parameters will override the default settings specified by get_default_soma_context().tiledb_config. Only one of the tiledb_config and context params can be specified.

• context – A custom tiledbsoma.SOMATileDBContext that will be used to open the SOMA object. Optional, defaults to None. Only one of the tiledb_config and context params can be specified.

Returns:

A tiledbsoma.Collection object containing the top-level census. It can be used as a context manager, which will automatically close upon exit.

Raises:

ValueError – if the census cannot be found, the URI cannot be opened, neither a URI or a version are specified, or an invalid mirror is provided.

See also

• get_source_h5ad_uri(): Look up the location of the source H5AD.

• get_default_soma_context(): Get a default SOMA context that can be updated with custom settings and used as the context argument.

Lifecycle

maturing

Examples

Open the default Census version, using a context manager which will automatically close the Census upon exit of the context.

>>> with cellxgene_census.open_soma() as census:
        ...

Open and close:

>>> census = cellxgene_census.open_soma()
    ...
    census.close()

Open a specific Census by version:

>>> with cellxgene_census.open_soma("2022-12-31") as census:
        ...

Open a Census by S3 URI, rather than by version.

>>> with cellxgene_census.open_soma(uri="s3://bucket/path") as census:
        ...

Open a Census by path (file:// URI), rather than by version.

>>> with cellxgene_census.open_soma(uri="/tmp/census") as census:
        ...

Open a Census using a mirror.

>>> with cellxgene_census.open_soma(mirror="s3-us-west-2") as census:
        ...

Open a Census with a custom TileDB configuration setting.

>>> with cellxgene_census.open_soma(tiledb_config={"py.init_buffer_bytes": 128 * 1024**2}) as census:
        ...