register_memory_datasource
Register a project whose image, mask or cell table live in memory.
from plexora import register_memory_datasourceregister_memory_datasource(
name,
image=None,
*,
segmentation=None,
adata=None,
table=None,
sdata=None,
sdata_table=None,
sdata_image=None,
sdata_labels=None,
channel_names=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,
pixel_size=None,
data_dir=None,
image_type=None,
segmentation_mode=None,
axes=None,
z_step=None,
frame_interval=None,
log=print,
)Each of image, segmentation and the table (adata or table) is
independently a path or an object -- a numpy.ndarray, a pandas or
polars DataFrame, an AnnData, or a SpatialData (via sdata). A
path is read from disk exactly as it always was; an object is
snapshotted and served from a small server this kernel starts on its
own thread, so nothing is written to disk. The mixed case is the one
this is really for: a whole-slide image on disk with an AnnData a
notebook has just finished annotating.
Calling this again with the same name replaces the snapshots and
re-reads the table, while leaving everything else about the project --
its saved channels, its ROIs, its figures -- alone. That is what makes
an annotate/look loop cheap: annotate the object, call this again,
look. Any argument left as None on a later call keeps what the
project already has; a name already used by a project this kernel does
not own is refused rather than overwritten.
When to use
This is the entry point for the objects a notebook is already
holding. Call plexora.view(name, image=array, adata=adata, ...)
for the common case of registering and opening a viewer in one
step; call register_memory_datasource directly to register
without opening a viewer, or to update an already-open project's
data before the next viewer.refresh(). For an image or table
that already lives in a file, use
plexora.register_anndata_datasource, plexora.register_datasource
or plexora.create_project instead -- there is nothing to gain
from reading a path through memory.
Parameters
namestrrequiredThe project's name.
imagestr | Path | numpy.ndarraydefault NoneThe whole-slide
image, or an array: (channel, row, col), or a z-stack or time
series with its axes named in axes. Required the first time a
project is registered under name; left out on a later call,
the project's existing image is kept.
segmentationstr | Path | numpy.ndarraykeyword-onlydefault NoneThe segmentation mask, as a path or a 2-D label array. Left out, the project's existing mask (if any) is kept.
adataAnnDatakeyword-onlydefault NoneA live AnnData to serve as the cell
table. Pass this or table, not both.
tableDataFramekeyword-onlydefault NoneA flat cell table -- pandas, polars,
or anything polars can read -- to serve as the cell table.
Pass this or adata, not both.
sdataSpatialDatakeyword-onlydefault NoneA live SpatialData object to take
image, segmentation and the table from, for whichever of
those was not also passed directly. Ambiguous when the store
holds more than one image, labels element or table; say which
one with sdata_image, sdata_labels or sdata_table.
sdata_tablestrkeyword-onlydefault NoneWhich table in sdata to use, when it
holds more than one.
sdata_imagestrkeyword-onlydefault NoneWhich image in sdata to use, when it
holds more than one.
sdata_labelsstrkeyword-onlydefault NoneWhich labels element in sdata to
use, when it holds more than one.
channel_nameslist[str]keyword-onlydefault NoneA name for each image channel, in channel order.
coordinate_sourcestrkeyword-onlydefault 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. Ignored for table.
obsm_keystrkeyword-onlydefault NoneThe obsm entry holding coordinates,
when coordinate_source="obsm". Defaults to "spatial".
xstrkeyword-onlydefault NoneThe column holding each cell's X coordinate --
an obs column for adata when coordinate_source="obs", or
a column of table.
ystrkeyword-onlydefault NoneThe column holding each cell's Y coordinate --
an obs column for adata when coordinate_source="obs", or
a column of table.
feature_sourcestrkeyword-onlydefault 'X'Where marker values come from, for
adata: "X" (the default), "layer" (see layer), or
"obs" (see feature_obs_columns). Ignored for table.
layerstrkeyword-onlydefault NoneThe adata.layers entry to read markers
from, when feature_source="layer".
feature_obs_columnslist[str]keyword-onlydefault NoneThe obs columns to
read as markers, when feature_source="obs".
obs_id_fieldstrkeyword-onlydefault NoneThe column holding each cell's unique
id. Defaults to a positional id for adata, or table's row
number.
celltype_columnstrkeyword-onlydefault NoneThe column holding a cell type or phenotype label, if there is one.
subset_bystrkeyword-onlydefault NoneAn obs column that separates several
images' cells in one AnnData; subset_value says which value
is this project's. Ignored for table.
subset_valuestrkeyword-onlydefault NoneThe value of subset_by that
belongs to this project.
apply_log_transformboolkeyword-onlydefault FalseWhether 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.
pixel_sizefloatkeyword-onlydefault NoneThe physical size of one pixel, in
micrometres, for an image array -- which carries no header
of its own. Leave unset for a path, whose own metadata is used
instead.
data_dirstr | Pathkeyword-onlydefault NoneThe data root to register the project under. Defaults to Plexora's configured data directory.
image_typestrkeyword-onlydefault None"brightfield" or "fluorescence", to
override how a path image is read. Defaults to None, which
decides from the file.
segmentation_modestrkeyword-onlydefault None"filled" (the default) stores
a filled label mask; "outlines" stores boundaries instead.
Only meaningful for a path segmentation.
axesstrkeyword-onlydefault NoneThe axes of an image array, slowest first,
from t, c, z, y, x and ending in yx -- "czyx" for a
multichannel z-stack, "zyx" for one channel. Defaults to
"cyx" for 3-D, "czyx" for 4-D and "tczyx" for 5-D arrays.
z_stepfloatkeyword-onlydefault NoneMicrometres between the planes of a z-stack array. Leave unset when unknown: sections and 3-D measurements then say the step is missing rather than assume one.
frame_intervalfloatkeyword-onlydefault NoneSeconds between the frames of a time-series array.
logcallablekeyword-onlydefault printWhere a warning about a large in-memory
copy is printed. Defaults to print.
Returns
ProjectThe project, reloaded from disk with its new snapshots attached.
Raises
MemoryDataErrorIf both adata and table are given, if sdata
does not resolve something it is asked for, or if name is
already used by a project this kernel does not own.
Examples
import numpy as np
import pandas as pd
import plexora
plexora.register_memory_datasource(
"quicklook", image=np.zeros((2, 256, 256), dtype=np.uint8))
table = pd.DataFrame({
"X": [10.0, 60.0, 110.0, 160.0],
"Y": [10.0, 60.0, 110.0, 160.0],
"CD3": [0.0, 1.0, 2.0, 3.0],
})
plexora.register_memory_datasource("quicklook", table=table, x="X", y="Y")Notes
This does not itself tell a running viewer to reload -- call
viewer.refresh() (or open a new plexora.view(...)) afterwards
to see the change.
Related
view
Open a notebook-displayable viewer on datasource.
PlexoraViewer
A running Plexora viewer, returned by plexora.view().