Analysis Constants

Feature definitions and frequency bands for signal processing.

class neurodent.constants.analysis.FeatureType(value)

Enumeration of feature data shapes.

Each feature in the system has exactly one FeatureType that describes how its data is stored and how common operations (averaging, filtering, channel remapping, plotting) should handle it.

Using classify_feature() with this enum eliminates the need for scattered match / if blocks that hard-code feature name strings.

Canonical extracted shapes (after stacking W windows via extract_*):

Type              Extracted shape       Axis semantics
──────────────    ────────────────      ──────────────────────────
LINEAR            (W, C)                windows, channels
LINEAR_2D         (W, C, K)             windows, channels, components
BAND              (W, C, B)             windows, channels, bands
SIMPLE_MATRIX     (W, C, C)             windows, ch_row, ch_col
BANDED_MATRIX     (W, C, C, B)          windows, ch_row, ch_col, bands
HIST              (W, C, F)             windows, channels, freq_bins

Convention: W is always axis 0. Channel axes (C) always come next (axis 1, and axis 2 for matrix types). Feature-specific semantic dimensions (bands B, components K, frequency bins F) are last.

This means:

• Channel collapse is always axis=1 (or axis=(1, 2) for matrices).

• vals[:, ch_idx] gives one channel’s data for every feature type.

• Matches per-cell storage order: LINEAR stores (C,), matrices store (C, C), so stacking windows on axis 0 produces the canonical shape.

Example:

from neurodent.constants import FeatureType, classify_feature

ftype = classify_feature("rms")
assert ftype is FeatureType.LINEAR
assert ftype.extracted_shape == "W, C"
assert ftype.channel_axes == (1,)
assert not ftype.is_dict_stored

LINEAR = 'linear'

Scalar per channel. Stored as a list of floats (one per channel).

LINEAR_2D = 'linear_2d'

Multi-component per channel. Stored as a 2-D array (n_channels, n_components).

BAND = 'band'

Dict keyed by frequency-band name, values are per-channel arrays.

BANDED_MATRIX = 'banded_matrix'

Dict keyed by frequency-band name, values are 2-D (channel × channel) matrices.

SIMPLE_MATRIX = 'simple_matrix'

2-D (channel × channel) matrix without a frequency-band dimension.

HIST = 'hist'

Histogram / spectral data stored as a (frequencies, values) tuple.

property extracted_shape: str

Symbolic shape string after extraction (e.g. 'W, C, B').

property channel_axes: tuple[int, ...]

Axis indices corresponding to channel dimensions.

property semantic_axes: dict[str, int]

Mapping of semantic dimension name to axis index.

property is_linear: bool

True for per-channel features (scalar or multi-component).

property is_matrix: bool

True for features stored as channel × channel matrices.

property is_dict_stored: bool

True for features stored as dicts keyed by frequency band.

neurodent.constants.analysis.FEATURE_SHAPES: dict[FeatureType, dict] = {FeatureType.BAND: {'cell_shape': '{band: (C,)}', 'channel_axes': (1,), 'description': 'One value per band per channel (e.g. psdband, logpsdband)', 'extracted_shape': 'W, C, B', 'semantic_axes': {'bands': 2}}, FeatureType.BANDED_MATRIX: {'cell_shape': '{band: (C, C)}', 'channel_axes': (1, 2), 'description': 'Channel x channel matrix per band (e.g. cohere, zcohere)', 'extracted_shape': 'W, C, C, B', 'semantic_axes': {'bands': 3}}, FeatureType.HIST: {'cell_shape': '(F,), (C, F)', 'channel_axes': (1,), 'description': 'Spectral histogram per channel (e.g. psd)', 'extracted_shape': 'W, C, F', 'semantic_axes': {'freq_bins': 2}}, FeatureType.LINEAR: {'cell_shape': 'C', 'channel_axes': (1,), 'description': 'Scalar per channel (e.g. rms, ampvar)', 'extracted_shape': 'W, C', 'semantic_axes': {}}, FeatureType.LINEAR_2D: {'cell_shape': 'C, K', 'channel_axes': (1,), 'description': 'K components per channel (e.g. psdslope)', 'extracted_shape': 'W, C, K', 'semantic_axes': {'components': 2}}, FeatureType.SIMPLE_MATRIX: {'cell_shape': 'C, C', 'channel_axes': (1, 2), 'description': 'Channel x channel matrix (e.g. pcorr, zpcorr)', 'extracted_shape': 'W, C, C', 'semantic_axes': {}}}

Canonical shape metadata for each FeatureType.

Keys per entry:

• extracted_shape: Symbolic shape after stacking W windows.

• cell_shape: Shape of a single cell in the WAR DataFrame.

• channel_axes: Tuple of axis indices that are channel dimensions.

• semantic_axes: Dict mapping semantic dimension names to axis indices.

• description: Human-readable description.

