spectral_connectivity.transforms.prepare_time_series#

prepare_time_series(time_series: ndarray[tuple[int, ...], dtype[floating]], axis: str | None = None) → ndarray[tuple[int, ...], dtype[floating]][source]#

Convert time series data to the 3D format required by Multitaper.

This helper function ensures your data has the correct shape (n_time_samples, n_trials, n_signals) for spectral analysis.

Parameters:

time_series (NDArray[floating]) – Input time series data with 1D, 2D, or 3D shape.
axis ({"signals", "trials"}, optional) – For 2D input, specify which axis represents the second dimension: - “signals”: shape is (n_time_samples, n_signals), adds trials axis - “trials”: shape is (n_time_samples, n_trials), adds signals axis Required for 2D input, ignored for 1D and 3D input.

Returns:

time_series_3d – Time series data reshaped to 3D format.

Return type:

NDArray[floating], shape (n_time_samples, n_trials, n_signals)

Raises:

ValueError – If input is 2D and axis parameter is not provided. If axis is not “signals” or “trials”. If input has more than 3 dimensions.

Examples

Single-trial EEG/LFP recording with multiple channels:

>>> import numpy as np
>>> # Load continuous EEG: 5 seconds at 1000 Hz, 64 channels
>>> eeg_data = np.random.randn(5000, 64)  # Shape: (n_time, n_channels)
>>> eeg_3d = prepare_time_series(eeg_data, axis="signals")
>>> eeg_3d.shape
(5000, 1, 64)  # (n_time, 1 trial, 64 channels)

Multiple trials of a single electrode:

>>> # 20 trials of one LFP channel, 2 seconds each at 1000 Hz
>>> lfp_trials = np.random.randn(2000, 20)  # Shape: (n_time, n_trials)
>>> lfp_3d = prepare_time_series(lfp_trials, axis="trials")
>>> lfp_3d.shape
(2000, 20, 1)  # (n_time, 20 trials, 1 channel)

Single time series (e.g., spike times converted to continuous):

>>> # One neuron's firing rate over time
>>> firing_rate = np.random.randn(1000)
>>> firing_rate_3d = prepare_time_series(firing_rate)
>>> firing_rate_3d.shape
(1000, 1, 1)  # (n_time, 1 trial, 1 signal)

Already properly formatted (pass-through):

>>> # Epoched data from MNE or similar: 10 trials, 5 channels, 100 timepoints
>>> epoched_data = np.random.randn(100, 10, 5)
>>> result = prepare_time_series(epoched_data)
>>> result.shape
(100, 10, 5)  # Unchanged

Notes

Common mistake: Using 2D data without specifying the axis parameter. A 2D array (100, 5) could mean either: - 100 time points × 5 signals (1 trial) → use axis=”signals” - 100 time points × 5 trials (1 signal) → use axis=”trials”

You must explicitly specify which interpretation is correct.