nirs4all.synthesis.measurement_modes module

Measurement mode simulation for synthetic NIRS data generation.

This module provides simulation of different NIR measurement geometries and their associated physics. The relationship between absorption coefficients and observed signal varies significantly with measurement mode.

Supported Measurement Modes:

Transmittance: Beer-Lambert law, direct transmission
Diffuse Reflectance: Kubelka-Munk theory for scattering samples
Transflectance: Double-pass transmission with mirror backing
ATR: Attenuated Total Reflectance with wavelength-dependent penetration

References

Kubelka, P. (1948). New contributions to the optics of intensely light-scattering materials. Part I. JOSA, 38(5), 448-457.
Burns, D. A., & Ciurczak, E. W. (2007). Handbook of Near-Infrared Analysis. CRC Press.
Harrick, N. J. (1967). Internal Reflection Spectroscopy. Wiley.
Dahm, D. J., & Dahm, K. D. (2007). Interpreting Diffuse Reflectance and Transmittance. NIR Publications.

class nirs4all.synthesis.measurement_modes.ATRConfig(crystal_material: str = 'diamond', crystal_refractive_index: float = 2.4, incidence_angle: float = 45.0, n_reflections: int = 1, sample_refractive_index: float = 1.5)[source]

Bases: object

Configuration for Attenuated Total Reflectance mode.

ATR uses internal reflection within a high-refractive-index crystal. The evanescent wave penetrates into the sample, with penetration depth depending on wavelength.

crystal_material

ATR crystal material.

Type:: str

crystal_refractive_index

Refractive index of crystal.

Type:: float

incidence_angle

Angle of incidence (degrees).

Type:: float

n_reflections

Number of internal reflections.

Type:: int

sample_refractive_index

Approximate refractive index of sample.

Type:: float

crystal_material: str = 'diamond'

crystal_refractive_index: float = 2.4

incidence_angle: float = 45.0

n_reflections: int = 1

sample_refractive_index: float = 1.5

class nirs4all.synthesis.measurement_modes.MeasurementMode(value)[source]

Bases: str, Enum

Types of NIR measurement geometries.

ATR = 'atr'

FIBER_OPTIC = 'fiber_optic'

INTERACTANCE = 'interactance'

REFLECTANCE = 'reflectance'

TRANSFLECTANCE = 'transflectance'

TRANSMITTANCE = 'transmittance'

class nirs4all.synthesis.measurement_modes.MeasurementModeConfig(mode: MeasurementMode = MeasurementMode.TRANSMITTANCE, transmittance: TransmittanceConfig = <factory>, reflectance: ReflectanceConfig = <factory>, transflectance: TransflectanceConfig = <factory>, atr: ATRConfig = <factory>, scattering: ScatteringConfig = <factory>, add_specular: bool = False, specular_fraction: float = 0.04)[source]

Bases: object

Complete configuration for measurement mode simulation.

Combines all mode-specific configurations into a single object.

mode

The measurement mode to simulate.

Type:: nirs4all.synthesis.measurement_modes.MeasurementMode

transmittance

Config for transmittance mode.

Type:: nirs4all.synthesis.measurement_modes.TransmittanceConfig

reflectance

Config for reflectance mode.

Type:: nirs4all.synthesis.measurement_modes.ReflectanceConfig

transflectance

Config for transflectance mode.

Type:: nirs4all.synthesis.measurement_modes.TransflectanceConfig

atr

Config for ATR mode.

Type:: nirs4all.synthesis.measurement_modes.ATRConfig

scattering

Scattering coefficient configuration.

Type:: nirs4all.synthesis.measurement_modes.ScatteringConfig

add_specular

Whether to add specular reflection component.

Type:: bool

specular_fraction

Fraction of specular vs diffuse reflection.

Type:: float

add_specular: bool = False

atr: ATRConfig

mode: MeasurementMode = 'transmittance'

reflectance: ReflectanceConfig

scattering: ScatteringConfig

specular_fraction: float = 0.04

