About This Tool

This computational tool uses optimal control to predict muscle activity of mouse forelimb movements. Users should provide a video of a mouse forelimb movement with annotations on the paw, elbow, and shoulder. A physics simulation with a musculoskeletal model of the mouse forelimb will be performed to reproduce the annotated kinematics and will estimate biomechanical features (including joint positions/velocities, torques, muscle excitations, fiber lengths/velocities). The computational tool outputs a .mot file, which contains the activity of more than 20 forelimb muscles by time.

If you use this computational tool for your research, please cite:

Gilmer, Jesse I., Susan K. Coltman, Geraldine Cuenu, John R. Hutchinson, Daniel Huber, Abigail L. Person, and Mazen Al Borno. "A novel biomechanical model of the proximal mouse forelimb predicts muscle activity in optimal control simulations of reaching movements." Journal of neurophysiology 133, no. 4 (2025): 1266-1278.

Usage Instructions

Get started using the example walkthrough. Or, start with the demo below.

There is also a tutorial video available

Demo

STEP 1: Install Anaconda

Download the executable from this link then follow the instructions there to install Anaconda.

STEP 2: Create a new Conda environment

In an Anaconda terminal, run conda create -n "mousearm-test" python=3.11 -y or any environment name.
Activate the environment with conda activate mousearm-test.

STEP 3: Install opensim via conda

Windows/Linux: conda install -c opensim-org opensim=4.4.
macOS (Apple Silicon): CONDA_SUBDIR=osx-64 conda install -c opensim-org opensim=4.4.

STEP 4: Go to your Documents folder

Windows: cd %USERPROFILE%\Documents. Linux/macOS: cd ~/Documents.

STEP 5: Clone this git repo and install the library

Run the following in the Anaconda terminal:

# Using SSH:
git clone git@github.com:Al-Borno-Lab/mousearm.git

# OR using HTTPS:
git clone https://github.com/Al-Borno-Lab/mousearm.git

cd mousearm
pip install uv

uv pip install -e .

STEP 6: Run the demo

To do this, run:

cd mousearm/Demo
python demo.py

Sample Usage

Place your data folder anywhere with the following format (any number of reachsets)

Data/
├── reachset_1/
│   └── kinematics_1.csv
└── reachset_2/
    └── kinematics_1.csv

Then, in a separate anaconda terminal, cd into the parent directory of the Data folder.

In a new python file in the same folder as the Data folder, enter:

from mousearm.simulate import run_simulation
run_simulation("Data", nReachSets=2) # Adjust nReachSets accordingly

Then, run it using python run from the parent directory of the Data folder.

Data Formatting

Process the motion capture data through DeepLabCut. The output file will have more data than necessary, so delete everything except time, paw (x,y,z), wrist (x,y,z), shoulder (x,y,z), elbow (x,y,z). At the end, the csv file should look like the following:

After formatting, the data folder should be formatted like this:

RawData/
└── reachsets/
    ├── reachset_1/
    │   └── kinematics_1.csv
    ├── reachset_2/
    │   └── kinematics_1.csv
    └── ...

Output File Processing

The important output files are muscle_solution and the muscle_kinematics:

• muscle_solution shows the solution that the model found for the movement. These can be visualized in OpenSim to observe the movement and predicted muscle actuations.
• muscle_kinematics shows the difference between the captured movement and the movement predicted by the model

These files can both be imported into a pandas dataframe for further analysis with the below python code. The directory should be structured like this:

RawData/
└── reachsets/
    ├── reachset_1/
    │   ├── muscle_solution_adjusted_kinematics_1.sto
    │   └── muscle_kinematics_adjusted_kinematics_1.csv
    ├── reachset_2/
    │   ├── muscle_solution_adjusted_kinematics_1.sto
    │   └── muscle_kinematics_adjusted_kinematics_1.csv
    └── ...

You can get your path by right clicking on the .sto file and clicking "Copy as Path." This will copy the path to you clipboard and you can paste it in with Ctrl+V. The code will look like this:

