Store Metadata as Values

.gitignore

@@ -45,4 +45,20 @@ 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/

dataset_tryout.py

@@ -0,0 +1,4 @@
+from libemg.datasets import *
+
+accs = evaluate('LDA', 300, 100, feature_list=['MAV','SSC','ZC','WL'], included_datasets=['FougnerLP'], save_dir='')
+print('\n' + str(accs))

docs/source/examples/offline_regression_example/offline_regression.md

@@ -0,0 +1,98 @@
+[View Source Code](https://github.com/LibEMG/LibEMG_OfflineRegression_Showcase)
+
+<img src="https://github.com/LibEMG/LibEMG_OfflineRegression_Showcase/blob/main/docs/results.png?raw=true"/>
+
+This simple offline example showcases some of the offline capabilities for regression analysis. In this example, we will load in the OneSubjectEMaGerDataset and assess the performance of multiple regressors. All code can be found in `main.py`.
+
+## Step 1: Importing LibEMG
+
+The very first step involves importing the modules needed. In general, each of LibEMG's modules has its own import. Make sure that you have successfully installed libemg through pip.
+
+```Python
+import numpy as np
+import matplotlib.pyplot as plt
+from libemg.offline_metrics import OfflineMetrics
+from libemg.datasets import OneSubjectEMaGerDataset
+from libemg.feature_extractor import FeatureExtractor
+from libemg.emg_predictor import EMGRegressor
+```
+
+## Step 2: Setting up Constants
+
+Preprocessing parameters, such as window size, window increment, and the feature set must be decided before EMG data can be prepared for estimation. LibEMG defines window and increment sizes as the number of samples. In this case, the dataset was recorded from the EMaGer cuff, which samples at 1 kHz, so a window of 150 samples corresponds to 150ms.
+
+The window increment, window size, and feature set default to 40, 150, and 'HTD', respecively. These variables can be customized in this script using the provided CLI. Use `python main.py -h` for an explanation of the CLI. Example usage is also provided below:
+
+```Bash
+python main.py --window_size 200 --window_increment 50 --feature_set MSWT
+```
+
+# Step 3: Loading in Dataset
+
+This example uses the `OneSubjectEMaGerDataset`. Instantiating the `Dataset` will automatically download the data into the specified directory, and calling the `prepare_data()` method will load EMG data and metadata (e.g., reps, movements, labels) into an `OfflineDataHandler`. This dataset consists of 5 repetitions, so we use 4 for training data and 1 for testing data. After splitting our data into training and test splits, we perform windowing on the raw EMG data. By default, the metadata assigned to each window will be based on the mode of that window. Since we are analyzing regression data, we pass in a function that tells the `OfflineDataHandler` to grab the label from the last sample in the window instead of taking the mode of the window. We can specify how we want to handle windowing of each type of metadata by passing in a `metadata_operations` dictionary.
+
+```Python
+# Load data
+odh = OneSubjectEMaGerDataset().prepare_data()
+
+# Split into train/test reps
+train_odh = odh.isolate_data('reps', [0, 1, 2, 3])
+test_odh = odh.isolate_data('reps', [4])
+
+# Extract windows
+metadata_operations = {'labels': lambda x: x[-1]}   # grab label of last sample in window
+train_windows, train_metadata = train_odh.parse_windows(args.window_size, args.window_increment, metadata_operations=metadata_operations)
+test_windows, test_metadata = test_odh.parse_windows(args.window_size, args.window_increment, metadata_operations=metadata_operations)
+```
+
+# Step 4: Feature Extraction
+
+We then extract features using the `FeatureExtractor` for our training and test data. The `fit()` method expects a dictionary with the keys `training_features` and `training_labels`, so we create one and pass in our extracted features and training labels.
+
+```Python
+training_features = fe.extract_feature_group(args.feature_set, train_windows, array=True),
+training_labels = train_metadata['labels']
+test_features = fe.extract_feature_group(args.feature_set, test_windows, array=True)
+test_labels = test_metadata['labels']
+
+training_set = {
+    'training_features': training_features,
+    'training_labels': training_labels
+}
+```
+
+# Step 5: Regression
+
+`LibEMG` allows you to pass in custom models, but you can also pass in a string that will create a model for you. In this example, we compare a linear regressor to a gradient boosting regressor. We iterate through a list of the models we want to observe, fit the model to the training data, and calculate metrics based on predictions on the test data. We then store these metrics for plotting later.
+
+```Python
+results = {metric: [] for metric in ['R2', 'NRMSE', 'MAE']}
+for model in models:
+    reg = EMGRegressor(model)
+
+    # Fit and run model
+    print(f"Fitting {model}...")
+    reg.fit(training_set.copy())
+    predictions = reg.run(test_features)
+
+    metrics = om.extract_offline_metrics(results.keys(), test_labels, predictions)
+    for metric in metrics:
+        results[metric].append(metrics[metric].mean())
+```
+
+# Step 6: Visualization
+
+Finally, we visualize our results. We first plot the decision stream for each model. After each model is fitted, we plot the offline metrics for each type of model.
+
+```Python
+# Note: this will block the main thread once the plot is shown. Close the plot to continue execution.
+reg.visualize(test_labels, predictions)
+
+fig, axs = plt.subplots(nrows=len(results), layout='constrained', figsize=(8, 8), sharex=True)
+for metric, ax in zip(results.keys(), axs):
+    ax.bar(models, np.array(results[metric]) * 100)
+    ax.set_ylabel(f"{metric} (%)")
+
+fig.suptitle('Metrics Summary')
+plt.show()
+```

docs/source/examples/offline_regression_example/offline_regression_example.rst

@@ -0,0 +1,4 @@
+Offline Regression Analysis
+==========================================
+.. include:: offline_regression.md
+   :parser: myst_parser.sphinx_

docs/source/index.rst

@@ -43,6 +43,7 @@ LibEMG
    examples/features_and_group_example/features_and_group_example
    examples/feature_optimization_example/feature_optimization_example
    examples/deep_learning_example/deep_learning_example
+   examples/offline_regression_example/offline_regression_example
 
 .. toctree::
    :maxdepth: 1

libemg/_datasets/_3DC.py

@@ -0,0 +1,45 @@
+from libemg._datasets.dataset import Dataset
+from libemg.data_handler import OfflineDataHandler, RegexFilter
+
+class _3DCDataset(Dataset):
+    def __init__(self, dataset_folder="_3DCDataset/"):
+        Dataset.__init__(self, 
+                        1000, 
+                        10, 
+                        '3DC Armband (Prototype)', 
+                        22, 
+                        {0: "Neutral", 1: "Radial Deviation", 2: "Wrist Flexion", 3: "Ulnar Deviation", 4: "Wrist Extension", 5: "Supination", 6: "Pronation", 7: "Power Grip", 8: "Open Hand", 9: "Chuck Grip", 10: "Pinch Grip"}, 
+                        '8 (4 Train, 4 Test)',
+                        "The 3DC dataset including 11 classes.",
+                        "https://doi.org/10.3389/fbioe.2020.00158")
+        self.url = "https://github.com/libemg/3DCDataset"
+        self.dataset_folder = dataset_folder
+
+    def prepare_data(self, split = False, subjects_values = None, sets_values = None, reps_values = None,
+                     classes_values = None):
+        if subjects_values is None:
+            subjects_values = [str(i) for i in range(1,23)]
+        if sets_values is None:
+            sets_values = ["train", "test"]
+        if reps_values is None:
+            reps_values = ["0","1","2","3"]
+        if classes_values is None:
+            classes_values = [str(i) for i in range(11)]
+
+        print('\nPlease cite: ' + self.citation+'\n')
+        if (not self.check_exists(self.dataset_folder)):
+            self.download(self.url, self.dataset_folder)
+
+        regex_filters = [
+            RegexFilter(left_bound = "/", right_bound="/EMG", values = sets_values, description='sets'),
+            RegexFilter(left_bound = "_", right_bound=".txt", values = classes_values, description='classes'),
+            RegexFilter(left_bound = "EMG_gesture_", right_bound="_", values = reps_values, description='reps'),
+            RegexFilter(left_bound="Participant", right_bound="/",values=subjects_values, description='subjects')
+        ]
+        odh = OfflineDataHandler()
+        odh.get_data(folder_location=self.dataset_folder, regex_filters=regex_filters, delimiter=",")
+        data = odh
+        if split:
+            data = {'All': odh, 'Train': odh.isolate_data("sets", [0], fast=True), 'Test': odh.isolate_data("sets", [1], fast=True)}
+
+        return data

libemg/_datasets/__init__.py

@@ -0,0 +1,17 @@
+from libemg._datasets import _3DC
+from libemg._datasets import ciil
+from libemg._datasets import continous_transitions
+from libemg._datasets import dataset
+from libemg._datasets import emg_epn612
+from libemg._datasets import fors_emg
+from libemg._datasets import fougner_lp
+from libemg._datasets import grab_myo
+from libemg._datasets import hyser
+from libemg._datasets import intensity
+from libemg._datasets import kaufmann_md
+from libemg._datasets import myodisco
+from libemg._datasets import nina_pro
+from libemg._datasets import one_subject_emager
+from libemg._datasets import one_subject_myo
+from libemg._datasets import radmand_lp
+from libemg._datasets import tmr_shirleyryanabilitylab

libemg/_datasets/ciil.py

@@ -0,0 +1,148 @@
+from libemg._datasets.dataset import Dataset
+from libemg.data_handler import OfflineDataHandler, RegexFilter, FilePackager
+from pathlib import Path
+
+
+
+class CIIL_MinimalData(Dataset):
+    def __init__(self, dataset_folder='CIILData/'):
+        Dataset.__init__(self, 
+                         200, 
+                         8, 
+                         'Myo Armband', 
+                         11, 
+                         {0: 'Close', 1: 'Open', 2: 'Rest', 3: 'Flexion', 4: 'Extension'}, 
+                         '1 Train (1s), 15 Test',
+                         "The goal of this Myo dataset is to explore how well models perform when they have a limited amount of training data (1s per class).", 
+                         'https://ieeexplore.ieee.org/abstract/document/10394393')
+        self.url = "https://github.com/LibEMG/CIILData"
+        self.dataset_folder = dataset_folder
+
+    def prepare_data(self, split = False):
+        print('\nPlease cite: ' + self.citation+'\n')
+        if (not self.check_exists(self.dataset_folder)):
+            self.download(self.url, self.dataset_folder)
+
+        subfolder = 'MinimalTrainingData'
+        subjects = [str(i) for i in range(0, 11)]
+        classes_values = [str(i) for i in range(0,5)]
+        reps_values = ["0","1","2"]
+        sets = ["train", "test"]
+        regex_filters = [
+            RegexFilter(left_bound = "/", right_bound="/", values = sets, description='sets'),
+            RegexFilter(left_bound = "/subject", right_bound="/", values = subjects, description='subjects'),
+            RegexFilter(left_bound = "R_", right_bound="_", values = reps_values, description='reps'),
+            RegexFilter(left_bound = "C_", right_bound=".csv", values = classes_values, description='classes')
+        ]
+        odh = OfflineDataHandler()
+        odh.get_data(folder_location=self.dataset_folder + '/' + subfolder, regex_filters=regex_filters, delimiter=",")
+
+        data = odh
+        if split:
+            data = {'All': odh, 'Train': odh.isolate_data("sets", [0], fast=True), 'Test': odh.isolate_data("sets", [1], fast=True)}
+
+        return data
+
+class CIIL_ElectrodeShift(Dataset):
+    def __init__(self, dataset_folder='CIILData/'):
+        Dataset.__init__(self, 
+                         200, 
+                         8, 
+                         'Myo Armband', 
+                         21, 
+                         {0: 'Close', 1: 'Open', 2: 'Rest', 3: 'Flexion', 4: 'Extension'}, 
+                         '5 Train (Before Shift), 8 Test (After Shift)',
+                         "An electrode shift confounding factors dataset.", 
+                         'https://link.springer.com/article/10.1186/s12984-024-01355-4')
+        self.url = "https://github.com/LibEMG/CIILData"
+        self.dataset_folder = dataset_folder
+
+    def prepare_data(self, split = False):
+        print('\nPlease cite: ' + self.citation+'\n')
+        if (not self.check_exists(self.dataset_folder)):
+            self.download(self.url, self.dataset_folder)
+
+        subfolder = 'ElectrodeShift'
+        subjects = [str(i) for i in range(0, 21)]
+        classes_values = [str(i) for i in range(0,5)]
+        reps_values = ["0","1","2","3","4"]
+        sets = ["training", "trial_1", "trial_2", "trial_3", "trial_4"]
+        regex_filters = [
+            RegexFilter(left_bound = "/", right_bound="/", values = sets, description='sets'),
+            RegexFilter(left_bound = "/subject", right_bound="/", values = subjects, description='subjects'),
+            RegexFilter(left_bound = "R_", right_bound="_", values = reps_values, description='reps'),
+            RegexFilter(left_bound = "C_", right_bound=".csv", values = classes_values, description='classes')
+        ]
+        odh = OfflineDataHandler()
+        odh.get_data(folder_location=self.dataset_folder + '/' + subfolder, regex_filters=regex_filters, delimiter=",")
+
+        data = odh
+        if split:
+            data = {'All': odh, 'Train': odh.isolate_data("sets", [0], fast=True), 'Test': odh.isolate_data("sets", [1,2,3,4], fast=True)}
+
+        return data
+
+
+class CIIL_WeaklySupervised(Dataset):
+    def __init__(self, dataset_folder='CIIL_WeaklySupervised/'):
+        Dataset.__init__(self, 
+                         1000, 
+                         8, 
+                         'OyMotion gForcePro+ EMG Armband', 
+                         16, 
+                         {0: 'Close', 1: 'Open', 2: 'Rest', 3: 'Flexion', 4: 'Extension'}, 
+                         '30 min weakly supervised, 1 rep calibration, 14 reps test',
+                         "A weakly supervised environment with sparse supervised calibration.", 
+                         'In Submission')
+        self.url = "https://unbcloud-my.sharepoint.com/:u:/g/personal/ecampbe2_unb_ca/EaABHYybhfJNslTVcvwPPwgB9WwqlTLCStui30maqY53kw?e=MbboMd"
+        self.dataset_folder = dataset_folder
+
+    def prepare_data(self, split = False):
+        print('\nPlease cite: ' + self.citation+'\n')
+        if (not self.check_exists(self.dataset_folder)):
+            self.download_via_onedrive(self.url, self.dataset_folder)
+
+        # supervised odh loading
+        subjects = [str(i) for i in range(0, 16)]
+        classes_values = [str(i) for i in range(0,5)]
+        reps_values = [str(i) for i in range(0,15)]
+        setting_values     = [".csv", ""] # this is arbitrary to get a field that separates WS from S
+        regex_filters = [
+            RegexFilter(left_bound = "", right_bound="", values = setting_values, description='settings'),
+            RegexFilter(left_bound = "/S", right_bound="/", values = subjects, description='subjects'),
+            RegexFilter(left_bound = "R", right_bound=".csv", values = reps_values, description='reps'),
+            RegexFilter(left_bound = "C", right_bound="_R", values = classes_values, description='classes')
+        ]
+        odh_s = OfflineDataHandler()
+        odh_s.get_data(folder_location=self.dataset_folder+"CIIL_WeaklySupervised/",
+                       regex_filters=regex_filters,
+                       delimiter=",")
+
+        # weakly supervised odh loading
+        subjects = [str(i) for i in range(0, 16)]
+        reps_values      = [str(i) for i in range(3)]
+        setting_values     = ["", ".csv"] # this is arbitrary to get a field that separates WS from S
+        regex_filters = [
+            RegexFilter(left_bound = "", right_bound="", values = setting_values, description='settings'),
+            RegexFilter(left_bound = "/S", right_bound="/", values = subjects, description='subjects'),
+            RegexFilter(left_bound = "WS", right_bound=".csv", values = reps_values, description='reps'),
+        ]
+        metadata_fetchers = [
+            FilePackager(regex_filter=RegexFilter(left_bound="", right_bound="targets.csv", values=["_"], description="classes"),
+            package_function=lambda x, y: (x.split("WS")[1][0] == y.split("WS")[1][0]) and (Path(x).parent == Path(y).parent)
+            )
+        ]
+        odh_ws = OfflineDataHandler()
+        odh_ws.get_data(folder_location=self.dataset_folder+"CIIL_WeaklySupervised/", 
+                     regex_filters=regex_filters, 
+                     metadata_fetchers=metadata_fetchers,
+                     delimiter=",")
+
+        data = odh_s + odh_ws
+        if split:
+            data = {'All': data, 
+                    'Pretrain': odh_ws,
+                    'Train': odh_s.isolate_data("reps", [0], fast=True), 
+                    'Test': odh_s.isolate_data("reps", list(range(1,15)), fast=True)}
+
+        return data