Export values and share the archive

In this lesson you will give a colleague a table they can open in another tool, without losing the history behind it. By the end you will have a CSV of the mean spectrum and a complete .mtrl archive, with an optional Excel route when a workbook is more useful. It takes about five minutes.

This carries on from Combine replicates: the mean you committed is exactly the sort of result worth sharing. CSV needs only the base package. The separate Excel example needs the excel extra.

Two files for two different jobs

Think of an export as a handout from your lab folder. It gives another tool the values it needs, but it is not the folder itself. The .mtrl archive remains the place to keep the exact records, their units, claims, revisions and provenance.

For a plain table, sample.export(result, path) is enough. Give it an active result owned by that facade; the path suffix selects the writer. A .csv destination needs neither pandas nor a plotting dependency.

The first example writes both files, then reads the CSV back with NumPy to compare the exported absorbance values with the mean’s. Both outputs live in a temporary directory so the example cleans up after itself. In your own work, choose destinations you retain.

before = len(sample.core.revisions)
csv_path = sample.export(mean, "mean-spectrum.csv")
archive_path = sample.save("polymer-film-01.mtrl")
exported = np.genfromtxt(csv_path, delimiter=",", names=True)
assert np.allclose(exported["absorbance"], mean.to_numpy()["absorbance"])
print(f"csv written: {csv_path.is_file()}; archive written: {archive_path.is_file()}")
print(f"revisions added: {len(sample.core.revisions) - before}")

csv written: True; archive written: True
revisions added: 0

Both files exist in your working directory, so the next lesson (and the optional workbook below) can keep building on them. The zero shows that exporting and saving did not add a revision: you shared existing work rather than committing a new scientific result. The plain assert checks that the exported absorbance values agree within NumPy’s comparison tolerance; it passes silently.

When your colleague needs a workbook

You do not need Excel support to use MTRL. If a colleague needs a workbook, install the excel extra into the same environment, for example with uv pip install --python .venv/bin/python 'vector-mtrl[excel]'. Then use the same facade call with an .xlsx destination.

The second example carries straight on, exporting the same mean to a workbook. The writer changes; the way you select and export a result does not.

Required install: vector-mtrl[excel]

workbook = sample.export(mean, "mean-spectrum.xlsx")
print(f"workbook written: {workbook.is_file()}")

workbook written: True

The workbook exists in your working directory beside the CSV and the archive.

Before sending either table, ask what the recipient needs to know. CSV contains the value table, not its units, lineage, history or integrity manifest. A workbook may include supporting sheets, but it still does not carry the complete archive history or all aggregate membership evidence. If a colleague needs to inspect those things, share the .mtrl archive alongside the convenient table.

What just happened?

The facade checked that the handle still named an active result in this sample, then delegated the write to the registered writer for the destination suffix. Export made a projection of the result without committing another one. Saving kept the complete committed history instead.

The export writer stages its output, so it does not replace a good destination with a half-written result. That protects the write; it does not turn the exported table into an archive or give it the archive’s history.

Where next

A table says what you measured, but not everything you believe about the specimen. Record a scientific claim adds an explicit interpretation without pretending it is another spectrum.