nirs4all.utils.header_units module

Centralized header unit utilities for consistent handling across the codebase.

This module provides a single source of truth for: - Axis labels based on header unit type - X-values extraction from headers - Axis orientation (for wavenumber inversion)

All visualization code should use these utilities instead of inline logic.

nirs4all.utils.header_units.apply_x_axis_limits(ax, x_values: ndarray) → None

Apply appropriate x-axis limits to preserve data ordering.

Matplotlib may auto-sort axis values. This function sets explicit limits to preserve the original ordering (ascending or descending).

Parameters:

• ax – Matplotlib Axes object

• x_values – Array of x-axis values

nirs4all.utils.header_units.get_axis_label(unit: str | HeaderUnit) → str

Get the appropriate axis label for a given unit type.

Parameters:

unit – Header unit type (string like “cm-1”, “nm” or HeaderUnit enum)

Returns:

Human-readable axis label string

Examples

>>> get_axis_label("cm-1")
'Wavenumber (cm⁻¹)'
>>> get_axis_label(HeaderUnit.WAVELENGTH)
'Wavelength (nm)'
>>> get_axis_label("unknown")  # Falls back gracefully
'Features'

nirs4all.utils.header_units.get_x_values_and_label(headers: List[str] | None, header_unit: str | HeaderUnit, n_features: int) → Tuple[ndarray, str]

Get x-axis values and label from headers and unit.

This is the main utility function for chart x-axis setup. It handles: - Numeric headers (wavelengths/wavenumbers) → parsed float array - Non-numeric headers → fallback to indices - Missing or mismatched headers → fallback to indices

Parameters:

• headers – List of header strings (wavelengths, feature names, etc.)

• header_unit – Header unit type (“cm-1”, “nm”, “none”, “text”, “index”)

• n_features – Number of features (for fallback and validation)

Returns:

Tuple of (x_values array, axis_label string)

Examples

>>> x_vals, label = get_x_values_and_label(["4000", "4500", "5000"], "cm-1", 3)
>>> x_vals
array([4000., 4500., 5000.])
>>> label
'Wavenumber (cm⁻¹)'

>>> x_vals, label = get_x_values_and_label(None, "cm-1", 5)
>>> x_vals
array([0, 1, 2, 3, 4])
>>> label
'Features'

nirs4all.utils.header_units.should_invert_x_axis(x_values: ndarray) → bool

Check if x-axis should be inverted (for wavenumber convention).

In spectroscopy, wavenumber (cm⁻¹) axes are often displayed in descending order (high to low) if the data is ordered that way.

Parameters:

x_values – Array of x-axis values

Returns:

True if x_values are in descending order and should be displayed as such