v0.2.0

Moves the project from a validator prototype towards a usable open-source data-quality tool.

Installable without a clone

The package builds as a wheel and an sdist through uv build, and both install into an empty environment where sci-contract runs from PATH with no repository in sight. PyPI metadata is complete — authors, keywords, classifiers, project URLs, the README as the long description — and py.typed ships beside the modules.

git clone https://github.com/ronfinn/scientific-data-contracts
uv tool install ./scientific-data-contracts
sci-contract --version

Not yet on PyPI. The name is unregistered, and the package is ready for whenever it is.

Realistic contract examples

examples/contracts/ holds three contracts written against real analysis situations rather than the committed toy datasets:

• a processed single-cell RNA-seq AnnData object;
• an imaging-based spatial dataset, Xenium-like;
• a sequencing-based spatial dataset, Visium/Visium HD-like.

The two spatial contracts are named after the assays that shape them, and that is where the resemblance stops. This tool validates a SpatialData store that already exists — it does not ingest a vendor bundle, and the element names in those files are the ones a converter chose rather than standard ones. Their README says what to change when adapting them.

Two new data-quality rules

unique names metadata columns whose values must not repeat. This is not the obs_names uniqueness the validator already always checks; it is a contract rule about an ordinary column.

obs:
  required: [sample_id, cell_barcode]
  unique:   [cell_barcode]

numeric_range bounds a column inclusively, with either end optional:

obs:
  numeric_range:
    pct_counts_mt:
      min: 0
      max: 100

Both follow declare-before-constrain, and both leave missing values to non_null rather than reporting one problem twice. Six issue codes join the report — duplicate_obs_values, out_of_range_obs_value, non_numeric_obs_value and their var counterparts — under an unchanged schema_version: 1.

A range states what a measurement can physically be, not which cells are good enough to keep. Deciding that is an analysis decision, and a contract that encoded one would fail datasets that are perfectly well-formed.

Nextflow

The report file name is now a --report parameter, so a pipeline validating several datasets no longer overwrites one file. Verified end to end against both committed examples and against a contract the dataset fails, which publishes the report, skips the analysis step and exits 1.

Compatibility

Contracts written for v0.1.0 remain valid and behave identically. Every new contract section is optional, and every new report field is additive.

v0.1.0

First useful public release of sci-contract.

• AnnData contracts — required obs/var columns, non-null and allowed-value constraints, unique observation and variable identifiers.
• SpatialData contracts — required elements by collection and required coordinate systems, plus table-to-region links, opt-in instance-to-region integrity, and per-element coordinate-system registrations.
• Provenance — required reproducibility fields read from uns["provenance"].
• Reports — a structured text report and a JSON report with a stable schema_version and stable issue codes.
• Nextflow example — examples/nextflow/ runs the validation as a pipeline quality gate: the report is published either way, and the workflow fails when the dataset does not satisfy its contract.

The contract format is specified in docs/contract-format.md and the report format in docs/report-format.md, each with its current limitations.