nirs4all.api.inspector_views module

Read-only Inspector result views owned by nirs4all, independent of transports.

The view algorithms were moved from Studio so the native product can request scientific diagnostics through its bounded library host without an HTTP backend.

class nirs4all.api.inspector_views.BiasVarianceEntry(*, group_label: str, bias_squared: float | None = None, variance: float | None = None, total_error: float | None = None, n_chains: int = 0, n_folds: int = 0, n_samples: int = 0, chain_ids: list[str] = [])

Bases: _StrictModel

One group’s bias-variance decomposition.

bias_squared: float | None

chain_ids: list[str]

group_label: str

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

n_chains: int

n_folds: int

n_samples: int

total_error: float | None

variance: float | None

class nirs4all.api.inspector_views.BiasVarianceRequest(*, chain_ids: list[str], score_column: str = 'cv_val_score', score_ref: ScoreRef | None = None, group_by: str = 'model_class')

Bases: _StrictModel

Request body for /inspector/bias-variance.

chain_ids: list[str]

group_by: str

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

score_column: str

score_ref: ScoreRef | None

class nirs4all.api.inspector_views.BiasVarianceResponse(*, entries: list[dict[str, Any]], score_column: str, group_by: str, reason: str | None = None)

Bases: _StrictModel

Response for /inspector/bias-variance.

entries: list[dict[str, Any]]

group_by: str

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

reason: str | None

score_column: str

class nirs4all.api.inspector_views.BranchComparisonEntry(*, branch_path: str, label: str, mean: float, std: float, min: float, max: float, ci_lower: float, ci_upper: float, count: int, chain_ids: list[str])

Bases: _StrictModel

A single branch comparison entry.

branch_path: str

chain_ids: list[str]

ci_lower: float

ci_upper: float

count: int

label: str

max: float

mean: float

min: float

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

std: float

class nirs4all.api.inspector_views.BranchComparisonRequest(*, run_id: list[str] | None = None, dataset_name: list[str] | None = None, score_column: str = 'cv_val_score')

Bases: _StrictModel

Request body for /inspector/branch-comparison.

dataset_name: list[str] | None

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

run_id: list[str] | None

score_column: str

class nirs4all.api.inspector_views.BranchComparisonResponse(*, branches: list[dict[str, Any]], score_column: str, total_chains: int)

Bases: _StrictModel

Response for /inspector/branch-comparison.

branches: list[dict[str, Any]]

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

score_column: str

total_chains: int

class nirs4all.api.inspector_views.BranchTopologyResponse(*, nodes: list[dict[str, Any]], pipeline_id: str, pipeline_name: str, has_stacking: bool, has_branches: bool, max_depth: int)

Bases: _StrictModel

Response for /inspector/branch-topology.

has_branches: bool

has_stacking: bool

max_depth: int

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

nodes: list[dict[str, Any]]

pipeline_id: str

pipeline_name: str

class nirs4all.api.inspector_views.CandlestickCategory(*, label: str, min: float, q25: float, median: float, q75: float, max: float, mean: float, count: int, outlier_values: list[float], chain_ids: list[str])

Bases: _StrictModel

Box-plot statistics for a single category.

chain_ids: list[str]

count: int

label: str

max: float

mean: float

median: float

min: float

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

outlier_values: list[float]

q25: float

q75: float

class nirs4all.api.inspector_views.CandlestickRequest(*, run_id: list[str] | None = None, dataset_name: list[str] | None = None, category_variable: str = 'model_class', score_column: str = 'cv_val_score')

Bases: _StrictModel

Request body for /inspector/candlestick.

category_variable: str

dataset_name: list[str] | None

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

run_id: list[str] | None

score_column: str

class nirs4all.api.inspector_views.CandlestickResponse(*, categories: list[dict[str, Any]], category_variable: str, score_column: str)

Bases: _StrictModel

Response for /inspector/candlestick.

categories: list[dict[str, Any]]

category_variable: str

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

score_column: str

class nirs4all.api.inspector_views.ConfusionMatrixCell(*, true_label: str, pred_label: str, count: int, normalized: float | None = None)

Bases: _StrictModel

A single cell in the confusion matrix.

count: int

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

normalized: float | None

pred_label: str

true_label: str

