Record a scientific claim

In this lesson you will record something said about the polymer film, rather than another set of measured values. By the end you will have given the physical sample a portable identity, attached a hypothetical polymer label and read that claim back. Allow about ten minutes: the distinction between a measurement and an assertion is more important here than the few lines of code.

The example needs only the recorded film from Record your first measurement. Any session that still has that sample is ready, including the one you have built through the earlier lessons. The label is illustrative, not an identification established by the synthetic spectrum.

A measurement and an interpretation answer different questions

So far the archive tells us what values were recorded and how they were processed. It does not follow that the archive knows which polymer the film is. An operator might read a label on its container, consult a supplier’s certificate or interpret a spectrum. Those are assertions about the sample, and they need somewhere to live without being confused with the measurements themselves.

A claim records an assertion. In this example, polymer.identity names the property and PET is the asserted value. The dotted property name helps organise the meaning, but it does not establish a shared scientific vocabulary by itself. Two teams still need to agree what their property identifiers mean.

The label on the bag is not the identity of the specimen

Our human-facing sample_id, polymer-film-01, is useful in a notebook or on a sample bag. It is not the portable physical identity used as a claim’s default subject. For that, MTRL uses a sample UID. The distinction keeps a readable label separate from the identity of the thing you are making a statement about.

Physical specimen: your polymer film
├── sample_id: polymer-film-01       the label you use to recognise it
├── sample UID                      its portable identity as a claim subject
├── measurement record              values recorded from an FTIR measurement
└── claim about the sample UID       polymer.identity = PET

Notice where the last line points. This claim is about the physical film, not merely one spectrum or the letters in its label. Other claims can have run or exact-record subjects through the advanced routes, but that is not what we are asserting here.

Before making a default sample claim, explicitly call sample.core.assign_sample_uid(). This assigns the portable identity without changing sample_id. It is a separate commit because assigning an identity and asserting a property are separate decisions. The facade does not hide an extra identity revision inside claim: one mutating facade call must not conceal two commits.

Give the assertion a place in the history

Run the example and watch the two revision counts. First the core assigns the sample UID; then sample.claim(property_id, value) records the assertion. Finally, sample.claims(...) reads it back without changing the history.

before = len(sample.core.revisions)
sample.core.assign_sample_uid()
print(f"revisions added: {len(sample.core.revisions) - before}")

before = len(sample.core.revisions)
claim = sample.claim("polymer.identity", "PET")
print(f"revisions added: {len(sample.core.revisions) - before}")
print(f"claim: {claim.property_id} {claim.value}")
print(f"identity claims: {len(sample.claims(property_id='polymer.identity'))}")

revisions added: 1
revisions added: 1
claim: polymer.identity PET
identity claims: 1

The identity assignment and the claim each add their own revision. Reading matching claims finds one without adding another revision.

It is worth pausing over what those lines do not say. The default method is operator-entered, and this example supplies neither supporting evidence nor an author. It therefore implies neither evidence nor attribution. We have recorded a hypothetical statement, not demonstrated that the film is PET.

What just happened?

You gave the physical sample a portable identity, kept its familiar label and committed one immutable claim version with that identity as its default subject. The measurement remained a measurement; the interpretation gained its own place in the history.

claims returns matching active, non-retracted claim heads. Calling claim again creates an independent claim, not an update to the one you made. If you need to replace or withdraw an assertion, supersession and retraction are explicit core operations, as are batching and historical queries. Do not assign another physical identity merely to change what you assert about the same specimen.

Archive verification remains a different question again. It checks recorded evidence and integrity facts; a consistent archive can faithfully preserve a mistaken claim. Whether the polymer identification is justified depends on the scientific evidence, not on the success of the archive’s hash checks.

Caution

Without an assigned UID, a default sample claim is refused. Claims about an explicit run or record use the advanced subject types instead; changing the subject is a scientific choice, not a workaround for a missing physical identity.

Tip

The scientific assertions guide adds evidence, typed subjects and the claim lifecycle through sample.core.

Where next

You now have measurements, derived results and a place for an interpretation. One complete analysis brings them together in one continuous workflow, with a correction, replicates and a saved archive.