nirs4all.api.tuning module

Public helpers for native DAG-ML tuning results.

class nirs4all.api.tuning.NativeTuning(space: Mapping[str, Any], force_params: Mapping[str, Any] | None = None, engine: str = 'optuna', metric: str = 'rmse', direction: str = 'minimize', n_trials: int = 50, sampler: str | None = None, pruner: str | None = None, seed: int | None = None, resume: bool = False, storage: str | None = None, study_name: str | None = None, score_data: TuningScoreData | Mapping[str, Any] | tuple[Any, ...] | list[Any] | None = None, winner: TuningWinner | Mapping[str, Any] | None = None, calibration: TuningCalibration | Mapping[str, Any] | None = None, workspace_tuning_id: str | None = None, workspace_metadata: Mapping[str, Any] | None = None)

Bases: object

Typed public configuration for the current native run(tuning=...) lane.

calibration: TuningCalibration | Mapping[str, Any] | None = None

direction: str = 'minimize'

engine: str = 'optuna'

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

inspect_space() → dict[str, Any]

Return the public ordered tuning.space inspection artifact.

metric: str = 'rmse'

n_trials: int = 50

pruner: str | None = None

resume: bool = False

sampler: str | None = None

score_data: TuningScoreData | Mapping[str, Any] | tuple[Any, ...] | list[Any] | None = None

seed: int | None = None

space: Mapping[str, Any]

storage: str | None = None

study_name: str | None = None

to_dict() → dict[str, Any]

Return the public mapping consumed by run(tuning=...).

to_tuning_spec() → DagMLTuningSpec

Return the normalized deterministic tuning contract.

winner: TuningWinner | Mapping[str, Any] | None = None

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

workspace_tuning_id: str | None = None

class nirs4all.api.tuning.OrderedSearchSpaceSpec(parameters: tuple[SearchSpaceParameter, ...])

Bases: object

Canonical ordered tuning search space.

This is the P3 bridge between public tuning.space syntax and optimizer adapters. It is intentionally JSON-native and execution-free: adapters can walk parameters in a stable order and produce ParameterPatch records without reparsing public dict syntax.

property fingerprint: str

TCV1 fingerprint of the ordered search-space contract.

classmethod from_mapping(space: Mapping[str, Any], *, context: str = 'run(tuning=...).space') → OrderedSearchSpaceSpec

Normalize a public mapping into deterministic ordered parameters.

classmethod from_tuning_spec(tuning: DagMLTuningSpec) → OrderedSearchSpaceSpec

Build the ordered space from a parsed tuning spec.

parameters: tuple[SearchSpaceParameter, ...]

patch(path: str, value: Any, *, context: str = 'tuning parameter patch') → ParameterPatch

Create a validated patch for one known path.

patches_from_mapping(params: Mapping[str, Any], *, context: str = 'trial params') → tuple[ParameterPatch, ...]

Normalize a candidate mapping into ordered ParameterPatch records.

property paths: tuple[str, ...]

Canonical parameter paths in optimizer iteration order.

to_dict() → dict[str, Any]

Return the deterministic JSON-like ordered search-space form.

to_space_mapping() → dict[str, Any]

Return the canonical DagMLTuningSpec.space mapping.

class nirs4all.api.tuning.ParameterPatch(path: str, segments: tuple[str, ...], value: Any)

Bases: object

One canonical candidate or force-parameter patch.

path: str

segments: tuple[str, ...]

to_dict() → dict[str, Any]

Return the deterministic JSON-like patch form.

value: Any

class nirs4all.api.tuning.SearchSpaceParameter(index: int, path: str, segments: tuple[str, ...], spec: Any)

Bases: object

One ordered, canonical tuning-space parameter.

path is the public patch path consumed by PipelineObjective. The parser accepts both dotted public spelling (ridge.alpha) and sklearn double-underscore spelling (ridge__alpha), then canonicalizes to dotted spelling so Optuna, n4m and native adapters see the same ordered contract.

index: int

path: str

segments: tuple[str, ...]

spec: Any

to_dict() → dict[str, Any]

Return the deterministic JSON-like parameter form.

class nirs4all.api.tuning.TunedSingleEstimatorConformalResult(run: RunResult, calibrated: CalibratedRunResult | PredictResult)

Bases: object

Result bundle returned by tune_single_estimator(..., calibration=...).

calibrated: CalibratedRunResult | PredictResult

property conformal_guarantee_status: dict[str, Any] | None

Guarantee metadata exposed by the calibrated result, when present.

interval(coverage: float) → Any

Return the materialized conformal interval for coverage.

property interval_coverages: tuple[float, ...]

Materialized conformal interval coverages on the calibrated result.

metrics(y_true: Any) → dict[float, Any]

