vector-mtrl 0.3.0__tar.gz → 0.4.2__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (155) hide show
  1. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/CHANGELOG.md +103 -0
  2. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/PKG-INFO +56 -42
  3. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/README.md +54 -41
  4. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/docs/user/concepts/05-lineage-and-the-recorded-recipe.md +6 -1
  5. vector_mtrl-0.4.2/docs/user/concepts/units-of-measure.md +62 -0
  6. vector_mtrl-0.4.2/docs/user/how-to/align-mixed-resolution-members.md +238 -0
  7. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/docs/user/how-to/anchor-verification-with-receipts.md +12 -8
  8. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/docs/user/how-to/attach-author-disclosure.md +18 -12
  9. vector_mtrl-0.4.2/docs/user/how-to/author-an-ingestion-loader.md +159 -0
  10. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/docs/user/how-to/check-external-evidence.md +13 -8
  11. vector_mtrl-0.4.2/docs/user/how-to/control-the-operation-registry.md +254 -0
  12. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/docs/user/how-to/handle-missing-extras.md +8 -6
  13. vector_mtrl-0.4.2/docs/user/how-to/handle-selection-and-data-errors.md +288 -0
  14. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/docs/user/how-to/index.md +13 -3
  15. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/docs/user/how-to/inspect-a-damaged-archive.md +12 -7
  16. vector_mtrl-0.4.2/docs/user/how-to/prepare-an-ml-dataset.md +340 -0
  17. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/docs/user/how-to/record-scientific-assertions.md +35 -20
  18. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/docs/user/how-to/replace-a-checkpoint.md +20 -9
  19. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/docs/user/how-to/replay-a-committed-chain.md +27 -7
  20. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/docs/user/how-to/resample-with-scipy.md +22 -13
  21. vector_mtrl-0.4.2/docs/user/how-to/use-scientific-python-libraries.md +220 -0
  22. vector_mtrl-0.4.2/docs/user/reference.md +1274 -0
  23. vector_mtrl-0.4.2/docs/user/start-here/01-your-first-record.md +148 -0
  24. vector_mtrl-0.4.2/docs/user/start-here/02-save-load-verify.md +123 -0
  25. vector_mtrl-0.4.2/docs/user/start-here/03-transform-and-plot.md +142 -0
  26. vector_mtrl-0.4.2/docs/user/start-here/04-handles-and-the-core.md +135 -0
  27. vector_mtrl-0.4.2/docs/user/start-here/05-fix-a-mistake.md +121 -0
  28. vector_mtrl-0.4.2/docs/user/start-here/06-replicates-and-the-mean.md +108 -0
  29. vector_mtrl-0.4.2/docs/user/start-here/07-get-your-data-out.md +107 -0
  30. vector_mtrl-0.4.2/docs/user/start-here/08-record-a-claim.md +120 -0
  31. vector_mtrl-0.4.2/docs/user/start-here/09-one-complete-analysis.md +289 -0
  32. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/__init__.py +7 -0
  33. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/_alignment_report.py +12 -6
  34. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/_archive_serialise.py +1 -3
  35. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/_run_management.py +16 -2
  36. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/_source_capture.py +1 -1
  37. vector_mtrl-0.4.2/mtrl/_summaries.py +664 -0
  38. vector_mtrl-0.4.2/mtrl/_summary_text.py +161 -0
  39. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/_transform_validation.py +15 -8
  40. vector_mtrl-0.4.2/mtrl/_unit_summary.py +151 -0
  41. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/archive/validation.py +7 -7
  42. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/domain/committed_values.py +13 -6
  43. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/exports.py +38 -2
  44. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/frames.py +196 -12
  45. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/grids.py +58 -18
  46. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/ml/__init__.py +5 -2
  47. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/ml/_adapters.py +65 -0
  48. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/ml/_dataset.py +169 -10
  49. vector_mtrl-0.4.2/mtrl/ml/_flat.py +201 -0
  50. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/ml/_preprocessing.py +76 -23
  51. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/ml/_specs.py +31 -9
  52. vector_mtrl-0.4.2/mtrl/ml/_summaries.py +225 -0
  53. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/models.py +41 -11
  54. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/mtrl.py +34 -97
  55. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/operations/__init__.py +1 -1
  56. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/operations/_validation.py +12 -1
  57. vector_mtrl-0.4.2/mtrl/operations/arithmetic.py +80 -0
  58. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/operations/base.py +53 -37
  59. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/operations/resampling.py +9 -2
  60. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/operations/resampling_scipy.py +7 -4
  61. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/operations/spectra.py +18 -4
  62. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/processing/registry.py +63 -129
  63. vector_mtrl-0.4.2/mtrl/sample.py +1535 -0
  64. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/pyproject.toml +6 -12
  65. vector_mtrl-0.3.0/docs/user/how-to/align-mixed-resolution-members.md +0 -104
  66. vector_mtrl-0.3.0/docs/user/how-to/control-the-operation-registry.md +0 -123
  67. vector_mtrl-0.3.0/docs/user/how-to/prepare-an-ml-dataset.md +0 -157
  68. vector_mtrl-0.3.0/docs/user/reference.md +0 -370
  69. vector_mtrl-0.3.0/docs/user/start-here/01-your-first-record.md +0 -98
  70. vector_mtrl-0.3.0/docs/user/start-here/02-save-load-verify.md +0 -163
  71. vector_mtrl-0.3.0/docs/user/start-here/03-fields-and-units.md +0 -103
  72. vector_mtrl-0.3.0/docs/user/start-here/04-transform-a-spectrum.md +0 -106
  73. vector_mtrl-0.3.0/docs/user/start-here/05-fix-a-mistake.md +0 -136
  74. vector_mtrl-0.3.0/docs/user/start-here/06-replicates-and-the-mean.md +0 -137
  75. vector_mtrl-0.3.0/docs/user/start-here/07-get-your-data-out.md +0 -221
  76. vector_mtrl-0.3.0/mtrl/_ingestion_shortcuts.py +0 -99
  77. vector_mtrl-0.3.0/mtrl/operations/arithmetic.py +0 -207
  78. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/.gitignore +0 -0
  79. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/LICENSE +0 -0
  80. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/NOTICE +0 -0
  81. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/docs/user/concepts/01-samples-runs-checkpoints.md +0 -0
  82. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/docs/user/concepts/02-the-commit-boundary.md +0 -0
  83. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/docs/user/concepts/03-two-kinds-of-identity.md +0 -0
  84. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/docs/user/concepts/04-corrections-vs-replacements.md +0 -0
  85. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/docs/user/concepts/06-revisions-the-archive-timeline.md +0 -0
  86. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/docs/user/concepts/07-inside-a-mtrl-archive.md +0 -0
  87. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/docs/user/concepts/08-trust-over-time.md +0 -0
  88. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/docs/user/concepts/index.md +0 -0
  89. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/_archive_documents.py +0 -0
  90. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/_archive_integrity.py +0 -0
  91. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/_archive_loading.py +0 -0
  92. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/_assertions_io.py +0 -0
  93. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/_assertions_ops.py +0 -0
  94. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/_assertions_validation.py +0 -0
  95. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/_candidate_matching.py +0 -0
  96. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/_cli.py +0 -0
  97. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/_disclosure.py +0 -0
  98. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/_install_targets.py +0 -0
  99. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/_optional.py +0 -0
  100. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/_provenance.py +0 -0
  101. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/_receipts.py +0 -0
  102. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/_record_resolution.py +0 -0
  103. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/_replay_plan.py +0 -0
  104. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/_replay_run.py +0 -0
  105. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/_table_plan.py +0 -0
  106. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/_table_provenance.py +0 -0
  107. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/_table_values.py +0 -0
  108. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/_transform_apply.py +0 -0
  109. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/_uuid7.py +0 -0
  110. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/archive/__init__.py +0 -0
  111. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/archive/canonical.py +0 -0
  112. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/archive/codecs.py +0 -0
  113. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/archive/dtypes.py +0 -0
  114. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/archive/reader.py +0 -0
  115. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/assertions/__init__.py +0 -0
  116. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/assertions/_resolver.py +0 -0
  117. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/connectors/__init__.py +0 -0
  118. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/connectors/protocols.py +0 -0
  119. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/disclosure.py +0 -0
  120. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/domain/__init__.py +0 -0
  121. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/domain/archive_limits.py +0 -0
  122. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/domain/assertions.py +0 -0
  123. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/domain/frozen_containers.py +0 -0
  124. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/domain/identities.py +0 -0
  125. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/domain/provenance.py +0 -0
  126. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/domain/records.py +0 -0
  127. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/domain/revisions.py +0 -0
  128. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/domain/source.py +0 -0
  129. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/domain/verification.py +0 -0
  130. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/excel.py +0 -0
  131. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/exceptions.py +0 -0
  132. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/features.py +0 -0
  133. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/integrity/__init__.py +0 -0
  134. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/integrity/canonical.py +0 -0
  135. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/integrity/digests.py +0 -0
  136. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/integrity/manifest.py +0 -0
  137. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/integrity/receipts.py +0 -0
  138. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/integrity/verification.py +0 -0
  139. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/ml/_canonical.py +0 -0
  140. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/ml/_group_keys.py +0 -0
  141. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/ml/_metadata_view.py +0 -0
  142. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/ml/_provenance.py +0 -0
  143. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/ml/_source_walk.py +0 -0
  144. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/ml/_splits.py +0 -0
  145. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/operations/_identity.py +0 -0
  146. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/processing/__init__.py +0 -0
  147. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/processing/_table_capture.py +0 -0
  148. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/processing/limits.py +0 -0
  149. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/protocols.py +0 -0
  150. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/py.typed +0 -0
  151. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/replay.py +0 -0
  152. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/tables.py +0 -0
  153. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/transformations/__init__.py +0 -0
  154. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/transformations/base.py +0 -0
  155. {vector_mtrl-0.3.0 → vector_mtrl-0.4.2}/mtrl/units.py +0 -0
