Skip to content
GitHub · 2.7.0

Reference

API cheatsheet

Common public signatures, maintained by hand. This list is not exhaustive. Each name links to its description and parameter/return tables in the API reference.

Core

App · Stream · Context · StreamInfo · Grid · Layout · TrainingData

Python
App(name, theme=True, docking=False, ui_scale=None, require_participant=False)
.streams(*streams)
.ui(fn) # decorator
.popout(title, gui_fn) # App(docking=True)
.start_recording(base_path="data")
.stop_recording(*, wait=False)
.run(mode="gui", window_size=(1280, 800), fullscreen=False) # or mode="headless"
.ctx # Context
Stream(name, source, window_ms, buffer_ms=10000, notch_hz=0)
.start() / .stop() / .reconnect(target=None)
.get_window() -> (data, ts) # data is channels-first
.get_display(n_pixels=800) -> (ts, data) | None # M4 display points; samples-first
.get_raw_snapshot() -> (ts, data) | None # full buffer; samples-first
Context # flat dataclass
.streams: dict[str, Stream]
.state: str # "idle" / "recording" / ...
.session: Session | None # current or most recent take
.class_names: list[str]
.status_message: str
Grid(rows, cols) # @app.ui layout helper
Grid.areas(template, *, row_height=None, col_width=None, bare=()) # named cells; "a | b" = tabs
.area(name) # with grid.area("record"):
Layout(wide=Grid, narrow=Grid, breakpoint=Px(1100))
[name] # with layout["record"]:
StreamInfo(n_channels, fs, dtype=float32, channel_names=None)
TrainingData(paths=[], class_names=[], classes=set())
.is_empty

Sources

LSLSource · ReplaySource · SerialSource

Python
LSLSource(stream_name, dtype="float32")
ReplaySource(session_path, stream_name, speed=1.0) # accepts .mg.zip
SyntheticSource(n_channels=8, fs=2048.0, *, noise=0.12, hum=0.35,
hum_hz=50.0, activation=1.0, direction=0.0,
waveform="sine", require_target=False) # opt in to waveform="emg"
SerialSource(
port, baud, n_channels, fs
) # extras:[serial]; from myogestic.sources.serial_source import SerialSource

Targets

Anything that moves is a target. Three methods, any transport.

Target · Capability · ControlBus · ControlLink · ControlLinkConnector · RemoteTarget · KeyboardTarget

Python
# The protocol you implement — no base class, no registration.
bind(controls: ControlSet) -> None # main thread, may raise: refuse a bad map here
send(values, changed) -> None # predict thread, must not raise
stop() -> None # idempotent
claims: frozenset[str] # optional: which aliases you drive
capabilities() -> Sequence[Capability] # optional: what you export
Capability(address, kind, lo=-1.0, hi=1.0, rest=0.0, states=(),
rest_state="", activation_threshold=0.0, description="")
load_control_map(mapping) -> ControlMap # a Mapping, not a path
resolve(control_map, capabilities) -> ControlSet # needs a live target's answer
ControlBus(controls, *, targets=(), smoothing=None, hz=50.0,
dead_zone=None, hysteresis=None, on_warn=None, ctx=None, record_as="controls")
.push(values) -> dict .select(name, state) -> bool .stop() -> None
connect_controls(control_map, targets, ...) -> ControlBus | None # None while unreachable
ControlLinkConnector(*links, retry_s=2.0).poll() -> bool # non-blocking UI retry

Outlets

LSLOutlet sends paced telemetry or serves as a target’s transport. It drives nothing on its own. It has no aliases, no declared range and no rest on stop. Use a target for these guarantees.

Python
LSLOutlet(name, n_channels, hz=50)
.push(data) -> None .flush() -> None .stop() -> None

ML pipeline

Pipeline · save_pickle · load_pickle

Python
Pipeline(app, predict_hz=50, *, input_streams=None)
@pipeline.extract(windows: dict[str, np.ndarray]) # channels-first
@pipeline.train(data: TrainingData)
@pipeline.predict(model, features) -> dict
.training_data: TrainingData | None
.start_training() / .start_predicting() / .stop_predicting()
.save_model / .load_model # set to enable buttons
.model / .predictions / .train_log
save_pickle(model, path) / load_pickle(path)

Session

open_session_store · iter_labeled_windows · iter_aligned_windows

Python
open_session_store(path) -> Session # folder OR .mg.zip
iter_labeled_windows(paths, stream_name, window_ms, hop_ms,
classes=None)
-> Iterator[(window, ts, class_index)] # window: (n_ch, n_samp)
iter_aligned_windows(paths, primary_stream_name, aligned_stream_names,
window_ms, hop_ms, n_alignment_samples=1, *, with_names=False)
-> Iterator[(primary_window, {name: vec}, ts)]

Filters

OneEuroFilter · GaussianFilter · IdentityFilter · make_filter

Python
OneEuroFilter(hz=50.0, min_cutoff_hz=1.0, beta=0.02, derivative_cutoff_hz=1.0)
GaussianFilter(n_vectors=5, sigma=1.0)
IdentityFilter()
make_filter(name, hz=50.0, **kwargs) -> VectorFilter
filter(x, timestamp=None) -> np.ndarray # __call__ all filters

Widgets

Construct once during setup, then call .ui(...) each frame in @app.ui. Full list on the Widgets API page.

SignalViewer · RawSignalViewer · RecordingControls · SessionManager · Heatmap · LinePlot · PostProcessor

Python
SignalViewer(stream_name, *, selectable=False, scale_mode="auto",
y_range=(-1, 1), show_diagnostics=False, show_markers=False)
.ui(ctx)
RawSignalViewer(stream_name, *, widget_id=None, show_title=True)
# Window selector; Channels chip popup
.ui(ctx)
RecordingControls(class_names=None, *, on_record, on_stop, on_gesture=None)
.ui(ctx)
SessionManager(base_path="data", *, title="Sessions", class_names=None)
.ui(participant=None) -> TrainingData(paths, class_names, classes)
ProcessLauncher(processes)
.ui()
Scatter2D(label, *, show_title=True) / Scatter3D(label, *, show_title=True)
.ui(points, labels=None, class_names=None)
Heatmap(label, *, label_fmt="%.1f", show_title=True)
.ui(data, x_tick_labels=None, y_tick_labels=None, vrange=None)
# shared colour range; scale strip
LinePlot(label, *, y_range=None, show_title=True)
.ui(data, channel_names=None) # Auto / Shared when y_range is given
panel_header(title, icon=None)
output_filter = PostProcessor(hz=50)
output_filter.ui()
popout_panel(title, gui_fn)
TemplateInspector(widget_id)
.ui(rows)
TrialPreview(widget_id=widget_id)
.ui(data, fs)

Plot widgets use panel headers and UI-scaled sizes; show_title=False hides the header title. Line and scatter plots show PALETTE-dot legend chips below the plot. Pass the same y_range=(low, high) to line plots that should be compared; they start in Shared mode. Raw viewers request only the visible samples and show sample rate, selected channels, points per channel and FPS in a mono footer. Give raw viewers distinct widget_id values to keep their windows and channel selections independent on one stream.

ML widgets

TrainButton · PredictButton · TrainingLog · SaveModelButton · LoadModelButton · PipelinePanel

Python
TrainButton(pipeline).ui()
PredictButton(pipeline).ui()
TrainingLog(pipeline).ui()
SaveModelButton(pipeline, path).ui()
LoadModelButton(pipeline, path).ui()
PipelinePanel(pipeline).ui()