nirs4all.data.synthetic.components module

Spectral components for synthetic NIRS spectra generation.

This module provides the core building blocks for defining NIR absorption bands and spectral components based on physical spectroscopy principles.

Classes:

NIRBand: Represents a single NIR absorption band with Voigt profile. SpectralComponent: A chemical compound or functional group with multiple bands. ComponentLibrary: Collection of spectral components for generation.

class nirs4all.data.synthetic.components.ComponentLibrary(random_state: int | None = None)

Bases: object

Library of spectral components for synthetic NIRS generation.

Supports both predefined components (based on known NIR band assignments) and programmatically generated random components for research purposes.

rng

NumPy random generator for reproducibility.

Example

>>> # Create from predefined components
>>> library = ComponentLibrary.from_predefined(
...     ["water", "protein", "lipid"],
...     random_state=42
... )
>>>
>>> # Or generate random components
>>> library = ComponentLibrary(random_state=42)
>>> library.generate_random_library(n_components=5)
>>>
>>> # Compute all component spectra
>>> wavelengths = np.arange(1000, 2500, 2)
>>> E = library.compute_all(wavelengths)  # shape: (n_components, n_wavelengths)

__contains__(name: str) → bool

Check if component exists by name.

__getitem__(name: str) → SpectralComponent

Get component by name.

__iter__()

Iterate over components.

__len__() → int

Return number of components.

add_component(component: SpectralComponent) → ComponentLibrary

Add a spectral component to the library.

Parameters:

component – SpectralComponent to add.

Returns:

Self for method chaining.

add_random_component(name: str, n_bands: int = 3, wavelength_range: Tuple[float, float] = (1000, 2500), zones: List[Tuple[float, float]] | None = None) → SpectralComponent

Generate and add a random spectral component.

Creates a component with randomly placed absorption bands within the specified wavelength range or zones.

Parameters:

• name – Component name.

• n_bands – Number of absorption bands to generate.

• wavelength_range – Overall wavelength range for band placement.

• zones – Optional list of (min, max) wavelength zones for band centers. If None, uses default NIR-relevant zones.

Returns:

The generated SpectralComponent.

Example

>>> library = ComponentLibrary(random_state=42)
>>> component = library.add_random_component(
...     "random_compound",
...     n_bands=4,
...     wavelength_range=(1000, 2500)
... )

property component_names: List[str]

Get list of component names in order.

property components: Dict[str, SpectralComponent]

Get all components in the library.

compute_all(wavelengths: ndarray) → ndarray

Compute spectra for all components at given wavelengths.

Parameters:

wavelengths – Array of wavelengths in nm.

Returns:

Array of shape (n_components, n_wavelengths) containing the spectrum of each component.

Example

>>> library = ComponentLibrary.from_predefined(["water", "protein"])
>>> wavelengths = np.arange(1000, 2500, 2)
>>> E = library.compute_all(wavelengths)
>>> print(E.shape)
(2, 751)

classmethod from_predefined(component_names: List[str] | None = None, random_state: int | None = None) → ComponentLibrary

Create a library from predefined spectral components.

Parameters:

• component_names – List of component names to include. If None, includes all predefined components.

• random_state – Random seed for reproducibility.

Returns:

ComponentLibrary instance populated with predefined components.

Raises:

ValueError – If an unknown component name is specified.

Example

>>> library = ComponentLibrary.from_predefined(
...     ["water", "protein", "lipid"]
... )

generate_random_library(n_components: int = 5, n_bands_range: Tuple[int, int] = (2, 6)) → ComponentLibrary

Generate a library of random spectral components.

Parameters:

• n_components – Number of components to generate.

• n_bands_range – Range (min, max) for number of bands per component.

Returns:

Self for method chaining.

Example

>>> library = ComponentLibrary(random_state=42)
>>> library.generate_random_library(n_components=5, n_bands_range=(2, 5))

property n_components: int

Number of components in the library.

class nirs4all.data.synthetic.components.NIRBand(center: float, sigma: float, gamma: float = 0.0, amplitude: float = 1.0, name: str = '')

Bases: object

Represents a single NIR absorption band.

This class models an absorption band using a Voigt profile, which is the convolution of Gaussian (thermal broadening) and Lorentzian (pressure broadening) line shapes.

center

Central wavelength in nm.

Type:

float

sigma

Gaussian width (standard deviation) in nm.

Type:

float

gamma

Lorentzian width (HWHM) in nm. Use 0 for pure Gaussian.

Type:

float

amplitude

Peak amplitude in absorbance units.

Type:

float

name

Descriptive name of the band (e.g., “O-H 1st overtone”).

Type:

str

Example

>>> band = NIRBand(center=1450, sigma=25, gamma=3, amplitude=0.8)
>>> wavelengths = np.arange(1400, 1500, 1)
>>> spectrum = band.compute(wavelengths)

amplitude: float = 1.0

center: float

compute(wavelengths: ndarray) → ndarray

Compute the band profile at given wavelengths using Voigt profile.

Parameters:

wavelengths – Array of wavelengths in nm at which to evaluate the band.

Returns:

Array of absorbance values at each wavelength.

Note

When gamma=0, a pure Gaussian profile is used for efficiency. Otherwise, the full Voigt profile (Gaussian ⊗ Lorentzian) is computed.

gamma: float = 0.0

name: str = ''

sigma: float

class nirs4all.data.synthetic.components.SpectralComponent(name: str, bands: ~typing.List[~nirs4all.data.synthetic.components.NIRBand] = <factory>, correlation_group: int | None = None)

Bases: object

A spectral component representing a chemical compound or functional group.

Each component consists of multiple absorption bands that together define the characteristic NIR signature of the compound.

name

Component name (e.g., “water”, “protein”, “lipid”).

Type:

str

bands

List of NIRBand objects defining the spectral signature.

Type:

List[nirs4all.data.synthetic.components.NIRBand]

correlation_group

Optional group ID for components that should have correlated concentrations (e.g., protein and nitrogen compounds).

Type:

int | None

Example

>>> water = SpectralComponent(
...     name="water",
...     bands=[
...         NIRBand(center=1450, sigma=25, gamma=3, amplitude=0.8),
...         NIRBand(center=1940, sigma=30, gamma=4, amplitude=1.0),
...     ],
...     correlation_group=1
... )
>>> wavelengths = np.arange(1000, 2500, 2)
>>> spectrum = water.compute(wavelengths)

bands: List[NIRBand]

compute(wavelengths: ndarray) → ndarray

Compute the full component spectrum by summing all bands.

Parameters:

wavelengths – Array of wavelengths in nm at which to evaluate.

Returns:

Array of absorbance values representing the combined spectrum.

correlation_group: int | None = None

name: str