@@ -12,6 +12,109 @@ break, and every breaking change is named in the release entry.
12
12
 
13
13
  ### Added
14
14
 
15
+ - Data-first `Sample` workflows, including explicit selection and correction helpers and
16
+ protocol-based `Sample.ingest` for connector-produced runs.
17
+ - `Sample.verify()` returns the core `VerifyResult` through the facade, preserving the separate
18
+ structural and hash facts and creating no revision; an existing receipt is consumed, while
19
+ receipt creation stays on `Mtrl.export_receipt()`.
20
+ - `Sample.export()` writes one committed result through the core suffix dispatch after it
21
+ validates the handle owner and exact active version, so a stale or foreign handle fails before
22
+ any write. The write is staged, no format fallback exists, and the call creates no revision; a
23
+ CSV or workbook projection is not a `.mtrl` substitute.
24
+ - `Sample.claim()` commits one scientific claim version and returns an immutable
25
+ `ScientificAssertion`, with `Sample.claims()` reading the active non-retracted heads in commit
26
+ order. One call is one core commit: each claim adds exactly one revision, and a default-subject
27
+ claim needs an existing sample identity because the facade never assigns one — the
28
+ `assign_sample_uid` prerequisite is reported, not repaired.
29
+ - `Sample.summary()` recaps the sample's active records and claims as bounded, deterministic text
30
+ in commit order, with declared units and real totals, and `Sample.history()` prints the record
31
+ graph behind that state: each active record's producing step and, one hop only, its exact input
32
+ versions, with corrected and replaced versions marked as superseded. Both calls are read-only —
33
+ no revision, no archive read, no verification, no optional import — and neither text carries a
34
+ generated identifier or a timestamp. Both contracts are recorded in `lat.md/interactive-api.md`.
35
+ - Detached `MLDataset.metadata_frame()`, `signal_frame()` and `auxiliary_frame()` views,
36
+ with channel/coordinate columns and a stable auxiliary encoding basis across splits.
37
+ - `MLDataset.summary()` recaps one prepared dataset as bounded, deterministic text: the row,
38
+ group, and channel totals, the target with its task type and class vocabulary, each channel's
39
+ point count, coordinate field, span, alignment mode, and resample flag, the auxiliary basis,
40
+ the metadata detail, the group kind, and the excluded candidate count, closed by that
41
+ dataset's canonical digest. It creates no revision and reads no archive; `limit` bounds the
42
+ channel listing from 1 to 50; and no payload value, sample identity, record identity, or
43
+ source path appears. The recap contract is recorded in `lat.md/ml-datasets.md`.
44
+ - `mtrl.ml.build_dataset()` builds one dataset from flat keyword arguments: `channel`,
45
+ `x_field`, `y_field`, `target_grid`, and `target` are mandatory, while the checkpoint
46
+ stage, alignment mode, task type, group kind, group property, and metadata detail default
47
+ to the guide's recipe. It composes one `DatasetSpec` and delegates to `build_ml_dataset()`,
48
+ so both routes produce one `spec_summary` and one `dataset_digest` for one logical
49
+ dataset, and unknown enumeration text fails with `DatasetPreparationError` naming the
50
+ received value and the valid choices.
51
+ - Bounded interactive summaries: `Mtrl.summary()` returns a bounded text summary of a
52
+ container, `_repr_html_()` renders the same escaped text for notebooks, and
53
+ `MaterialData` and `InstrumentRun` gain the matching text and HTML forms. The summary
54
+ contract is recorded in `lat.md/interactive-api.md`.
55
+
56
+ ### Changed
57
+
58
+ - **Breaking:** `MaterialData` and `InstrumentRun` no longer print their previous pydantic
59
+ default representation. Both render a bounded summary from `__repr__`, `__str__` and
60
+ `_repr_html_()` that never shows payload values, and `repr()` of a container returns
61
+ `Mtrl.summary()`. Code that parsed the old representation, or expected it to carry field
62
+ values, must read the documented accessors instead. The interactive-summary contract is
63
+ recorded in `lat.md/interactive-api.md`.
64
+ - **Breaking:** the default operation catalogue contains eight neutral version-two
65
+ contracts. Their input roles are `data` and `members`. Operations require the field
66
+ parameters their schemas declare: `y_field` for scale/offset; `x_field` and `y_field`
67
+ for resampling/mean/median; neither for identity. No field names are guessed.
68
+ - **Breaking:** `GridAlignmentSpec` requires keyword `x_field` and `y_field`, and
69
+ `FeatureChannelSpec` requires keyword `alignment`. `grid_from_record` and `shared_range`
70
+ require an axis-field argument, accepted positionally or by keyword.
71
+ - **Breaking:** alignment reports no longer assume a spectral axis when provenance does
72
+ not record one. Pass `x_field` explicitly in that case; conflicting recorded roles fail.
73
+ - **Breaking:** remove the version-one execution profile and `include_legacy` factory
74
+ argument, the retired peak-normalisation/zero-at-point implementations and aliases, and
75
+ the unused `mtrl.models.SPECTRUM_DTYPE` and `mtrl.models.CHECKPOINT_FILE_TYPE_SUFFIXES`
76
+ constants. The eight current contracts are defined
77
+ directly, not derived from retained historical descriptors.
78
+ - **Breaking:** direct arithmetic, resampling and aggregation functions require explicit
79
+ field arguments too. The read-only operation views reflect only the current catalogue;
80
+ detached registered `apply` validates that catalogue's parameters before execution.
81
+ - Historical archives load as data and stay verifiable, with one precise boundary: a
82
+ payload entry written under the retired `.spa` suffixed convention fails structural
83
+ validation loudly instead of loading. Removed operations are unavailable for replay, and
84
+ version-one general steps refuse the current version-two contract rather than silently
85
+ substituting a different implementation.
86
+ - **Breaking:** remove `Mtrl.load_spa` and `Mtrl.load_tri` and their lazy suite imports. The
87
+ core references no instrument suite: pass an explicit loader to
88
+ `Mtrl.load_instrument_file` or `Sample.ingest`. `LoadedInstrumentFile` and `SourceFile`
89
+ are new top-level exports so a loader needs only `from mtrl import ...`.
90
+ - **Breaking:** bytes payloads are always stored as `.bin`; the archive format no longer
91
+ derives payload suffixes from `file_type`. Archives written with a `.spa` payload entry
92
+ fail structural validation loudly. `file_type` remains recorded manifest provenance.
93
+ - **Breaking:** whole-container frame projection is strict by default. `runs_to_frame`,
94
+ `Mtrl.to_pandas` and `InstrumentRun.to_pandas` refuse with one `UnexportableCheckpointError`
95
+ listing every unconvertible checkpoint instead of warning and returning a partial frame.
96
+ Pass `strict=False` to keep the diagnostic partial frame. Contested label aliases such as
97
+ `type` beside `type_1` now reject in the CSV and labelled-frame paths rather than emitting
98
+ a duplicated column header.
99
+
100
+ ## [0.3.1] - 2026-10-27
101
+
102
+ ### Changed
103
+
104
+ - Point the PyPI front door at the documentation site: the README leads with
105
+ `mtrl-docs.vector-labs.app` and keeps the shipped guide paths as the offline route, and
106
+ the project URLs name the same documentation URL for the PyPI sidebar. The source-tree
107
+ version fallback also names `0.3.1` when installed distribution metadata is absent.
108
+
109
+ - The post-publish resolution check no longer races PyPI index propagation: a bounded,
110
+ read-only wait (`scripts/public_core_resolution_wait.py`) polls the same simple index
111
+ the resolver reads until both published archives appear, with offline-tested refusal
112
+ handling, before the single-shot resolution runs. The wait never re-uploads.
113
+
114
+ ## [0.3.0] - 2026-10-26
115
+
116
+ ### Added
117
+
15
118
  - Scientific assertions: claims, versions, subjects, evidence, and supersession as a core
