nirs4all.data.synthetic.environmental module

Environmental effects simulation for synthetic NIRS data generation.

This module provides simulation of environmental and matrix effects on NIR spectra, including temperature-induced changes and moisture/water activity effects.

Key Features:

Temperature-dependent peak shifts (especially O-H bands)
Temperature-dependent intensity changes (hydrogen bonding effects)
Temperature-dependent band broadening (thermal motion)
Region-specific temperature effects (water vs. C-H bands)
Moisture/water activity effects on hydrogen bonding
Free water vs. bound water band differentiation

References

Maeda, H., Ozaki, Y., Tanaka, M., Hayashi, N., & Kojima, T. (1995). Near infrared spectroscopy and chemometrics studies of temperature-dependent spectral variations of water. Journal of Near Infrared Spectroscopy, 3(4), 191-201.
Segtnan, V. H., Šašić, Š., Isaksson, T., & Ozaki, Y. (2001). Studies on the structure of water using two-dimensional near-infrared correlation spectroscopy and principal component analysis. Analytical Chemistry, 73(13), 3153-3161.
Büning-Pfaue, H. (2003). Analysis of water in food by near infrared spectroscopy. Food Chemistry, 82(1), 107-115.
Luck, W. A. P. (1998). The importance of cooperativity for the properties of liquid water. Journal of Molecular Structure, 448(2-3), 131-142.

class nirs4all.data.synthetic.environmental.EnvironmentalEffectsConfig(temperature: ~nirs4all.data.synthetic.environmental.TemperatureConfig = <factory>, moisture: ~nirs4all.data.synthetic.environmental.MoistureConfig = <factory>, enable_temperature: bool = True, enable_moisture: bool = True)[source]

Bases: object

Combined configuration for all environmental effects.

temperature

Temperature effect configuration.

Type:: nirs4all.data.synthetic.environmental.TemperatureConfig

moisture

Moisture effect configuration.

Type:: nirs4all.data.synthetic.environmental.MoistureConfig

enable_temperature

Whether to apply temperature effects.

Type:: bool

enable_moisture

Whether to apply moisture effects.

Type:: bool

enable_moisture: bool = True

enable_temperature: bool = True

moisture: MoistureConfig

temperature: TemperatureConfig

class nirs4all.data.synthetic.environmental.EnvironmentalEffectsSimulator(config: EnvironmentalEffectsConfig | None = None, random_state: int | None = None)[source]

Bases: object

Combined simulator for all environmental effects.

Applies temperature and moisture effects in the correct order with proper interactions.

config: Environmental effects configuration.

temperature_sim: Temperature effect simulator.

moisture_sim: Moisture effect simulator.

rng: Random number generator.

Example

>>> config = EnvironmentalEffectsConfig(
...     temperature=TemperatureConfig(sample_temperature=40.0),
...     moisture=MoistureConfig(water_activity=0.7)
... )
>>> simulator = EnvironmentalEffectsSimulator(config, random_state=42)
>>> spectra_out = simulator.apply(spectra, wavelengths)

apply(spectra: ndarray, wavelengths: ndarray, sample_temperatures: ndarray | None = None, water_activities: ndarray | None = None) → ndarray[source]

Apply all environmental effects to spectra.

Effects are applied in order: 1. Moisture effects (with temperature interaction) 2. Temperature effects

Parameters:

spectra – Input spectra array (n_samples, n_wavelengths).
wavelengths – Wavelength array in nm.
sample_temperatures – Optional per-sample temperatures.
water_activities – Optional per-sample water activities.

Returns:

Modified spectra with all environmental effects applied.

class nirs4all.data.synthetic.environmental.MoistureConfig(water_activity: float = 0.5, moisture_content: float = 0.1, free_water_fraction: float = 0.3, bound_water_shift: float = 25.0, temperature_interaction: bool = True, reference_aw: float = 0.5)[source]

Bases: object

Configuration for moisture/water activity effect simulation.

Moisture affects NIR spectra through: - Direct water absorption bands - Hydrogen bonding with sample matrix - Free vs. bound water ratio

water_activity

Water activity (a_w) value (0.0 to 1.0).

Type:: float

moisture_content

Moisture content as fraction (optional, for intensity).

Type:: float

free_water_fraction

Fraction of water that is “free” vs. bound (0-1).

Type:: float

bound_water_shift

