Channel Features

Status

The channel-feature domain currently has both canonical and legacy surfaces.

• Canonical (new code):

  • src/cogpy/core/preprocess/badchannel/channel_features.py

  • src/cogpy/core/preprocess/badchannel/pipeline.py

  • src/cogpy/core/preprocess/badchannel/spatial.py

  • src/cogpy/core/preprocess/badchannel/badlabel.py

• Legacy (compatibility only):

  • src/cogpy/core/preprocess/channel_feature_functions.py (deprecated)

  • src/cogpy/core/preprocess/channel_feature.py (legacy)

  • src/cogpy/core/preprocess/detect_bads.py (legacy)

Canonical stack

1) Raw per-channel features

badchannel/channel_features.py defines raw temporal features over arrays shaped like (..., time), e.g.:

• relative_variance

• deviation

• standard_deviation

• amplitude

• time_derivative

• hurst_exponent

• kurtosis

• noise_to_signal (with snr alias)

For xarray workflows, use extract_channel_features_xr(...).

2) Sliding-window utilities

Canonical sliding logic is in src/cogpy/core/utils/sliding_core.py.

badchannel/channel_features.py uses:

• running_reduce_xr(...)

• running_blockwise_xr(...)

badchannel/pipeline.py uses shared window index helpers:

• window_onsets(...)

• window_centers_idx(...)

This avoids re-implementing rolling/window indexing in preprocess modules.

3) Spatial normalization and feature maps

badchannel/pipeline.py orchestrates per-window feature map construction:

• compute_feature_maps_for_window(...) for normalized spatial features

• compute_raw_feature_maps_for_window(...) for raw maps

• compute_features_sliding(...) for stacked (feature, AP, ML, time_win) output

Normalization primitives are in badchannel/spatial.py:

• normalize_ratio

• normalize_difference

• normalize_robust_z

• neighborhood statistics from adjacency

4) Outlier labeling

badchannel/badlabel.py is the canonical DBSCAN outlier path:

• dbscan_outliers(...)

• grouped_dbscan_outliers(...)

Notes on legacy modules

Legacy modules remain importable for compatibility, but should not be used for new implementations.

• channel_feature_functions.py contains deprecated duplicates and older helpers.

• channel_feature.py / detect_bads.py retain older orchestration patterns and APIs.

When migrating code:

1. Move raw feature logic to badchannel/channel_features.py.

2. Keep spatial normalization in badchannel/spatial.py + badchannel/pipeline.py.

3. Use sliding_core.py for all rolling/window primitives.