Update README.md

README.md

@@ -3,22 +3,18 @@ tags:
 - computer_vision
 - pose_estimation
 ---
+# MODEL CARD:
 
-Copyright 2021-2023 by Mackenzie Mathis, Alexander Mathis, Shaokai Ye and contributors. All rights reserved.
+## Model Details
 
+• SuperAnimal-TopViewMouse model developed by the [M.W.Mathis Lab](http://www.mackenziemathislab.org/) in 2023, trained to predict quadruped pose from images. 
+Please see [Shaokai Ye et al. 2023](https://arxiv.org/abs/2203.07436) for details.
 
-- Please cite **Ye et al 2023** if you use this model in your work https://arxiv.org/abs/2203.07436v1 
-- If this license is not suitable for your business or project
-please contact EPFL-TTO (https://tto.epfl.ch/) or Mackenzie Mathis (mackenzie.mathis @ epfl.ch) for a full commercial license.
+• The model is an DLRRNet and HRNet-w32 trained on our TopViewMouse-5K dataset.
 
-This software may not be used to harm any animal deliberately!
-
-
-**MODEL CARD:**
-
-This model was trained a dataset called "TopViewMouse-5K." It was trained in Tensorflow 2 within the [DeepLabCut framework](www.deeplabcut.org). 
-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:
+•  It was trained within the DeepLabCut framework. 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
@@ -30,7 +26,36 @@ model_dir.mkdir()
 download_huggingface_model("superanimal_topviewmouse", model_dir)
 ```
 
-**Training Data:**
+## 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:
 
@@ -57,16 +82,58 @@ 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.
 
-Please note that each dataest was labeled by separate labs, seperate 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). 
-You will also 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. 
-
 <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