neuralset.extractors.base.BaseExtractor

class neuralset.extractors.base.BaseExtractor(*, event_types: str | tuple[str, ...] = '', aggregation: Literal['single', 'sum', 'mean', 'first', 'middle', 'last', 'cat', 'stack', 'trigger'] = 'single', allow_missing: bool = False, frequency: float | Literal['native'] = 0.0)

Base class for extracting features from events within a Segment.

Subclasses define what data to extract (e.g. audio embeddings, EEG signals) while BaseExtractor handles event selection, temporal alignment, and multi-event aggregation.

To create a custom extractor, subclass BaseExtractor and implement:

• _get_data(events) — expensive per-event computation (typically cached via exca.MapInfra).

• _get_timed_arrays(events, start, duration) — return an iterable of TimedArray, one per event.

For extractors that produce a single static value per event (no time dimension), subclass BaseStatic instead and override get_static().

Parameters:

• event_types (str or tuple of str) – Event type name(s) this extractor operates on (e.g. "Audio" or ("Image", "Text")). Must be set as a class-level default in every concrete subclass.

• aggregation (str) –

  Strategy for combining values when multiple matching events fall inside the same segment:

  • "single" — exactly one event expected (raises otherwise).

  • "sum" / "mean" — element-wise sum or mean.

  • "first" / "middle" / "last" — pick one event.

  • "cat" — concatenate along the first dimension.

  • "stack" — stack along a new first dimension.

  • "trigger" — use only the trigger event passed to __call__.

• allow_missing (bool) – If True, return a zero tensor when no matching event is found in the segment instead of raising. Requires that prepare() has been called first so the output shape is known.

• frequency (float or "native") – Output sampling rate in Hz. Use "native" to keep the original sampling rate of the input data. 0 is reserved for static extractors (BaseStatic).