16
119
  feature, plus the portable UUIDv7 physical-sample identity `sample_uid`
17
120
  (`Mtrl.sample_uid` and `Mtrl.assign_sample_uid()`).
@@ -1,7 +1,8 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: vector-mtrl
3
- Version: 0.3.0
3
+ Version: 0.4.2
4
4
  Summary: Materials research tools for spectra and archive workflows.
5
+ Project-URL: Documentation, https://mtrl-docs.vector-labs.app
5
6
  Author-email: Fuzzy Labs <info@fuzzylabs.ai>
6
7
  License-Expression: MPL-2.0
7
8
  License-File: LICENSE
@@ -33,8 +34,8 @@ immutable record with exact lineage.
33
34
  - Machine-learning dataset preparation across archives: checkpoint state selection, in-memory
34
35
  preprocessing, grid alignment, leak-free group splits, and canonical provenance digests.
35
36
  - Bounded `.mtrl` archives with an integrity manifest, external receipts, and forensic inspection.
36
- - NumPy-only operations: identity, scale, offset, peak normalisation, zero-at-point, and linear
37
- resample, beside mean and median aggregates.
37
+ - NumPy-only operations: identity, scale, offset, and linear resample, beside mean and median
38
+ aggregates. The `interp` extra adds SciPy PCHIP and cubic resampling.
38
39
  - Explicit analysis grids and a read-only alignment report.
