Skip to main content

vcti-measure

Domain-agnostic measurement model — stable identities, canonical units, and one self-describing JSON document per run

Declare a quantity by name and the readings it yields. Declare what to measure it on, and what to read the numbers against. This package obtains the readings — or validates the ones you already have — and turns them into one JSON document per run.

It measures whatever can be read: a person's blood pressure, a city's air, a furnace, a piece of executing code. What is worth measuring, and what can measure it, belong to the domain rather than to the model, so this package declares no measurements, provides no instruments and defines no units. It draws nothing either — reports are built from the document, elsewhere.

Installation

pip install vcti-measure

In requirements.txt

vcti-measure>=1.1.0

In pyproject.toml dependencies

dependencies = [
    "vcti-measure>=1.1.0",
]

Quick Start

Declare the quantity you want, with the readings it yields and the units they are recorded in:

from vcti.measure.core import FactorDecl, Measurement, MetricDecl

BLOOD_PRESSURE = Measurement(
    name="blood-pressure",
    summary="Arterial pressure at the upper arm.",
    metrics={
        "systolic": MetricDecl(unit="mmHg"),
        "diastolic": MetricDecl(unit="mmHg"),
    },
    factors={"arm": FactorDecl(values=("left", "right"), required=True)},
)

Declare what to measure it on. A manifest is data, at module scope, holding no presentation — under a namespace nobody else would choose, so your results never collide with someone else's:

from vcti.measure.core import Axis, Manifest, Study, Target, Unit

MANIFEST = Manifest(
    "example.cardiology",
    [Study(
        "medication-follow-up",
        summary="Follow arterial pressure after a medication change.",
        subjects={"patient-8841": patient_record(8841)},
        axes=[Axis(name="posture", values=("seated", "standing"))],
        measurements=[BLOOD_PRESSURE],
        targets={"blood-pressure.systolic": Target(at_most=120)},
    )],
    units=[Unit(name="mmHg")],
)

Run it, saying what the run was taken under:

from vcti.measure.core import ProgressSummary, Registry, run

summary = ProgressSummary(units=MANIFEST.units)
artifact = run(
    MANIFEST,
    Registry([]),  # the instruments this run may use
    conditions={"site": {"clinic": "north", "protocol_revision": "3"}},
    progress=summary,
)
summary.finish()

document = artifact.model_dump_json(indent=2)

That document is the whole output: the declaration it ran, the units it uses, the conditions, and every observation. Where it goes is yours — this package touches no storage. Rendering it is a separate step, in a separate package.

Nothing above measures anything yet. The registry is empty, so no instrument provides blood-pressure, and every observation comes back marked unavailable carrying the reason — which is the designed behaviour, not a failure. The artifact is still complete and still valid. Register an instrument that provides the measurement and the same manifest produces numbers.


Key API surface

Everything below is importable from vcti.measure.core.

What you are doing What you use
Declaring a quantity Measurement, MetricDecl, FactorDecl
Declaring what to measure it on Study, Item, Axis, Derivation, Description
Reading numbers against something Target
Publishing a set of studies Manifest, Unit
Providing a measurement Instrument, Reading, Registry, Selection
Obtaining readings run(), ProgressSummary
Validating readings you already hold assemble(), Observation, MetricValue, FactorValue
Reading a document back load_artifact(), or parse_artifact() and validate_artifact() separately
Working with a document Artifact, Status, json_schema(), format_value()
Naming a reading without measuring ObservationIdentity, MetricIdentity, SeriesIdentity
Handling a refusal MeasureError and its three stages

An observation carries one of four statuses — measured, unavailable, failed or skipped — and the last three carry a reason. A declaration is refused as a ManifestError, a set of observations as an AssemblyError, and an unreadable or invalid document as an ArtifactError; all three descend from MeasureError.

The full reference, generated from the source, is published in the unified VCollab documentation.


What this package is not

It compares nothing. What it supplies is what a comparison needs to be possible: a stable name for what was measured, a canonical unit, and a record self-describing enough to be read years later. Which comparison is worth making — against a target, against something measured beside it, along an axis, across runs — belongs to whoever is asking.

A few things worth knowing, each explained in the design document:

  • Preparation receives the item handle and the coordinate, never the instrument, and sits outside the measured interval.
  • Subjects are followed over time; references exist only to give a subject's number meaning.
  • Each measurement is taken separately, with its own preparation and release.
  • An attempt that produced nothing still appears, carrying a status and a reason. Nothing silently disappears, because an observation missing from the document is indistinguishable from one nobody asked for.
  • Metric names, units, targets and the points a study declines are all in the declaration, so a manifest can be checked with no instrument installed at all.
  • Which instrument answered is provenance, never identity, so replacing a device does not orphan the readings it produced.

Dependencies

pydantic. The artifact's contract is defined as pydantic models, so the JSON Schema published with each format version is generated from the same definitions the implementation validates against — the two cannot drift.


Documentation

If you want to… Read
See practical, real-world usage docs/patterns.md
Understand the architecture and design decisions docs/design.md
Navigate and understand the source docs/source-guide.md
Declare a measurement or write an instrument docs/extending.md

Metadata

Release files for vcti-measure 1.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for vcti-measure 1.1.0
File Size Uploaded Provenance Actions
vcti_measure-1.1.0.tar.gz 85.3 kB With provenance Details for vcti_measure-1.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for vcti-measure 1.1.0
File Interpreter ABI Platform Actions
vcti_measure-1.1.0-py3-none-any.whl Python 3 none any Details for vcti_measure-1.1.0-py3-none-any.whl

Total release size: 141.0 kB

Release files / vcti_measure-1.1.0.tar.gz

Download URL vcti_measure-1.1.0.tar.gz
Size 85.3 kB
Tags Source
SHA-256 checksum
How to use checksums
9faa27298f10cca95b9962d4bccd7b31af94a8b939f387c11666ef4eebe93563
BLAKE2b-256 checksum
How to use checksums
7d1841bcab0daf396f7b0eff1153254f72af6ea264ad231a7677fce49b06d10f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 3, 2026.

Transparency log

Release files / vcti_measure-1.1.0-py3-none-any.whl

Download URL vcti_measure-1.1.0-py3-none-any.whl
Size 55.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
88860ffcd07a53a23f060a9fce2265636d138cc328306b5f6945b3de6dae5705
BLAKE2b-256 checksum
How to use checksums
c7f6397599b71a1d38f9bf42767d8f9d04cc05feef337e8fe755cc72e8bdbadf
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 3, 2026.

Transparency log

Security for vcti-measure 1.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for vcti_measure-1.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 3, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page