Deeplabcut

In the works for a bit, nice enhancements & good bug fixes -- Happy tracking!

*Enhancements/additions:*
- Much faster tracklet parsing
https://github.com/DeepLabCut/DeepLabCut/pull/826
- Johansson-like video creation
https://github.com/DeepLabCut/DeepLabCut/pull/841
- Computation of distance statistics upon network evaluation
https://github.com/DeepLabCut/DeepLabCut/pull/716
- Duplicate previous frame keypoints for faster labeling
https://github.com/DeepLabCut/DeepLabCut/pull/859
- updated augmentation; default is now set to imgaug. Many parameters are also easier to control without changing the code. See: https://github.com/DeepLabCut/DeepLabCut/pull/801
- full macaque model added to model zoo / adding in the full_macaque network, from ttps://www.biorxiv.org/content/10.1101/2020.07.30.229989v2
https://github.com/DeepLabCut/DeepLabCut/pull/832
- cross validation takes previous runs into account: https://github.com/DeepLabCut/DeepLabCut/commit/a06da5f4cf3833c20f188d459860fc29ac5f487d
- ability to show multiple scoremaps/part affinity fields in a single image https://github.com/DeepLabCut/DeepLabCut/pull/709

*Bugfixes:*
closing the GUI no longer causes a SEGFAULT
https://github.com/DeepLabCut/DeepLabCut/commit/e4b3d025c41e832c4a6234e6856ff9cda7e0e0c8
fix unresponsive legend in tracklet GUI
https://github.com/DeepLabCut/DeepLabCut/commit/d2ce225c8be31c8da0cc449c72b58a389cddfb47
improved check_labels consistency
https://github.com/DeepLabCut/DeepLabCut/pull/852
fix a bug where the data were not correctly saved after extracting outlier frames with
https://github.com/DeepLabCut/DeepLabCut/pull/857
improved labeling accuracy
https://github.com/DeepLabCut/DeepLabCut/pull/856
fix ugly cross display when checking labels
https://github.com/DeepLabCut/DeepLabCut/pull/883

Supported by https://chanzuckerberg.com/eoss/proposals/deeplabcut-an-open-source-toolbox-for-robust-animal-pose-estimation/

Thanks for all the contributions from the community and jeylau!

We now also suggest that single animal DLC users install 2.2b7; the improvements to "normal" DLC are also of interest to all, and extra features like skeleton builder can be used for plotting and analysis, plus plotting heatmaps, etc.

Although this is a beta release, it is deemed a stable release (not alpha). the full 2.2 release will have more features, but no backwards breaking functions.

**we also recommend running `pip install --upgrade matplotlib` if you are using an older env file**

This release includes:
- setting of more Tracklet GUI tracking settings is not possible, and better defaults:
- Pass more options to the TrackletManager from the GUI
- Add docstring / HELP button information
- Now pass minimum track and swap lengths as the in number of frames
- Huge fitting speed boost!
- Update deprecated usage
- More informative errors printed
- Updated defaults to avoid huge memory use!
- adding compatibility for the fxn "analyze_skeleton" for maDLC 750
- speed improvement for batch processing creating labeled videos 748
- Allow creating of videos with full detection for specific body parts only 787
- path clean up across OS (c293048, b2cefc0, 189c11a)
- Ignore uncertain keypoints when augmenting dataset 741 (when you use the tracklet GUI there is an option to throw any refined frames back into training, but now this ignores low pcutoff points that you did not adjust)
- bug fix in mislabeled data 774, 777
- bug fix: Reindex labeled data to match config individual and bodypart order 764, 762
- `horse_sideview` model added to the zoo! 793
- better heatmaps are plotted during evaluation (easier to read)
- Tracklet GUI speed/video side improvements
- Fix SkeletonBuilder; if not all parts are ever labeled, still can be used and warning given to the user 763, 756
- Only rely on ffprobe when robust metadata are desired (773)
* Do not rely on ffprobe at all if robust_nframes is false
- DOCS: added governance & core principles 792, many other small doc upgrades.

Contributors to those updates:
internal:
AlexEMG
jeylau
MMathisLab
external:
smu160
fcatus
neslihanedes
PolarBean
alesantuz

Thanks!

