nirs4all.synthesis.environmental module

Environmental effects configuration for synthetic NIRS data generation.

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

Note

For applying environmental effects to spectra, use the operators in nirs4all.operators.augmentation.environmental: - TemperatureAugmenter: Temperature-induced spectral changes - MoistureAugmenter: 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.synthesis.environmental.EnvironmentalEffectsConfig(temperature: TemperatureConfig = <factory>, moisture: MoistureConfig = <factory>, enable_temperature: bool = True, enable_moisture: bool = True)

Bases: object

Combined configuration for all environmental effects.

Variables:

• temperature (nirs4all.synthesis.environmental.TemperatureConfig) – Temperature effect configuration.

• moisture (nirs4all.synthesis.environmental.MoistureConfig) – Moisture effect configuration.

• enable_temperature (bool) – Whether to apply temperature effects.

• enable_moisture (bool) – Whether to apply moisture effects.

enable_moisture: bool = True

enable_temperature: bool = True

moisture: MoistureConfig

temperature: TemperatureConfig

class nirs4all.synthesis.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)

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

Variables:

• water_activity (float) – Water activity (a_w) value (0.0 to 1.0).

• moisture_content (float) – Moisture content as fraction (optional, for intensity).

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

• bound_water_shift (float) – Wavelength shift for bound water relative to free (nm).

• temperature_interaction (bool) – Whether moisture effects interact with temperature.

• reference_aw (float) – Reference water activity for baseline.

__post_init__()

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.synthesis.environmental.SpectralRegion(value)

Bases: StrEnum

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

Bases: object

Configuration for temperature effect simulation.

Variables:

• reference_temperature (float) – Reference temperature in °C (typically 25°C).

• sample_temperature (float) – Actual sample temperature in °C.

• temperature_variation (float) – Sample-to-sample temperature variation (std dev in °C).

• enable_shift (bool) – Whether to apply wavelength shifts.

• enable_intensity (bool) – Whether to apply intensity changes.

• enable_broadening (bool) – Whether to apply band broadening.

• region_specific (bool) – Whether to use region-specific parameters.

• custom_regions (dict[nirs4all.synthesis.environmental.SpectralRegion, nirs4all.synthesis.environmental.TemperatureEffectParams] | None) – Optional custom region parameters to override defaults.

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.synthesis.environmental.TemperatureEffectParams(wavelength_range: tuple[float, float], shift_per_degree: float, intensity_change_per_degree: float, broadening_per_degree: float, reference: str = '')

Bases: object

Temperature effect parameters for a spectral region.

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

Variables:

• wavelength_range (tuple[float, float]) – Affected wavelength range (nm).

• shift_per_degree (float) – Peak position shift per °C (nm). Negative = blue shift.

• intensity_change_per_degree (float) – Fractional intensity change per °C.

• broadening_per_degree (float) – Fractional bandwidth increase per °C.

• reference (str) – Literature reference for values.

broadening_per_degree: float

intensity_change_per_degree: float

reference: str = ''

shift_per_degree: float

wavelength_range: tuple[float, float]

nirs4all.synthesis.environmental.get_temperature_effect_regions() → dict[str, tuple[float, float]]

Get the wavelength regions with significant temperature effects.

Returns:

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