Plexora
Python APIData sources

register_anndata_datasource

Register an image and an AnnData-backed cell table as a project.

Generated from Plexora 0.0.55View source
from plexora import register_anndata_datasource
register_anndata_datasource(
    name,
    image,
    features=None,
    adata=None,
    segmentation=None,
    coordinate_source=None,
    obsm_key=None,
    x=None,
    y=None,
    feature_source='X',
    layer=None,
    feature_obs_columns=None,
    obs_id_field=None,
    celltype_column=None,
    subset_by=None,
    subset_value=None,
    apply_log_transform=False,
    channel_names=None,
    copy=False,
    data_dir=None,
    table=None,
    segmentation_async=False,
    segmentation_mode=None,
    image_type=None,
    pyramidize=None,
)

Writes directly to Plexora's project registry. Exactly one of features (a path to an existing .h5ad) or adata (a live AnnData) must be given; a live object is written to an .h5ad inside the project's own folder first.

Passing table as well switches this to SpatialData mode: features is then a .zarr store and table names the table inside it to load. plexora.register_spatialdata_datasource is the friendlier entry point for that case. If the store or file cannot be fully read yet -- several tables and none named, or a table spanning more images than subset_by answers -- the project is still registered, as an image with the open question recorded; whichever tool needs the table asks for it.

When to use

plexora.create_project is the newer entry point and answers the same questions progressively, with plexora.configure_project filling in whatever is left. register_anndata_datasource is the older, all-at-once form, and still the direct call for a script that already knows every column and matrix it wants. Use plexora.register_memory_datasource instead of passing a live adata here when the project should read straight out of this kernel rather than through a written .h5ad.

Parameters

namestrrequired

The project's name.

imagestr | Pathrequired

The whole-slide image -- OME-TIFF/TIFF, DICOM, or a Zarr store. A web address is read in place.

featuresstr | Pathdefault None

An existing .h5ad file, or (with table) a SpatialData .zarr store. Exactly one of features or adata is required.

adataAnnDatadefault None

A live AnnData, written to an .h5ad inside the project's folder before it is registered. Exactly one of features or adata is required.

segmentationstr | Pathdefault None

The segmentation mask, if there is one.

coordinate_sourcestrdefault None

"obsm" to read coordinates from adata.obsm (see obsm_key), or "obs" to read them from two columns (see x, y). Left unset, adata.obsm['spatial'] is used automatically when present and unambiguous.

obsm_keystrdefault None

The obsm entry holding coordinates, when coordinate_source="obsm". Defaults to "spatial".

xstrdefault None

The obs column holding each cell's X coordinate, when coordinate_source="obs".

ystrdefault None

The obs column holding each cell's Y coordinate, when coordinate_source="obs".

feature_sourcestrdefault 'X'

Where marker values come from: "X" (the default), "layer" (see layer), or "obs" (see feature_obs_columns).

layerstrdefault None

The adata.layers entry to read markers from, when feature_source="layer".

feature_obs_columnslist[str]default None

The obs columns to read as markers, when feature_source="obs".

obs_id_fieldstrdefault None

The obs column holding each cell's unique id. Defaults to a positional id (0..n-1).

celltype_columnstrdefault None

The obs column holding a cell type or phenotype label, if there is one.

subset_bystrdefault None

An obs column that separates several images' cells in one table; subset_value says which value is this project's.

subset_valuestrdefault None

The value of subset_by that belongs to this project.

apply_log_transformbooldefault False

Whether the chosen feature source is already log-transformed. Defaults to False; get this right, since it also controls whether gates keep float precision or round to whole numbers.

channel_nameslist[str]default None

A name for each image channel, in channel order. Derived from adata.var_names, the image's own metadata, or adata.uns['all_markers'], in that order, when not given.

copybooldefault False

Copy image, segmentation and features into the project's own folder instead of reading them where they are. Ignored for a live adata, which is always written into the project's folder. Defaults to False.

data_dirstr | Pathdefault None

The data root to register the project under. By default the project is registered where new projects go (on your own computer, Documents/Plexora/projects, which the Plexora website opens too) and what registering builds is written to Plexora's configured data directory.

tablestrdefault None

The table inside features to load, when features is a SpatialData .zarr store. A store with exactly one table resolves on its own.

segmentation_asyncbooldefault False

Defer mask conversion to a background job and return immediately, leaving the returned entry's segmentation_status as "pending". Defaults to False.

segmentation_modestrdefault None

"filled" (the default) stores a filled label mask; "outlines" stores boundaries instead.

image_typestrdefault None

"brightfield" or "fluorescence", to override how the image is read. Defaults to None, which decides from the file.

pyramidizebool or strdefault None

What to do with a large multiplex TIFF that has no reduced-resolution levels. None (the default) and True write a pyramidized copy once, beside the original (or in the project's folder when that one is not writable), and open the copy; the original is never changed. A 16-bit image's copy is <name>.pyramid.approx, about 75% smaller than an exact copy with every pixel within its noise, unless the setting compress_pyramids is off; otherwise <name>.pyramid.ome.tiff. "compressed" or "exact" asks for that kind. False opens the original as it is.

Returns

dict

The project's saved config entry.

Raises

ValueError

If both or neither of features and adata are given, or if table is given together with adata.

Examples

import plexora

plexora.register_anndata_datasource(
    "tonsil", image="slide.ome.tif", features="cells.h5ad",
)

register_memory_datasource

Register a project whose image, mask or cell table live in memory.

view

Open a notebook-displayable viewer on datasource.

register_spatialdata_datasource

Register one table of a SpatialData (.zarr) store as a project.

Guides

Python

Notebook

register_datasource

Register an image and a flat cell table as a project, in one call.

register_spatialdata_datasource

Register one table of a SpatialData (.zarr) store as a project.

On this page

When to useParametersReturnsRaisesExamplesRelatedGuides