Skip to content

Dataset

Central object for accessing one NimbusImage dataset.

nimbusimage.dataset.Dataset

Access point for a single NimbusImage dataset.

Metadata is fetched lazily on first access to any property.

pixel_size property

Physical size of one pixel, or None when it is unknown.

Read the way the app reads it: the caller's view scales over the dataset's configuration scales (collections.scales), which the app seeds from the file's calibration and the user can edit. Without a configuration, the file's own mm_x. What the app stores for "no calibration" counts as unknown: 0 or null (getDatasetScales on a file without mm_x) or its 1 m placeholder.

upload(paths)

Upload image files into this dataset's folder.

Call before :meth:configure. Uploading does not by itself make a usable dataset -- the files are just items in a folder until they are configured into a multi-source image.

Parameters:

Name Type Description Default
paths

A file path, a directory, or an iterable of paths. Directories are not recursed into; a subdirectory raises rather than being skipped, so a partial upload can't look like a complete one. Dotfiles are ignored.

 required

Returns:

Type Description
list[str]

The ids of the created items, ordered as uploaded.

Raises:

Type Description
ValueError

a directory contains a subdirectory.
RuntimeError

an upload failed AND the files already uploaded by this call could not be removed again (the message names them). Any other upload failure propagates unchanged, with the folder left as it was found.

configure(*, assignments=None, transcode=None, split_rgb_bands=True, enable_compositing=False, create_view=True, dry_run=False)

Configure the uploaded files as one multi-dimensional image.

This is the API equivalent of the web UI's dataset-configuration screen: it works out which filename tokens and file metadata map to XY / Z / Time / Channel, writes the multi-source configuration, and (unless every file is .nd2 and at most 16 tiles are composited) schedules a transcode job.

Start with dry_run=True. It computes and returns everything without writing, including validation_error and variables. A real run turns that error into an exception, so the dry run is the only way to see the variable list you need in order to fix it::

plan = ds.configure(dry_run=True)
if not plan.is_valid:
    print(plan.validation_error)
    print(plan.unassigned_variables)

Parameters:

Name Type Description Default
assignments dict | None

Per-dimension overrides, {dim: {"source", "guess"} | None} for dims XY/Z/T/C. Copy source/guess from a variable returned by a dry run; None leaves a dimension unassigned, and omitted dimensions keep their default.

 None
transcode bool | None

Convert to a single tiled TIFF. Defaults to the same rule the UI uses: on unless every file is .nd2, and also on when compositing more than 16 tiles (stage positions, from many files or one multi-position file; a long job for thousands of tiles; pass False to skip).

 None
split_rgb_bands bool

Split an RGB image into three channels.

 True
enable_compositing bool

Lay out ND2 files by their stage positions instead of as separate XY positions. Takes effect for one multi-position ND2, or for a folder of ND2 files (e.g. one per tile) of the same tile size once the variable that tells the files apart is assigned to XY -- the filename parser often guesses a bare tile number as C, so dry-run first and pass an assignments override that moves it to XY. result.compositing says whether it applies (XY then collapses to one position). A request that cannot be honored -- files that cannot composite, or two tiles at the same stage position -- shows up as the dry run's validation_error and makes a real run fail rather than fall back to separate positions. result.compositing_check explains a duplicate or warns about a sparse layout, and counts the composited tiles (tileCount). Compositing more than 16 tiles transcodes by default.

 False
create_view bool

Also create the collection and dataset view the web UI needs. On by default: without them the dataset is readable through this API but has nothing to open in the browser, and client.list_datasets() -- which enumerates dataset views -- will not show it.

 True
dry_run bool

Compute without writing anything.

 False

Returns:

Type Description
MultiSourceConfiguration

MultiSourceConfiguration. When transcoding, job_id is the
MultiSourceConfiguration

conversion job -- pass it to client.job(...) to wait on it.
MultiSourceConfiguration

With create_view, view_id is set and ds.open()
MultiSourceConfiguration

works.

Raises:

Type Description
HttpError

400 if the configuration is invalid (unassigned variables, mixed pixel types across sources, an item with zero or several files, or filenames whose parts do not line up -- the web UI cannot configure that folder either), 409 if the dataset is already configured.
Note

Unlike the web UI, this does not warm the tile/histogram caches, so the first open of a large dataset is slower.

When transcode is on this returns as soon as the job is queued, so checking it is the caller's job::

result = ds.configure()
if result.job_id and not client.job(result.job_id).wait():
    ...  # the dataset is configured but its image is broken

A failed transcode leaves the dataset configured with an unusable image, and configuring again raises 409 because the configuration item exists. Recovering means deleting that item (result.item_id) or starting from a new dataset.

info_url()

URL for the dataset info page.

view_url(xy=None, z=None, time=None, layer=None, unroll_xy=None, unroll_z=None, unroll_t=None)

URL for the dataset image viewer.

Parameters:

Name Type Description Default
xy int | None

XY position to navigate to.

 None
z int | None

Z-slice to navigate to.

 None
time int | None

Time point to navigate to.

 None
layer str | None

Layer mode ('single', 'multiple', 'unroll').

 None
unroll_xy bool | None

Unroll XY dimension.

 None
unroll_z bool | None

Unroll Z dimension.

 None
unroll_t bool | None

Unroll time dimension.

 None

Returns:

Type Description
str

URL string for the image viewer.

Raises:

Type Description
ValueError

If no dataset view exists for this dataset.

configuration_url()

URL for this dataset's configuration page.

open(xy=None, z=None, time=None, **kwargs)

Open the dataset viewer in the default browser.

Parameters:

Name Type Description Default
xy, z, time

Navigate to this position.

 required
**kwargs

Additional args passed to view_url().

 {}

Returns:

Type Description
str

The URL that was opened.