transflectance: TransflectanceConfig

transmittance: TransmittanceConfig

class nirs4all.synthesis.measurement_modes.MeasurementModeSimulator(config: MeasurementModeConfig | None = None, random_state: int | None = None)[source]

Bases: object

Simulate different NIR measurement modes.

Converts absorption coefficients to measured signal (absorbance, reflectance, etc.) based on the physics of different measurement geometries.

config: Measurement mode configuration.

rng: Random number generator for reproducibility.

Example

>>> config = MeasurementModeConfig(mode=MeasurementMode.REFLECTANCE)
>>> simulator = MeasurementModeSimulator(config, random_state=42)
>>> reflectance = simulator.apply(absorption_coefficients, wavelengths)

absorbance_to_reflectance(absorbance: ndarray) → ndarray[source]

Convert apparent absorbance to reflectance.

R = 10^(-A)

Parameters:: absorbance – Apparent absorbance values.
Returns:: Reflectance values (0-1).

apply(absorption: ndarray, wavelengths: ndarray, scattering: ndarray | None = None) → ndarray[source]

Apply measurement mode transformation.

Converts absorption coefficients (K) to measured signal based on the configured measurement mode.

Parameters:

absorption – Absorption coefficient array (n_samples, n_wavelengths).
wavelengths – Wavelength array in nm.
scattering – Optional scattering coefficient array (n_samples, n_wavelengths). If None and needed, will be generated automatically.

Returns:

Measured signal (absorbance, reflectance, etc.) depending on mode.

generate_scattering_coefficients(shape: Tuple[int, int], wavelengths: ndarray) → ndarray[source]

Generate realistic scattering coefficients.

Scattering coefficient follows approximate relationship: S(λ) ∝ λ^(-α) * (particle_size)^β

Parameters:

shape – Output shape (n_samples, n_wavelengths).
wavelengths – Wavelength array in nm.

Returns:

Scattering coefficient array.

inverse_kubelka_munk(ks_ratio: ndarray) → ndarray[source]

Inverse Kubelka-Munk transformation.

Given K/S, solve for R∞: R∞ = 1 + K/S - sqrt((K/S)² + 2*K/S)

Parameters:: ks_ratio – K/S ratio values.
Returns:: Reflectance values.

kubelka_munk(reflectance: ndarray) → ndarray[source]

Apply Kubelka-Munk transformation.

f(R) = (1 - R)² / (2R) = K/S

Parameters:: reflectance – Reflectance values (0-1).
Returns:: Kubelka-Munk function values (K/S ratio).

reflectance_to_absorbance(reflectance: ndarray) → ndarray[source]

Convert reflectance to apparent absorbance.

A = log10(1/R) = -log10(R)

Parameters:: reflectance – Reflectance values (0-1).
Returns:: Apparent absorbance values.

class nirs4all.synthesis.measurement_modes.ReflectanceConfig(geometry: str = 'integrating_sphere', reference_material: str = 'spectralon', reference_reflectance: float = 0.99, illumination_angle: float = 0.0, collection_angle: float = 45.0, sample_presentation: str = 'powder')[source]

Bases: object

Configuration for diffuse reflectance measurement mode.

Implements Kubelka-Munk theory: f(R) = (1-R)² / 2R = K/S where R is reflectance, K is absorption coefficient, S is scattering.

geometry

Measurement geometry (integrating sphere, fiber probe, etc.).

Type:: str

reference_material

Reference standard material.

Type:: str

reference_reflectance

Reflectance of reference standard.

Type:: float

illumination_angle

Angle of illumination (degrees from normal).

Type:: float

collection_angle

Angle of collection (degrees from normal).

Type:: float

sample_presentation

How sample is presented (powder, solid, slurry).

Type:: str

collection_angle: float = 45.0

geometry: str = 'integrating_sphere'

illumination_angle: float = 0.0

reference_material: str = 'spectralon'

reference_reflectance: float = 0.99

sample_presentation: str = 'powder'

