nirs4all.api.calibrate module

Public conformal calibration entry point.

class nirs4all.api.calibrate.ConformalCalibrationData(y_true: Any | None = None, y_pred: Any | None = None, sample_ids: Any = None, groups: Any = None, metadata: Any = None, dataset: Any | None = None, selector: Mapping[str, Any] | None = None, sample_id_column: str | None = None, group_column: str | None = None, metadata_columns: str | list[str] | tuple[str, ...] | None = None, include_augmented: bool = False, predictor: Any | None = None, predictor_bundle: str | Path | None = None, model_bundle: str | Path | None = None, predictor_path: str | Path | None = None, model_path: str | Path | None = None, predictor_result: Any | None = None, predictor_chain_id: str | None = None, workspace_chain_id: str | None = None, workspace_path: str | Path | None = None, predictor_fingerprint: str | None = None)

Bases: object

Typed public calibration evidence for nirs4all.calibrate().

Use either explicit replayed arrays (y_true/y_pred/sample_ids) or a dataset-backed source (dataset + selector) with one replay lane such as y_pred or predictor. The object serializes to the mapping consumed by the existing runtime; it does not create implicit splits or discover predictors automatically.

dataset: Any | None = None

group_column: str | None = None

groups: Any = None

include_augmented: bool = False

metadata: Any = None

metadata_columns: str | list[str] | tuple[str, ...] | None = None

model_bundle: str | Path | None = None

model_path: str | Path | None = None

predictor: Any | None = None

predictor_bundle: str | Path | None = None

predictor_chain_id: str | None = None

predictor_fingerprint: str | None = None

predictor_path: str | Path | None = None

predictor_result: Any | None = None

sample_id_column: str | None = None

sample_ids: Any = None

selector: Mapping[str, Any] | None = None

to_dict() → dict[str, Any]

Return the public mapping consumed by nirs4all.calibrate().

workspace_chain_id: str | None = None

workspace_path: str | Path | None = None

y_pred: Any | None = None

y_true: Any | None = None

exception nirs4all.api.calibrate.Nirs4AllCalibrationNotImplementedError(calibration_spec: ConformalCalibrationSpec, *, missing_gates: tuple[str, ...] = ('automatic predictor lookup for dataset/replay calibration forms', 'native predictor bundle calibration fitting'))

Bases: NotImplementedError

Structured boundary for public calibration forms that are still planned.

nirs4all.api.calibrate.attach_calibrated_result_to_bundle(model_bundle_path: str | Path, calibrated: CalibratedRunResult | str | Path, output_path: str | Path | None = None, *, overwrite: bool = False) → Path

Attach a calibrated conformal result sidecar to an existing model .n4a bundle.

nirs4all.api.calibrate.calibrate(calibration_data: ConformalCalibrationData | PredictResult | Mapping[str, Any] | tuple[Any, ...] | None = None, *, y_true: Any | None = None, y_pred_calibration: Any | None = None, y_pred: Any | None = None, calibration_sample_ids: Any | None = None, prediction_sample_ids: Any | None = None, coverage: float | list[float] | tuple[float, ...] = 0.9, method: str = 'split_absolute_residual', unit: str = 'physical_sample', group_by: Any | None = None, multi_target: str = 'marginal', calibration_groups: Any | None = None, calibration_metadata: Any | None = None, prediction_groups: Any | None = None, prediction_metadata: Any | None = None, result_metadata: Mapping[str, Any] | None = None, target_name: str | None = None, predictor_fingerprint: str | None = None, store_path: str | Path | None = None, bundle_path: str | Path | None = None, workspace_path: str | Path | None = None, workspace_name: str = '', workspace_conformal_id: str | None = None, workspace_metadata: Mapping[str, Any] | None = None, overwrite_store: bool = False, as_predict_result: bool = False) → CalibratedRunResult | PredictResult

Calibrate replayed point predictions with split conformal intervals.

This first public surface is intentionally narrow: callers must provide calibration targets, replayed calibration predictions or an explicit predictor replay source over a selected dataset-backed cohort, prediction outputs, and explicit physical sample ids. Automatic predictor discovery remains a planned follow-up gate. When group_by is provided, callers must also provide row-aligned prediction group evidence via prediction_groups and/or prediction_metadata so intervals can be routed to a calibrated group without fallback.

nirs4all.api.calibrate.conformal_metrics(calibrated: CalibratedRunResult | PredictResult | str | Path, *, y_true: Any) → dict[float, ConformalMetricSet]

Compute observed coverage, widths and interval scores for conformal predictions.

nirs4all.api.calibrate.export_calibrated_result(result: CalibratedRunResult, path: str | Path, *, overwrite: bool = False) → Path

Export a calibrated result as a zipped .n4a conformal bundle.

nirs4all.api.calibrate.load_calibrated_result(path: str | Path) → CalibratedRunResult

Load a verified conformal calibration result store or bundle.

nirs4all.api.calibrate.load_workspace_calibrated_predict_result(workspace_path: str | Path, conformal_id: str) → PredictResult

Load a workspace conformal result as a public PredictResult.

nirs4all.api.calibrate.load_workspace_calibrated_result(workspace_path: str | Path, conformal_id: str) → CalibratedRunResult

Load a verified calibrated conformal result from a nirs4all workspace.

nirs4all.api.calibrate.predict_calibrated(calibrated: CalibratedRunResult | str | Path, *, y_pred: Any, prediction_sample_ids: Any, result_metadata: Mapping[str, Any] | None = None, as_predict_result: bool = True) → CalibratedRunResult | PredictResult

Apply an existing conformal calibrator to already computed predictions.

nirs4all.api.calibrate.save_workspace_calibrated_result(workspace_path: str | Path, result: CalibratedRunResult, *, name: str = '', conformal_id: str | None = None, metadata: Mapping[str, Any] | None = None, run_id: str | None = None, pipeline_id: str | None = None, chain_id: str | None = None, prediction_id: str | None = None) → str

Persist a calibrated conformal result in a nirs4all workspace.