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.

`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) 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`).	`None`
`split_rgb_bands`	`bool`	Split an RGB image into three channels.	`True`
`enable_compositing`	`bool`	Lay out a single multi-position ND2 by stage coordinates instead of as separate XY positions. Only takes effect for a single source with ND2 frame metadata -- check `result.compositing` for what actually happened, and note that when it applies, XY collapses to one position.	`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.