Signals and Spectra#

Load sample recordings, configure filtering and envelope normalization, and estimate power spectral densities.

Sample Recordings#

Bundled sample neural recordings and their sampling rates.

class neuralfieldmanifold.datasets.Recording(signal: ndarray, sampling_rate_hz: float, name: str)[source]#

One-dimensional raw sample, sampling rate in Hz, and sample name.

neuralfieldmanifold.datasets.load(name)[source]#

Load a bundled raw neural recording.

Parameters:

name ({"monkey_lfp", "mouse_lfp"}) – Monkey LFP is 20 seconds at 500 Hz. Mouse LFP is five seconds at 20 kHz.

Returns:

One-dimensional signal, sampling rate in Hz, and sample name. The duration is available as duration_seconds.

Return type:

Recording

Preprocessing#

Filtering, resampling, and envelope normalization for one-dimensional signals.

class neuralfieldmanifold.preprocessing.PreprocessConfig(notch_hz: float | None = None, notch_quality: float = 30.0, band_hz: tuple[float, float] | None = None, filter_order: int = 4, output_rate_hz: float | None = None, envelope_band_hz: tuple[float, float] | None = None, envelope_lowpass_hz: float | None = 3.0, envelope_epsilon: float = 1e-06)[source]#

Settings for notch, bandpass, decimation, and envelope processing.

Parameters:

  • notch_hz (float or None) – Line frequency to remove, in Hz. None disables notch filtering.

  • notch_quality (float) – Notch quality factor (center frequency divided by bandwidth).

  • band_hz (tuple of float or None) – Lower and upper bandpass cutoffs in Hz.

  • filter_order (int) – Butterworth order used by the bandpass filter.

  • output_rate_hz (float or None) – Output sampling rate. Must divide the input rate by an integer.

  • envelope_band_hz (tuple of float or None) – Band in Hz used for envelope normalization, after decimation. None disables normalization.

  • envelope_lowpass_hz (float or None) – Lowpass cutoff for the Hilbert envelope. None leaves it unsmoothed.

  • envelope_epsilon (float) – Positive constant added to the envelope before division.

Notes

Steps run in the order listed above. All filter cutoffs must lie below Nyquist at the stage where they are applied.

class neuralfieldmanifold.preprocessing.ProcessedSignal(signal: ndarray, bandpassed: ndarray, envelope: ndarray | None, sampling_rate_hz: float)[source]#

Processing results and output sampling rate.

signal#

Final processed signal.

Type:

ndarray

bandpassed#

Signal after filtering and decimation, before envelope processing.

Type:

ndarray

envelope#

Hilbert amplitude envelope, or None if normalization is disabled.

Type:

ndarray or None

sampling_rate_hz#

Output sampling rate in Hz.

Type:

float

neuralfieldmanifold.preprocessing.bandpass(x, *, sampling_rate_hz, band_hz, order=4)[source]#

Zero-phase Butterworth SOS bandpass; no normalization.

neuralfieldmanifold.preprocessing.notch(x, *, sampling_rate_hz, frequency_hz, quality=30.0)[source]#

Zero-phase IIR notch at the specified line frequency.

neuralfieldmanifold.preprocessing.envelope_normalize(x, *, sampling_rate_hz, band_hz, lowpass_hz=3.0, epsilon=1e-06)[source]#

Normalize a bandpassed signal by its Hilbert amplitude envelope.

A fourth-order Butterworth bandpass is applied with zero-phase filtering. The Hilbert amplitude can be smoothed by a second-order lowpass filter. The output is the filtered signal divided by envelope + epsilon, then multiplied by the median envelope.

Parameters:

  • x (array_like, shape (n_samples,)) – Input signal.

  • sampling_rate_hz (float) – Sampling rate in Hz.

  • band_hz (tuple of float) – Bandpass cutoffs in Hz.

  • lowpass_hz (float or None) – Envelope smoothing cutoff in Hz.

  • epsilon (float) – Positive denominator offset.

Returns:

  • normalized (ndarray) – Envelope-normalized signal.

  • filtered (ndarray) – Bandpassed signal before normalization.

  • envelope (ndarray) – Hilbert amplitude envelope, smoothed if requested.

neuralfieldmanifold.preprocessing.process(x, *, sampling_rate_hz, config)[source]#

Apply the configured processing steps to a one-dimensional signal.

Parameters:

  • x (array_like, shape (n_samples,)) – Input signal.

  • sampling_rate_hz (float) – Input sampling rate in Hz.

  • config (PreprocessConfig) – Filtering, output rate, and envelope settings.

Returns:

Processed signal, pre-normalization signal, envelope, and output rate.

Return type:

ProcessedSignal

Power Spectra#

Welch power spectral density estimation.

class neuralfieldmanifold.spectral.PowerSpectrum(frequencies_hz: ndarray, density: ndarray)[source]#

Frequency coordinates in Hz and their power spectral density.

neuralfieldmanifold.spectral.welch(x, *, sampling_rate_hz, n_fft=4096, overlap_samples=2048, window='hamming', frequency_range_hz=None, smooth_bins=None)[source]#

Estimate power spectral density with Welch’s method.

Parameters:

  • x (array_like, shape (n_samples,)) – Input signal.

  • sampling_rate_hz (float) – Sampling rate in Hz.

  • n_fft (int) – FFT length and maximum segment length. Short signals use their full length as the segment and are zero-padded to this FFT length.

  • overlap_samples (int) – Segment overlap, capped at one less than the segment length.

  • window (str or tuple) – Window specification accepted by scipy.signal.welch.

  • frequency_range_hz (tuple of float or None) – Inclusive lower and upper frequencies to retain.

  • smooth_bins (float or None) – Standard deviation of optional Gaussian smoothing, in frequency bins.

Returns:

Frequencies in Hz and density in signal-units squared per Hz.

Return type:

PowerSpectrum

Notes

Each segment is detrended by subtracting its mean.