Compose emgpredictor

.gitignore

@@ -45,4 +45,27 @@ test_*.py
 *.csv
 .vscode/*
 test_delsys_api.py
-resources/
+resources/
+*.csv 
+*.txt
+ContinuousTransitions/*
+FORS-EMG/*
+MyoDisCo/*
+NinaProDB1/*
+*.zip
+libemg/_datasets/__pycache__/*
+CIILData/*
+EMGEPN612.pkl
+OneSubjectMyoDataset/
+_3DCDataset/
+ContractionIntensity/
+CIILData/
+*.pkl
+LimbPosition/
+CNN.py
+MLP.py
+__pycache__/
+MLPR.py
+docs/Makefile
+sifibridge-*
+*.pyc

docs/source/conf.py

@@ -22,7 +22,7 @@
 author = 'Ethan Eddy, Evan Campbell, Angkoon Phinyomark, Scott Bateman, and Erik Scheme'
 
 # The full version, including alpha/beta/rc tags
-release = '1.0.0'
+release = '2.0.0'
 
 
 # -- General configuration ---------------------------------------------------

docs/source/doc.md

@@ -20,6 +20,10 @@ The goal of this library is to provide an easy to use and feature-rich API for d
 $ pip install libemg
 ```
 
+# Interactive API Walkthrough
+
+Interactive offline and online walkthroughs were created as part of a `LibEMG` workshop we presented at [MEC24](https://www.unb.ca/ibme/mec/index.html), hosted by the Institute of Biomedical Engineering. These walkthroughs step through much of the core functionality of `LibEMG`, and offer visuals to explain pieces of the API. The offline example is formatted as a jupyter notebook, allowing you to see visuals for each code snippet without running the code yourself. Please check out out the workshop GitHub repository to see these interactive API walkthroughs: <https://github.com/LibEMG/LibEMG_MEC24_Workshop>.
+
 # Questions
 Check out our discord server if you have questions, comments, or feature requests: https://discord.gg/NeqTTXmM4F
 

docs/source/documentation/adaptation/adaptation.rst

@@ -0,0 +1,4 @@
+Online Adaptation
+------------------------------
+.. include:: adaptation_doc.md
+   :parser: myst_parser.sphinx_

docs/source/documentation/adaptation/adaptation_doc.md

@@ -0,0 +1,160 @@
+[View Source Code](https://github.com/ECEEvanCampbell/CoAdaptUnderCurriculum)
+
+The offline performance of a myoelectric model (e.g., $R^2$, mean absolute error on screen-guided training data) does not necessarily reflect how usable it is once a person is actually in the loop. A model that looks excellent on a calibration set can still drift or feel unresponsive online. `LibEMG` provides an **adaptation suite** that keeps improving a model *while the user operates it*, using the ongoing interaction as a source of labels. This is the mechanism behind context-informed incremental learning (see [Context-Informed Incremental Learning Improves Throughput and Reduces Drift in Regression-Based Myoelectric Control, Morrell et al. 2025](https://github.com/ECEEvanCampbell/CoAdaptUnderCurriculum)).
+
+This tutorial builds the minimal pipeline: a **within-subject initialization** from screen-guided training (SGT) data, followed by an **online environment that adapts the model** as the user plays through it.
+
+# Architecture
+Adaptation runs as **four cooperating processes** that communicate over shared memory. The `libemg.adaptation._base.get_edil_adaptation_objects` helper pre-builds every shared-memory item and `OutputWriter` needed to wire them together (each modality buffer and its sample counter are paired on a shared lock so readers always see a consistent snapshot), so you never allocate them by hand.
+
+1. **`OnlineEMGRegressor`** — the live model. It windows the incoming EMG, extracts features, predicts, and publishes each feature vector (`model_input`) with a timestamp to shared memory. It also watches an `adapt_flag`; when the adaptation manager raises it, the regressor hot-swaps in the newly adapted model.
+2. **Environment** (`CurricularFitts`) — the task the user performs. Every frame it turns the current cursor/target geometry into a *pseudo-label* through a `feedback_handle`, and writes that label (`environment_feedback`) with the same timestamp and trial number.
+3. **`MemoryManager`** — joins each `environment_feedback` row to the `model_input` row with the matching timestamp, appends the pair to a `Memory`, and saves one memory slice (`memory_<trial>.pkl`) at the end of every trial.
+4. **`AdaptationManager`** — loads memory slices (seeded by the SGT data for stability), calls `model.adapt(memory)`, saves the updated model (`mdl<N>.pkl`), and — if `notify=True` — sets the `adapt_flag` so the live model reloads it.
+
+The loop is therefore: **predict → act → pseudo-label → remember → adapt → reload → predict …**, all without pausing the user.
+
+**You supply three things.** The suite is model-agnostic; it only assumes:
+- a **model** with `predict(features)`, `adapt(memory)`, `save(path)`, and `load(path)` (the reference repository uses a small MLP / Transformer),
+- a **memory** subclassing `libemg.adaptation.memory.Memory` (implementing `append`, `reset`, `save`, `load`, and `__add__`),
+- a **feedback function** mapping game state to a pseudo-label — `libemg.adaptation._base.produce_tciil_feedback` is a ready-made regression example.
+
+**Note:** The snippets below use the `Myo Armband` and a 2-DOF wrist regressor (flexion/extension and radial/ulnar deviation). Any hardware works by switching the `streamer`, `window_size`, and `window_increment`.
+
+# Step 1 — Within-Subject Initialization
+First, record a short screen-guided training session and fit an initial model to it. This is the same collection flow used elsewhere in `LibEMG`; for regression we prompt the four wrist directions and record continuous labels.
+
+```Python
+import libemg
+from libemg.streamers import myo_streamer
+
+# Stream from the device and collect calibration (SGT) data.
+streamer, sm_items = myo_streamer()
+odh = libemg.data_handler.OnlineDataHandler(shared_memory_items=sm_items)
+
+gui = libemg.gui.GUI(odh, args={
+    'media_folder': 'media/',        # regression prompts (wrist flexion/extension, radial/ulnar)
+    'data_folder':  'data/sgt/',
+    'num_reps':     5,
+    'rep_time':     5,
+    'auto_advance': True,
+})
+gui.start_gui()
+streamer.stop()
+```
+
+Next, parse those recordings with an `OfflineDataHandler`, fit your model, and — crucially — save the SGT data **as a memory slice**. That slice seeds the adaptation manager so early online updates don't wander away from a known-good starting point.
+
+```Python
+# Parse the SGT recordings.
+offdh = libemg.data_handler.OfflineDataHandler()
+offdh.get_data('data/sgt/', regex_filters, metadata_fetchers, delimiter=',')
+
+# Fit the initial within-subject model (implements predict/adapt/save/load).
+model = MyModel(...)
+model.calibrate(offdh)
+
+# Seed the adaptation with the SGT data as the first memory slice.
+initial_memory = MyMemory(...)          # subclass of libemg.adaptation.memory.Memory
+initial_memory.load_from_odh(offdh)
+initial_memory.save('data/adapt/sgt_memory.pkl')
+```
+
+The same `model` object is handed to both the live regressor and the adaptation manager below; because they run in separate processes each gets its own copy.
+
+# Step 2 — Launch the Online Adaptive Environment
+Now assemble the four processes. Start by requesting the pre-wired shared-memory items and output writers.
+
+```Python
+from libemg.adaptation._base import get_edil_adaptation_objects, produce_tciil_feedback
+from libemg.adaptation.managers import MemoryManager, AdaptationManager
+from libemg.environments.controllers import RegressorController
+from libemg.environments.curricular_fitts import (
+    CurricularFitts, CurricularFittsConfig, RadiusTargetGenerator,
+)
+
+NUM_FEATURES, NUM_DOFS, NUM_TRIALS = 64, 2, 80
+ADAPT_DIR = 'data/adapt/'   # adapted models (mdl<N>.pkl) AND memory slices (memory_<trial>.pkl)
+
+(model_smi, model_ow,
+ environment_smi, environment_ow,
+ adaptation_manager_smi, adaptation_manager_ow,
+ memory_manager_smi, memory_manager_ow) = get_edil_adaptation_objects(
+    num_features=NUM_FEATURES, num_outputs=NUM_DOFS)
+```
+
+**The live model.** Pass `model_ow`/`model_smi` so it publishes `model_input` and exposes the `active_flag`/`adapt_flag`. Its `file_path` is where it reloads adapted models from.
+
+```Python
+streamer, sm_items = myo_streamer()
+odh = libemg.data_handler.OnlineDataHandler(shared_memory_items=sm_items)
+
+emg_regressor = libemg.emg_predictor.EMGRegressor(model)   # the SGT-trained model
+online_regressor = libemg.emg_predictor.OnlineEMGRegressor(
+    offline_regressor   = emg_regressor,
+    online_data_handler = odh,
+    window_size = 100, window_increment = 40,
+    features = ['WENG'],
+    output_writers = model_ow,          # publishes model_input (features + timestamp)
+    smm = True, smm_items = model_smi,  # exposes active_flag / adapt_flag / model_input
+    file_path = ADAPT_DIR,              # reloads mdl<N>.pkl from here when adapt_flag is set
+)
+online_regressor.run(block=False)
+```
+
+**The environment.** The `feedback_handle` converts cursor/target geometry into a pseudo-label; `environment_ow` writes it out for the memory manager.
+
+```Python
+controller = RegressorController()
+config = CurricularFittsConfig(
+    feedback_handle = produce_tciil_feedback,
+    num_trials      = NUM_TRIALS,
+    controller_map  = [1, -1],
+)
+env = CurricularFitts(
+    controller, config,
+    target_generator = RadiusTargetGenerator(config, F=0, P=0),
+    environment_ow   = environment_ow,   # writes environment_feedback (label + timestamp + trial)
+    save_file        = ADAPT_DIR,
+)
+```
+
+**The memory and adaptation managers.** Two path linkages must line up: the adaptation manager's `load_dir` equals the memory manager's `save_dir` (where slices are written), and its `save_dir` equals the online regressor's `file_path` (where adapted models are read back). Setting `notify=True` is what closes the loop by raising the `adapt_flag`.
+
+```Python
+memory_manager = MemoryManager(
+    memory   = MyMemory(...),        # empty memory of the same type as the SGT seed
+    smi      = memory_manager_smi,
+    ow       = memory_manager_ow,
+    save_dir = ADAPT_DIR,            # writes memory_<trial>.pkl
+)
+
+adaptation_manager = AdaptationManager(
+    model              = model,      # adapts its own copy of the SGT model
+    smi                = adaptation_manager_smi,
+    ow                 = adaptation_manager_ow,
+    initial_memory_loc = ADAPT_DIR + 'sgt_memory.pkl',   # SGT seed for stability
+    load_dir           = ADAPT_DIR,  # reads memory_<trial>.pkl  (== MemoryManager.save_dir)
+    save_dir           = ADAPT_DIR,  # writes mdl<N>.pkl         (== OnlineEMGRegressor.file_path)
+    stop_condition     = lambda n: n >= NUM_TRIALS - 1,
+    notify             = True,       # raise adapt_flag so the live model hot-swaps
+)
+```
+
+Finally, launch them. Run the environment and memory manager in the background and block on the adaptation manager; it returns once `stop_condition` is met. Then tear everything down.
+
+```Python
+env.run_helper(block=False)               # spawn the game
+memory_manager.run_helper(block=False)    # spawn the memory assembler
+adaptation_manager.run_helper(block=True) # adapt until stop_condition; blocks here
+
+# Cleanup once adaptation ends.
+env.process.join()
+memory_manager.signal.set(); memory_manager.join()
+online_regressor.odh.stop_all()
+online_regressor.stop_running()
+streamer.stop()
+```
+
+# Result
+As the user completes trials, memory slices accumulate, the adaptation manager retrains on them (seeded by the SGT slice), and the live model is swapped out mid-session — so control quality improves *during* use rather than only between sessions. To make the model non-adaptive for a baseline comparison, build everything identically but pass `notify=False` to the `AdaptationManager`: memories are still collected, but the `adapt_flag` is never raised and the live model stays fixed.

docs/source/documentation/animation/animation.rst

@@ -0,0 +1,4 @@
+Animation
+------------------------------
+.. include:: animation_doc.md
+   :parser: myst_parser.sphinx_

docs/source/documentation/animation/animation_doc.md

@@ -0,0 +1,75 @@
+## Use Case
+
+The `Animator` class offers some simple functionality to create animations in multiple video formats (e.g., .gif and .mp4). Specific `Animator` classes have been created to help create specific visual prompts, such as bar plots and cartesian plots. These prompts are primarily used for training of regression-based myoelectric control systems, but the `Animator` class can also be used to generate these prompts for any purpose. For fully custom animations, you can inherit from the `Animator` class and pass a set of frames to `save_video()` (see other `Animators` for examples). If you'd rather implement a custom plotting animation that isn't supported, you can inherit from `PlotAnimator` instead.
+
+For all further examples, we will use a generated set of coordinates to illustrate the difference between plots.
+
+```Python
+import numpy as np
+
+fps = 24
+coordinates = np.concatenate((
+    np.linspace(0, 1, num=fps),  # each movement is 24 frames -> 1 second
+    np.ones(2 * fps),   # steady state
+    np.linspace(1, -1, num=2 * fps),
+    np.ones(2 * fps) * -1,
+    np.linspace(-1, 0, num=fps)
+))
+coordinates = np.hstack((
+    np.expand_dims(coordinates, 1),
+    np.zeros((coordinates.shape[0], 1))
+))
+```
+
+## Bar Plots
+
+One type of `Animator` built into `LibEMG` creates bar plot animations. Pass in an array of coordinates to the `plot_icon` method to create a bar plot visualization (see Figure 1).
+
+```Python
+from libemg.animator import BarPlotAnimator
+
+animator = BarPlotAnimator(['Open', 'Close'], fps=fps)
+animator.save_plot_video(coordinates)
+```
+
+![alt text](bar.gif)
+<p align="center">Figure 1: Simple bar plot animation.</p>
+
+Additional information can also be shown during these animations, such as the next destination and a countdown for steady states (see Figure 2).
+
+```Python
+animator = BarPlotAnimator(['Open', 'Close'], fps=fps, show_countdown=True, show_direction=True)
+animator.save_plot_video(coordinates)
+```
+
+![alt text](bar-info.gif)
+<p align="center">Figure 2: Bar plot animation with added information.</p>
+
+Parameters such as the time per unit distance, figure size, and more can also be modified. See the `BarPlotAnimator` API for more details.
+
+## Scatter Plots
+
+`LibEMG` also provides a helper class to animate scatter plots (see Figure 3).
+
+```Python
+from libemg.animator import ScatterPlotAnimator
+
+animator = ScatterPlotAnimator(['Open', 'Close'], fps=fps)
+animator.save_plot_video(coordinates)
+```
+
+![alt text](scatter.gif)
+<p align="center">Figure 3: Simple scatter plot animation.</p>
+
+Similar to the bar plot animation, extra information can be added such as next destination, a countdown, and a unit circle boundary (see Figure 4).
+
+```Python
+
+animator = ScatterPlotAnimator(['Open', 'Close'], fps=fps, show_countdown=True, show_direction=True, show_boundary=True)
+animator.save_plot_video(coordinates)
+```
+
+![alt text](scatter-info.gif)
+<p align="center">Figure 4: Scatter plot animation with added information.</p>
+
+Parameters such as the time per unit distance, figure size, and more can also be modified. See the `ScatterPlotAnimator` API for more details.