vector-mtrl API reference

This document lists the public surface of the core: the Mtrl routes and their common call shapes, the stable typed imports, the exact package-root export list, the operation registry names, the format-feature gate, the scientific assertion module, the machine-learning dataset module, the exports, and the archive safety contract. The Call shapes for common routes section states the exact signature, commit status, required extras, and errors of the twenty-nine most used symbols, and the test suite checks those signatures against the source. Start with the tutorial path and the how-to guides.

Public routes

Use these Mtrl routes:

• Start a first analysis with the Sample facade: Sample(sample_id) records structured arrays or DataFrames, sample.transform() runs your own function, and sample.records lists the committed results as RecordedData handles. sample.core returns the Mtrl container behind the sample, so every route below stays available. Sample.record, Sample.transform, Sample.correct, Sample.aggregate and Sample.ingest return RecordedData, which exposes .ref, .name, .to_numpy() and .to_pandas().
• Read verification facts through the facade with sample.verify(), export one committed result with sample.export(result, path), and record or read scientific claims with sample.claim() and sample.claims().
• Create and add data with Mtrl.add() and Mtrl.add_checkpoint().
• Read instrument data with Mtrl.load_instrument_file(loader=...), passing an object you supply that implements the InstrumentFileLoader protocol. The core ships no instrument parser, so the loader comes from your own code or from an authorised suite distribution, and Sample.ingest() is the facade route to the same call.
• Change data with Mtrl.transform(), Mtrl.aggregate(), Mtrl.correct_checkpoint(), and Mtrl.replace_checkpoint().
• Read alignment facts with Mtrl.alignment_report().
• Read the replay plan with Mtrl.replay_plan() and the required operations with Mtrl.capability_view(). Both are read-only and execute no operation.
• Rerun a committed chain with Mtrl.rerun(). It resolves each step only through the local registry, commits fresh identities, and reports the recorded versus fresh digests per step.
• Export the replay plan of one committed target as a standalone document with Mtrl.export_execution_plan(). The document is code-free, holds recorded facts only, and never grants execution approval.
• Change the active view with Mtrl.remove_run().
• Read active runs in commit order from the read-only Mtrl.data mapping.
• Inspect a container in a notebook without payload dumps with Mtrl.summary(); repr() returns the same bounded text.
• Build unit mappings from reported text with Unit.from_raw() and Unit.from_raw_map().
• Read the one combined checkpoint of an AggregatedRun with AggregatedRun.checkpoint.
• Find runs with Mtrl.get_run() and Mtrl.get_runs_by_name().
• Find exact record history with Mtrl.get_record(), Mtrl.get_active_record(), and Mtrl.get_revision(). Name the currently active record for a correction or replacement with Mtrl.active_ref().
• Write and read archives with Mtrl.save() and Mtrl.load().
• Check archive state with Mtrl.verify(), verify_archive(), and forensic_inspect(). Print a readable verification report with VerifyResult.format_summary() and VerifyResult.explain_issues().
• Export receipts with Mtrl.export_receipt().
• Convert data with Mtrl.to_pandas() and write one checkpoint with Mtrl.export_checkpoint().
• Attach one archive-root environment record with Mtrl.attach_environment_record().
• Attach one passive source bundle to a custom record with Mtrl.attach_source_bundle().
• Inspect attachments with the read-only Mtrl.environment_record and Mtrl.source_bundles.
• Export one bundle as inert files with Mtrl.export_source_bundle().
• Read the portable physical sample identity with Mtrl.sample_uid and set it with Mtrl.assign_sample_uid().
• Record scientific claims with Mtrl.assert_property() and Mtrl.assert_properties().
• Change claims with Mtrl.supersede_assertion() and Mtrl.retract_assertion().
• Read claims with Mtrl.get_assertion() and Mtrl.list_assertions(). Pass as_of_revision to Mtrl.list_assertions() to read the claim state at an earlier revision.
• Convert a container’s assertions to a pandas frame with Mtrl.assertions_to_pandas().
• Check external-record evidence offline with resolve_external_evidence() from mtrl.assertions.
• Prepare datasets across archives with the flat build_dataset() entry point, or spell the whole recipe in a DatasetSpec and call build_ml_dataset(); both live in mtrl.ml.
• Recap a prepared dataset as bounded text with MLDataset.summary().
• Split a dataset without group leakage with MLDataset.split_grouped().
• Expose one dataset to scikit-learn with MLDataset.to_sklearn(), to pandas with MLDataset.to_pandas(), to PyTorch with MLDataset.to_torch_dataset(), to TensorFlow with MLDataset.to_tf_dataset(), and to MLflow with MLDataset.log_to_mlflow().

Call shapes for common routes

These twenty-nine symbols carry an exact signature, a status, and a failure list. The test suite compares every signature with the supported source, so a renamed parameter or a changed default breaks the check rather than quietly misleading the reader.

Each entry states one status:

• read reads the container and its committed evidence. It adds no record and creates no revision. It may write a file or refresh verification facts.
• candidate returns a detached object that the container does not hold. Mtrl.add() commits it.
• commit commits a new record and creates exactly one revision.
• create returns a new container with its genesis revision and commits no record.

Signatures use the source parameter names, parameter kinds, and default expressions, with self and cls omitted. Every other route in Public routes above keeps its route entry and its module docstring; those routes are not signature-checked here. The internal mtrl.tables prototype is out of scope.

Constructing and committing

A successful commit creates exactly one revision, and a failed call leaves the records and the revision history unchanged.

Mtrl

def Mtrl(
    sample_id: str | None = None,
    *,
    sample_uid: str | None = None,
    registry: OperationRegistry | None = None,
) -> Mtrl: ...

Status: create — returns an empty container with its genesis revision and commits no record.

