Skip to content
GitHub · 2.7.0

Reference

Session

Read back an on-disk recording session: iterate labeled or aligned windows for training, or open the raw store. See Record and replay.

Reading sessions

Three window iterators, differing only in what each window is paired with. iter_labeled_windows gives a class index from the label track. iter_target_windows gives the value of a recorded TargetSource stream at the window’s end — the causal choice, and the one to reach for whenever the target is graded rather than cued; see Record for proportional control. iter_aligned_windows gives a sample from one or more arbitrary streams nearest the window’s midpoint.

open_session_store

open_session_store(path: str | Path) -> Session

Open a saved session folder or .mg.zip as a read-only Session.

Folder sessions keep the existing layout and use zarr.open_array(str(path / "<stream>.zarr"), mode="r"). Zip sessions use a zarr.storage.ZipStore and read the same array paths inside the archive.

Examples

>>> from myogestic.session import open_session_store
>>> session = open_session_store("sessions/demo.mg.zip")
>>> info = session.stream_info("emg")
>>> session.close()

recover_session

recover_session(path: str | Path) -> Path

Pack a crashed take's folder with the normal, verified archive path.

Stop the recording process before calling this. Requires the meta.json checkpoint written by current recorders; older crashed folders without one cannot be recovered this way. The original folder is removed only after packing succeeds. An unfinished take stays marked finished=False.

Only data already written to disk can be recovered. Buffered event rows, labels and extras changed since the last checkpoint, and finalize-hook outputs may be missing. Recovery does not resume acquisition or run hooks.

Parameters

NameTypeDescriptionDefault
pathstr | Path

The unpacked take folder, not its parent or an existing archive.

Returns

NameTypeDescriptionDefault
pathlib.Path

The packed .mg.zip path, readable by open_session_store and myogestic.widgets.SessionManager.

Examples

>>> from myogestic.session import recover_session
>>> archive = recover_session("data/P-001/recordings/P-001_20261107-0930")

iter_labeled_windows

iter_labeled_windows(
    paths: list[str] | list[Path],
    stream_name: str,
    window_ms: float,
    hop_ms: float,
    classes: set[int] | None = None,
) -> Iterator[tuple[np.ndarray, np.ndarray, int]]

Yield (window, ts, class_index) triples from labeled segments.

window is channels-first (n_channels, n_samples) — the library's standard signal layout. ts is the matching 1-D timestamp array. Walks each session's label track, finds the time interval each label covers (this label's timestamp to next label's timestamp), and chops that interval into fixed-size windows. Works for folders and .mg.zip sessions.

Examples

>>> from myogestic.session import iter_labeled_windows
>>> for window, timestamps, class_index in iter_labeled_windows(
... ["sessions/demo.mg.zip"], "emg", 200, 100
... ):
... print(window.shape, class_index)

iter_target_windows

iter_target_windows(
    paths: list[str] | list[Path],
    stream_name: str,
    target_stream_name: str,
    window_ms: float,
    hop_ms: float,
    phases: set[str] | None = None,
) -> Iterator[tuple[np.ndarray, np.ndarray, float]]

Yield (window, ts, target) triples against a recorded continuous target.

The continuous sibling of iter_labeled_windows. That one walks the label track and hands back a class index, so a session of three cued classes holds three distinct target values — a regressor trained on -1 / 0 / +1 has never seen an intermediate one, and nothing in the data says what half a contraction should produce, so whatever it emits there comes from the estimator's own bias rather than the recording. This one pairs each window with the value of a recorded target stream — a myogestic.sources.target.TargetSource the subject was following — so the targets densely cover the range and interpolation is learned rather than hoped for.

window is channels-first (n_channels, n_samples) and ts the matching 1-D timestamp array, exactly as in iter_labeled_windows. target is channel 0 of the target stream, in whatever units it was recorded in (percent MVC for a force ramp, signed [-1, +1] for a cursor) — this function does not rescale it.

The target is the value at the window's END. The model is causal: it sees a trailing window of EMG and must emit the command for now, so the instant the window ends is the instant it is answering for. Taking the centre would train it to predict the past by half a window, and the mean would train it to output a smeared average that lags every ramp — both produce a model that scores well offline and drags in the hand.

Alignment is by timestamp, never by index. The target stream is typically far slower than the EMG (100 Hz beside 2 kHz) and starts and stops at its own chunk boundaries, so sample i of one is not sample i of the other. The lookup starts from the newest target sample at or before the window's end. A window whose end falls outside the target stream's own time span is dropped, not clamped to the first or last recorded value, because clamping would invent ground truth for the seconds the subject was not being shown anything. A window ending inside a hole in the target stream is dropped for exactly that reason: a gap wider than _MAX_GAP_PERIODS sample periods is a dropout, and the span it covers is as unrecorded as the span past the end.

