import_sample
Detect and register one sample from these paths, and return its name.
from plexora import import_sampleimport_sample(
*paths,
name=None,
dataset=None,
answers=None,
node=None,
replace=None,
wait=False,
) -> strThe programmatic form of the viewer's Import Sample dialog (which calls
a project a "sample"): point it at a Xenium run, a SpatialData store, a
folder, or any mix of individual files, and it works out what they are,
groups them into one sample, picks the reference image, and registers the
lot.
create_project is the same registration reached the other way -- by
naming each role (image=, segmentation=, data=) rather than letting
detection work them out. Both end up at the same per-resource writers, so
they produce the same kind of project either way.
When to use
Use import_sample for a run folder, a SpatialData store, or a mix
of files you have not sorted into roles yourself. Use create_project
when you already know which file is which -- in a script over a
directory of runs, that is the clearer thing to read.
Parameters
*pathsOne or more paths: a run folder, a SpatialData store, or a mix of individual files (an image, a mask, a cell table).
namestrkeyword-onlydefault NoneOverride the name Plexora would otherwise
derive from the files. Raises if it is already taken by a
different sample than the one named in replace.
datasetstr | dictkeyword-onlydefault NoneFile the new sample under this
dataset. A plain string is an existing dataset's id (not its
name); {"new": "Cohort Name"} finds or creates a dataset by
name instead.
answersdictkeyword-onlydefault None{question_id: value} for anything
detection could not work out. A question left unanswered takes
its default and is recorded on the layer as unresolved, so
nothing here ever refuses an import for want of an answer.
nodestrkeyword-onlydefault NoneThe data node these paths are on. Detection then runs over there, on that machine's own disk, and the sample it registers addresses the files rather than reading them from here.
replacestrkeyword-onlydefault NoneThe name of an existing sample this is a re-import of. Its layers are replaced in place instead of a second sample being made beside it.
waitboolkeyword-onlydefault FalseBlock until every derived artefact (transcript
tiles, the mask pyramid) has been built. Defaults to False,
which returns as soon as the record exists -- what the viewer
wants. Pass True in a script whose next line reads the result.
Returns
strThe sample's (project's) name.
Raises
ExceptionIf nothing at these paths is something Plexora can
register, or if name collides with an existing sample that
is not the one named in replace.
Examples
import plexora
name = plexora.import_sample("slide.ome.tif", "cells.csv", wait=True)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.
Related
create_project
Register one project and return its name.
add_layers
Add one or more files to a sample that is already registered.
configure_project
Answer questions about a project that is already registered.