Parameters:

• sample_id: the human-facing sample label, or None when it is unknown.
• sample_uid: the portable UUIDv7 physical sample identity, validated at construction.
• registry: the operation registry. The default is a fresh built-in registry with no suite operations.

Returns: a new container whose data mapping is empty.

Raises: InvalidRecordRevisionError when sample_uid is not a canonical UUIDv7 string.

Extras: none.

Mtrl.add

def add(run: InstrumentRun) -> None: ...

Status: commit — one successful call creates exactly one revision.

Parameters:

• run: the instrument run to add. The commit boundary detaches it, keeps its run_id, and generates a fresh record_id for every checkpoint it holds.

Returns: None. Read the committed run through Mtrl.data or Mtrl.get_run().

Raises: DuplicateRunError, DuplicateCheckpointError, UnsupportedCommittedValueError. A refusal adds no record and no revision; the selection and data errors guide shows the recovery for unsupported data.

Extras: none.

Mtrl.add_checkpoint

def add_checkpoint(run_id: str, checkpoint: MaterialData) -> InstrumentRun: ...

Status: commit — one successful call creates exactly one revision.

Parameters:

• run_id: the identifier of an active run in this container.
• checkpoint: the checkpoint to commit. Its checkpoint_id may not collide with any active or historical record, and its record_id is generated at the commit boundary.

Returns: the run the checkpoint was added to, including the new checkpoint.

Raises: UnknownRunError, DuplicateCheckpointError, UnsupportedCommittedValueError.

Extras: none.

Selecting runs and records

Selection reads only. The optional-return methods keep returning None or an empty list, and only Mtrl.active_ref() raises for a missing target. The selection and data errors guide shows both behaviours in runnable examples.

Mtrl.get_run

def get_run(run_id: str) -> InstrumentRun | None: ...

Status: read — searches the active runs of this container.

Parameters:

• run_id: the run identifier to look up.

Returns: the matching run, or None for a miss. Probe the result, or use Mtrl.active_ref() when the record is required.

Raises: none.

Extras: none.

Mtrl.get_runs_by_name

def get_runs_by_name(run_name: str) -> list[InstrumentRun]: ...

Status: read — searches the active runs of this container.

Parameters:

• run_name: the run name to look up. Several runs may share one name.

Returns: every matching run in the order they were added, or an empty list. Select the result you want explicitly; the call never guesses between repeat measurements.

Raises: none.

Extras: none.

Mtrl.get_record

def get_record(record_id: str) -> MaterialData | None: ...

Status: read — searches active and historical records.

Parameters:

• record_id: the immutable record version identifier.

Returns: the matching committed record, or None. A corrected, replaced, or removed record stays reachable here after it leaves the active view.

Raises: none.

Extras: none.

Mtrl.get_active_record

def get_active_record(checkpoint_id: str) -> MaterialData | None: ...

Status: read — searches the active runs of this container.

Parameters:

• checkpoint_id: the logical checkpoint identifier.

Returns: the record that is active for that logical identity, or None.

Raises: none.

Extras: none.

Mtrl.active_ref

def active_ref(checkpoint_id: str, *, run_id: str | None = None) -> RecordRef: ...

Status: read — resolves the exact target that a correction or replacement asks for.

Parameters:

• checkpoint_id: the logical checkpoint identifier.
• run_id: scope the search to one active run when given, otherwise search every run.

Returns: the RecordRef pairing the stable checkpoint_id with the record_id of the currently active record. Pass this ref, not a remembered one, to Mtrl.correct_checkpoint() or Mtrl.replace_checkpoint().

Raises: UnknownRunError when run_id names no active run, and UnknownCheckpointError when no active record carries the checkpoint identifier.

Extras: none.

Inspecting in a notebook

A summary reads stored state and renders bounded text. It runs no verification, reads no archive, and executes no operation.

Mtrl.summary

def summary(*, limit: int = DEFAULT_SUMMARY_LIMIT) -> str: ...

Status: read — renders bounded text from the container’s stored state.

Parameters:

• limit: the maximum number of listed runs and preview entries. The default is the module constant DEFAULT_SUMMARY_LIMIT, which is 10, and the largest accepted value is 50.

Returns: a multi-line text summary holding the sample and archive identities, the format status, real totals for runs, active checkpoints, stored records, revisions, and sources, a bounded run listing, and the stored verification facts. repr(container) returns the same text, and _repr_html_ returns it in one escaped pre block.

Raises: ValueError when limit is not an integer from 1 to 50.

Extras: none.

Changing data

Units travel with the checkpoint. A committed units mapping is read-only, units=None on a candidate declares that the values carry no unit contract and MTRL records none, and Mtrl.transform(units=...) replaces the mapping for its result. An aggregation requires exactly equal unit mappings across its members.

Mtrl.transform

def transform(
    run_id: str,
    checkpoint_id: str,
    transformation: str | Callable[..., Any],
    parameters: dict[str, Any] | None = None,
    checkpoint_name: str | None = None,
    units: dict[str, Unit] | None = None,
) -> MaterialData: ...

Status: commit — commits the result to the source checkpoint’s run and creates exactly one revision.

Parameters:

• run_id: the identifier of the run holding the source checkpoint.
• checkpoint_id: the identifier of the source checkpoint.
• transformation: a qualified operation name or short alias in this container’s registry, or a custom callable that takes the checkpoint content as its first argument.
• parameters: keyword parameters for the transformation. Role-using operations require the roles their schema declares: x_field and y_field for the resample operations, y_field for scale and offset, and nothing for identity. Provenance records the supplied values and any effective defaults; omitted arguments stay omitted from the call.
• checkpoint_name: the name of the new checkpoint. The default is the source checkpoint’s own name.
• units: the unit mapping for the result, replacing the source units.

