nirs4all.visualization.charts.heatmap module

HeatmapChart - Heatmap visualization of performance across two variables.

CORE LOGIC: 1. Get all predictions 2. Rank predictions by rank_metric on rank_partition using rank_agg 3. Group by (x_var, y_var) 4. For each cell, get display_metric from display_partition using display_agg 5. Normalize per dataset if requested 6. Render with color based on normalized scores

class nirs4all.visualization.charts.heatmap.HeatmapChart(predictions, dataset_name_override: str | None = None, config=None, analyzer: PredictionAnalyzer | None = None)[source]

Bases: BaseChart

Heatmap visualization of performance across two variables.

Supports flexible ranking and display configurations with multiple aggregation strategies.

render(x_var: str, y_var: str, rank_metric: str | None = None, rank_partition: str = 'val', display_metric: str = '', display_partition: str = 'test', figsize: tuple | None = None, normalize: bool = False, rank_agg: str = 'best', display_agg: str = 'mean', show_counts: bool = True, local_scale: bool = False, column_scale: bool = False, aggregate: bool | str | None = None, aggregate_method: str | None = None, aggregate_exclude_outliers: bool | None = None, score_scope: str = 'refit', top_k: int | None = None, sort_by: str | None = None, task_type: str | None = None, **filters) → Figure | list[Figure][source]

Render performance heatmap (Optimized with Polars).

Uses vectorized operations for 20x+ speedup. When aggregate is provided, uses the slower but accurate aggregation path.

Parameters:

  • x_var – Variable for X-axis (columns).

  • y_var – Variable for Y-axis (rows).

  • rank_metric – Metric used for ranking models.

  • rank_partition – Partition used for ranking (‘val’, ‘test’, ‘train’).

  • display_metric – Metric displayed in cells.

  • display_partition – Partition for display metric.

  • figsize – Figure size (auto-computed if None).

  • normalize – Whether to normalize displayed values.

  • rank_agg – Ranking aggregation (‘best’, ‘worst’, ‘mean’, ‘median’).

  • display_agg – Display aggregation strategy.

  • show_counts – Whether to show sample counts.

  • local_scale – If True, use local scale for colors.

  • column_scale – If True, normalize colors per column (best in column = 1.0). Automatically sets local_scale=False when enabled.

  • aggregate – Aggregation mode for sample-level aggregation.

  • aggregate_method – Aggregation method ("mean", "median", or "vote").

  • aggregate_exclude_outliers – Whether grouped aggregation excludes outliers before reducing each group.

  • top_k – If provided, show only top K models. Selection uses Borda count: first keeps top-1 per column, then ranks by Borda count.

  • sort_by – Sorting method for Y-axis (rows). Options: - None: Alphabetical sorting (default). - ‘value’: Sort by ranking score on rank_partition column. - ‘mean’: Sort by mean score across all columns. - ‘median’: Sort by median score across all columns. - ‘borda’: Sort by Borda count (sum of ranks across columns). - ‘condorcet’: Sort by pairwise wins (Copeland method). - ‘consensus’: Sort by consensus (geometric mean of normalized ranks).

  • task_type – If provided, filter predictions to this task type. When None and mixed task types exist, renders separate figures per task type.

  • **filters – Additional filters for predictions.

Returns:

Matplotlib Figure with the heatmap, or a list of Figures when auto-separating by task type.

validate_inputs(x_var: str, y_var: str, rank_metric: str, **kwargs) → None[source]

Validate inputs.