tiledbsoma.io.spatial.from_visium¶

tiledbsoma.io.spatial.from_visium(experiment_uri: str, input_path: ~pathlib.Path | ~tiledbsoma.io.spatial.ingest.VisiumPaths, measurement_name: str, scene_name: str, *, context: ~tiledbsoma.options._soma_tiledb_context.SOMATileDBContext | None = None, platform_config: ~typing.Dict[str, ~typing.Mapping[str, ~typing.Any]] | object | None = None, X_layer_name: str = 'data', raw_X_layer_name: str = 'data', image_name: str = 'tissue', image_channel_first: bool = True, ingest_mode: ~typing.Literal['write', 'schema_only', 'resume'] = 'write', use_relative_uri: bool | None = None, X_kind: type[~tiledbsoma._sparse_nd_array.SparseNDArray] | type[~tiledbsoma._dense_nd_array.DenseNDArray] = <class 'tiledbsoma._sparse_nd_array.SparseNDArray'>, registration_mapping: ~tiledbsoma.io._registration.ambient_label_mappings.ExperimentAmbientLabelMapping | None = None, additional_metadata: ~typing.Dict[str, bytes | float | int | str] | None = None, use_raw_counts: bool = False, write_obs_spatial_presence: bool = True, write_var_spatial_presence: bool = False) → str¶

Reads a 10x Visium dataset and writes it to an Experiment.

This function is for ingesting Visium data for prototyping and testing the proposed spatial design.

WARNING: This was only tested for Space Ranger version 2 output.

Parameters:

experiment_uri – The experiment to create or update.
input_path – A path to the base directory storing SpaceRanger output or a VisiumPaths object.
measurement_name – The name of the measurement to store data in.
context – Optional SOMATileDBContext containing storage parameters, etc.
platform_config – Platform-specific options used to specify TileDB options when creating and writing to SOMA objects.
X_layer_name – SOMA array name for the AnnData’s X matrix.
raw_X_layer_name – SOMA array name for the AnnData’s raw/X matrix.
image_name – SOMA multiscale image name for the multiscale image of the Space Ranger output images.
image_channel_first – If True, the image is ingested in channel-first format. Otherwise, it is ingested into channel-last format. Defaults to True.
ingest_mode –
The ingestion type to perform: - write: Writes all data, creating new layers if the SOMA already exists. - resume: Adds data to an existing SOMA, skipping writing data

that was previously written. Useful for continuing after a partial or interrupted ingestion operation.
- schema_only: Creates groups and the array schema, without writing any data to the array. Useful to prepare for appending multiple H5AD files to a single SOMA.
X_kind – Which type of matrix is used to store dense X data from the H5AD file: DenseNDArray or SparseNDArray.

registration_mapping –

Mapping for soma_joinid when ingesting multiple Visium datasets or ingesting into an existing Experiment. This is done by first registering the Visium dataset(s):

import tiledbsoma.io.spatial
rd = tiledbsoma.io.register_h5ads(
    experiment_uri,
    visium_paths,
    measurement_name="RNA",
    context=context,
)

Once they are registered, the Visium datasets can be ingested in any order using:

tiledbsoma.io.from_visium(
    experiment_uri,
    visium_path,
    measurement_name="RNA",
    ingest_mode="write",
    registration_mapping=rd,
)

additional_metadata –
Optional metadata to add to the Experiment and all descendents. This is a coarse-grained mechanism for setting key-value pairs on all SOMA objects in an Experiment hierarchy. Metadata for particular objects is more commonly set like:
```
with soma.open(uri, 'w') as exp:
    exp.metadata.update({"aaa": "BBB"})
    exp.obs.metadata.update({"ccc": 123})
```
use_raw_counts – If True ingest the raw gene expression data, otherwise use the filtered gene expression data. Only used if input_path is not a VisiumPaths object. Defaults to False.
write_obs_spatial_presence – If True create and write data to the obs presence matrix. Defaults to True.
write_var_spatial_presence – If True create and write data to the var presence matrix. Defaults to False.

Returns:

The URI of the newly created experiment.

Lifecycle

Experimental