create_dataset
Make a dataset, registering its projects if they are not there yet.
from plexora import create_datasetcreate_dataset(
name,
images=None,
projects=None,
*,
description='',
node=None,
exist_ok=False,
on_progress=None,
cancel=None,
) -> DatasetA dataset is a named group of projects -- a cohort, a TMA series, any set
of samples that belong together. images/projects register each entry
the same way create_project would, then put them all in the dataset.
Everything is checked before anything is registered: the dataset name, every spec, every path -- including a path on a data node, which is checked by asking the node about it rather than changing anything there. A cohort that would fail on its last slide because of a typo fails before the first one has spent minutes building a pyramid.
When to use
Use this to register a whole cohort in one call instead of looping
over create_project. Use create_project on its own for a single
sample, or when each one needs its own answers worked out one at a
time.
Parameters
namestrrequiredThe dataset's name.
imageslistdefault NoneImage paths -- the short form. Each becomes
a project named after its file, exactly as calling
create_project(image) would for each one.
projectslistdefault NoneProject specs -- the long form. Each entry
is a dict of any of PROJECT_SPEC_KEYS (or a bare path, meaning
the same as an entry of images). Pass images or projects,
never both; both default to nothing, which makes an empty
dataset -- a real, useful thing, since projects can be added to
it later with Dataset.add.
descriptionstrkeyword-onlydefault ''A note about the dataset.
nodestrkeyword-onlydefault NonePut every path in this batch on this data node,
unless an entry names its own node, or opts a single file out
of the default with {"path": ..., "node": None}.
exist_okboolkeyword-onlydefault FalseIf a dataset named name already exists,
add to it instead of raising. This is about the dataset, not its
projects -- a spec whose own project already exists is refused
the same way create_project refuses it unless that spec sets
its own exist_ok: True.
on_progresscallablekeyword-onlydefault NoneCalled as on_progress(index, total, spec) before each project is registered, and once more
with index == total when they all have.
cancelthreading.Eventkeyword-onlydefault NoneChecked between projects. Once
set, no further project is started and the dataset is returned
holding what registered so far -- nothing is rolled back, for the
reason DatasetCreateError gives.
Returns
DatasetThe dataset, holding every project this call registered or
adopted, plus whatever was already in it when exist_ok=True.
Raises
ValueErrorIf both images and projects are given, if the dataset
name or a spec is invalid, or if a path -- local or on a data
node -- cannot be found.
DatasetCreateErrorIf registering one of the projects fails. What registered before the failure is kept and assigned to the dataset rather than rolled back -- see that class.
Examples
import plexora
cohort = plexora.create_dataset(
"Melanoma Cohort", images=["slide.ome.tif", "slide2.ome.tif"])
print(cohort.name, list(cohort))How is this different?
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
Dataset
A named group of projects, and a handle for changing that group.
list_datasets
List every dataset, sorted by name.
dataset
Get one dataset, by name or by id.
create_project
Register one project and return its name.