|
--- |
|
tags: |
|
- computer_vision |
|
- pose_estimation |
|
- animal_pose_estimation |
|
- deeplabcut |
|
pipeline_tag: keypoint-detection |
|
--- |
|
# MODEL CARD: |
|
|
|
## Model Details |
|
|
|
• SuperAnimal-TopViewMouse model developed by the [M.W.Mathis Lab](http://www.mackenziemathislab.org/) in 2023, |
|
trained to predict mouse topline pose from images. |
|
Please see [Shaokai Ye et al. 2023](https://arxiv.org/abs/2203.07436) for details. |
|
|
|
• The there are three models: |
|
- `pose_model.pth` is an HRNet-w32 compatable for DLC3.0+ Pytorch code, trained on our TopViewMouse-5K dataset. |
|
- `detector.pt` is a Faster R-CNN that can be used as a detector for top-down detection. |
|
- `DLC_ma_supertopview5k_resnet_50_iteration-0_shuffle-1.tar.gz` is a DLCRNet trained on our TopViewMouse-5K dataset. |
|
|
|
|
|
• Full training details can be found in Ye et al. 2023. |
|
You can use this model simply with our light-weight loading package called [DLCLibrary](https://github.com/DeepLabCut/DLClibrary). |
|
Here is an example useage: |
|
|
|
```python |
|
from pathlib import Path |
|
from dlclibrary import download_huggingface_model |
|
|
|
# Creates a folder and downloads the model to it |
|
model_dir = Path("./superanimal_topviewmouse_model") |
|
model_dir.mkdir() |
|
download_huggingface_model("superanimal_topviewmouse_model", model_dir) |
|
``` |
|
|
|
## Intended Use |
|
|
|
• Intended to be used for pose tracking of lab mice videos filmed from an overhead view. The models can be used as a plug-and- |
|
play solution if extremely high precision is not required (we benchmark the zero-shot performance in the paper). Otherwise, it is |
|
recommended to also be used as the weights for transfer learning and fine-tuning. |
|
|
|
• Intended for academic and research professionals working in fields related to animal behavior, neuroscience, biomechanics, and |
|
ecology. |
|
|
|
• Not suitable for other species and other camera views. Also not suitable for videos that look dramatically different from those we |
|
show in the paper. |
|
|
|
## Factors |
|
|
|
• Based on the known robustness issues of neural networks, the relevant factors include the lighting, contrast and resolution of the |
|
video frames. The present of objects might also cause false detections of the mice and keypoints. When two or more animals are |
|
extremely close, it could cause the top-down detectors to only detect only one animal, if used without further fine-tuning. |
|
|
|
|
|
## Metrics |
|
• Mean Average Precision (mAP) |
|
|
|
• Root Mean Square Error (RMSE) |
|
|
|
## Evaluation Data |
|
|
|
• The test split of TopViewMouse-5K and in the paper on two benchmarks, DLC Openfield and TriMouse |
|
|
|
|
|
## Training Data |
|
|
|
It consists of being trained together on the following datasets: |
|
|
|
- **3CSI, BM, EPM, LDB, OFT** See full details at (1) and in (2). |
|
|
|
- **BlackMice** See full details at (3). |
|
|
|
- **WhiteMice** Courtesy of Prof. Sam Golden and Nastacia Goodwin. See details in SIMBA (4). TriMouse See full details |
|
at (5). |
|
|
|
- **DLC-Openfield** See full details at (6). |
|
|
|
- **Kiehn-Lab-Openfield, Swimming, and treadmill** Courtesy of Prof. Ole |
|
Kiehn, Dr. Jared Cregg, and Prof. Carmelo Bellardita; see details at (7). |
|
|
|
- **MausHaus** We collected video data from five |
|
single-housed C57BL/6J male and female mice in an extended home cage, carried out in the laboratory of Mackenzie Mathis |
|
at Harvard University and also EPFL (temperature of housing was 20-25C, humidity 20-50%). Data were recorded at 30Hz |
|
with 640 × 480 pixels resolution acquired with White Matter, LLC eV cameras. Annotators localized 26 keypoints across 322 |
|
frames sampled from within DeepLabCut using the k-means clustering approach (8). All experimental procedures for mice |
|
were in accordance with the National Institutes of Health Guide for the Care and Use of Laboratory Animals and approved by |
|
the Harvard Institutional Animal Care and Use Committee (IACUC) (n=1 mouse), and by the Veterinary Office of the Canton |
|
of Geneva (Switzerland; license GE01) (n=4 mice). |
|
|
|
Here is an image with examples from the datasets, the distribution of images per dataset, and the keypoint guide. |
|
|
|
<p align="center"> |
|
<img src="https://images.squarespace-cdn.com/content/v1/57f6d51c9f74566f55ecf271/1690986892069-I1DP3EQU14DSP5WB6FSI/modelcard-TVM.png?format=1500w" width="95%"> |
|
</p> |
|
|
|
## Ethical Considerations |
|
|
|
• Data was collected with IUCAC or other governmental approval. Each individual dataset used in training reports the ethics approval |
|
they obtained. |
|
|
|
## Caveats and Recommendations |
|
|
|
• The model may have reduced accuracy in scenarios with extremely varied lighting conditions or atypical mouse characteristics not |
|
well-represented in the training data. For example, this dataset only has one set of white mice, therefore it may not generalize well |
|
to diverse settings of white lab mice. |
|
|
|
• Please note that each training dataset was labeled by separate labs and different individuals, therefore while we map names to a |
|
unified pose vocabulary, there will be annotator bias in keypoint placement (See Ye et al. 2023 for our Supplementary Note on |
|
annotator bias). |
|
|
|
• Note the dataset is primarily using C56Blk6/J mice and only some CD1 examples. |
|
|
|
• We recommend if performance is not as good as you need it to be, first try video adaptation (see Ye et al. 2023), or fine-tune these |
|
weights with your own labeling. |
|
|
|
## License |
|
|
|
Modified MIT. |
|
|
|
Copyright 2023 by Mackenzie Mathis, Shaokai Ye, and contributors. |
|
|
|
Permission is hereby granted to you (hereafter "LICENSEE") a fully-paid, non-exclusive, |
|
and non-transferable license for academic, non-commercial purposes only (hereafter “LICENSE”) |
|
to use the "MODEL" weights (hereafter "MODEL"), subject to the following conditions: |
|
|
|
The above copyright notice and this permission notice shall be included in all copies or substantial |
|
portions of the Software: |
|
|
|
This software may not be used to harm any animal deliberately. |
|
|
|
LICENSEE acknowledges that the MODEL is a research tool. |
|
THE MODEL IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING |
|
BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. |
|
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, |
|
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE MODEL |
|
OR THE USE OR OTHER DEALINGS IN THE MODEL. |
|
|
|
If this license is not appropriate for your application, please contact Prof. Mackenzie W. Mathis |
|
(mackenzie@post.harvard.edu) and/or the TTO office at EPFL (tto@epfl.ch) for a commercial use license. |
|
|
|
Please cite **Ye et al** if you use this model in your work https://arxiv.org/abs/2203.07436v2. |
|
|
|
## References |
|
|
|
1. Oliver Sturman, Lukas von Ziegler, Christa Schläppi, Furkan Akyol, Mattia Privitera, Daria Slominski, Christina Grimm, Laetitia Thieren, Valerio |
|
Zerbi, Benjamin Grewe, et al. Deep learning-based behavioral analysis reaches human accuracy and is capable of outperforming commercial |
|
solutions. Neuropsychopharmacology, 45(11):1942–1952, 2020. |
|
2. Lukas von Ziegler, Oliver Sturman, and Johannes Bohacek. Videos for deeplabcut, noldus ethovision X14 and TSE multi conditioning systems |
|
comparisons. https://doi.org/10.5281/zenodo.3608658. Zenodo, January 2020. |
|
3. Isaac Chang. Trained DeepLabCut model for tracking mouse in open field arena with topdown view. https://doi.org/10.5281/zenodo.3955216. |
|
Zenodo, July 2020. |
|
4. Simon RO Nilsson, Nastacia L. Goodwin, Jia Jie Choong, Sophia Hwang, Hayden R Wright, Zane C Norville, Xiaoyu Tong, Dayu Lin, Bran- |
|
don S. Bentzley, Neir Eshel, Ryan J McLaughlin, and Sam A. Golden. Simple behavioral analysis (simba) – an open source toolkit for computer |
|
classification of complex social behaviors in experimental animals. bioRxiv, 2020. |
|
5. Jessy Lauer, Mu Zhou, Shaokai Ye, William Menegas, Steffen Schneider, Tanmay Nath, Mohammed Mostafizur Rahman, Valentina Di Santo, |
|
Daniel Soberanes, Guoping Feng, Venkatesh N. Murthy, George Lauder, Catherine Dulac, Mackenzie W. Mathis, and Alexander Mathis. Multi- |
|
animal pose estimation, identification and tracking with deeplabcut. Nature Methods, 19:496 – 504, 2022. |
|
6. Alexander Mathis, Pranav Mamidanna, Kevin M Cury, Taiga Abe, Venkatesh N Murthy, Mackenzie Weygandt Mathis, and Matthias Bethge. Deeplab- |
|
cut: markerless pose estimation of user-defined body parts with deep learning. Nature neuroscience, 21:1281–1289, 2018. |
|
7. Jared M. Cregg, Roberto Leiras, Alexia Montalant, Paulina Wanken, Ian R. Wickersham, and Ole Kiehn. Brainstem neurons that command |
|
mammalian locomotor asymmetries. Nature neuroscience, 23:730 – 740, 2020 |