Shape convention: (W, C, [C₂], ...semantic). Windows (W) is always axis 0. Channel axes (C) always follow immediately. Semantic dimensions (bands, components, freq bins) are trailing.

neurodent.constants.analysis.LINEAR_FEATURES = ['rms', 'ampvar', 'psdtotal', 'nspike', 'logrms', 'logampvar', 'logpsdtotal', 'lognspike']

List of linear (scalar) feature names computed per channel.

neurodent.constants.analysis.LINEAR_2D_FEATURES = ['psdslope']

List of multi-component linear features (stored as 2-D arrays per channel).

neurodent.constants.analysis.BAND_FEATURES = ['psdband', 'psdfrac', 'logpsdband', 'logpsdfrac']

List of frequency-band feature names (one value per band).

neurodent.constants.analysis.MATRIX_FEATURES = ['cohere', 'zcohere', 'imcoh', 'zimcoh', 'pcorr', 'zpcorr']

List of connectivity/matrix feature names (channel pairs).

neurodent.constants.analysis.BANDED_MATRIX_FEATURES = ['cohere', 'zcohere', 'imcoh', 'zimcoh']

Matrix features with frequency band dimension (stored as dict with band keys).

neurodent.constants.analysis.SIMPLE_MATRIX_FEATURES = ['pcorr', 'zpcorr']

Matrix features without frequency bands (single 2D correlation matrix).

neurodent.constants.analysis.HIST_FEATURES = ['psd']

List of histogram/spectral feature names.

neurodent.constants.analysis.FEATURES = ['rms', 'ampvar', 'psdtotal', 'nspike', 'logrms', 'logampvar', 'logpsdtotal', 'lognspike', 'psdslope', 'psdband', 'psdfrac', 'logpsdband', 'logpsdfrac', 'cohere', 'zcohere', 'imcoh', 'zimcoh', 'pcorr', 'zpcorr', 'psd']

Complete list of all available features.

neurodent.constants.analysis.WAR_FEATURES = ['rms', 'ampvar', 'psdtotal', 'logrms', 'logampvar', 'logpsdtotal', 'psdslope', 'psdband', 'psdfrac', 'logpsdband', 'logpsdfrac', 'cohere', 'zcohere', 'imcoh', 'zimcoh', 'pcorr', 'zpcorr', 'psd']

Features available in WindowAnalysisResult (excludes spike-related).

neurodent.constants.analysis.FEATURE_TYPES: dict[str, FeatureType] = {'ampvar': FeatureType.LINEAR, 'cohere': FeatureType.BANDED_MATRIX, 'imcoh': FeatureType.BANDED_MATRIX, 'logampvar': FeatureType.LINEAR, 'lognspike': FeatureType.LINEAR, 'logpsdband': FeatureType.BAND, 'logpsdfrac': FeatureType.BAND, 'logpsdtotal': FeatureType.LINEAR, 'logrms': FeatureType.LINEAR, 'nspike': FeatureType.LINEAR, 'pcorr': FeatureType.SIMPLE_MATRIX, 'psd': FeatureType.HIST, 'psdband': FeatureType.BAND, 'psdfrac': FeatureType.BAND, 'psdslope': FeatureType.LINEAR_2D, 'psdtotal': FeatureType.LINEAR, 'rms': FeatureType.LINEAR, 'zcohere': FeatureType.BANDED_MATRIX, 'zimcoh': FeatureType.BANDED_MATRIX, 'zpcorr': FeatureType.SIMPLE_MATRIX}

Mapping from every known feature name to its FeatureType.

neurodent.constants.analysis.classify_feature(feature_name: str) → FeatureType

Return the FeatureType for a given feature name.

Parameters:

feature_name – Name of the feature (e.g. 'rms', 'psdband', 'cohere').

Returns:

The corresponding FeatureType enum member.

Raises:

ValueError – If feature_name is not a recognised feature.

neurodent.constants.analysis.FREQ_BANDS = {'alpha': (8, 13), 'beta': (13, 25), 'delta': (1, 4), 'gamma': (25, 40), 'theta': (4, 8)}

Dictionary mapping frequency band names to (min_hz, max_hz) tuples.

Delta band adjusted to 1-4 Hz (changed from 0.1-4 Hz) for reliable coherence estimation with short epochs and to avoid insufficient cycles warnings.

neurodent.constants.analysis.BAND_NAMES = ['delta', 'theta', 'alpha', 'beta', 'gamma']

[‘delta’, ‘theta’, ‘alpha’, ‘beta’, ‘gamma’].

Type:

Ordered list of frequency band names

neurodent.constants.analysis.FREQ_BAND_TOTAL = (1, 40)

Total frequency range covered by all bands (min, max) in Hz.

neurodent.constants.analysis.FREQ_MINS = [1, 4, 8, 13, 25]

List of minimum frequencies for each band.

neurodent.constants.analysis.FREQ_MAXS = [4, 8, 13, 25, 40]

List of maximum frequencies for each band.