The value is interpolated only within one phase. Inside a phase the trajectory is smooth and slow, so numpy.interp between the two bracketing target samples reads it more finely than the target's own rate. Across a phase change the value is held at the same sample that supplied the phase, because the value can step there — TargetSource.stop drops the level and switches to idle in a single sample — and interpolating through a step produces a level the subject was never shown: a plausible-looking label for effort that never happened.

A window must also span the time it claims to. Windows are cut by sample index, so wherever the signal stream dropped out, win_samples consecutive recorded samples reach back further than window_ms. Such a window is dropped once it spans more than _MAX_SPAN_SLACK times its nominal length: the target at its end is not the answer for samples much older than it, which is the causal argument above failing rather than an edge case of it.

Phases. Channel 1 carries the phase code (PHASE_CODES). By default only windows ending in a phase where the subject is actually following the target are yielded — every name in PHASE_CODES except "idle" (no block running) and "done" (block finished). Both sit at target 0 while the subject does whatever they like, which is exactly the data that teaches a model that silence means zero and that zero means silence. Pass phases to override, e.g. phases=set(PHASE_CODES) to keep everything, or {"hold"} for plateaus only.

A window straddling a phase boundary is classified by its end, the same instant that gives it its target, and both are read from the same target sample, so the two can never disagree. A window reaching from rest into ramp_up is a ramp_up window and is kept; one whose last sample lands past the end of the block is done and is dropped, along with the EMG that trails it.

Parameters

NameTypeDescriptionDefault
pathslist[str] | list[Path]

Session locations — folders or .mg.zip archives.

stream_namestr

The signal to window, e.g. "emg".

target_stream_namestr

The recorded TargetSource stream, e.g. "target".

window_msfloat

Window length in milliseconds.

hop_msfloat

Step between consecutive window starts, in milliseconds.

phasesset[str] | None

Phase names (not codes) to keep. None means every phase except "idle" and "done".

None

Raises

NameTypeDescriptionDefault
ValueError

If window_ms or hop_ms is not positive, if phases names a phase that is not in PHASE_CODES, or if a session is missing the target stream, recorded it empty, or did not record it from a TargetSource — fewer than that source's two channels, or channel names that are not its ["target_pct", "phase"]. Unlike a missing signal stream — which is skipped with a log line, as in iter_labeled_windows — a missing target is raised: this iterator exists for the target, and silently dropping the one session recorded without it means training on two thirds of the data and never being told.

Examples

>>> from myogestic.session import iter_target_windows
>>> for window, timestamps, target in iter_target_windows(
... ["sessions/demo.mg.zip"], "emg", "target", 200, 100
... ):
... print(window.shape, target)

iter_aligned_windows

iter_aligned_windows(
    paths: list[str] | list[Path],
    primary_stream_name: str,
    aligned_stream_names: list[str],
    window_ms: float,
    hop_ms: float,
    n_alignment_samples: int = 1,
    *,
    with_names: bool = False,
) -> Iterator[tuple[np.ndarray, dict[str, Any], np.ndarray]]

Yield (primary_window, aligned, ts) for regression training.

primary_window is channels-first (n_channels, n_samples). For each primary window, find the nearest sample in every aligned stream at the window midpoint and average n_alignment_samples around that index.

With with_names=True each aligned stream's value is a dict[channel_name, float] instead of a bare vector, so a training script selects a target by name rather than by wire position. That is the difference between a script that keeps working when a configuration is reordered and one that silently trains on the wrong channel. Requires the recording to carry channel names; it raises naming the stream if it does not.

Examples

>>> from myogestic.session import iter_aligned_windows
>>> for window, aligned, timestamps in iter_aligned_windows(
... ["sessions/demo.mg.zip"], "emg", ["vhi_control"], 200, 50
... ):
... target = aligned["vhi_control"]

split_sessions_by_stream

split_sessions_by_stream(paths: Iterable[P], stream: str) -> SessionSplit[P]

Sort session paths by whether they recorded stream, without holding them open.

The question every mixed training callback asks first: sessions with a kinematics stream train against it, the rest fall back to synthetic targets from their labels.

Each session is opened only to read its store list and is closed again straight away — an open zarr.storage.ZipStore keeps a lock on the .mg.zip, which on Windows blocks deleting or moving the file afterwards.

Parameters

