create_project
Register one project and return its name.
from plexora import create_projectcreate_project(
image,
*,
name=None,
segmentation=None,
data=None,
table=None,
subset=None,
cell_id=None,
x=None,
y=None,
z=None,
sample=None,
celltype=None,
markers=None,
metadata=None,
coordinates=None,
layer=None,
log1p=None,
single_image=None,
row_number_ids=None,
channel_names=None,
image_type=None,
copy=False,
exist_ok=False,
dataset=None,
node=None,
) -> strimage is the only required argument, and a project with nothing else is
complete: it opens, it can be looked at, and a mask or a table can be
attached at any point afterwards with configure_project.
Anything named here is recorded as an answer and Plexora never asks about
it again. Anything left out is either absent, or a guess Plexora made from
the file itself -- and a guess is shown back, once, to whichever tool
needs it first, rather than being treated as confirmed. So naming
cell_id="CellID" here is different from leaving it out and letting
Plexora find that column itself, even when both land on the same column.
A file does not have to be on this machine: node (or a per-file
{"path": ..., "node": ...} / "node://<node>/<path>" value for image,
segmentation or data) says which data node it is on, and the project
then addresses it there instead of copying it here.
When to use
Use create_project when you already know which file plays which
role -- in a script over a directory of runs, that reads more clearly
than detection. import_sample is the other way to reach the same
registration: point it at a folder or a mix of files and it works out
what they are. create_project needs only an image and lets every
other question be answered later with configure_project.
Parameters
Core resources
imagestr | PathrequiredThe image file. The only required argument.
namestrkeyword-onlydefault NoneThe project's name. Defaults to the image's filename with its suffix removed, de-duplicated against any project already registered.
segmentationstr | Pathkeyword-onlydefault NoneA label image outlining cells (a segmentation mask).
datastr | Pathkeyword-onlydefault NoneA cell table -- CSV, Parquet, or an
AnnData/SpatialData store (.h5ad, .zarr).
Table interpretation
tablestrkeyword-onlydefault NoneWhich table to read, for a data store that
holds more than one (a SpatialData .zarr store, for instance).
Leave unset for a single-table file, or to answer this later
with configure_project.
subsetstr | tuple | dictkeyword-onlydefault NoneRestrict data to one
image's rows, for a table that covers more than one image --
"column=value", (column, value), or
{"column": ..., "value": ...}. AnnData/SpatialData only.
cell_idstrkeyword-onlydefault NoneThe column that holds each cell's id.
xstrkeyword-onlydefault NoneThe column that holds each cell's X coordinate.
ystrkeyword-onlydefault NoneThe column that holds each cell's Y coordinate.
coordinatesdictkeyword-onlydefault NoneWhere an AnnData/SpatialData table's
coordinates live: {"source": "obsm", "obsm_key": ...} or
{"source": "obs", "x_column": ..., "y_column": ...}.
samplestrkeyword-onlydefault NoneThe column that says which image a row
belongs to, for a data table that covers more than one image.
celltypestrkeyword-onlydefault NoneThe column that holds a cell type or phenotype label.
markerslist[str]keyword-onlydefault NoneWhich columns are marker intensities.
metadatalist[str]keyword-onlydefault NoneWhich columns are per-cell metadata
rather than markers. Naming only one of markers/metadata
fills in the other from the table's remaining columns.
layerstrkeyword-onlydefault NoneWhich of the file's alternate matrices
(adata.layers) to read marker values from, instead of the main
matrix. AnnData/SpatialData only.
log1pboolkeyword-onlydefault NoneWhether to log1p-transform marker values as they are read.
single_imageboolkeyword-onlydefault NoneThis table covers exactly one image,
so Plexora should not ask for a sample column. AnnData/
SpatialData only.
row_number_idsboolkeyword-onlydefault NoneUse each row's position as the cell id, for a file with no column that holds one. AnnData/SpatialData only.
Image
channel_nameslist[str]keyword-onlydefault NoneA name for each image channel, in order. Detected from the image or the table when left unset.
image_typestrkeyword-onlydefault None"brightfield" or "fluorescence",
overriding Plexora's own detection.
Location
copyboolkeyword-onlydefault FalseCopy image, segmentation and data into
Plexora's own data directory instead of reading them where they
are. Defaults to False. There is nothing to copy for a file
addressed on a data node.
nodestrkeyword-onlydefault NoneThe data node image, segmentation and
data are on, when it is not this machine. Any of the three can
override this for itself.
Registry
datasetstr | Datasetkeyword-onlydefault NonePut the new project in this
dataset -- named, by id, or as a Dataset handle. A name that
matches no existing dataset creates one.
exist_okboolkeyword-onlydefault FalseIf a project already exists under name
(or, with no name, one already reads this same image), adopt it
instead of raising. Defaults to False.
Other parameters
zstrkeyword-onlydefault NoneThe column that holds each cell's plane, for a table over a z-stack that places its cells in depth.
Returns
strThe project's name. Equal to name when one was given (or, with
exist_ok, the name of the project adopted); otherwise derived
from image's filename, with a numeric suffix added if that name
is already taken.
Raises
ValueErrorIf image, segmentation or data cannot be found; if
a project already exists under name and exist_ok was not
set; if image is a flat picture (PNG/JPEG) combined with a
mask or a table, which have nowhere to attach on a flat image;
or if a data node named in node (or in one of the files) cannot
be reached, or is not serving that file.
Examples
import plexora
name = plexora.create_project(
"slide.ome.tif", data="cells.csv",
cell_id="CellID", x="X_centroid", y="Y_centroid")
print(name)How is this different?
import_sample or create_project?
import_sample | create_project | |
|---|---|---|
| You pass | Files or a run folder | An image, with every other file named by role |
| Plexora works out | What each file is (image, mask, table, transcripts) | Nothing: you said what each file is |
| Best for | A folder of files, or files whose role is clear from their contents | Scripts that must not guess; files with unusual names |
| Returns | The project name | The project name |
Both create the same kind of project. Use import_sample when the files
explain themselves, and create_project when you want to be explicit.
create_project or register_datasource?
create_project needs only an image and lets you answer the remaining
questions later with configure_project. register_datasource is the
older, all-at-once form: the image, the table and the coordinate columns
in one call. New code should use create_project; register_datasource
stays for scripts that already use it.
create_dataset or create_project?
A project is one sample: one image with its mask, table and layers.
A dataset is a folder of projects that belong together, such as a
cohort or a TMA series. create_dataset can register images as
projects while it creates the dataset, or collect projects that
already exist.
Related
import_sample
Detect and register one sample from these paths, and return its name.
configure_project
Answer questions about a project that is already registered.
project_manifest
What one project has, what it was told, and what is still open.
PROJECT_SPEC_KEYS
Every key a project may be defined with, in one place, so the Python API, the CLI and any --from spec.json all accept exactly the same vocabulary. A caller that knows this tuple knows the whole schema.