Returns: the new transformed checkpoint, already added to the run and committed.

Raises: UnknownRunError, UnknownCheckpointError, InvalidTransformationError, DuplicateCheckpointError.

Extras: none for the core operations. vector-mtrl[interp] supplies SciPy for resample_pchip and resample_cubic.

A custom callable’s provenance is recorded, but its step is not replayable: a replay plan marks it ineligible and Mtrl.rerun() raises ReplayIneligibleError rather than executing a local function. Registering an operation is the reviewed route for repeatable work.

Mtrl.aggregate

def aggregate(
    members: Sequence[RunCheckpointPair | tuple[str, str]],
    run_name: str,
    method: AggregationMethod | str = AggregationMethod.MEAN,
    checkpoint_name: str | None = None,
    *,
    parameters: Mapping[str, Any] | None = None,
) -> AggregatedRun: ...

Status: candidate — reads committed members, stores nothing, and creates no revision. Mtrl.add() commits the returned run and creates exactly one revision.

Parameters:

• members: the checkpoints to combine, as RunCheckpointPair values or (run_id, checkpoint_id) pairs. The lineage records one exact ref per member in this order.
• run_name: the name of the new run. The run generates its own run_id.
• method: a registered aggregation. mean and median are built in, and AggregationMethod.MEAN is the default.
• checkpoint_name: the name of the new checkpoint. The default is "aggregated".
• parameters: the required field roles for the selected aggregation. mean and median read x_field and y_field, which the caller must supply: the default catalogue declares no field-name default. A call that omits either fails before the adapter runs.

Returns: an AggregatedRun with one aggregated checkpoint and the frozen members and method. It is detached until Mtrl.add().

Raises: InvalidAggregationError for an empty member list, an unknown member, an unregistered method, an invalid override, or fields that cannot be aligned; MissingOptionalDependencyError for a declared dependency this installation lacks; IntegrityMismatchError when committed evidence changed.

Extras: none for mean and median.

Mtrl.correct_checkpoint

def correct_checkpoint(
    run_id: str,
    target: RecordRef,
    replacement: MaterialData,
) -> MaterialData: ...

Status: commit — one successful call creates exactly one revision.

Parameters:

• run_id: the identifier of the run holding the checkpoint to correct.
• target: the exact RecordRef of the active record. Both identifiers must match the currently active record.
• replacement: the new content. Its checkpoint_id and record_id are overridden: a correction keeps the prior checkpoint_id and generates a new record_id.

Returns: the newly committed corrected record. It links to the prior record with a correction-of relationship, and descendants still reference the prior record_id.

Raises: UnknownRunError, UnknownCheckpointError, InvalidRecordRevisionError for a mismatched, stale, historical, or removed target, and UnsupportedCommittedValueError.

Extras: none.

Mtrl.replace_checkpoint

def replace_checkpoint(
    run_id: str,
    target: RecordRef,
    replacement: MaterialData,
) -> MaterialData: ...

Status: commit — one successful call creates exactly one revision.

Parameters:

• run_id: the identifier of the run holding the checkpoint to replace.
• target: the exact RecordRef of the active record. Both identifiers must match the currently active record.
• replacement: the new content. Both a new checkpoint_id and a new record_id are generated at the commit boundary.

Returns: the newly committed replacement record. It links to the replaced record with a replacement-of relationship; the replaced record and payload stay reachable through Mtrl.get_record().

Raises: UnknownRunError, UnknownCheckpointError, InvalidRecordRevisionError for a mismatched, stale, historical, or removed target, DuplicateCheckpointError, and UnsupportedCommittedValueError.

Extras: none.

Frames, files, and archives

Mtrl.to_pandas() converts the whole container, Mtrl.export_checkpoint() writes one checkpoint, and MaterialData.to_pandas() converts exactly one. A frame is a detached analysis copy; it is not a checkpoint and carries no record identity. A container or run conversion is a strict projection by default: it raises rather than return a frame with a checkpoint missing.

Mtrl.to_pandas

def to_pandas(*, strict: bool = True) -> pd.DataFrame: ...

Status: read — returns a detached frame and creates no revision.

Parameters:

• strict: when True (the default), the conversion refuses to return a partial frame. When False, it warns and returns the rows it can convert.

Returns: one stacked DataFrame for every checkpoint of every active run, in the layout that runs_to_frame in mtrl.frames describes. With strict=False, one CheckpointExportWarning names each checkpoint left out, and the frame carries the rest.

Raises: UnexportableCheckpointError when strict is True and any checkpoint holds no table. The error lists every failed checkpoint as its run identifier, its checkpoint identifier, and the reason, in frame order, before any rows are combined. A checkpoint is never dropped silently. MissingOptionalDependencyError when the vector-mtrl[tabular] extra is absent.

Extras: vector-mtrl[tabular].

Mtrl.export_checkpoint

def export_checkpoint(run_id: str, checkpoint_id: str, filename: str | Path) -> Path: ...

Status: read — writes one file and creates no revision.

Parameters:

• run_id: the identifier of the run holding the checkpoint.
• checkpoint_id: the identifier of the checkpoint to write.
• filename: the destination. The suffix selects the registered writer: .csv is available in the base install, and .xlsx needs the vector-mtrl[excel] extra.

Returns: the path written. The write is staged, so a failed write preserves an existing destination.

Raises: UnknownRunError, UnknownCheckpointError, UnsupportedExportFormatError, UnexportableCheckpointError when the checkpoint holds no table, and MissingOptionalDependencyError for an absent writer extra.

Extras: none for CSV; vector-mtrl[excel] for .xlsx.

Mtrl.save

def save(
    filename: str | Path,
    *,
    integrity: bool = True,
    limits: ArchiveLimits | None = None,
) -> Path: ...