NameTypeDescriptionDefault
pathsIterable[P]

Session locations — folders or .mg.zip archives, e.g. data.paths.

streamstr

The stream name to test for, e.g. "vhi_control".

Returns

NameTypeDescriptionDefault
SessionSplit

The three-way outcome, each list in the order the paths came in.

Examples

>>> from myogestic.session import split_sessions_by_stream
>>> kin, labels, unreadable = split_sessions_by_stream([], "vhi_control")
>>> kin, labels, unreadable
([], [], [])

SessionSplit

Bases: NamedTuple

Which sessions carry a stream, which do not, and which could not be opened.

Attributes

NameTypeDescriptionDefault
with_streamlist[P]

Paths whose recording contains the stream — the iter_aligned_windows set.

without_streamlist[P]

Paths that opened fine and simply do not have it — the iter_labeled_windows fallback set.

unreadablelist[tuple[P, Exception]]

(path, exception) for every path that would not open at all. Returned rather than logged, because where a skipped session is reported belongs to the caller: a training callback puts it in the app's own log, not in logging.

Where takes are saved

Everything for one participant lives under data/<ID>/, in recordings/, predictions/ and models/. See On-disk layout and how each file is named in File names.

participant_dir

participant_dir(
    root: str | Path,
    participant: str = '',
    kind: str = 'recordings',
) -> Path

Return the folder that holds one kind of file for one participant.

Parameters

NameTypeDescriptionDefault
rootstr | Path

Data root, usually "data".

participantstr

Pseudonymized ID, reduced to a safe single path segment.

''
kindstr

"recordings", "predictions" or "models". "" drops the kind level, for tools that keep their own layout.

'recordings'

Returns

NameTypeDescriptionDefault
pathlib.Path

root/ID/kind, or root/kind when the ID has no usable characters. Nothing is created.

Examples

>>> participant_dir("data", "P-014", "models").as_posix()
'data/P-014/models'

labelled_path

labelled_path(
    base_path: str | Path,
    participant: str = '',
    suffix: str = '',
    *,
    kind: str = 'recordings',
    when: time.struct_time | None = None,
) -> Path

Build a timestamped path in a participant's folder for one kind of file.

Parameters

NameTypeDescriptionDefault
base_pathstr | Path

Data root, usually "data".

participantstr

Pseudonymized ID, reduced to a safe single path segment. An empty slug drops the participant level and the filename prefix.

''
suffixstr

Optional filename suffix, appended after an underscore, such as "spar-mlp.joblib".

''
kindstr

Subfolder, see participant_dir. Default "recordings".

'recordings'
whentime.struct_time | None

Local time to stamp, from time.localtime. Default: now.

None

Returns

NameTypeDescriptionDefault
pathlib.Path

base/ID/kind/ID_YYYYMMDD-HHMM[_suffix] or base/kind/YYYYMMDD-HHMM[_suffix], in local time. No directories are created and no name is reserved: two files in one minute share it.

class_codes

class_codes(
    class_names: Sequence[str],
    pinned: Mapping[str, str] | None = None,
) -> dict[str, str]

Build short class codes for file names. Rest → R, Three-Finger-Pinch → Tfp.

A code is the first letter of the first word, plus the first letter of each further word (a number stays whole). Where two codes would match, ignoring case, both take more letters of their first word until they differ: Rest and Ring become Re and Ri. Codes are worked out over the whole list, so a class keeps its code in every take of an app. Classes alike to the last letter (Rest and rest) get their position appended, Rest1 and Rest2: pin a code to choose an alternative.

Parameters

NameTypeDescriptionDefault
class_namesSequence[str]

The app's classes, usually ctx.class_names.

pinnedMapping[str, str] | None

Codes the app fixes itself, by class name; the rest are worked out around them. Pin the codes once an app has recorded data: adding a class later can otherwise change the codes of the ones it clashes with.

None

Returns

NameTypeDescriptionDefault
dict

Class name to code, in class_names order.

Raises

NameTypeDescriptionDefault
ValueError

A pinned code is not ASCII letters and digits, or two pinned codes match.

Examples

>>> class_codes(["Rest", "Thumb", "Index", "Middle", "Ring", "Little"])
{'Rest': 'Re', 'Thumb': 'T', 'Index': 'I', 'Middle': 'M', 'Ring': 'Ri', 'Little': 'L'}
>>> class_codes(["Rest", "Fist", "Three-Finger-Pinch"], {"Rest": "0"})
{'Rest': '0', 'Fist': 'F', 'Three-Finger-Pinch': 'Tfp'}

model_path

