LabGrymace

LabGrymace (LabGym + grimace) is an open-source tool for quantifying pain-related facial expressions in freely moving mice.

• Objective and reproducible — Facial grimace is a widely used indicator of pain in mice, but manual scoring is labor-intensive and subjective. LabGrymace automatically quantifies pain-related facial movements from the tracking output generated by LabGym.
• A biologically calibrated pain score — Ear, eye, and nose movements are integrated into a single pain score that is continuous over time and calibrated to biological reference points, which enables quantitative comparisons across animals and experiments.
• Easy to use — A point-and-click GUI generates summary spreadsheets, computes pain scores, and produces annotated videos with the score displayed on every frame. No programming required.

This repository contains two parts:

• LabGrymace, the graphical application for pain-score computation and visualization.
• LabGym_LabGrymace, a modified version of LabGym 2.9.0, which performs facial region tracking and generates the input files used by LabGrymace.

LabGrymace Outputs:

1. Annotated video

An .mp4 copy of the original recording with the continuously updated pain score overlaid on each frame, allowing direct comparison between the quantified pain score and the animal's behavior.

Below is an example comparing a recording with a high pain score and one with a low pain score:

Chemically induced pain	Baseline

2. Summary spreadsheets

Three Excel files (ear_summary.xlsx, eye_summary.xlsx, nose_summary.xlsx) containing frame-by-frame measurements for each facial region. Frames removed by the mirror-reflection filter are highlighted in orange, and the merged measurements used for pain-score calculation are highlighted in yellow.

3. Pain score analysis

The analysis includes:

• pain_scores.xlsx — one row per 100 s window, plus a Summary sheet with each recording's overall score.
• pain_scores_per_frame.xlsx — a pain score for every frame.
• pain_score_chart.png — a dot plot of the batch, one point per recording.

Usage

The LabGrymace workflow consists of two steps:

1. Generate summary files — Select the folder containing the LabGym output. LabGrymace generates ear_summary.xlsx, eye_summary.xlsx, and nose_summary.xlsx files for each recording.
2. Compute pain scores — Select the folders containing the summary files. LabGrymace generates pain_scores.xlsx, pain_scores_per_frame.xlsx, pain_score_chart.png, and (optionally) an annotated video with pain score overlaid on each frame.

The reflection filter is disabled by default and can be enabled with a checkbox during step 2. The figures in the accompanying manuscript were generated with this filter enabled, and the reproduction scripts set it automatically.

Documentation

• How LabGym_LabGrymace differs from the original LabGym (upstream) — summarizes the modifications to LabGym and highlights those that affect analysis results.

Licensing

LabGrymace is available under a dual-licensing model.

Open-source license

This repository is licensed under the GNU General Public License v3.0 (GPL-3.0). See LICENSE for details.

This repository includes a modified version of LabGym (Ye Lab, University of Michigan), which is licensed under GPL-3.0. The original attribution and license are preserved in LabGym_LabGrymace/LICENSE.txt.

Commercial licensing

Commercial licenses are available from Behaviora LLC for organizations that wish to use LabGrymace under terms different from the GPL-3.0 license, including proprietary commercial applications, redistribution, enterprise deployment, and commercial support.

For commercial licensing or support inquiries, please contact: contact@labgym.org

Citing LabGrymace

If you use LabGrymace in publications, please cite LabGrymace, LabGym1, and LabGym2.

Installation