import pandas as pd
mcolnames = ["time", "/jointset/shoulder/elv_angle/value", "/jointset/shoulder/extension_angle/value", "/jointset/shoulder/rotation_angle/value", "/jointset/humerus_ulna/elbow_flex/value", "/jointset/ulna_radius_pj/radius_rot/value", "/jointset/wrist/wrist_angle/value", "/jointset/shoulder/elv_angle/speed", "/jointset/shoulder/extension_angle/speed", "/jointset/shoulder/rotation_angle/speed", "/jointset/humerus_ulna/elbow_flex/speed", "/jointset/ulna_radius_pj/radius_rot/speed", "/jointset/wrist/wrist_angle/speed", "/forceset/Pectoralis_Clavicle_Head/activation", "/forceset/Biceps_Short_Head/activation", "/forceset/Biceps_Long_Head/activation", "/forceset/Deltoid_Medial/activation", "/forceset/Triceps_Lat_Head/activation", "/forceset/Triceps_Long_Head/activation", "/forceset/Brachialis_Proximal_Head/activation", "/forceset/Brachialis_Distal_Head/activation", "/forceset/Anconeus/activation", "/forceset/Deltoid_Posterior/activation", "/forceset/Anconeus_Short_Head/activation", "/forceset/Subscapularis_SuperiorHead/activation", "/forceset/Infraspinatus/activation", "/forceset/PronatorTeres/activation", "/forceset/FlexorCarpiRadialis/activation", "/forceset/Brachioradialis/activation", "/forceset/Triceps_Medial_Head/activation", "/forceset/Latissimus_Dorsi_Rostral/activation", "/forceset/Latissimus_Dorsi_Caudal/activation", "/forceset/Pectoralis_Major_Anterior/activation", "/forceset/Pectoralis_Major_Posterior/activation", "/forceset/Pectoralis_Clavicle_Head", "/forceset/Biceps_Short_Head", "/forceset/Biceps_Long_Head", "/forceset/Deltoid_Medial", "/forceset/Triceps_Lat_Head", "/forceset/Triceps_Long_Head", "/forceset/Brachialis_Proximal_Head", "/forceset/Brachialis_Distal_Head", "/forceset/Anconeus", "/forceset/Deltoid_Posterior", "/forceset/Anconeus_Short_Head", "/forceset/Subscapularis_SuperiorHead", "/forceset/Infraspinatus", "/forceset/PronatorTeres", "/forceset/FlexorCarpiRadialis", "/forceset/Brachioradialis", "/forceset/Triceps_Medial_Head", "/forceset/Latissimus_Dorsi_Rostral", "/forceset/Latissimus_Dorsi_Caudal", "/forceset/Pectoralis_Major_Anterior", "/forceset/Pectoralis_Major_Posterior"]
file = r".\Test Reaches\reachset_1\muscle_solution_adjusted_kinematics_2.sto" # REPLACE WITH YOUR PATH
muscleSolution = pd.read_csv(file, sep= r'\t',engine='python', header=18, names=mcolnames, index_col=None)

After this, you can run print(muscleSolution.columns) to get a list of your columns. Then, if you would like to plot any of them against time, you can do so like this (this will plot the biceps activations):

import matplotlib.pyplot as plt
plt.plot(muscleSolution["time"], muscleSolution["/forceset/Biceps_Long_Head/activation"])
plt.xlabel("Time (s)")
plt.ylabel("Biceps Activation")
plt.show()

If you would like to get data on the muscle fiber lengths, you can do so using the getMuscleLengths.py script from this github repo. Those will be outputted to additional .sto files that you can plot and analyze with python code like above, except using these column names:

mcolnames = ["time", "Pectoralis_Clavicle_Head", "Biceps_Short_Head", "Biceps_Long_Head", "Deltoid_Medial", "Triceps_Lat_Head", "Triceps_Long_Head", "Brachialis_Proximal_Head", "Brachialis_Distal_Head", "Anconeus", "Deltoid_Posterior", "Anconeus_Short_Head", "Subscapularis_SuperiorHead", "Infraspinatus", "PronatorTeres", "FlexorCarpiRadialis", "Brachioradialis", "Triceps_Medial_Head", "Latissimus_Dorsi_Rostral", "Latissimus_Dorsi_Caudal", "Pectoralis_Major_Anterior", "Pectoralis_Major_Posterior"]