- Expanded capabilities of conversion code for importing single animal labels to multianimal projects (docs expanded too); 718
- Expanded capabilities of SkeletonBuilder (now also functional if no frame has a scene with all bodyparts) 717
- Refactored imports, which speeds up loading etc. 714
- Labeling GUI: added hotkeys
- Defaults changed: *keeping tracklets of all lengths!*
https://github.com/DeepLabCut/DeepLabCut/blob/master/deeplabcut/refine_training_dataset/tracklets.py#L1056

Fixes:
- Fix gui crop for Windows 694
- ffprobe, robuster 713 711
- Video analysis over folders excludes keyword videos of the form:
*_labeled.videotype
*_full.videotype
https://github.com/DeepLabCut/DeepLabCut/commit/a6c4e9e5aa52e521a0066e90d1b14745a542fea5

- More robust auto-crop training set generation: 704
Note: We are considering not storing cropped data in /labeled-data but rather some subfolder of /trainingset-data
I.e. behavior of deeplabcut.cropimagesandlabels might change. We would be interested in user feedback.

- Docstring update https://github.com/DeepLabCut/DeepLabCut/commit/0e5380bb04d49a7ab97427c0d15173bb88c7559a

**This is the release of the multi-animal DeepLabCut 2.2.b5 BETA version. Note, this is a beta release and not all 2.2 features and abilities are integrated yet. However, given the large amount of changes, we want to get community feedback before the stable v2.2 is released! While this is still a beta version, it is a fully functional multi-animal pose estimation toolbox, and we do not anticipate any major backwards-breaking changes.**

Please carefully review the new docs!

**Major updates:**
- multi-animal project creation functions (multianimal=True)
- updated data structure to create, store, ... multianimal pose data
- functionality to check labels by bodypart and individual ID
- function for cropimagesandlabels
- data loader for maDLC; create training dataset
- multi-task deep neural network that predicts limb-connections, scoremaps, locref layers
- faster training methods
- functions to plot scoremaps, locref, and limb-connections (PAFs)
- video analysis and detection of animal ID in a bottom-up manner; cross validation methods for finding best parameters with a global, Bayesian optimization with gaussian processes
- various different target metrics to optimize for (oks/rmse)
- new Refine Tracklet GUI; i.e. one can correct and save the corrected videos (bodypart and animal ID) (VIDEO: https://youtu.be/bEuBKB7eqmk)
- functionality in create_labeled_videos
- - increased speed for video creation code (deeplabcut.label_frames(); now one can also turn off frames)
- function dlc.CropVideo
- many new functions built into the Project Manager GUI
- - add more videos, video_editor tab (downsample, crop, shorten videos), refine tracklets, edit config, edit inference parameters, show figures, etc.
- small updates: 464, 604
- EXTENDED docs and several new video tutorials released (https://www.youtube.com/channel/UC2HEbWpC_1v6i9RnDMy-dfA)!
- function to convert older projects into 2.2 format for multi-animal if desired, otherwise this update is backwards compatible with your pre-2.2 projects

Funded, in part by a grant to the DeepLabCut team from the Chan-Zuckerberg Essential Open Source Science Grant - https://chanzuckerberg.com/eoss/proposals/deeplabcut-an-open-source-toolbox-for-robust-animal-pose-estimation/

Final release before 2.2 -- stay tuned & already update!

Improvements:
- Epipolar lines and related changes 834 (from 2.1.10.3)
- Unbundled GUI code 1155 (from 2.1.10.3)
- Storing evaluation results from all shuffles/trainingsplits etc. in one summary table. So far they were separate per shuffle and split but combined iterations. 85126659534496055a626719d645a0d9cf9880fd
- Contrast augmentation conveniently included in imgaug, see: 1166 84259d70baa6f192def16ffbe5f8f45b9fbcba24

Minor changes:
- Rollback of ResNet_50 naming convention. 1195 -- this was accidentally introduced when adding the EfficientNets in January and caused videos to be reanalyzed as the `DLCsccorername` changed. This is a fix for backwards compatibility, but of course all new projects from January 21 - now suffer the same problem... One can of course write a script to re-name the output files & or simply re-run DLC. Sorry for the inconvenience.

How to upgrade:

with GUI support:
`pip install --upgrade 'deeplabcut[gui]'`
otherwise:
`pip install --upgrade deeplabcut`