model_path(root: str | Path, participant: str, model: str) -> Path

Claim a new model file, root/ID/models/<ID>_<YYYYMMDD-HHMM>_<model>.joblib.

Parameters

NameTypeDescriptionDefault
rootstr | Path

Data root, usually "data".

participantstr

Pseudonymized ID; empty puts the model in root/models.

modelstr

The model's type, such as "spar-mlp", lowercased into the name.

Returns

NameTypeDescriptionDefault
pathlib.Path

A new, empty file, -2, -3 … when another model of that type was saved in the same minute, never overwriting one. Save the model over it.

Examples

>>> model_path("data", "P-023", "SPAR MLP").name
'P-023_20261105-1535_spar-mlp.joblib'

Data model

Session

Session(
    base_path: str = 'data',
    participant: str = '',
    kind: str = 'recordings',
) -> None

One on-disk recording with per-stream Zarr arrays and a label track.

Created when the user clicks Record, finalized when they click Stop. While active, every acquisition thread with a registered stream appends to the session's Zarr stores; UI label clicks emit [LabelEvent][] entries onto the label track. Metadata is checkpointed at creation and stream declaration with finished=False. save_meta updates it at stop, and pack_to_zip packs the tree into a portable .mg.zip.

Layout on disk (one folder per recording, named with the start minute, packed on stop to <ID>_<YYYYMMDD-HHMM>_<what>.mg.zip, see File names)::

data/P-014/recordings/P-014_20260517-1423/
emg.zarr/ # shape (n_samples, n_channels)
emg_timestamps.zarr/ # shape (n_samples,) float64
vhi_control.zarr/ # any additional stream
vhi_control_timestamps.zarr/
meta.json # streams_info, app_name, class_names
labels.json # the LabelEvent list

Read sessions back with open_session_store, which handles both folders and .mg.zip archives.

Parameters

NameTypeDescriptionDefault
base_pathstr

Data root; the session creates a timestamp-named subdirectory in base_path/ID/kind. Default "data" (created if missing).

'data'
participantstr

Pseudonymized ID. A safe slug labels the folder and meta.json and nests the recording under base_path/ID/kind. Empty by default, which puts the recording directly in base_path/kind.

''
kindstr

"recordings" (default) or "predictions", see participant_dir. "" writes straight into base_path (or base_path/ID), for a converter or script that keeps its own folder layout.

'recordings'

Examples

>>> from myogestic.session import Session
>>> session = Session("data")
>>> session.add_label(0, timestamp=123.0)

init_stream

init_stream(
    stream_name: str,
    info: StreamInfo,
    *,
    chunk_rows: int | None = None,
) -> None

Called once per stream when recording starts.

chunk_rows sizes the zarr chunk; the default is one second of samples. Event streams pass EVENT_CHUNK_ROWS because their rate is nominal.

append

append(stream_name: str, data: np.ndarray, timestamps: np.ndarray) -> None

Called from acquire loop when recording. data: (n_samples, n_channels).

event_streams

event_streams: tuple[str, ...]

Names of the event streams, in declaration order. One row per tick, nominal rate.

append_event

append_event(
    name: str,
    values: Any,
    timestamp: float,
    *,
    channel_names: Sequence[str] | None = None,
    fs: float = 1.0,
    dtype: Any = np.float32,
) -> None

Append one timestamped row to an event stream, declaring it on first use.

values is flattened and cast to dtype; its width is fixed by the first call. A later row with another width raises ValueError to prevent ragged arrays. fs is the nominal rate the declaration carries, so ReplaySource can pace the stream; the rows are irregular and meta.json lists the stream under event_streams to say so.

Rows are buffered and written in batches (EVENT_CHUNK_ROWS, EVENT_FLUSH_SECONDS). After freeze a row is dropped with a debug log, like a late append.

Parameters
NameTypeDescriptionDefault
dtypeAny

Dtype fixed by the first declaration of name. Later calls ignore their dtype argument and coerce rows to the stored dtype. Callers cannot change a declared stream's dtype. Defaults to float32 for signals and features. Use float64 for clocks such as LSL timestamps or local_clock(). Float32 has about 7 significant digits and loses millisecond precision after roughly a day of uptime.

np.float32

freeze

freeze() -> None

Close the session to new rows and flush every event buffer. Idempotent.

App.stop_recording calls this right after detaching the streams and before any finalize hook or meta.json is written, so nothing can declare a stream that the metadata does not list. pack_to_zip and discard call it as well.

Flushes every buffer even if one fails; per-buffer failures are logged at warning level, and the buffer is marked dead to prevent retries.