Wavelength shift for bound water relative to free (nm).

Type:: float

temperature_interaction

Whether moisture effects interact with temperature.

Type:: bool

reference_aw

Reference water activity for baseline.

Type:: float

__post_init__()[source]: Validate water activity range.

bound_water_shift: float = 25.0

free_water_fraction: float = 0.3

moisture_content: float = 0.1

reference_aw: float = 0.5

temperature_interaction: bool = True

water_activity: float = 0.5

class nirs4all.data.synthetic.environmental.MoistureEffectSimulator(config: MoistureConfig | None = None, random_state: int | None = None)[source]

Bases: object

Simulate moisture and water activity effects on NIR spectra.

Water in samples exists in different states: - Free water: bulk water with normal O-H bands - Bound water: hydrogen-bonded to matrix, shifted peaks

The ratio of free to bound water depends on water activity (a_w), temperature, and sample matrix composition.

config: Moisture effect configuration.

rng: Random number generator.

Example

>>> config = MoistureConfig(
...     water_activity=0.7,
...     moisture_content=0.15,
...     free_water_fraction=0.4
... )
>>> simulator = MoistureEffectSimulator(config, random_state=42)
>>> spectra_out = simulator.apply(spectra, wavelengths)

apply(spectra: ndarray, wavelengths: ndarray, water_activities: ndarray | None = None, temperature_offset: float = 0.0) → ndarray[source]

Apply moisture effects to spectra.

Parameters:

spectra – Input spectra array (n_samples, n_wavelengths).
wavelengths – Wavelength array in nm.
water_activities – Optional per-sample water activity values.
temperature_offset – Temperature offset from reference (affects water state).

Returns:

Modified spectra with moisture effects applied.

get_water_band_positions(free_fraction: float) → Dict[str, Tuple[float, float]][source]

Get expected water band positions for given free/bound ratio.

Parameters:: free_fraction – Fraction of water that is free (0-1).
Returns:: Dictionary with band names and (free_position, effective_position).

class nirs4all.data.synthetic.environmental.SpectralRegion(value)[source]

Bases: str, Enum

NIR spectral regions with distinct temperature responses.

CH_COMBINATION = 'ch_combination'

CH_FIRST_OVERTONE = 'ch_1st_overtone'

NH_COMBINATION = 'nh_combination'

NH_FIRST_OVERTONE = 'nh_1st_overtone'

OH_COMBINATION = 'oh_combination'

OH_FIRST_OVERTONE = 'oh_1st_overtone'

WATER_BOUND = 'water_bound'

WATER_FREE = 'water_free'

class nirs4all.data.synthetic.environmental.TemperatureConfig(reference_temperature: float = 25.0, sample_temperature: float = 25.0, temperature_variation: float = 0.0, enable_shift: bool = True, enable_intensity: bool = True, enable_broadening: bool = True, region_specific: bool = True, custom_regions: Dict[SpectralRegion, TemperatureEffectParams] | None = None)[source]

Bases: object

Configuration for temperature effect simulation.

reference_temperature

Reference temperature in °C (typically 25°C).

Type:: float

sample_temperature

Actual sample temperature in °C.

Type:: float

temperature_variation

Sample-to-sample temperature variation (std dev in °C).

Type:: float

enable_shift

Whether to apply wavelength shifts.

Type:: bool

enable_intensity

Whether to apply intensity changes.

Type:: bool

enable_broadening

Whether to apply band broadening.

Type:: bool

region_specific

Whether to use region-specific parameters.

Type:: bool

custom_regions

Optional custom region parameters to override defaults.

Type:: Dict[nirs4all.data.synthetic.environmental.SpectralRegion, nirs4all.data.synthetic.environmental.TemperatureEffectParams] | None

custom_regions: Dict[SpectralRegion, TemperatureEffectParams] | None = None

property delta_temperature: float: Temperature difference from reference.

enable_broadening: bool = True

enable_intensity: bool = True

enable_shift: bool = True

reference_temperature: float = 25.0

region_specific: bool = True

sample_temperature: float = 25.0

temperature_variation: float = 0.0

class nirs4all.data.synthetic.environmental.TemperatureEffectParams(wavelength_range: Tuple[float, float], shift_per_degree: float, intensity_change_per_degree: float, broadening_per_degree: float, reference: str = '')[source]

Bases: object