Status: read — the records and the revision history do not change and no revision is created. A successful save adopts each supplied bound that is higher and records the saved archive path.

Parameters:

• filename: the destination. The written path always ends in .mtrl.
• integrity: must stay True. False is rejected before any write starts, because the current format always requires integrity.
• limits: the archive limits for this save, or None to read the limits the container stores.

Returns: the path the .mtrl file was written to.

Raises: IntegrityRequiredError when integrity is False, SourceEvidenceRemovalError for missing, changed, or moved source inventory evidence, and IntegrityMismatchError when retained source bytes disagree with their recorded digest or length. The write also enforces the format-feature and archive-limit contract described above.

Extras: none.

Mtrl.load

def load(
    filename: str | Path,
    *,
    receipt: Receipt | None = None,
    policy: VerifyPolicy = VerifyPolicy(),
    limits: ArchiveLimits = ArchiveLimits(),
    registry: OperationRegistry | None = None,
) -> Mtrl: ...

Status: read — returns a new container and creates no revision.

Parameters:

• filename: the .mtrl archive to read.
• receipt: an optional external receipt for anchor verification.
• policy: the verification policy. require_full_coverage defaults to True, so a partial archive is rejected unless the policy allows it.
• limits: the archive limits for the bounded read.
• registry: the operation registry for the loaded container. The default is a fresh built-in registry, which holds no suite operations; pass a registry that registered the suite to rerun suite operations.

Returns: a new Mtrl populated from the file, including its records, revisions, and verification facts.

Raises: InvalidMtrlFileError when the suffix is not .mtrl, and MtrlFormatError when the archive content cannot be parsed or decoded. The bounded reader also fails closed for an unsupported required format feature, a limit violation, and an integrity mismatch.

Extras: none.

Mtrl.verify

def verify(
    receipt: Receipt | None = None,
    *,
    policy: VerifyPolicy = VerifyPolicy(),
    claim_refs: tuple[RecordRef, ...] | None = None,
) -> VerifyResult: ...

Status: read — returns verification facts and refreshes the stored verification state without changing records or revisions.

Parameters:

• receipt: an optional external receipt to scope the anchor check.
• policy: the verification policy for this call.
• claim_refs: exact derived claims for source-closure verification.

Returns: the current VerifyResult. A container that was never saved returns NOT_CHECKED facts rather than an error, so a notebook can call it before the first save.

Raises: AnchorMismatchError when policy.require_anchor is set and the receipt does not match, and InsufficientCoverageError, IntegrityMismatchError, or MtrlFormatError under the blocking mismatch policy.

Extras: none.

Checkpoint and run helpers

MaterialData.to_pandas

def to_pandas() -> pd.DataFrame: ...

Status: read — returns a detached frame for this one checkpoint and creates no revision.

Parameters: none.

Returns: a DataFrame with one column for each named field of the checkpoint content. One checkpoint has no partial mode: it either converts completely or raises.

Raises: UnexportableCheckpointError when the content holds no table, such as the raw instrument bytes a raw checkpoint can hold, and MissingOptionalDependencyError when the vector-mtrl[tabular] extra is absent.

Extras: vector-mtrl[tabular].

InstrumentRun.to_pandas

def to_pandas(*, strict: bool = True) -> pd.DataFrame: ...

Status: read — returns a detached frame for this one run and creates no revision.

Parameters:

• strict: the strict projection switch that Mtrl.to_pandas documents.

Returns: one stacked DataFrame for every checkpoint of the run, in the layout that runs_to_frame in mtrl.frames describes. With strict=False, one CheckpointExportWarning names each checkpoint left out.

Raises: UnexportableCheckpointError when strict is True and any checkpoint holds no table, with every failed checkpoint and its reason listed in frame order. With strict=False, the frame carries the checkpoints that convert. MissingOptionalDependencyError when the vector-mtrl[tabular] extra is absent.

Extras: vector-mtrl[tabular].

InstrumentRun.get_checkpoint

def get_checkpoint(checkpoint_id: str) -> MaterialData | None: ...

Status: read — searches the checkpoints of this one run.

Parameters:

• checkpoint_id: the checkpoint identifier to look up.

Returns: the matching checkpoint, or None.

Raises: none.

Extras: none.

Sample facade

The facade verbs keep the core commit and ownership rules: every read adds no revision, and a claim commit adds exactly one.

Sample.verify

def verify(
    receipt: Receipt | None = None,
    *,
    policy: VerifyPolicy = VerifyPolicy(),
) -> VerifyResult: ...

Status: read — returns the core verification facts and creates no revision.

Parameters:

• receipt: an optional external receipt for the anchor check. Consuming a receipt is allowed; creating one stays in Mtrl.export_receipt().
• policy: the verification policy for this call.

Returns: the same VerifyResult that Mtrl.verify() returns for the same evidence. The structural, hash, anchor, coverage, and source-closure statuses stay separate, and the facade adds no combined verdict.

Raises: the same failures as Mtrl.verify(): AnchorMismatchError when policy.require_anchor is set and the receipt does not match, and InsufficientCoverageError, IntegrityMismatchError, or MtrlFormatError under the blocking mismatch policy.

Extras: none.

Sample.export

def export(result: RecordedData, path: str | Path) -> Path: ...

Status: read — writes one file and creates no revision.

Parameters:

• result: an owned handle for the exact active version. A foreign or stale handle fails before any write.
• path: the destination. The suffix selects the same registered writer that Mtrl.export_checkpoint() uses: .csv in the base install, and .xlsx with the vector-mtrl[excel] extra.

Returns: the path written. The write is staged, so a failed write preserves an existing destination, and an unknown suffix never falls back to another format. A CSV or workbook projection is not a .mtrl archive: use Sample.save() when the result must reload as a sample.