39
40
  - A read-only replay plan, a capability view, and a detached rerun for committed chains.
40
41
  - Author disclosure that stays inert: stored environment records and passive source bundles that
@@ -54,12 +55,14 @@ uv pip install --python .venv/bin/python vector-mtrl
54
55
 
55
56
  ## Quick start
56
57
 
57
- Commit one synthetic spectrum, normalise it, save an archive, verify it, load it, and export
58
- CSV. The base install alone runs every step.
58
+ Start with the `Sample` facade: one object that records, transforms, selects, corrects,
59
+ exports, and saves. It is the routine route for notebook work, like pyplot over the object
60
+ model. `sample.core` returns the underlying container whenever a task outgrows the facade.
59
61
 
60
- ### Example: Quick start
62
+ Record one synthetic spectrum, normalise it with your own function, save, verify, reload,
63
+ and export CSV. The base install alone runs every step.
61
64
 
62
- **Required install:** `vector-mtrl`
65
+ <!-- example: Quick start -->
63
66
 
64
67
  ```python
65
68
  from pathlib import Path
@@ -67,61 +70,72 @@ from tempfile import TemporaryDirectory
67
70
 
68
71
  import numpy as np
69
72
 
70
- from mtrl import InstrumentRun, MaterialData, Mtrl, verify_archive
73
+ from mtrl import Sample
71
74
 
72
- application = Mtrl(sample_id="sample-01")
73
- run = InstrumentRun(run_name="replicate-01")
75
+ sample = Sample("sample-01")
74
76
  axis = np.array([2000.0, 2100.0, 2200.0])
75
77
  content = np.empty(axis.size, dtype=[("wavenumber", "<f8"), ("absorbance", "<f8")])
76
78
  content["wavenumber"] = axis
77
79
  content["absorbance"] = [0.1, 0.2, 0.3]
78
- checkpoint = MaterialData(
79
- content=content,
80
- type="raw",
81
- checkpoint_name="spectrum",
82
- )
83
- run.add_checkpoint(checkpoint)
84
- application.add(run)
85
-
86
- normalised = application.transform(
87
- run.run_id,
88
- checkpoint.checkpoint_id,
89
- "normalise_peak",
90
- )
91
- print(normalised.lineage.provenance.qualified_identifier)
80
+ raw = sample.record(content, name="spectrum")
81
+
82
+
83
+ def normalise_peak(data, *, target=1.0):
84
+ """Scale absorbance so its largest signed value equals the target."""
85
+ peak = float(data["absorbance"].max())
86
+ if not np.isfinite(peak) or peak == 0.0:
87
+ raise ValueError("absorbance has no finite, non-zero maximum to normalise")
88
+ scaled = data.copy()
89
+ scaled["absorbance"] = data["absorbance"] * (target / peak)
90
+ return scaled
91
+
92
+
93
+ normalised = sample.transform(raw, normalise_peak, name="normalised")
94
+ print(f"records: {len(sample.records)}; latest: {normalised.name}")
92
95
 
93
96
  with TemporaryDirectory() as directory:
94
- archive_path = application.save(Path(directory) / "sample.mtrl")
95
- verification = verify_archive(archive_path)
97
+ archive_path = sample.save(Path(directory) / "sample.mtrl")
98
+ verification = sample.verify()
96
99
  print(verification.structural_status.value, verification.hash_status.value)
97
100
 
98
- loaded = Mtrl.load(archive_path)
99
- print(loaded.sample_id, loaded.get_run(run.run_id) is not None)
100
- csv_path = loaded.export_checkpoint(
101
- run.run_id,
102
- normalised.checkpoint_id,
103
- Path(directory) / "signal.csv",
104
- )
101
+ loaded = Sample.load(archive_path)
102
+ current = loaded.one(name="normalised")
103
+ csv_path = loaded.export(current, Path(directory) / "signal.csv")
105
104
  exported = np.genfromtxt(csv_path, delimiter=",", names=True)
106
- np.testing.assert_allclose(exported["absorbance"], [1 / 3, 2 / 3, 1])
105
+ assert np.allclose(exported["absorbance"], [1 / 3, 2 / 3, 1])
107
106
  print(csv_path.is_file())
108
107
  ```
