Datasets

Registry operations are explicitly network-capable. Dataset loading validates the generic measurement manifest and returns the same model and measurement objects used elsewhere in the API. See the dataset guide for the on-disk contract and provenance policy.

DatasetRegistryEntry

Metadata and local-cache state for one registered dataset version.

id property

id: str

Return the stable registry identifier.

version property

version: str

Return the source-controlled dataset version.

title property

title: str

Return the human-readable dataset title.

description property

description: str

Return the registry description of the data and acquisition.

format_version property

format_version: int

Return the measurement-manifest format version.

archive_url property

archive_url: str

Return the URL of the downloadable archive.

archive_sha256 property

archive_sha256: str

Return the expected lowercase SHA-256 archive digest.

archive_size_bytes property

archive_size_bytes: int

Return the expected archive size in bytes.

license_spdx property

license_spdx: str

Return the dataset license as an SPDX identifier.

license_url property

license_url: str

Return the URL of the dataset license text.

citation_doi property

citation_doi: str

Return the dataset citation DOI recorded by the registry.

citation_text property

citation_text: str

Return the preferred human-readable citation.

source_url property

source_url: str

Return the authoritative source or landing-page URL.

source_description property

source_description: str

Return provenance details supplied by the dataset publisher.

tags property

tags: list[str]

Return searchable registry tags.

cached property

cached: bool

Return whether a verified local copy is available.

cache_path property

cache_path: Path | None

Return the verified local dataset directory, if cached.

DatasetRegistry

DatasetRegistry(
    *,
    registry_url: str | None = None,
    cache_dir: Path | None = None,
)

Discover, verify, cache, and open datasets from a JSON registry.

Parameters:

Name	Type	Description	Default
registry_url	str | None	Registry JSON URL. None selects the packaged default registry.	None
cache_dir	Path | None	Managed cache directory. None selects the platform-specific default.	None

Notes

Listing may fetch registry metadata. Download and open may access the network; an already cached dataset is verified before use.

registry_url property

registry_url: str

Return the configured registry URL.

cache_dir property

cache_dir: Path

Return the managed local cache directory.

list

list() -> list[DatasetRegistryEntry]

Return registry entries annotated with their local cache state.

download

download(id: str) -> Path

Download, checksum-verify, extract, and return one dataset directory.

download_all

download_all() -> list[Path]

Download and verify every registry entry, returning local directories.

open

open(id: str) -> Dataset

Open a cached dataset, downloading it first when necessary.

clean

clean(id: str) -> bool

Remove one cached dataset and return whether it existed.

clean_all

clean_all() -> int

Remove all managed datasets and return the number removed.

Dataset

Loaded measurements, models, optional truth, and provenance.

Dataset loading validates the manifest and array shapes before returning this object. Arrays are exposed using the same conventions as the core API.

path property

path: Path | None

Return the local dataset directory, if it originated on disk.

measurements property

measurements: MeasurementStack

Return the resident measured-intensity stack.

true_model property

true_model: ImagePlaneModel

Return the acquisition model, including known simulated errors.

reconstruction_model property

reconstruction_model: ImagePlaneModel

Return the model intended for reconstruction.

ground_truth_object property

ground_truth_object: ComplexArray | None

Return the complex ground-truth field when supplied by the dataset.

valid_object_mask property

valid_object_mask: MaskArray | None

Return the optional valid-pixel mask for object-space evaluation.

provenance property

provenance: Mapping[str, str]

Return immutable acquisition and source provenance fields.

measurement_units property

measurement_units: str | None

Return the declared units of measured intensities, if present.

reconstruction_problem

reconstruction_problem() -> ReconstructionProblem

Build a validated problem from the dataset measurements and model.

open_dataset

open_dataset(
    id: str,
    *,
    registry_url: str | None = None,
    cache_dir: Path | None = None,
) -> Dataset

Open a registered dataset using a temporary DatasetRegistry.

Parameters are equivalent to DatasetRegistry; id is the exact registry identifier. The dataset is downloaded if no verified cached copy is available.