Raises: UnknownRunError, UnknownCheckpointError, or InvalidRecordRevisionError for a foreign or stale handle before any write; then UnsupportedExportFormatError, UnexportableCheckpointError when the checkpoint holds no table, and MissingOptionalDependencyError for an absent writer extra.

Extras: none for CSV; vector-mtrl[excel] for .xlsx.

Sample.claim

def claim(
    property_id: str,
    value: Any,
    *,
    method: AssertionMethod = AssertionMethod.OPERATOR_ENTERED,
    subject: SubjectRef | None = None,
    unit: Unit | None = None,
    evidence: Sequence[EvidenceRef] = (),
    author: str | None = None,
) -> ScientificAssertion: ...

Status: commit — one successful call commits one claim version and creates exactly one revision.

Parameters:

• property_id: the namespaced lower-case property token, for example polymer.identity.
• value: the asserted value. The commit detaches and freezes it.
• method: how the value was obtained. The default records an operator entry.
• subject: the thing the claim describes. None uses the container’s own sample identity.
• unit: the unit of the value, or None.
• evidence: the evidence references that support the claim.
• author: the person or system that made the claim, or None.

Returns: the committed, immutable ScientificAssertion.

Raises: InvalidAssertionError when a field is invalid, or when subject is None and the sample has no identity. The message names assign_sample_uid; the facade never assigns an identity as a side effect, because one facade call is one core commit. Call sample.core.assign_sample_uid() first as its own committed step. SampleIdentityConflictError when an explicit sample subject does not match the container.

Extras: none.

Sample.claims

def claims(
    subject: SubjectRef | None = None,
    *,
    property_id: str | None = None,
) -> tuple[ScientificAssertion, ...]: ...

Status: read — returns the active claim heads in commit order and creates no revision.

Parameters:

• subject: keep only claims about this subject. None reads every subject.
• property_id: keep only claims about this property, or None for every property.

Returns: one tuple entry for the active, non-retracted head of each matching claim, in commit order. A retracted claim is absent, and no match returns an empty tuple.

Raises: none.

Extras: none.

Sample.summary

def summary(*, limit: int = DEFAULT_SUMMARY_LIMIT) -> str: ...

Status: read — recaps the active records and claims as bounded text and creates no revision.

Parameters:

• limit: the maximum number of active records to list, an integer from 1 to 50. The totals in the header stay real when the listing truncates.

Returns: a text recap in commit order: the sample label with active record and claim counts, then one entry per record with its shape and its declared field units. No generated identifiers, payloads, revisions or verification facts appear, so identical logical work yields identical text. str(sample) returns the same text, and the notebook HTML hook renders it escaped.

Raises: ValueError if limit is not an integer in the accepted range.

Extras: none.

Sample.history

def history(*, limit: int = DEFAULT_SUMMARY_LIMIT) -> str: ...

Status: read — prints each active record’s producing step and exact inputs, and creates no revision.

Parameters:

• limit: the maximum number of active records to list, an integer from 1 to 50. The totals in the header stay real when the listing truncates.

Returns: a deterministic adjacency-list history in commit order: the sample label with the active record total, then one entry per record with its producing step and, one hop only, its exact input versions. An active input is named with its listing index, 'name' [index]; an input that a correction or replacement superseded is marked as the original or replaced version instead. A corrected version carries its correction note, a source record states recorded values (no producing step), a truncated listing ends with (+N more records), and an empty sample prints (no records). No generated identifier and no timestamp appears, so identical committed work yields identical text.

Raises: ValueError if limit is not an integer in the accepted range.

Extras: none.

Machine-learning datasets

The flat builder is the routine route into the dataset builder, and one prepared dataset carries the same bounded recap contract as the facade views.

build_dataset

def build_dataset(
    sources: Sequence[Path | str | Mtrl | Sample | ArchiveSourceInput],
    *,
    channel: str,
    x_field: str,
    y_field: str,
    target_grid: Sequence[float],
    target: str,
    stage: str = "raw",
    mode: str = "resample-linear",
    task_type: str = "classification",
    group_by: str = "sample-uid",
    group_property: str | None = None,
    metadata_detail: str = "standard",
) -> MLDataset: ...

Status: read — assembles one dataset from the sources and creates no revision.

Parameters:

• sources: the archives to read: path objects, path strings, loaded Mtrl containers, ArchiveSourceInput items that pin as_of_revision, or Sample facades. Every source is read as of its named revision.
• channel: the name of the signal channel that the flat route builds. Required.
• x_field and y_field: the names of the coordinate field and the value field of each record. Both are required, because MTRL never guesses a field name.
• target_grid: the shared axis, as a sequence of at least two finite numbers. Required; the default resample mode interpolates every spectrum onto it.
• target: the property identifier that supplies each row’s target value. Required.
• stage: the committed checkpoint state that the channel selects from each run, as the canonical text of CheckpointStage: 'active-latest', 'raw', 'latest-processed', 'by-name', or 'by-operation'. Defaults to 'raw'.
• mode: the grid alignment mode, as the canonical text of GridAlignmentMode: 'strict', 'auto-shared-linear', 'resample-linear', 'resample-pchip', or 'resample-cubic'. Defaults to 'resample-linear'.
• task_type: 'classification' encodes the sorted class vocabulary as int64 indices, and 'regression' keeps finite float64 values. Defaults to 'classification'.
• group_by: 'sample-uid' groups rows by the portable physical sample identity, and 'property' groups them by one assertion property. Defaults to 'sample-uid'.
• group_property: the assertion property identifier for the 'property' group kind, or None. Defaults to None.
• metadata_detail: the per-row metadata detail, as the canonical text of MetadataDetailLevel: 'none', 'minimal', 'standard', or 'full-audit'. Defaults to 'standard'.

