stacie.spectrum module

Utility to prepare the spectrum and other inputs for given sequences.

class Spectrum(mean, variance, timestep, nstep, freqs, ndofs, amplitudes, amplitudes_ref=None)[source]

Bases: object

Container class holding all the inputs for the autocorrelation integral estimate.

Parameters:
amplitudes: ndarray[tuple[Any, ...], dtype[float]]

The spectrum amplitudes averaged over the given input sequences.

amplitudes_ref: ndarray[tuple[Any, ...], dtype[float]] | None

Optionally, the known analytical model of the power spectrum, on the same frequency grid.

freqs: ndarray[tuple[Any, ...], dtype[float]]

The equidistant frequency axis of the spectrum.

mean: float

The mean of the input sequences multiplied by the square root of the prefactor.

ndofs: ndarray[tuple[Any, ...], dtype[float]]

The number of independent contributions to each amplitude.

property nfreq: int

The number of RFFT frequency grid points.

nstep: int

The number of time steps in the input.

timestep: float

The time between two subsequent elements in the given sequence.

variance: float

The variance of the input sequences multiplied by the prefactor.

without_zero_freq()[source]

Return a copy without the DC component.

Return type:

Self

compute_spectrum(sequences, *, prefactors=1.0, timestep=1, include_zero_freq=True)[source]

Compute a spectrum and store all inputs for estimate_acint in a Spectrum instance.

The spectrum amplitudes are computed as follows:

\[C_k = \frac{1}{M}\sum_{m=1}^M \frac{F_m h}{2 N} \left| \sum_{n=0}^{N-1} x^{(m)}_n \exp\left(-i \frac{2 \pi n k}{N}\right) \right|^2\]

where:

  • \(F_m\) is the given prefactor (may be different for each sequence),

  • \(h\) is the timestep,

  • \(N\) is the number of time steps in the input sequences,

  • \(M\) is the number of independent sequences,

  • \(x^{(m)}_n\) is the value of the \(m\)-th sequence at time step \(n\),

  • \(k\) is the frequency index.

The sum over \(m\) simply averages spectra obtained from different sequences. The factor \(F_m h/ 2 N\) normalizes the spectrum so that its zero-frequency limit is an estimate of the autocorrelation integral.

Parameters:

  • sequences (Iterable[ndarray[tuple[Any, ...], dtype[float]]] | ndarray[tuple[Any, ...], dtype[float]]) –

    The input sequences, which can have several forms. If prefactors is not None, it can be:

    • An array with shape (nindep, nstep) or (nstep,). In case of a 2D array, each row is a time-dependent sequence. In case of a 1D array, a single sequence is used.

    • An iterable whose items are arrays as described in the previous point. This option is convenient when a single array does not fit in memory.

    If prefactors is None:

    • A tuple of a prefactor (or an array of prefactors) and a sequences array, either 1D or 2D as described above.

    • An iterable whose items are tuples of a prefactor (or an array of prefactors) and a sequences array, either 1D or 2D as described above.

    All sequences are assumed to be statistically independent and have length nstep. (Time correlations within one sequence are fine, obviously.) We recommend using multiple independent sequences to reduce uncertainties. Arrays must be used. (lists of floating point values are not supported.)

  • prefactors (Iterable[ndarray[tuple[Any, ...], dtype[float]]] | ndarray[tuple[Any, ...], dtype[float]] | None) –

    A positive factor to be multiplied with the autocorrelation function to give it a physically meaningful unit. This argument can be given in multiple forms:

    • None, in which case the sequences are assumed to be one or more (prefactors, sequences) tuples.

    • A single floating point value: the same prefactor is used for all input sequences.

    • A single array with shape (nindep,): each sequence is multiplied with the corresponding prefactor.

    • An iterable whose items are of the form described in the previous two points. In this case, the sequences must also be given as an iterable with the same length.

  • timestep (float) – The time step of the input sequence.

  • include_zero_freq (bool) – When set to False, the DC component of the spectrum is discarded.

Return type:

Spectrum

Returns:

spectrum – A Spectrum object holding all the inputs needed to estimate the integral of the autocorrelation function.