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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.