109
108
 
110
- `Mtrl.add()` commits a detached copy, so later changes to your arrays cannot alter the record.
111
- Every mutation, including the transform above, creates one new revision.
109
+ ```text
110
+ records: 2; latest: normalised
111
+ valid consistent
112
+ True
113
+ ```
114
+
115
+ You should see the two records and the transform's name, the two verification facts, and
116
+ `True` for the exported CSV. `sample.record()` commits a detached copy, so later changes to your arrays cannot alter the
117
+ record. Every committed change, including the transform above, creates one new revision, and
118
+ the transform records your own function as a custom step. The function scales by the largest
119
+ signed absorbance value; use `np.abs(...).max()` instead when the spectrum can go negative and
120
+ you want the largest magnitude. `sample.one(name=...)` requires exactly one match, and
121
+ `sample.export` writes one active result through the registered writer for the file suffix — a
122
+ projection of the data, not a substitute for the archive.
112
123
 
113
124
  ## Guides
114
125
 
115
- The expanded guides ship in the source archive under `docs/user/`. Download the archive for a
116
- release from https://pypi.org/project/vector-mtrl/#files, then read:
126
+ Read the guides online at https://mtrl-docs.vector-labs.app. The same pages ship in
127
+ the source archive under `docs/user/` for offline reading: download the archive for a release
128
+ from https://pypi.org/project/vector-mtrl/#files, then read:
117
129
 