Evaluate materialized conformal intervals against observed targets.

robustness(*, y_true: Any, X: Any | None = None, predictor: Any | None = None, mode: str = 'clean_frozen', scenarios: Sequence[Any] | None = None, slice_by: Sequence[str] | None = None, metadata: Mapping[str, Any] | Sequence[Mapping[str, Any]] | None = None, seed: int | None = None, workspace_path: str | Path | None = None, workspace_name: str = '', workspace_robustness_id: str | None = None, workspace_metadata: Mapping[str, Any] | None = None) → Any

Compute a robustness report from the calibrated prediction result.

run: RunResult

property tuning_best_params: dict[str, Any]

Best native tuning parameters attached to the underlying run.

property tuning_best_value: float | None

Best native tuning objective value attached to the underlying run.

property tuning_id: str | None

Workspace tuning id attached to the underlying run, if persisted.

property tuning_result: TuningResult | None

Native tuning result attached to the underlying run.

class nirs4all.api.tuning.TuningCalibration(y_pred: Any, prediction_sample_ids: Any, coverage: float | Sequence[float] = 0.9, method: str = 'split_absolute_residual', unit: str = 'physical_sample', workspace_conformal_id: str | None = None, workspace_metadata: Mapping[str, ~typing.Any] | None=None, as_predict_result: bool = True, extra: Mapping[str, ~typing.Any]=<factory>)

Bases: object

Typed public conformal calibration payload nested under tuning.

as_predict_result: bool = True

coverage: float | Sequence[float] = 0.9

extra: Mapping[str, Any]

method: str = 'split_absolute_residual'

prediction_sample_ids: Any

to_dict() → dict[str, Any]

Return the public mapping consumed by run(tuning=...).calibration.

unit: str = 'physical_sample'

workspace_conformal_id: str | None = None

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

y_pred: Any

class nirs4all.api.tuning.TuningConformalScoreCalibration(X: Any | None = None, X_calibration: Any = None, features: Any = None, y_true: Any | None = None, y: Any | None = None, y_calibration: Any = None, target: Any = None, targets: Any = None, sample_ids: Any = None, calibration_sample_ids: Any = None, physical_sample_ids: Any = None, groups: Any = None, calibration_groups: Any = None, metadata: Any = None, calibration_metadata: Any = None)

Bases: object

Typed development calibration cohort for conformal-aware tuning scores.

This cohort is used only inside run(tuning=...).score_data to rank candidates with a temporary split conformal calibrator. It is not the final run(..., calibration=...) calibration payload.

X: Any | None = None

X_calibration: Any = None

calibration_groups: Any = None

calibration_metadata: Any = None

calibration_sample_ids: Any = None

features: Any = None

groups: Any = None

metadata: Any = None

physical_sample_ids: Any = None

sample_ids: Any = None

target: Any = None

targets: Any = None

to_dict() → dict[str, Any]

Return the mapping consumed by score_data.conformal_calibration.

y: Any | None = None

y_calibration: Any = None

y_true: Any | None = None

class nirs4all.api.tuning.TuningPassthrough

Bases: object

Typed JSON-native marker for an optional non-final preprocessing step.

Use this in NativeTuning.space when a named preprocessing step should be searchable as a no-op without relying on the raw "passthrough" string.

to_dict() → dict[str, str]

Return the public JSON-native marker consumed by run(tuning=...).

class nirs4all.api.tuning.TuningScoreData(X: Any | None = None, X_score: Any | None = None, y: Any | None = None, y_score: Any | None = None, metric: str | None = None, score_metric: str | None = None, sample_ids: Any = None, score_sample_ids: Any = None, prediction_sample_ids: Any = None, physical_sample_ids: Any = None, groups: Any = None, score_groups: Any = None, metadata: Any = None, score_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 | Sequence[str] | None = None, include_augmented: bool = False, conformal_calibration: TuningConformalScoreCalibration | Mapping[str, Any] | None = None, conformal_coverage: float | None = None)

Bases: object

Typed public score cohort for run(tuning=...).

Use either explicit X/y arrays, a positional tuple at the call site, or an explicit dataset-backed source via dataset + selector. The object serializes to the mapping form consumed by the existing runtime.

X: Any | None = None

X_score: Any | None = None

conformal_calibration: TuningConformalScoreCalibration | Mapping[str, Any] | None = None

conformal_coverage: float | None = None

dataset: Any | None = None

group_column: str | None = None

groups: Any = None

include_augmented: bool = False

metadata: Any = None

metadata_columns: str | Sequence[str] | None = None

metric: str | None = None

physical_sample_ids: Any = None

prediction_sample_ids: Any = None

sample_id_column: str | None = None

sample_ids: Any = None

score_groups: Any = None

score_metadata: Any = None

score_metric: str | None = None

