spectrochempy.PSD

class PSD(*, log_level='WARNING', warm_start=False, harmonic=1, input_mode='auto', integration_method='trapezoid', method='matrix', n_spectra_per_cycle=None, phase_unit='degrees', phi=None, subtract_mean=False)[source]

PSD (Phase-Sensitive Detection) for demodulating spectroscopic data.

Supports two computation methods: 1. Matrix transform method: demodulated = np.dot(T, A) 2. Explicit integration method: PSD(phi, nu) = 2/T * ∫ D(t,nu) * sin(k*ω*t + phi) dt

Parameters:

Computation method. “matrix” is faster using linear algebra.
Number of spectra per cycle. If None, inferred from data shape.
Input data format
- “raw” (2D (N_cycles*n_spectra_per_cycle, n_wavenumbers))
- “grouped” (3D (N_cycles, n_spectra_per_cycle, n_wavenumbers))
- “averaged” (2D (n_spectra_per_cycle, n_wavenumbers))
- “auto” (infer from shape)
Demodulation harmonic index (k in sin(k*ω*t + phi)).
Phase angles for demodulation (in degrees).
Quadrature method for numerical integration weights.
If True, subtract mean from data before demodulation.
Unit for phase output.

harmonicint, optional, default: 1: Demodulation harmonic index.

input_mode : any value of ['auto', 'raw', 'grouped', 'averaged'], optional, default: 'auto'

integration_method : any value of ['rectangle', 'riemann', 'trapezoid', 'simpson'], optional, default: 'trapezoid'

method : any value of ['matrix', 'integration'], optional, default: 'matrix'

n_spectra_per_cycleint, optional, default: None: Number of spectra per cycle.

phase_unit : any value of ['degrees', 'radians'], optional, default: 'degrees'

phia list or a numpy array, optional, default: None: Phase angles for demodulation (in degrees).
subtract_meanbool, optional, default: False: If True, subtract mean from data before demodulation.

Notes

Requires phi to contain 0° and 90° for in_phase/quadrature extraction.
Matrix method is default and faster.
Integration method uses explicit numerical integration with configurable quadrature.

Math notation:

T = transform matrix (shape: n_phi × n_spectra_per_cycle)
period = modulation period (from time coordinate)
ω = 2π / period (angular frequency)
harmonic = k (demodulation harmonic index)

PSD equation (matrix method):

A = T · D_averaged

where D_averaged has shape (n_spectra_per_cycle, n_wavenumbers), averaged across all cycles.

PSD equation (integration method):

PSD(φ, λ) = (2/period) ∫ D_averaged(t, λ) · sin(k·ω·t + φ) dt

where φ is the demodulation phase angle, λ is wavenumber, and t is normalized time within one modulation period.

Examples

>>> import spectrochempy as scp
>>> import numpy as np
>>> # Raw 2D input (120 spectra, 1000 wavenumbers)
>>> X = scp.NDDataset(np.random.rand(120, 1000))
>>> psd = scp.PSD(n_spectra_per_cycle=60, method='matrix')
>>> psd.fit(X)
>>> in_phase = psd.in_phase
>>> quadrature = psd.quadrature
>>> amplitude = psd.amplitude
>>> phase = psd.phase

T

Transform matrix (NOT the period). Shape: (n_phi, n_spectra_per_cycle). Dims: [“y”, “x”] where y=phi angles, x=time/spectra.

Type:: NDDataset

period[source]

Modulation period (from time coordinate).

Type:: float

prs

Phase-resolved spectra (PRS) with shape (n_phi, n_wavenumbers) and dims [“y”, “x”].

Type:: NDDataset

in_phase

In-phase component (phi=0°) with shape (n_wavenumbers,).

Type:: NDDataset

quadrature

Quadrature component (phi=90°) with shape (n_wavenumbers,).

Type:: NDDataset

amplitude

Amplitude = sqrt(in_phase² + quadrature²) with shape (n_wavenumbers,).

Type:: NDDataset

phase

Phase = atan2(quadrature, in_phase) with shape (n_wavenumbers,).

Type:: NDDataset

fit(X)[source]: Fit the PSD model to data X.

