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)

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: str | None = None, top_k: int | None = None, sort_by_value: bool = False, sort_by: str | None = None, **filters) → Figure

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 column for sample-level aggregation.

• 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_value – If True, sort Y-axis by ranking score (best first) instead of alphabetically. Uses rank_metric on rank_partition. Deprecated: use sort_by=’value’ instead.

• 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).

• **filters – Additional filters for predictions.

Returns:

Matplotlib Figure with the heatmap.

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

Validate inputs.