118
- - `docs/user/start-here/` for the seven-lesson tutorial path: installation, first records,
119
- the save, load, verify loop, fields and units, transforms, corrections, aggregates, and
120
- exports.
130
+ - `docs/user/start-here/` for the tutorial path: installation, first records, the save,
131
+ load, verify loop, fields and units, transforms, corrections, aggregates, exports, and
132
+ one continuous notebook analysis, which the documentation website also offers as a
133
+ downloadable notebook.
121
134
  - `docs/user/concepts/` for the ideas underneath, in plain language.
122
135
  - `docs/user/how-to/` for task guides: replacements, resampling, mixed-resolution alignment,
123
136
  replay, receipts, forensic inspection, disclosure, registry control, missing extras,
124
- scientific assertions, external evidence, and machine-learning datasets.
137
+ scientific assertions, external evidence, machine-learning datasets, and
138
+ scientific-Python interoperability with pandas, NumPy, SciPy, and matplotlib.
125
139
  - `docs/user/reference.md` for every public route, the stable typed imports, the exact
126
140
  package-root export list, registry names, format features, and the archive safety contract.
127
141
 
@@ -12,8 +12,8 @@ immutable record with exact lineage.
12
12
  - Machine-learning dataset preparation across archives: checkpoint state selection, in-memory
13
13
  preprocessing, grid alignment, leak-free group splits, and canonical provenance digests.
14
14
  - Bounded `.mtrl` archives with an integrity manifest, external receipts, and forensic inspection.
15
- - NumPy-only operations: identity, scale, offset, peak normalisation, zero-at-point, and linear
16
- resample, beside mean and median aggregates.
15
+ - NumPy-only operations: identity, scale, offset, and linear resample, beside mean and median
16
+ aggregates. The `interp` extra adds SciPy PCHIP and cubic resampling.
17
17
  - Explicit analysis grids and a read-only alignment report.
18
18
  - A read-only replay plan, a capability view, and a detached rerun for committed chains.
19
19
  - Author disclosure that stays inert: stored environment records and passive source bundles that
@@ -33,12 +33,14 @@ uv pip install --python .venv/bin/python vector-mtrl
33
33
 
34
34
  ## Quick start
35
35
 
36
- Commit one synthetic spectrum, normalise it, save an archive, verify it, load it, and export
37
- CSV. The base install alone runs every step.
36
+ Start with the `Sample` facade: one object that records, transforms, selects, corrects,
37
+ exports, and saves. It is the routine route for notebook work, like pyplot over the object
38
+ model. `sample.core` returns the underlying container whenever a task outgrows the facade.
38
39
 
39
- ### Example: Quick start
40
+ Record one synthetic spectrum, normalise it with your own function, save, verify, reload,
41
+ and export CSV. The base install alone runs every step.
40
42
 
41
- **Required install:** `vector-mtrl`
43
+ <!-- example: Quick start -->
42
44
 