Returns: one read-only MLDataset, assembled exactly as build_ml_dataset() assembles it from one DatasetSpec. The flat call composes that specification from its keyword arguments, so the two routes produce one spec_summary and one dataset_digest for one logical dataset. The advanced route spells the channels, filters, auxiliary features, and conflict policies that the flat call leaves at their defaults.

Raises: TypeError if a mandatory keyword is missing. DatasetPreparationError if an enumeration keyword holds unknown text — the message names the received value and the valid choices — or if the composed specification is invalid. The build also raises the documented build_ml_dataset() failures: IntegrityMismatchError for one loaded source whose committed state changed, InvalidRecordRevisionError for an unknown revision, GridMismatchError for unaligned grids or disagreeing units, ConflictingAssertionError for competing target claims, and DatasetPreparationError when no sample is retained.

Extras: none.

MLDataset.summary

def summary(*, limit: int = DEFAULT_SUMMARY_LIMIT) -> str: ...

Status: read — recaps the prepared dataset as bounded text and creates no revision.

Parameters:

• limit: the maximum number of signal channels to list, an integer from 1 to 50. The totals in the header stay real when the listing truncates.

Returns: a text recap of the assembled dataset: the row, group, and channel totals, the target property with its task type and, for a classification target, the sorted class vocabulary, and one line per signal channel with its point count, coordinate field, span, alignment mode, and resample flag. It then states the auxiliary column count with its distinct feature names, the metadata detail level, the group kind, and the excluded candidate count, and closes with the canonical dataset_digest as sha256:<64 lowercase hex>. A truncated listing ends with (+N more channels). No sample identity, record identity, group key, timestamp, payload value, or source path appears. The text is deterministic except for that digest, because record identities mint per rebuilt archive, so read the digest by its format only. str(dataset) returns the same text, and the notebook HTML hook renders it escaped.

Raises: ValueError if limit is not an integer in the accepted range.

Extras: none.

Stable typed imports

Use these module paths for supporting types. Each name has one stable module import location.

Names	Import module
LoadedInstrumentFile, SourceFile	mtrl
RecordedData	mtrl.sample
ArchiveRecordRef, CheckpointId, SourceId, SourceRef	mtrl.domain
CheckpointType	mtrl.models
StructuralStatus, HashStatus, AnchorStatus, CoverageStatus	mtrl.domain
SourceClosureStatus, SourceClaimClosure, CommittedRecord, Revision	mtrl.domain
OperationAdapter, ResolvedOperation, OperationRegistrySnapshot	mtrl.processing
OperationKind, OperationCardinality, capture_table_records	mtrl.processing
AlignmentReport, MemberAlignment, AlignmentKind, AlignmentBasis	mtrl.grids
EnvironmentRecord, SourceBundle, IncompleteCaptureReason	mtrl.disclosure
ReplayPlan, ReplayStep, ReplayReport, StepComparison	mtrl.replay
RecordedNode, RecordedNodeReason, ReplayNodeState	mtrl.replay
DigestRelation, CapabilityView, OperationCapability	mtrl.replay
DistributionRequirement	mtrl.replay
ExecutionPlanDocument, ExecutionPlanStep, ExecutionPlanLimits	mtrl.replay
SubjectKind, SubjectRef, EvidenceKind, PhysicalRelationship	mtrl.assertions
EvidenceRef, AssertionMethod, AssertionStatus, AssertionDraft	mtrl.assertions
ScientificAssertion, EvidenceResolutionStatus	mtrl.assertions
EvidenceResolutionReport, resolve_external_evidence	mtrl.assertions
ArchiveSourceInput, AuxiliaryFeatureSpec, CheckpointStage, ConflictPolicy	mtrl.ml
DatasetProvenanceManifest, DatasetRecordProvenance, DatasetSpec, DatasetSplitBundle	mtrl.ml
ExcludedRecordEntry, FeatureChannelSpec, FilterSpec, GridAlignmentMode	mtrl.ml
GridAlignmentSpec, GroupByKind, GroupSpec, MLDataset	mtrl.ml
MetadataDetailLevel, MetadataSelectionSpec, PreprocessingStep, SklearnDatasetBundle	mtrl.ml
TargetSpec, TorchMapDataset, build_ml_dataset	mtrl.ml

CanonicalisationError is available from mtrl.exceptions. It is not a package-root export. TablePlan, TableResult, and evaluate_table_plan are internal prototype names, not stable package-root exports.

Exact package-root exports

mtrl.__all__ contains this ordered list. The internal table prototype and third-party modules are not part of it.

CheckpointExportWarning
AggregatedRun
AggregationMethod
DuplicateCheckpointError
DuplicateRunError
InvalidAggregationError
InvalidGridError
InstrumentRun
InvalidMtrlFileError
InvalidTransformationError
LoadedInstrumentFile
Manifest
ManifestVersionWarning
MaterialData
MetadataField
Mtrl
Unit
MtrlError
MtrlFormatError
RunCheckpointPair
SourceFile
UnexportableCheckpointError
UnknownCheckpointError
UnknownRunError
UnrecognisedFileError
UnsupportedDatasetError
UnsupportedExportFormatError
ArchiveId
RecordId
RevisionId
RecordRef
RecordedData
SourcePolicy
ArchiveLimits
ReceiptLimits
OperationRegistry
OperationDescriptor
VerifyPolicy
VerifyResult
VerifyIssue
Receipt
verify_archive
forensic_inspect
load_receipt
receipt_to_text
UnsupportedCommittedValueError
CommittedRecordMutationError
InvalidRecordRevisionError
ArchiveLimitError
IntegrityMismatchError
AnchorMismatchError
InsufficientCoverageError
ReceiptUnavailableError
IntegrityRequiredError
RegistryCollisionError
RegistryAmbiguityError
MissingLoaderError
MissingOptionalDependencyError
ReplayIneligibleError
ReplayPlanError
TableSelectionError
TablePlanError
TableDuplicateError
TableLimitError
InvalidFeatureError
validate_feature
register_supported_features
EnvironmentRecordError
SourceBundleError
Sample

