Handle missing extras

Code that needs an optional extra should fail helpfully when the extra is not installed, and MTRL gives you one specific exception to catch for exactly that situation.

Facade routes raise the same MissingOptionalDependencyError as their core counterparts — sample.export for a workbook is the common case — so the recovery here applies unchanged.

This guide assumes: you have finished the tutorial path. No concepts pages are needed.

MTRL keeps its base install small. Capabilities that need heavy third-party libraries live behind extras (optional add-ons you name at install time, such as vector-mtrl[tabular]). Three exist: interp adds the SciPy-backed resampling operations, tabular adds the pandas frame conversions, and excel adds the Excel workbook writer. When your code calls a capability whose extra is missing, MTRL raises MissingOptionalDependencyError and names the distribution that supplies it. Catching that one exception lets you print the guidance and carry on, instead of dying on a traceback.

from mtrl import MissingOptionalDependencyError, Mtrl

try:
    Mtrl(sample_id="polymer-film-01").to_pandas()
except MissingOptionalDependencyError as error:
    print(error)

Run this in an environment with only the base install of vector-mtrl. The call raises, the except block catches it, and the script prints the error message naming the extra that provides the capability. With vector-mtrl[tabular] installed, the same script runs without printing anything, because no exception is raised.

What just happened?

Mtrl.to_pandas() converts the active record data into a pandas DataFrame, and pandas only ships with the tabular extra. With the base install, the call raises MissingOptionalDependencyError before doing any work, and the message names the distribution to install. Because it is one specific exception, a narrow except is enough. You never need a blanket except Exception to stay friendly.

The same pattern covers every optional capability. The resample_pchip and resample_cubic transforms need interp, and exporting a checkpoint to .xlsx needs excel. Each raises the same exception when its library is absent, so one error-handling shape serves your whole codebase. CSV export needs no optional package at all, and the core defines no suite-selection extras: instrument readers come from separately licensed distributions.

Tip

The extra named in the error message is the one to quote in your install command, for example uv pip install "vector-mtrl[tabular]". Install it, then rerun the same code unchanged.

Where next

• Reference — the full table of installs and the capabilities each extra unlocks.
• Get your data out — CSV export, which works with the base install alone.