43
45
  ```python
44
46
  from pathlib import Path
@@ -46,61 +48,72 @@ from tempfile import TemporaryDirectory
46
48
 
47
49
  import numpy as np
48
50
 
49
- from mtrl import InstrumentRun, MaterialData, Mtrl, verify_archive
51
+ from mtrl import Sample
50
52
 
51
- application = Mtrl(sample_id="sample-01")
52
- run = InstrumentRun(run_name="replicate-01")
53
+ sample = Sample("sample-01")
53
54
  axis = np.array([2000.0, 2100.0, 2200.0])
54
55
  content = np.empty(axis.size, dtype=[("wavenumber", "<f8"), ("absorbance", "<f8")])
55
56
  content["wavenumber"] = axis
56
57
  content["absorbance"] = [0.1, 0.2, 0.3]
57
- checkpoint = MaterialData(
58
- content=content,
59
- type="raw",
60
- checkpoint_name="spectrum",
61
- )
62
- run.add_checkpoint(checkpoint)
63
- application.add(run)
64
-
65
- normalised = application.transform(
66
- run.run_id,
67
- checkpoint.checkpoint_id,
68
- "normalise_peak",
69
- )
70
- print(normalised.lineage.provenance.qualified_identifier)
58
+ raw = sample.record(content, name="spectrum")
59
+
60
+
61
+ def normalise_peak(data, *, target=1.0):
62
+ """Scale absorbance so its largest signed value equals the target."""
63
+ peak = float(data["absorbance"].max())
64
+ if not np.isfinite(peak) or peak == 0.0:
65
+ raise ValueError("absorbance has no finite, non-zero maximum to normalise")
66
+ scaled = data.copy()
67
+ scaled["absorbance"] = data["absorbance"] * (target / peak)
68
+ return scaled
69
+
70
+
71
+ normalised = sample.transform(raw, normalise_peak, name="normalised")
72
+ print(f"records: {len(sample.records)}; latest: {normalised.name}")
71
73
 
72
74
  with TemporaryDirectory() as directory:
73
- archive_path = application.save(Path(directory) / "sample.mtrl")
74
- verification = verify_archive(archive_path)
75
+ archive_path = sample.save(Path(directory) / "sample.mtrl")
76
+ verification = sample.verify()
75
77
  print(verification.structural_status.value, verification.hash_status.value)
76
78
 
77
- loaded = Mtrl.load(archive_path)
78
- print(loaded.sample_id, loaded.get_run(run.run_id) is not None)
79
- csv_path = loaded.export_checkpoint(
80
- run.run_id,
81
- normalised.checkpoint_id,
82
- Path(directory) / "signal.csv",
83
- )
79
+ loaded = Sample.load(archive_path)
80
+ current = loaded.one(name="normalised")
81
+ csv_path = loaded.export(current, Path(directory) / "signal.csv")
84
82
  exported = np.genfromtxt(csv_path, delimiter=",", names=True)
85
- np.testing.assert_allclose(exported["absorbance"], [1 / 3, 2 / 3, 1])
83
+ assert np.allclose(exported["absorbance"], [1 / 3, 2 / 3, 1])
86
84
  print(csv_path.is_file())
87
85
  ```
88
86
 
89
- `Mtrl.add()` commits a detached copy, so later changes to your arrays cannot alter the record.
90
- Every mutation, including the transform above, creates one new revision.
87
+ ```text
88
+ records: 2; latest: normalised
89
+ valid consistent
90
+ True
91
+ ```
92
+
93
+ You should see the two records and the transform's name, the two verification facts, and
94
+ `True` for the exported CSV. `sample.record()` commits a detached copy, so later changes to your arrays cannot alter the
95
+ record. Every committed change, including the transform above, creates one new revision, and
96
+ the transform records your own function as a custom step. The function scales by the largest
97
+ signed absorbance value; use `np.abs(...).max()` instead when the spectrum can go negative and
98
+ you want the largest magnitude. `sample.one(name=...)` requires exactly one match, and
99
+ `sample.export` writes one active result through the registered writer for the file suffix — a
100
+ projection of the data, not a substitute for the archive.
91
101
 
92
102
  ## Guides
93
103
 
94
- The expanded guides ship in the source archive under `docs/user/`. Download the archive for a
95
- release from https://pypi.org/project/vector-mtrl/#files, then read:
104
+ Read the guides online at https://mtrl-docs.vector-labs.app. The same pages ship in
105
+ the source archive under `docs/user/` for offline reading: download the archive for a release
106
+ from https://pypi.org/project/vector-mtrl/#files, then read:
96
107
 
97
- - `docs/user/start-here/` for the seven-lesson tutorial path: installation, first records,
98
- the save, load, verify loop, fields and units, transforms, corrections, aggregates, and
99
- exports.
108
+ - `docs/user/start-here/` for the tutorial path: installation, first records, the save,
109
+ load, verify loop, fields and units, transforms, corrections, aggregates, exports, and
110
+ one continuous notebook analysis, which the documentation website also offers as a
111
+ downloadable notebook.
100
112
  - `docs/user/concepts/` for the ideas underneath, in plain language.
101
113
  - `docs/user/how-to/` for task guides: replacements, resampling, mixed-resolution alignment,
102
114
  replay, receipts, forensic inspection, disclosure, registry control, missing extras,
103
- scientific assertions, external evidence, and machine-learning datasets.
115
+ scientific assertions, external evidence, machine-learning datasets, and
116
+ scientific-Python interoperability with pandas, NumPy, SciPy, and matplotlib.
104
117
  - `docs/user/reference.md` for every public route, the stable typed imports, the exact