Operation registry names

OperationRegistry.with_builtins() registers eight general operations:

Short name	Qualified operation
identity	mtrl.transform.identity
scale	mtrl.arithmetic.scale
offset	mtrl.arithmetic.offset
resample_linear	mtrl.resample.linear
resample_pchip	mtrl.resample.pchip
resample_cubic	mtrl.resample.cubic
mean	mtrl.aggregate.mean
median	mtrl.aggregate.median

The retired version-one recipes normalise_peak (mtrl.arithmetic.normalise-peak) and zero_at_point (mtrl.arithmetic.zero-at-point) no longer exist. No factory, keyword argument, module, or function body supplies them, and resolve reports both names as UnknownOperationError. Every field role is required, so a call that omits x_field or y_field fails before an adapter runs.

Historical archives still load and verify, because loading and verification treat recorded operation metadata as data. A replay plan reports a retired step as unregistered, and a rerun refuses it before any mutation. An archive never supplies code. The registry guide gives the registration call.

The pchip and cubic resample operations load SciPy lazily through the interp extra of the vector-mtrl distribution. Use an OperationRegistry to register trusted local adapters. MTRL writes the qualified identifier and effective parameters to provenance. Archive data cannot register or select code.

from mtrl.operations.arithmetic import normalise_to_peak, zero_at_point fails: those functions and the mtrl.operations.legacy module are gone. The read-only views mtrl.operations.base.TRANSFORMATIONS and mtrl.operations.base.DEFAULT_PARAMETERS remain, and they describe the six current transforms only.

Mtrl.aggregate() returns an AggregatedRun whose members and method are frozen. A save-load round trip reads the run back as a plain InstrumentRun; the combined checkpoint still records the method and members in its lineage.aggregation.

Format features

An archive declares format features that gate load. A feature string has the grammar <owner>.<name>/<major>: one dot-free owner label, a dot-separated name, and a canonical non-negative integer major. The owner mtrl is reserved.

Only format features gate load. An installation registers the features it supports with register_supported_features(). The core distribution registers mtrl.environment-records/1 and mtrl.source-bundles/1 at import, so the set is not empty by default. Load fails closed when an archive requires a feature that this installation does not support, and the message names the distribution that supplies it.

Save applies the same grammar and owner rules. A save rejects a feature with invalid grammar, and it rejects an mtrl-owned feature that is not registered. A save also rejects a required feature that this installation does not support, so a writer can always read the archive it writes. Operation capabilities stay advisory and never gate load.

Author disclosure

Mtrl.attach_environment_record() stores one archive-root environment record, and Mtrl.attach_source_bundle() stores one passive source bundle for a custom transformation output. Inspection returns inert values, and Mtrl.export_source_bundle() writes the bundle, its document, and the owning record’s recorded provenance facts as three files. MTRL never imports, compiles, or executes bundle content, and never resolves it through the operation registry. A bundle never shadows the mandatory output record.

Warning: source text and configuration can contain secrets. Attach only content that you have reviewed, because MTRL adds no scanner and certifies nothing as safe. An author’s lockfile_digest is claim text, never verified; the stored document’s storage digest is the MTRL fact that proves the record is unchanged.

Scientific assertions

The mtrl.assertions module supplies the assertion value types, and the Mtrl methods commit them. A scientific assertion records one typed property value about the physical sample, one run, or one exact record. A property_id is a namespaced lower-case token, for example polymer.identity.

Manifest.sample_uid holds the portable physical sample identity, and Manifest.sample_id keeps the human-facing label. Mtrl(sample_id=..., sample_uid=...) accepts the identity at construction, and Mtrl.assign_sample_uid() mints or validates one later. The identity is a UUIDv7 string and never changes sample_id.

Import these names from mtrl.assertions:

• SubjectRef with the factories SubjectRef.sample(sample_uid), SubjectRef.run(run_id), and SubjectRef.record(checkpoint_id, record_id).
• EvidenceRef with the factories EvidenceRef.for_local_record(...), EvidenceRef.for_local_source(...), and EvidenceRef.for_external_record(...).
• ArchiveRecordRef, imported from mtrl.domain, which names one exact record in a different archive with an optional expected payload digest.
• AssertionDraft, the frozen candidate that Mtrl.assert_properties() commits.
• ScientificAssertion, one frozen committed version of a claim.
• resolve_external_evidence, which checks external-record evidence offline against the archives that the caller supplies.

Each claim keeps one ClaimId across its versions, and each version keeps its own AssertionId. Mtrl.assert_property() commits one claim in one revision, and Mtrl.assert_properties() commits several drafts in one atomic revision. A failure changes nothing. Mtrl.supersede_assertion() adds a new version of a claim, and Mtrl.retract_assertion() withdraws a claim with a non-empty reason. Both keep the prior versions in the audit history. Independent claims for the same subject and property coexist, so a later claim never overwrites an earlier claim.

Mtrl.list_assertions() reads the claim heads, and as_of_revision reconstructs the claim state at an earlier revision. The frame conversion Mtrl.assertions_to_pandas() needs the vector-mtrl[tabular] extra. A container with assertions saves them in assertions.json and requires the format feature mtrl.scientific-assertions/1, which the core registers at import. ArchiveLimits.max_assertions caps the number of assertion versions, and the default is 10,000. Each commit method accepts a limits keyword, so a container above the default cap can still supersede or retract a claim.

