neuralset.segments.Segment

class neuralset.segments.Segment(start: float, duration: float, timeline: str, _trigger_idx: int | None = None, _store_id: ~uuid.UUID = <factory>, _store_ref: ~neuralset.segments._EventStore | None = None, _cache_key: tuple[float, float, str] | None = None, _cached_events: list[~neuralset.events.etypes.Event] = <factory>)

A time window on a single timeline, backed by a shared event store.

Created by list_segments() (or via Segmenter) — not meant to be instantiated directly. Each segment references an internal event store that holds all events; overlapping events are resolved on access via ns_events.

Segments are mutable: changing start or duration changes which events ns_events returns (useful for jittering).

The underlying event data is snapshotted at creation time — later modifications to the source DataFrame have no effect.

copy(offset: float = 0.0, duration: float | None = None) → Segment

Create a copy of the current segment with optional offset and duration.

property events: DataFrame

Events occurring within the segment.

Returns:

DataFrame containing all events in this segment, with the original indices preserved.

Return type:

pd.DataFrame

property ns_events: list[Event]

Events overlapping this segment’s [start, start + duration) window.

The result is cached and automatically invalidated when start, duration, or timeline changes.

property stop: float

End time of the segment.

Returns:

The stop time, calculated as start + duration.

Return type:

float

property trigger: Event | None

The event that triggered this segment, or None.