add_label

add_label(class_index: int, timestamp: float | None = None) -> None

Append a label event to the session's label track.

Parameters
NameTypeDescriptionDefault
class_indexint

Class index for the event; -1 marks a rest / no-class boundary.

timestampfloat | None

Event time in seconds (mne_lsl clock). Defaults to the current local_clock() when omitted.

None

save_meta

save_meta(
    app_name: str,
    class_names: list[str] | None = None,
    control_space: Mapping[str, object] | None = None,
    control_spaces: Mapping[str, Mapping[str, object]] | None = None,
    class_codes: Mapping[str, str] | None = None,
    *,
    finished: bool = True,
) -> None

Write meta.json + labels.json to the session folder.

Parameters
NameTypeDescriptionDefault
app_namestr

Identifier for the producing app.

class_nameslist[str] | None

Optional human-readable names for label class indices. Persisting them lets readers render saved labels without an external lookup.

None
control_spaceMapping[str, object] | None

Optional control configuration this recording was made under, as produced by ControlMap.as_control_space(). Records each value's alias and target control. Carries a format tag; read it back with myogestic.controls.read_control_space, which refuses a pre-alias control space by name instead of reinterpreting it.

None
control_spacesMapping[str, Mapping[str, object]] | None

Additional control configurations keyed by recording stream name. Each entry has the same format as control_space. Omitted from metadata when empty, preserving the single-link recording format.

None
class_codesMapping[str, str] | None

Codes the app pins for some classes, usually ctx.class_codes. The rest are worked out by class_codes; the whole map is saved as meta.json's class_codes and names the archive.

None
finishedbool

Whether the take stopped normally. Start and declaration checkpoints pass False; finalization uses the default True. Recovery keeps an unfinished take marked False even after it is packed.

True

pack_to_zip

pack_to_zip() -> Path

Pack the session folder into one <ID>_<YYYYMMDD-HHMM>_<what>.mg.zip.

<what> comes from take_stem: the recorded classes' codes (R+F, the first three and a count past 40 characters) and the name, or free, guided or follow-F for a take in predictions/. -2, -3 … are added only when that whole name is taken.

Uses ZIP_STORED: zarr chunks are already compressed internally, so an outer compression layer would add CPU for little gain.

discard

discard() -> None

Delete this session's folder and everything recorded into it.

Use for a discarded recording, such as a false start or bad trial. Releases Zarr handles before removal, as pack_to_zip does. Windows cannot remove the folder while any chunk file remains open.

get_trials

get_trials(
    stream_name: str,
    pre_s: float = 0.0,
    post_s: float = 0.0,
    class_names: list[str] | None = None,
) -> list[Recording]

Extract discrete labeled windows for classification training.

get_continuous

get_continuous(stream_name: str) -> tuple[np.ndarray, np.ndarray]

Return full stream data + timestamps for regression training.

stream_info

stream_info(stream_name: str) -> StreamInfo

Public accessor for a stream's StreamInfo.

close

close() -> None

Release file handles held by this session.

Closes the ZipStore opened by [open_session_store][] for a .mg.zip and drops the array references. Safe to call more than once. On Windows an open ZipStore keeps the archive locked, so close the session before moving or deleting the .mg.zip. Use with open_session_store(p) as s: ... for automatic closure.

LabelEvent

LabelEvent(timestamp: float, class_index: int) -> None

A class selection at an LSL timestamp in the session's label track.

Recorded whenever the user clicks a class button in RecordingControls. The label track is a chronological list of these events; the recording-window iterators (iter_labeled_windows, iter_aligned_windows) walk it to decide which sample range gets which class index.

Attributes

NameTypeDescriptionDefault
timestampfloat

LSL clock time (seconds) when the label was emitted. Mint one by hand with mne_lsl.lsl.local_clock().

class_indexint

Index into the session's class_names list. -1 is the unlabeled sentinel (the iterators skip it).

Examples

>>> from myogestic.session import LabelEvent
>>> event = LabelEvent(timestamp=123.0, class_index=1)
>>> event.class_index
1

Recording

Recording(
    class_index: int,
    class_name: str,
    data: np.ndarray,
    timestamps: np.ndarray,
) -> None

A single labeled trial, extracted from a Session.

Examples

>>> import numpy as np
>>> from myogestic.session import Recording
>>> recording = Recording(
... 1, "Fist", np.zeros((3, 2), dtype=np.float32), np.arange(3, dtype=np.float64)
... )
>>> (recording.class_name, recording.data.shape)
('Fist', (3, 2))