class nirs4all.api.inspector_views.ConfusionMatrixRequest(*, chain_ids: list[str], partition: str = 'val', normalize: str = 'none', target_index: Annotated[int, Ge(ge=0)] = 0)

Bases: _StrictModel

Request body for /inspector/confusion.

chain_ids: list[str]

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

normalize: str

partition: str

target_index: int

class nirs4all.api.inspector_views.ConfusionMatrixResponse(*, cells: list[dict[str, Any]], labels: list[str], total_samples: int, partition: str, normalize: str, reason: str | None = None)

Bases: _StrictModel

Response for /inspector/confusion.

cells: list[dict[str, Any]]

labels: list[str]

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

normalize: str

partition: str

reason: str | None

total_samples: int

class nirs4all.api.inspector_views.FoldScoreEntry(*, chain_id: str, model_class: str, preprocessings: str | None = None, fold_id: str, fold_index: int, score: float)

Bases: _StrictModel

A single fold score entry.

chain_id: str

fold_id: str

fold_index: int

model_class: str

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

preprocessings: str | None

score: float

class nirs4all.api.inspector_views.FoldStabilityRequest(*, chain_ids: list[str], score_column: str = 'cv_val_score', score_ref: ScoreRef | None = None, partition: str = 'val')

Bases: _StrictModel

Request body for /inspector/fold-stability.

chain_ids: list[str]

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

partition: str

score_column: str

score_ref: ScoreRef | None

class nirs4all.api.inspector_views.FoldStabilityResponse(*, entries: list[dict[str, Any]], fold_ids: list[str], score_column: str, total_chains: int)

Bases: _StrictModel

Response for /inspector/fold-stability.

entries: list[dict[str, Any]]

fold_ids: list[str]

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

score_column: str

total_chains: int

class nirs4all.api.inspector_views.HeatmapCell(*, x_label: str, y_label: str, value: float | None = None, count: int, chain_ids: list[str])

Bases: _StrictModel

A single heatmap cell.

chain_ids: list[str]

count: int

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

value: float | None

x_label: str

y_label: str

class nirs4all.api.inspector_views.HeatmapRequest(*, run_id: list[str] | None = None, dataset_name: list[str] | None = None, x_variable: str = 'model_class', y_variable: str = 'preprocessings', score_column: str = 'cv_val_score', aggregate: str = 'best')

Bases: _StrictModel

Request body for /inspector/heatmap.

aggregate: str

dataset_name: list[str] | None

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

run_id: list[str] | None

score_column: str

x_variable: str

y_variable: str

class nirs4all.api.inspector_views.HeatmapResponse(*, cells: list[dict[str, Any]], x_labels: list[str], y_labels: list[str], x_variable: str, y_variable: str, score_column: str, min_value: float | None = None, max_value: float | None = None)

Bases: _StrictModel

Response for /inspector/heatmap.

cells: list[dict[str, Any]]

max_value: float | None

min_value: float | None

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

score_column: str

x_labels: list[str]

x_variable: str

y_labels: list[str]

y_variable: str

class nirs4all.api.inspector_views.HistogramBin(*, bin_start: float, bin_end: float, count: int, chain_ids: list[str])

Bases: _StrictModel

A single histogram bin.

bin_end: float

bin_start: float

chain_ids: list[str]

count: int

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class nirs4all.api.inspector_views.HistogramResponse(*, bins: list[HistogramBin], score_column: str, total_chains: int, min_score: float | None = None, max_score: float | None = None, mean_score: float | None = None)

Bases: _StrictModel

Response for /inspector/histogram.

bins: list[HistogramBin]

max_score: float | None

mean_score: float | None

min_score: float | None

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

score_column: str

total_chains: int

class nirs4all.api.inspector_views.HyperparameterPoint(*, chain_id: str, param_value: float, score: float, model_class: str)

Bases: _StrictModel

One chain’s hyperparameter value + score.

chain_id: str

model_class: str

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

param_value: float

score: float

class nirs4all.api.inspector_views.HyperparameterRequest(*, run_id: list[str] | None = None, dataset_name: list[str] | None = None, param_name: str, score_column: str = 'cv_val_score')

Bases: _StrictModel

Request body for /inspector/hyperparameter.

dataset_name: list[str] | None

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

param_name: str

run_id: list[str] | None

score_column: str