Temperature effect parameters for a spectral region.

Based on literature values for temperature-induced spectral changes in NIR.

wavelength_range

Affected wavelength range (nm).

Type:: Tuple[float, float]

shift_per_degree

Peak position shift per °C (nm). Negative = blue shift.

Type:: float

intensity_change_per_degree

Fractional intensity change per °C.

Type:: float

broadening_per_degree

Fractional bandwidth increase per °C.

Type:: float

reference

Literature reference for values.

Type:: str

broadening_per_degree: float

intensity_change_per_degree: float

reference: str = ''

shift_per_degree: float

wavelength_range: Tuple[float, float]

class nirs4all.data.synthetic.environmental.TemperatureEffectSimulator(config: TemperatureConfig | None = None, random_state: int | None = None)[source]

Bases: object

Simulate temperature-dependent spectral changes.

Temperature affects NIR spectra through: - Peak position shifts (especially hydrogen-bonded groups) - Intensity changes (hydrogen bond population changes) - Band broadening (thermal motion)

The effects are strongest for O-H and N-H groups due to their involvement in hydrogen bonding. C-H groups show smaller effects.

config: Temperature effect configuration.

rng: Random number generator for reproducibility.

Example

>>> config = TemperatureConfig(
...     sample_temperature=40.0,
...     reference_temperature=25.0
... )
>>> simulator = TemperatureEffectSimulator(config, random_state=42)
>>> spectra_out = simulator.apply(spectra, wavelengths)

apply(spectra: ndarray, wavelengths: ndarray, sample_temperatures: ndarray | None = None) → ndarray[source]

Apply temperature effects to spectra.

Parameters:

spectra – Input spectra array (n_samples, n_wavelengths).
wavelengths – Wavelength array in nm.
sample_temperatures – Optional per-sample temperatures. If None, uses config.sample_temperature with variation.

Returns:

Modified spectra with temperature effects applied.

nirs4all.data.synthetic.environmental.apply_moisture_effects(spectra: ndarray, wavelengths: ndarray, water_activity: float = 0.5, moisture_content: float = 0.1, random_state: int | None = None) → ndarray[source]

Apply moisture effects to spectra with simple API.

Parameters:

spectra – Input spectra (n_samples, n_wavelengths).
wavelengths – Wavelength array (nm).
water_activity – Water activity (0-1).
moisture_content – Moisture content fraction.
random_state – Random seed.

Returns:

Spectra with moisture effects applied.

Example

>>> # Simulate wet sample (high water activity)
>>> spectra_wet = apply_moisture_effects(spectra, wavelengths, water_activity=0.9)

nirs4all.data.synthetic.environmental.apply_temperature_effects(spectra: ndarray, wavelengths: ndarray, temperature: float = 25.0, reference_temperature: float = 25.0, random_state: int | None = None) → ndarray[source]

Apply temperature effects to spectra with simple API.

Parameters:

spectra – Input spectra (n_samples, n_wavelengths).
wavelengths – Wavelength array (nm).
temperature – Sample temperature in °C.
reference_temperature – Reference temperature in °C.
random_state – Random seed.

Returns:

Spectra with temperature effects applied.

Example

>>> # Simulate spectra measured at 40°C
>>> spectra_40c = apply_temperature_effects(spectra, wavelengths, temperature=40.0)

nirs4all.data.synthetic.environmental.get_temperature_effect_regions() → Dict[str, Tuple[float, float]][source]

Get the wavelength regions with significant temperature effects.

Returns:: Dictionary mapping region names to (start, end) wavelength tuples.

nirs4all.data.synthetic.environmental.simulate_temperature_series(spectrum: ndarray, wavelengths: ndarray, temperatures: List[float], reference_temperature: float = 25.0, random_state: int | None = None) → ndarray[source]

Generate a series of spectra at different temperatures.

Useful for simulating temperature studies or generating training data for temperature-robust models.

Parameters:

spectrum – Single reference spectrum (n_wavelengths,).
wavelengths – Wavelength array (nm).
temperatures – List of temperatures to simulate.
reference_temperature – Reference temperature for the input spectrum.
random_state – Random seed.

Returns:

Array of spectra (n_temperatures, n_wavelengths).

Example

>>> temps = [20, 25, 30, 35, 40]
>>> temp_series = simulate_temperature_series(spectrum, wavelengths, temps)