Machine-learning datasets

The mtrl.ml package prepares training and evaluation datasets across saved .mtrl archives. It mutates no archive and commits no revision. The base install imports the module without SciPy, pandas, or any external ML framework.

Import these names from mtrl.ml:

• DatasetSpec, the full declarative specification of one dataset.
• FeatureChannelSpec, one signal channel: the checkpoint stage, the on-the-fly preprocessing steps, and the alignment.
• GridAlignmentSpec and GridAlignmentMode, which align heterogeneous spectra onto one coordinate grid. A GridAlignmentSpec requires the x_field and y_field keywords, and a FeatureChannelSpec requires the alignment keyword: MTRL never guesses a field name. The modes are STRICT, AUTO_SHARED_LINEAR, RESAMPLE_LINEAR, RESAMPLE_PCHIP, and RESAMPLE_CUBIC. The pchip and cubic modes need the vector-mtrl[interp] extra.
• MetadataSelectionSpec and MetadataDetailLevel, which select the per-row metadata detail: NONE, MINIMAL, STANDARD, or FULL_AUDIT.
• TargetSpec, which names the predicted property and the conflict policy for competing claims: FAIL, EXCLUDE_SAMPLE, or PREFER_METHOD.
• FilterSpec, which excludes duplicate source digests and runs that match declared filters.
• GroupSpec and GroupByKind, which control the leak-free grouping of the split.
• build_ml_dataset, which turns archive sources and one DatasetSpec into one read-only MLDataset.
• MLDataset, DatasetSplitBundle, DatasetProvenanceManifest, DatasetRecordProvenance, ExcludedRecordEntry, SklearnDatasetBundle, TorchMapDataset, and ArchiveSourceInput.

build_ml_dataset() accepts archive paths, path strings, loaded Mtrl containers, ArchiveSourceInput items, and mtrl.Sample facades. A facade source unwraps to its committed container, so it keeps the head-revision policy. ArchiveSourceInput pins the revision that one source reads with as_of_revision. Every excluded run records one machine-readable reason in dataset.provenance.excluded_records. MLDataset.split_grouped() partitions rows so that all rows of one group land in the same subset, and the same seed always produces the same split.

The provenance manifest holds one canonical dataset_digest with the form sha256:<64-hexadecimal-digits>. The same sources and the same specification always produce the same digest. MLDataset.summary() recaps that digest with the row, group, and channel totals as bounded text that carries no payload value and no generated identity. tracking_tags() flattens the dataset facts for an experiment tracker, and MLDataset.log_to_mlflow() logs the same mapping as tags and as parameters.

MLDataset.to_sklearn() returns one immutable bundle and needs no scikit-learn installation. MLDataset.to_pandas() needs the vector-mtrl[tabular] extra. MLDataset.to_torch_dataset(), MLDataset.to_tf_dataset(), and MLDataset.log_to_mlflow() load their frameworks lazily, so a missing framework raises MissingOptionalDependencyError with installation guidance.

Archive and data safety

MTRL reads .mtrl archives with configured bounds. It checks ZIP paths, entries, JSON, references, payloads, and integrity before it returns a normal loaded object. It does not extract archive files.

Mtrl.save() accepts a limits keyword. The save validates the written archive under the caller bounds, and a successful save adopts each supplied bound that is higher.

Archive content:

• does not install packages;
• does not import operation code;
• does not change a registry;
• does not execute stored source;
• does not change committed records directly.

Committed records and their values are immutable. Do not mutate committed records directly. Use Mtrl methods to create a new record version or change the active view.

Source bytes are retained by default. Choose digest-only source evidence before the first source commit when you must not retain those bytes. The source policy then stays fixed for that history. Each save checks retained source bytes against their recorded digest and byte length before it writes the archive.

New archives require integrity coverage. Keep a receipt outside the archive if you need to detect a complete rewrite. A receipt has no signature and needs an independent trusted channel. forensic_inspect() reports damaged archive facts, but it does not return damaged data for normal analysis.

Exports

Mtrl.to_pandas() converts every checkpoint of every active run into one detached DataFrame, and it refuses by default rather than drop a checkpoint that holds no table. strict=False returns the partial frame with one CheckpointExportWarning naming each checkpoint it left out. The conversion needs the vector-mtrl[tabular] extra. Mtrl.export_checkpoint() writes one selected checkpoint as CSV or Excel. CSV needs no optional package, and it has one data table. Excel has five sheets: data, manifest, metadata, lineage, and units. The units sheet records each field’s raw unit and QUDT terms. The .xlsx writer needs the vector-mtrl[excel] extra, and the core registers it at import. Export writes are staged so a failed write preserves an existing destination.

Optional capabilities

The interp, tabular, and excel extras of the vector-mtrl distribution supply the SciPy resample operations and the pandas and Excel conversions. Select one extra with the same install command and the extra in brackets, for example uv pip install --python .venv/bin/python "vector-mtrl[interp]". When a capability is missing, MTRL raises MissingOptionalDependencyError and names the distribution or extra that supplies it.

Install	Capability
vector-mtrl[interp]	Pchip and cubic resample with SciPy
vector-mtrl[tabular]	pandas conversion
vector-mtrl[excel]	Excel export with pandas and OpenPyXL

The core ships no instrument-file parser. Instrument input arrives through Mtrl.load_instrument_file() or Sample.ingest() with a loader that you supply, and any object whose load method matches the InstrumentFileLoader protocol shape is a loader. Reading and writing an archive needs no extra beyond the base install.

Authorised customers receive approved instrument readers as separate Vector Labs suite distributions under a separate written agreement. Each authorised suite documents its own loader in its own repository.