class nirs4all.api.inspector_views.HyperparameterResponse(*, points: list[dict[str, Any]], param_name: str, score_column: str, available_params: list[str], reason: str | None = None)

Bases: _StrictModel

Response for /inspector/hyperparameter.

available_params: list[str]

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

param_name: str

points: list[dict[str, Any]]

reason: str | None

score_column: str

class nirs4all.api.inspector_views.InspectorDataResponse(*, chains: list[dict[str, ~typing.Any]], total: int, available_metrics: list[str], available_models: list[str], available_datasets: list[str], available_runs: list[str], available_preprocessings: list[str], available_targets: list[dict[str, ~typing.Any]] = <factory>, generated_at: str)

Bases: _StrictModel

Response for /inspector/data.

available_datasets: list[str]

available_metrics: list[str]

available_models: list[str]

available_preprocessings: list[str]

available_runs: list[str]

available_targets: list[dict[str, Any]]

chains: list[dict[str, Any]]

generated_at: str

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

total: int

exception nirs4all.api.inspector_views.InspectorViewError(*, status_code: int, detail: str)

Bases: ValueError

class nirs4all.api.inspector_views.PreprocessingImpactEntry(*, step_name: str, impact: float | None = None, mean_with: float | None = None, mean_without: float | None = None, count_with: int = 0, count_without: int = 0)

Bases: _StrictModel

One preprocessing step’s impact on score.

count_with: int

count_without: int

impact: float | None

mean_with: float | None

mean_without: float | None

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

step_name: str

class nirs4all.api.inspector_views.PreprocessingImpactRequest(*, run_id: list[str] | None = None, dataset_name: list[str] | None = None, score_column: str = 'cv_val_score')

Bases: _StrictModel

Request body for /inspector/preprocessing-impact.

dataset_name: list[str] | None

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

run_id: list[str] | None

score_column: str

class nirs4all.api.inspector_views.PreprocessingImpactResponse(*, entries: list[dict[str, Any]], score_column: str, total_chains: int)

Bases: _StrictModel

Response for /inspector/preprocessing-impact.

entries: list[dict[str, Any]]

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

score_column: str

total_chains: int

class nirs4all.api.inspector_views.RankingsResponse(*, rankings: list[dict[str, Any]], total: int, score_column: str, sort_ascending: bool)

Bases: _StrictModel

Response for /inspector/rankings.

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

rankings: list[dict[str, Any]]

score_column: str

sort_ascending: bool

total: int

class nirs4all.api.inspector_views.ScatterPoint(*, chain_id: str, model_class: str, model_name: str | None = None, preprocessings: str | None = None, y_true: list[float], y_pred: list[float], sample_indices: list[int] | None = None, fold_id: str | None = None, score: float | None = None)

Bases: _StrictModel

A single chain’s scatter data.

chain_id: str

fold_id: str | None

model_class: str

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_name: str | None

preprocessings: str | None

sample_indices: list[int] | None

score: float | None

y_pred: list[float]

y_true: list[float]

class nirs4all.api.inspector_views.ScatterRequest(*, chain_ids: list[str], partition: str = 'val', target_index: Annotated[int, Ge(ge=0)] = 0)

Bases: _StrictModel

Request body for /inspector/scatter.

chain_ids: list[str]

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

partition: str

target_index: int

class nirs4all.api.inspector_views.ScatterResponse(*, points: list[ScatterPoint], partition: str, total_samples: int)

Bases: _StrictModel

Response for /inspector/scatter.

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

partition: str

points: list[ScatterPoint]

total_samples: int

class nirs4all.api.inspector_views.ScoreRef(*, key: str | None = None, metric: str | None = None, protocol: str | None = None, partition: str | None = None, aggregation: str | None = None, legacyScoreColumn: str | None = None, legacy_score_column: str | None = None, **extra_data: Any)

Bases: _StrictModel

Structured score identifier accepted alongside legacy score_column.

aggregation: str | None

key: str | None

legacyScoreColumn: str | None

legacy_score_column: str | None

metric: str | None

