ctxseg 0.1.4

Official package for Segmentation by Context (CTX-SEG)

CTXSEG

Installation | CTXSEG | CTXGEN | Examples

Official repository for Segmentation by Context (CTXSEG) and Context Generation (CTXGEN).

Installation

This package is available on PyPI.

pip install ctxseg

The package provides two modules:

import ctxseg
import ctxgen

Comparison

{% include experiments/results_table.md %}

Module: ctxseg

CTXSEG is a method of creating variable-size segments (aka. adaptive segmentation) in multi-channel time-series signals, such as electroencephalography (EEG), by finding statistical differences in the frequency spectrum. It can be readily used in a pre-processing step of existing machine learning pipelines.

Main namespaces:

• ctxseg.segment_signal

ctxseg.segment_signal

segment_signal(x: np.ndarray, w: int, s: int = 1, alpha: float = 0.05, win_fn: Union[str, np.ndarray] = "hamming", engine: Literal["c", "npy"] = "c")

Performs adaptive segmentation on a signal shape (C, N) using CTXSEG with two-sliding windows and paired t-test on log-magnitude frequency spectrum, derived from windowed FFT. C: is channels. N: is signal length.

Parameters:

• x: Signal as a NumPy array with shape (C, N).
• w: Window size (samples).
• s: Stride (samples).
• alpha: Paired t-test significance threshold for boundary discovery.
• win_fn: Window function for FFT, either as a NumPy array or a named string compatible with scipy.signal.windows.
• engine: Backend implementation: c (C/C++ compiled) or npy (Python/NumPy).

Returns:

• A boolean NumPy array indicating segment boundaries, shape (C, N).

Module: ctxgen

CTXGEN is a synthetic signal generator, that uses multiple leaky integrate-and-fire (LIF) spiking neuron model, based on user-definable signal characteristics while maintaining the randomness of real EEG signals.

Main namespaces:

• ctxgen.CtxGen
• ctxgen.CtxGen.generate_signal

ctxgen.CtxGen

CtxGen(n_neurons: int = 500, sfreq: int = 256, sfreq_gen: int = 2048, v_thresh: int = 24, tau: float = 0.02, verbose: bool = True)

CtxGen constructor.

Parameters:

• n_neurons: Number of LIF models to use.
• sfreq: Output sample frequency (Hz).
• sfreq_gen: Internal sample frequency for signal generation (Hz).
• v_thresh: Threshold for resetting membrane potential.
• tau: Time constant.

ctxgen.CtxGen.generate_signal

generate_signal(states: List[Tuple[int, int]], pad: int = 8, seed: int = 42, as_raw: bool = True)

Generate the signal by supplying signal characteristics in the form of context states, which are tuples of firing rate and time duration.

Parameters:

• states: Context states as a list of tuple(firing rate in Hz, duration in secs). For example, [(2, 360), (40, 1)] means 2 Hz for 360 secs then 40 Hz for 1 sec.
• pad: Amount of seconds to pad each state to avoid artifacts.
• seed: Random seed.
• as_raw: Return the signal as a mne.io.Raw.

Returns, either:

• mne.io.Raw if as_raw=True, or
• Tuple of (signal, firing_rates), both as NumPy arrays, if as_raw=False.

Examples

Code examples are available in /tests.

Below is a performance comparison between backend implementations while segmenting a 6 minute signal on Apple M2 Max. [Source]

C engine took: 0.195 secs
NumPy engine took: 3.108 secs