transform(X)[source]: Transform data using fitted model (returns PSD).

inverse_transform()[source]: Not supported for PSD.

Initialize the BaseConfigurable class.

Parameters:

log_level (int, optional) – The log level at startup. Default is logging.WARNING.
**kwargs (dict) – Additional keyword arguments for configuration.

Attributes Summary

`T`	Return the transform matrix T.
`X`	Return the X input dataset (eventually modified by the model).
`amplitude`	Return the amplitude (sqrt(in_phase² + quadrature²)).
`config`	`traitlets.config.Config` object.
`harmonic`	Demodulation harmonic index.
`in_phase`	Return the in-phase component (phi=0°).
`input_mode`	An enum whose value must be in a given sequence.
`integration_method`	An enum whose value must be in a given sequence.
`log`	Return `log` output.
`method`	An enum whose value must be in a given sequence.
`n_spectra_per_cycle`	Number of spectra per cycle.
`name`	Object name
`phase`	Return the phase (atan2(quadrature, in_phase)).
`phase_unit`	An enum whose value must be in a given sequence.
`phi`	Phase angles for demodulation (in degrees).
`prs`	Return the phase-resolved spectra (PRS).
`quadrature`	Return the quadrature component (phi=90°).
`subtract_mean`	If True, subtract mean from data before demodulation.

Methods Summary

`fit`(X[, Y])	Fit the PSD model on X.
`fit_transform`(X, **kwargs)	Fit the PSD model on X and return the PSD.
`inverse_transform`([X_transform])	Inverse transform is not supported for PSD.
`parameters`([replace, removed, default])	Alias for `params` method.
`params`([default])	Return current or default configuration values.
`reset`()	Reset configuration parameters to their default values.
`to_dict`()	Return config value in a dict form.
`transform`(X)	Transform data X using the fitted PSD model.

Attributes Documentation

T: Return the transform matrix T.

X: Return the X input dataset (eventually modified by the model).

amplitude: Return the amplitude (sqrt(in_phase² + quadrature²)).

config: traitlets.config.Config object.

harmonic: Demodulation harmonic index.

in_phase: Return the in-phase component (phi=0°).

input_mode: An enum whose value must be in a given sequence.

integration_method: An enum whose value must be in a given sequence.

log: Return log output.

method: An enum whose value must be in a given sequence.

n_spectra_per_cycle: Number of spectra per cycle.

name: Object name

phase: Return the phase (atan2(quadrature, in_phase)).

phase_unit: An enum whose value must be in a given sequence.

phi: Phase angles for demodulation (in degrees).

prs: Return the phase-resolved spectra (PRS).

quadrature: Return the quadrature component (phi=90°).

subtract_mean: If True, subtract mean from data before demodulation.

Methods Documentation

fit(X, Y=None)[source]

Fit the PSD model on X.

Parameters:

X (NDDataset or array-like) – Input data for PRS.
Y (None) – Ignored, present for API compatibility.

Returns:

self (PSD) – The fitted PSD instance.

fit_transform(X, **kwargs)[source]

Fit the PSD model on X and return the PSD.

Parameters:

X (NDDataset or array-like) – Input data for PSD.
**kwargs – Additional keyword arguments (ignored).

Returns:

NDDataset – Phase-resolved spectra (PRS).

inverse_transform(X_transform=None, **kwargs)[source]

Inverse transform is not supported for PSD.

Raises:: NotImplementedError – Always raised as PRS is not invertible.

parameters(replace="params", removed="0.8.0") def parameters(self, default=False)[source]: Alias for params method.

Deprecated since version 0.8.0: Use params instead.

params(default=False)[source]

Return current or default configuration values.

Parameters:: default (bool, optional, default: False) – If default is True, the default parameters are returned, else the current values.
Returns:: dict – Current or default configuration values.

reset()[source]: Reset configuration parameters to their default values.

to_dict()[source]

Return config value in a dict form.

Returns:: dict – A regular dictionary.

transform(X)[source]

Transform data X using the fitted PSD model.

Parameters:: X (NDDataset or array-like) – Input data for PRS.
Returns:: np.ndarray – Phase-resolved spectra (PRS) result.

Examples using spectrochempy.PSD