105
118
  package-root export list, registry names, format features, and the archive safety contract.
106
119
 
@@ -30,6 +30,11 @@ that supplies hand-built data, like the lesson 5 correction, records what it cor
30
30
  operation recipe, because no operation produced the new values. Only records an operation
31
31
  produced carry the full recipe described below.
32
32
 
33
+ You can read those edges for one sample without inspecting the archive internals:
34
+ `print(sample.history())` lists each active record's producing step and, one hop only, the exact
35
+ versions it consumed, marking a version that a later correction superseded — see
36
+ [one complete analysis](../start-here/09-one-complete-analysis.md).
37
+
33
38
  ## The provenance envelope
34
39
 
35
40
  The lineage says which step ran. A second, richer object says everything about how it ran: the
@@ -74,4 +79,4 @@ digest to compare against. The how-to guides cover replay in detail.
74
79
  Each sealed recipe becomes one step in a longer history —
75
80
  [Revisions: the archive timeline](06-revisions-the-archive-timeline.md) shows how those steps
76
81
  accumulate into a verifiable archive. To record a recipe of your own, revisit
77
- [Transform a spectrum](../start-here/04-transform-a-spectrum.md).
82
+ [Transform and plot a spectrum](../start-here/03-transform-and-plot.md).
@@ -0,0 +1,62 @@
1
+ # Units of measure
2
+
3
+ Think of a lab notebook. When you write "peak at 2500 cm⁻¹", the number and the unit travel
4
+ together, and a colleague can read both. If the notebook silently rewrote your "cm⁻¹" as
5
+ "1/cm", you would wonder what else it changed. MTRL treats units the same careful way: it
6
+ keeps the text you declared, understands the spellings it knows, and never rewrites a unit
7
+ behind your back.
8
+
9
+ ## What you declare
10
+
11
+ Every field of a record can carry one unit, written exactly as your instrument or notebook
12
+ reports it. A wavenumber axis might say `"cm^-1"` or `"cm⁻¹"`; a time axis might say `"s"`;
13
+ a normalised intensity often says `"a.u."`. The declaration is part of the record, so it
14
+ survives save, load, correction and export unchanged.
15
+
16
+ MTRL does not guess. A field with no declared unit stays undeclared, and a unit it does not
17
+ recognise is preserved verbatim rather than rewritten or dropped.
18
+
19
+ ## The standard behind the text
20
+
21
+ Behind the scenes MTRL matches the spellings it knows against **QUDT** — Quantities, Units,
22
+ Dimensions and Types, a public standard vocabulary for measurement. QUDT separates two
23
+ ideas that are easy to blur:
24
+
25
+ - The **quantity kind** is the property being measured: an inverse length, a time, a
26
+ dimensionless ratio.
27
+ - The **unit** is the measure of that property: per centimetre, seconds, unitless.
28
+
29
+ A recognised spelling carries both, so a check can compare meaning rather than text. Two
30
+ fields that disagree fail their check with the disagreement named, instead of one being
31
+ converted to match the other.
32
+
33
+ ## The spellings MTRL recognises today
34
+
35
+ The recognised set is deliberately small. Each row shows the spellings that map to the same
36
+ standard terms:
37
+
38
+ | You write | QUDT unit | Quantity kind |
39
+ | --- | --- | --- |
40
+ | `cm^-1`, `cm⁻¹`, `1/cm` | per centimetre | inverse length |
41
+ | `s`, `second` | seconds | time |
42
+ | `a.u.` | unitless | dimensionless |
43
+
44
+ Anything else — `"K"`, `"MPa"`, `"counts"`, your own domain unit — is kept exactly as you
45
+ wrote it, with no standard terms attached. It still records, exports and round-trips; it
46
+ plays no part in unit-checked comparisons until the recognised set grows.
47
+
48
+ ## Where units matter
49
+
50
+ Declared units do real work in three places. A transform preserves the declarations of the
51
+ fields its output keeps, so derived records stay labelled. Machine-learning dataset
52
+ specifications can require an `expected_unit` for a channel, feature or target, and a
53
+ mismatch fails the build with the field and its declared unit named. And exports carry the
54
+ declared text, so a colleague reading your CSV or workbook sees the same unit you wrote.
55
+
56
+ ## How to write units well
57
+
58
+ Use the spelling your instrument reports; that is the honest record. When you are free to
59
+ choose, prefer the canonical forms from the table above (`cm^-1`, `s`, `a.u.`) so the
60
+ standard terms attach. Keep one spelling per field across a study, because comparisons read
61
+ the declaration you wrote. And when a check fails on units, change the declaration or the
62
+ data deliberately — MTRL will not choose for you.