model_config = {'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

partition: str | None

protocol: str | None

class nirs4all.api.inspector_views.TopologyNode(*, id: str, label: str, type: str, depth: int, branch_path: list[int], metrics: dict[str, Any] | None = None, children: list[dict[str, Any]] | None = None, chain_ids: list[str] | None = None)

Bases: _StrictModel

A single node in the pipeline topology DAG.

branch_path: list[int]

chain_ids: list[str] | None

children: list[dict[str, Any]] | None

depth: int

id: str

label: str

metrics: dict[str, Any] | None

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

type: str

nirs4all.api.inspector_views.get_bias_variance(request: BiasVarianceRequest)

Bias-variance decomposition grouped by a chain field.

For each group, collects fold-level predictions across chains. Per sample appearing in 2+ folds:

bias² = (mean_pred - y_true)² variance = Var(y_pred across folds)

Aggregated per group: mean_bias², mean_variance, total_error.

nirs4all.api.inspector_views.get_branch_comparison(request: BranchComparisonRequest)

Branch comparison: mean score with CI per branch.

Groups chains by branch_path and computes descriptive statistics including 95% confidence intervals for each branch.

nirs4all.api.inspector_views.get_branch_topology(pipeline_id: str, score_column: str = 'cv_val_score', score_ref: str | None = None)

Pipeline topology: DAG structure with metrics overlay.

Uses nirs4all.pipeline.analysis.topology.analyze_topology() to parse the expanded pipeline config into a tree of nodes.

nirs4all.api.inspector_views.get_candlestick_data(request: CandlestickRequest)

Box-plot statistics per category.

Groups chains by category_variable and computes min, Q25, median, Q75, max, mean, and IQR-based outliers for the chosen score column.

nirs4all.api.inspector_views.get_confusion_matrix(request: ConfusionMatrixRequest)

Confusion matrix for classification chains.

Aggregates y_true/y_pred from fold-level predictions across the selected chains and computes the confusion matrix with optional normalization (by row=recall, column=precision, or all).

nirs4all.api.inspector_views.get_fold_stability(request: FoldStabilityRequest)

Per-fold score stability for selected chains.

For each chain, retrieves fold-level predictions and extracts the score for the requested partition.

nirs4all.api.inspector_views.get_heatmap_data(request: HeatmapRequest)

Performance heatmap: aggregated score at intersection of two variables.

Groups chains by (x_variable, y_variable) and aggregates score_column using the requested aggregation method (best/mean/median/worst).

nirs4all.api.inspector_views.get_histogram_data(run_id: list[str] | None = None, dataset_name: list[str] | None = None, score_column: str = 'cv_val_score', n_bins: int = 20)

Score distribution histogram.

Computes histogram bins from chain summary scores and includes chain_ids per bin for click-to-select functionality.

nirs4all.api.inspector_views.get_hyperparameter_data(request: HyperparameterRequest)

Get hyperparameter value vs score scatter data.

Extracts numeric values of the requested param_name from each chain’s variant params, paired with the chain’s score.

nirs4all.api.inspector_views.get_inspector_data(run_id: list[str] | None = None, dataset_name: list[str] | None = None, model_class: list[str] | None = None, preprocessings: list[str] | None = None, task_type: str | None = None, metric: str | None = None)

Load chain summaries and metadata for the Inspector.

Returns all matching chains plus lists of unique values for populating filter bar dropdowns (metrics, models, datasets, runs, preprocessings). Supports multi-value filters via repeated query params.

nirs4all.api.inspector_views.get_preprocessing_impact(request: PreprocessingImpactRequest)

Analyse the impact of each preprocessing step on the score.

For each unique preprocessing step found across chains, computes the mean score of chains with vs without that step, and the impact (difference). Sign is flipped for lower-is-better metrics.

nirs4all.api.inspector_views.get_rankings_data(run_id: list[str] | None = None, dataset_name: list[str] | None = None, score_column: str = 'cv_val_score', sort_ascending: bool | None = None, limit: int = 50, offset: int = 0)

Ranked chain summaries.

Returns chains sorted by the chosen score column, with rank numbers. Sort direction is auto-detected from the metric (lower-better for RMSE, etc.).

nirs4all.api.inspector_views.get_scatter_data(request: ScatterRequest)

Get y_true/y_pred arrays for scatter visualization.

For each chain_id, loads the fold-level predictions matching the requested partition and concatenates the arrays.

nirs4all.api.inspector_views.read_inspector_view(operation: str, workspace_path: str, request: dict[str, Any]) → dict[str, Any]

Read one validated view from an explicit read-only workspace snapshot.