Guides
Record for proportional control
A proportional decoder estimates effort and direction. Half a contraction moves the paddle half as fast. Cued Down, Rest and Up provide three distinct target values. Recording only those cues leaves a three-class target problem regardless of the estimator’s name. Establish level coverage in the recording before choosing a model. Tree ensembles benefit from more levels; a linear model can interpolate between three. See the measurement below.
This page is the graded counterpart to Record good training data,
which covers the cued protocol for classification.
examples/start_here/pong.py
records this block through its Follow the cursor button and fits it in Proportional mode.
Error with three levels
On three 8-channel bracelet recordings of cued Down/Rest/Up, a CatBoost regressor fitted to class values predicts rest below about 30 % effort.
A tree ensemble’s output is an average of training targets, so it cannot emit a level the block never asked for. A simulation of the same protocol reproduces this error: at a true +0.50, the three-class fit emits -0.34. Fitting the same estimator on densely covered levels cuts intermediate-effort error 14x, with CatBoost MAE 0.402 → 0.029.
The active ingredient is the number of distinct levels
Do not choose a followed cursor on the claim that it is more accurate than a staircase. The reason to prefer it is human feedback. A cursor gives participants continuous visual error feedback to reach intermediate levels. A staircase cue such as “go to 0.6” requires them to judge what 0.6 feels like.
Choose the protocol for your estimator:
- If your estimator is linear, this protocol buys you nothing. Record whatever is convenient.
- A cued staircase can use eleven holds to cover intermediate levels; three holds leave sparse coverage.
Record the block
Pursuit is the trajectory: rest at exactly 0.0, then a
smooth aperiodic wander over signed [-1, +1], then rest again. It is deterministic
arithmetic on the hop index, so two sessions record the identical path and an offline
script can assert an exact value.
TargetSource records the cursor as a stream
on the EMG’s clock, providing aligned targets for training. Reconstructing
from a start time and saved parameters would require trusting that the clocks
agree and that nobody edited the parameters between the note and the take.
from myogestic import Streamfrom myogestic.sources import TargetSourcefrom myogestic.tracking import Pursuit
# Defaults are a 58 s block: 5 s rest, 24 hops of 2 s, 5 s recover.cursor = TargetSource(Pursuit())target_stream = Stream("target", source=cursor, window_ms=200)Follow these four wiring steps:
- Call
target_stream.reconnect(). A software source has nothing physical to attach it automatically.start_recordingsilently skips a stream whoseinfo is None. - Press Record first, then start the block.
cursor.start()restarts task time from zero; the stream runs fromreconnect()todisconnect()either way. - Exclude the target with
DevicePicker("emg", exclude=("target",)). One stray Connect replaces theTargetSourcewith an amplifier and the recording holds EMG under the nametarget. - Draw the cursor from
cursor.elapsed, not from a fresh clock reading. It is the task time of the newest sample actually emitted, so the ghost cannot sit a frame off the ground truth the model is later fitted against.
Pursuit accepts hop_s, hops and reps. hop_s sets seconds per waypoint
segment; halving it doubles every rate while preserving levels. Fewer than about
16 hops can leave clustered coverage. Increase hops to lengthen a block;
repetitions are identical and can be learned after the first.
Fit it
iter_target_windows pairs each EMG window with
the recorded cursor value at the window’s end. This trains the model to estimate
the current command from a trailing window. This is the causal target choice. A centre target is half a window
behind; a window mean introduces ramp lag.
By default it includes windows ending in followed phases. It excludes PHASE_CODES
idle and done, which hold target 0 before and after a block. Those
phases have no following task, and the participant may move freely, so their
zero targets do not describe the participant’s effort.
The block below fabricates a rehearsal recording so the page is self-checking; with a real
session you replace the path and keep everything from features down.
import tempfile
import numpy as np
from myogestic.session import Sessionfrom myogestic.sources.target import PHASE_CODESfrom myogestic.stream import StreamInfofrom myogestic.tracking import Pursuit
task = Pursuit(rest_s=1.0, hop_s=0.5, hops=24, recover_s=1.0) # short, so this runs fastfs, target_fs = 1000.0, 100.0rng = np.random.default_rng(0)
# Channels 0-3 answer Down, 4-7 answer Up; every channel grows with effort.side = np.where(np.arange(8) < 4, -1.0, 1.0)
def synth(levels: np.ndarray) -> np.ndarray: """Synthetic EMG for a column of signed effort levels — one row per sample.""" return rng.normal(scale=0.05 + 0.45 * np.maximum(levels[:, None] * side, 0.0))
sess = Session(base_path=tempfile.mkdtemp())sess.init_stream("emg", StreamInfo(n_channels=8, fs=fs, dtype=np.dtype("float32")))sess.init_stream( "target", StreamInfo( n_channels=2, fs=target_fs, dtype=np.dtype("float32"), channel_names=["target_pct", "phase"], ),)
emg_ts = np.arange(int(task.total_duration * fs)) / fssess.append("emg", synth(np.array([task.value_at(t) for t in emg_ts])).astype(np.float32), emg_ts)
target_ts = np.arange(int(task.total_duration * target_fs)) / target_fssess.append( "target", np.array( [(task.value_at(t), PHASE_CODES[task.phase_at(t)]) for t in target_ts], dtype=np.float32 ), target_ts,)sess.save_meta("cursor rehearsal")from myogestic.recipes.estimators import directional_decoderfrom myogestic.recipes.features import mav, rmsfrom myogestic.session import iter_target_windows
def features(window: np.ndarray) -> np.ndarray: """RMS and MAV of one channels-first window, stacked into one row.""" return np.concatenate([rms(window), mav(window)])
X, y = [], []for window, _ts, level in iter_target_windows([str(sess.path)], "emg", "target", 200, 100): X.append(features(window)) y.append(level)
model = directional_decoder().fit(np.stack(X), np.array(y))directional_decoder is the model this
protocol uses. It estimates effort from the row total, rescaled to 0 at rest
and 1 at full contraction. It estimates direction by projecting the
amplitude-normalized row onto a Fisher axis, then multiplies effort and direction.
A regressor over raw features can conflate the two and learn the louder cue,
causing the non-monotonic CatBoost behaviour above. It requires only NumPy. catboost_regressor also works on this data and is the
comparison worth running; it is the estimator the 14x number above was measured on.
Check before the participant does
Assert that the decoder is monotonic in effort:
probe = [-1.0, -0.5, 0.0, 0.5, 1.0]commands = model.predict(np.stack([features(synth(np.full(400, level)).T) for level in probe]))
print([round(float(c), 2) for c in commands]) # [-1.0, -0.59, -0.0, 0.61, 1.0]assert np.all(np.diff(commands) > 0.0), "the fit is not monotonic in effort"On real data the same check is a held-out probe at a few levels, plus a global gain sweep: multiply every channel by 1.0 / 1.3 / 1.6 and the command must not fall. That is the sweep CatBoost fails even on a densely covered block. Run it against whichever estimator you actually ship; it is a property of the model, not of the recording.
Decoder requirements
The effort scale is fitted per window and pooled by median, over the windows whose
target reaches abs(y) >= 0.5:
span_ = median((total - rest_) / abs(y)) over abs(y) >= 0.5, at least 3 windowsTwo consequences for how you record:
- Record at least three windows at half deflection or above. Below this count,
fitraises with the count and largestabs(y)instead of fitting two windows. A defaultPursuit()block provides 165 qualifying windows, 55 times the floor of 3. - The target must be in signed
[-1, +1].fitraises on anyabs(y) > 1, because nothing else in it can see a unit error: a percent-of-MVC column divides through the span at up to 100 instead of 1,activationsaturates, and the graded command becomes a three-step staircase with no complaint. See Mixing cued and cursor sessions. - Cued blocks retain the same scale. Every non-rest window has
abs(y) == 1, so the threshold selects the same windows asy != 0. Dividing by 1 is a no-op and the median is translation-equivariant. The scaled-target and cued-only rules return identical floats on the three cued recordings with odd window counts. With even counts,numpy.medianaverages the two middle values; the measured worst-case difference is 1.8e-15.
The threshold trades bias for count. Dividing by abs(y) multiplies a window’s noise by
1 / abs(y), and an EMG baseline adds to the row total without scaling with effort, so
low-target windows read high:
abs(y) threshold |
0.25 | 0.50 | 0.75 | 0.90 |
|---|---|---|---|---|
| fitted span (reference 4.23) | 4.40 | 4.29 | 4.24 | 4.22 |
| windows used | 301 | 165 | 68 | 25 |
0.5 caps the noise gain at 2x, lands 1.3 % high and keeps a third of the block. Getting that to 0.1 % costs four fifths of the windows, which is the wrong side of the trade on a short recording.
The direction estimate uses every non-rest window, including quiet ones. This choice was measured. Restricting it to the same strong windows changed mean MAE 0.0820 → 0.0812 over five seed pairs, a 1 % difference that swaps sign across levels, for two thirds fewer rows in the covariance.
Mixing cued and cursor sessions
Both protocols produce a signed [-1, +1] target column and can train together.
Cued Down / Rest / Up correspond to constant levels -1 / 0 / +1.
This compatibility is the reason for the signed target standard.
split_sessions_by_stream routes each
session by target-stream presence, allowing cued recordings to contribute:
from myogestic.session import iter_labeled_windows, iter_target_windows, split_sessions_by_stream
split = split_sessions_by_stream(paths, "target")
for path in split.with_stream: # cursor blocks: the recorded level for window, _ts, level in iter_target_windows([path], "emg", "target", 200, 100): ...
for path in split.without_stream: # cued blocks: the class as a level for window, _ts, class_index in iter_labeled_windows([path], "emg", 200, 100): ...Do not expect three cued sessions plus one cursor session to behave like four cursor sessions. Distinct target levels matter, and a fit dominated by cued data still sees mostly three levels.
See also
- Record good training data - the cued protocol, and how many cycles a classifier actually needs.
- Track a force target - the other recorded-target protocol: isometric trapezoids in percent of MVC, on an amplifier AUX channel.
- Examples directory -
start_here/pong.py, this page as an application. - Estimator recipes -
directional_decoderin full, including the measurements behind it.