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
| Name | Type | Description | Default |
|---|---|---|---|
path | str | Path |
The unpacked take folder, not its parent or an existing archive. |
Returns
| Name | Type | Description | Default |
|---|---|---|---|
| pathlib.Path |
The packed |
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
| Name | Type | Description | Default |
|---|---|---|---|
paths | list[str] | list[Path] |
Session locations — folders or | |
stream_name | str |
The signal to window, e.g. | |
target_stream_name | str |
The recorded | |
window_ms | float |
Window length in milliseconds. | |
hop_ms | float |
Step between consecutive window starts, in milliseconds. | |
phases | set[str] | None |
Phase names (not codes) to keep. | None |
Raises
| Name | Type | Description | Default |
|---|---|---|---|
| ValueError |
If |
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
| Name | Type | Description | Default |
|---|---|---|---|
paths | Iterable[P] |
Session locations — folders or | |
stream | str |
The stream name to test for, e.g. |
Returns
| Name | Type | Description | Default |
|---|---|---|---|
| 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
| Name | Type | Description | Default |
|---|---|---|---|
with_stream | list[P] |
Paths whose recording contains the stream — the | |
without_stream | list[P] |
Paths that opened fine and simply do not have it — the | |
unreadable | list[tuple[P, Exception]] |
|
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
| Name | Type | Description | Default |
|---|---|---|---|
root | str | Path |
Data root, usually | |
participant | str |
Pseudonymized ID, reduced to a safe single path segment. | '' |
kind | str |
| 'recordings' |
Returns
| Name | Type | Description | Default |
|---|---|---|---|
| pathlib.Path |
|
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
| Name | Type | Description | Default |
|---|---|---|---|
base_path | str | Path |
Data root, usually | |
participant | str |
Pseudonymized ID, reduced to a safe single path segment. An empty slug drops the participant level and the filename prefix. | '' |
suffix | str |
Optional filename suffix, appended after an underscore, such as
| '' |
kind | str |
Subfolder, see | 'recordings' |
when | time.struct_time | None |
Local time to stamp, from | None |
Returns
| Name | Type | Description | Default |
|---|---|---|---|
| pathlib.Path |
|
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
| Name | Type | Description | Default |
|---|---|---|---|
class_names | Sequence[str] |
The app's classes, usually | |
pinned | Mapping[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
| Name | Type | Description | Default |
|---|---|---|---|
| dict |
Class name to code, in |
Raises
| Name | Type | Description | Default |
|---|---|---|---|
| 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
| Name | Type | Description | Default |
|---|---|---|---|
root | str | Path |
Data root, usually | |
participant | str |
Pseudonymized ID; empty puts the model in | |
model | str |
The model's type, such as |
Returns
| Name | Type | Description | Default |
|---|---|---|---|
| pathlib.Path |
A new, empty file, |
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 listRead sessions back with open_session_store,
which handles both folders and .mg.zip archives.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
base_path | str |
Data root; the session creates a timestamp-named subdirectory in
| 'data' |
participant | str |
Pseudonymized ID. A safe slug labels the folder and | '' |
kind | str |
| '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
| Name | Type | Description | Default |
|---|---|---|---|
dtype | Any |
Dtype fixed by the first declaration of | 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
| Name | Type | Description | Default |
|---|---|---|---|
class_index | int |
Class index for the event; | |
timestamp | float | None |
Event time in seconds ( | 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
| Name | Type | Description | Default |
|---|---|---|---|
app_name | str |
Identifier for the producing app. | |
class_names | list[str] | None |
Optional human-readable names for label class indices. Persisting them lets readers render saved labels without an external lookup. | None |
control_space | Mapping[str, object] | None |
Optional control configuration this recording was made under, as produced
by | None |
control_spaces | Mapping[str, Mapping[str, object]] | None |
Additional control configurations keyed by recording stream name. Each
entry has the same format as | None |
class_codes | Mapping[str, str] | None |
Codes the app pins for some classes, usually | None |
finished | bool |
Whether the take stopped normally. Start and declaration checkpoints
pass | 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
| Name | Type | Description | Default |
|---|---|---|---|
timestamp | float |
LSL clock time (seconds) when the label was emitted. Mint one by hand
with | |
class_index | int |
Index into the session's |
Examples
>>> from myogestic.session import LabelEvent>>> event = LabelEvent(timestamp=123.0, class_index=1)>>> event.class_index1Recording
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))