class nirs4all.synthesis.measurement_modes.ScatteringConfig(baseline_scattering: float = 1.0, wavelength_exponent: float = 1.0, particle_size_um: float = 50.0, particle_size_variation: float = 0.2, sample_to_sample_variation: float = 0.15)[source]

Bases: object

Configuration for scattering coefficient generation.

Controls how scattering coefficients are generated for samples, which is essential for Kubelka-Munk reflectance simulation.

baseline_scattering

Base scattering coefficient (arbitrary units).

Type:: float

wavelength_exponent

Exponent for wavelength dependence (Rayleigh-like). S(λ) ∝ λ^(-exponent), typically 0.5-2.0

Type:: float

particle_size_um

Mean particle size in micrometers.

Type:: float

particle_size_variation

Coefficient of variation in particle size.

Type:: float

sample_to_sample_variation

How much scattering varies between samples.

Type:: float

baseline_scattering: float = 1.0

particle_size_um: float = 50.0

particle_size_variation: float = 0.2

sample_to_sample_variation: float = 0.15

wavelength_exponent: float = 1.0

class nirs4all.synthesis.measurement_modes.TransflectanceConfig(path_length_mm: float = 0.5, reflector_type: str = 'gold', reflector_reflectance: float = 0.95, spacer_thickness_mm: float = 0.5)[source]

Bases: object

Configuration for transflectance measurement mode.

Light passes through sample, reflects off a mirror/diffuser, and passes through sample again (double-pass).

path_length_mm

Single-pass path length in mm.

Type:: float

reflector_type

Type of backing reflector.

Type:: str

reflector_reflectance

Reflectance of backing material.

Type:: float

spacer_thickness_mm

Spacer thickness controlling path length.

Type:: float

path_length_mm: float = 0.5

reflector_reflectance: float = 0.95

reflector_type: str = 'gold'

spacer_thickness_mm: float = 0.5

class nirs4all.synthesis.measurement_modes.TransmittanceConfig(path_length_mm: float = 1.0, path_length_variation: float = 0.02, cuvette_material: str = 'quartz', reference_type: str = 'air')[source]

Bases: object

Configuration for transmittance measurement mode.

Implements Beer-Lambert law: A = εcl where A is absorbance, ε is molar absorptivity, c is concentration, and l is path length.

path_length_mm

Optical path length in mm.

Type:: float

path_length_variation

Sample-to-sample variation in path length.

Type:: float

cuvette_material

Material of sample holder (affects NIR absorption).

Type:: str

reference_type

Type of reference measurement.

Type:: str

cuvette_material: str = 'quartz'

path_length_mm: float = 1.0

path_length_variation: float = 0.02

reference_type: str = 'air'

nirs4all.synthesis.measurement_modes.create_atr_simulator(crystal_material: str = 'diamond', incidence_angle: float = 45.0, n_reflections: int = 1, random_state: int | None = None) → MeasurementModeSimulator[source]

Create an ATR mode simulator.

Parameters:

crystal_material – ATR crystal material.
incidence_angle – Incidence angle in degrees.
n_reflections – Number of internal reflections.
random_state – Random seed.

Returns:

Configured MeasurementModeSimulator.

nirs4all.synthesis.measurement_modes.create_reflectance_simulator(geometry: str = 'integrating_sphere', particle_size_um: float = 50.0, random_state: int | None = None) → MeasurementModeSimulator[source]

Create a diffuse reflectance mode simulator.

Parameters:

geometry – Measurement geometry.
particle_size_um – Mean particle size.
random_state – Random seed.

Returns:

Configured MeasurementModeSimulator.

nirs4all.synthesis.measurement_modes.create_transmittance_simulator(path_length_mm: float = 1.0, random_state: int | None = None) → MeasurementModeSimulator[source]

Create a transmittance mode simulator.

Parameters:

path_length_mm – Optical path length in mm.
random_state – Random seed.

Returns:

Configured MeasurementModeSimulator.