score_sample_ids: Any = None

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

to_dict() → dict[str, Any]

Return the public mapping consumed by run(tuning=...).

y: Any | None = None

y_score: Any | None = None

class nirs4all.api.tuning.TuningWinner(X: Any | None = None, y_true: Any | None = None, score: float | None = None, metric: str | None = None, sample_ids: Any = None, winner_sample_ids: Any = None, prediction_sample_ids: Any = None, physical_sample_ids: Any = None, dataset_name: str = 'tuning_winner', model_name: str | None = None, task_type: str = 'regression', metadata: Mapping[str, Any] | Sequence[Mapping[str, Any]] | None = 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 | Sequence[str] | None = None, include_augmented: bool = False)

Bases: object

Typed public winner projection cohort for run(tuning=...).

X: Any | None = None

dataset: Any | None = None

dataset_name: str = 'tuning_winner'

group_column: str | None = None

include_augmented: bool = False

metadata: Mapping[str, Any] | Sequence[Mapping[str, Any]] | None = None

metadata_columns: str | Sequence[str] | None = None

metric: str | None = None

model_name: str | None = None

physical_sample_ids: Any = None

prediction_sample_ids: Any = None

sample_id_column: str | None = None

sample_ids: Any = None

score: float | None = None

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

task_type: str = 'regression'

to_dict() → dict[str, Any]

Return the public mapping consumed by run(tuning=...).winner.

winner_sample_ids: Any = None

y_true: Any | None = None

nirs4all.api.tuning.get_tuning_space_schema() → dict[str, Any]

Return the JSON Schema for ordered tuning search-space artifacts.

nirs4all.api.tuning.inspect_tuning_space(tuning: DagMLTuningSpec | NativeTuning | Mapping[str, Any]) → dict[str, Any]

Inspect and fingerprint the ordered public tuning search space.

The returned mapping is JSON-native and intended for docs, CLIs, Studio and bindings. It shows the canonical dotted patch paths, deterministic parameter order, optional force_params as decoded ParameterPatch records, the search-space fingerprint and the enclosing tuning-contract fingerprint.

nirs4all.api.tuning.load_workspace_tuning_result(workspace_path: str | Path, tuning_id: str) → TuningResult

Load a verified native DAG-ML tuning result from a nirs4all workspace.

nirs4all.api.tuning.save_workspace_tuning_result(workspace_path: str | Path, result: TuningResult, *, name: str = '', tuning_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) → str

Persist a native DAG-ML tuning result in a nirs4all workspace.

nirs4all.api.tuning.tune_single_estimator(pipeline: Any, X: Any, y: Any, tuning: DagMLTuningSpec | NativeTuning | Mapping[str, Any], *, score_extractor: Callable[[Any], float] | None = None, X_score: Any | None = None, y_score: Any | None = None, score_metric: str | None = None, score_sample_ids: Any = None, score_groups: Any = None, score_metadata: Any = None, sample_ids: Any = None, groups: Any = None, metadata: Any = None, clone_estimator: bool = True, refit: bool = True, workspace_path: str | Path | None = None, workspace_name: str = '', workspace_tuning_id: str | None = None, workspace_metadata: Mapping[str, Any] | None = None, run_id: str | None = None, pipeline_id: str | None = None, chain_id: str | None = None, resume_tuning_result: TuningResult | None = None, resume_tuning_id: str | None = None, per_dataset: Mapping[str, Any] | None = None, winner_x: Any | None = None, winner_y_true: Any | None = None, winner_score: float | None = None, winner_metric: str | None = None, winner_sample_ids: Sequence[Any] | None = None, winner_dataset_name: str = 'tuning_winner', winner_model_name: str | None = None, winner_task_type: str = 'regression', winner_metadata: Mapping[str, Any] | None = None, calibration: TuningCalibration | Mapping[str, Any] | None = None) → RunResult | TunedSingleEstimatorConformalResult

Tune the explicit native linear lane and return a RunResult.

This is the narrow Python surface for the currently implemented native DAG-ML tuning seams. It accepts only the single-estimator and linear transformer→estimator forms supported by compile_pipeline_objective and is not a replacement for the planned full run(tuning=...) pipeline compiler.

Scoring is explicit. Provide exactly one of:

• a custom score_extractor callable;

• explicit X_score/y_score arguments;

• NativeTuning(score_data=...) or a mapping tuning["score_data"].

When a cohort is supplied, the scorer uses score_metric, the metric nested in score_data, or the metric from tuning. Optional scoring identities are validated for row alignment and forwarded to predict() when the fitted estimator accepts those keyword arguments.

nirs4all.api.tuning.tuning_space_schema_json(*, indent: int | None = 2) → str

Serialize the ordered tuning search-space JSON Schema deterministically.