Skip to main content

Library for kinematic analysis of DeepLabCut outputs

Project description

PyPI version Downloads Downloads Code style: black Generic badge codecov Twitter Follow DOI

cam cntrl

A post-deeplabcut module for kinematic analysis

This repo will continue to grow, but here are some helper functions to get you started. Note, the API is subject to change. You can run the functions on data files obtained from running inference with DeepLabCut. Currently, this code requires python 3.8 onwards. We recommend using the DEEPLABCUT conda file, and then simply run pip install dlc2kinematics within your environment.

Quick start

pip install dlc2kinematics

Useage

import dlc2kinematics

Load data:

df, bodyparts, scorer = dlc2kinematics.load_data(<path of the h5 file>)

Basic Operations

Compute velocity:

  • For all bodyparts:
    df_vel = dlc2kinematics.compute_velocity(df,bodyparts=['all'])
    
  • For only few bodyparts:
    df_vel = dlc2kinematics.compute_velocity(df,bodyparts=['nose','joystick'])
    

Compute acceleration:

  • For all bodyparts:
    df_acc = dlc2kinematics.compute_acceleration(df,bodyparts=['all'])
    
  • For only few bodyparts:
    df_vel = dlc2kinematics.compute_acceleration(df,bodyparts=['nose','joystick'])
    

Compute speed:

df_speed = dlc2kinematics.compute_speed(df,bodyparts=['nose','joystick'])

Computations in joint coordinates

To compute joint angles, we first create a dictionary where keys are the joint angles and the corresponding values are the set of bodyparts:

joints_dict= {}
joints_dict['R-Elbow']  = ['R_shoulder', 'Right_elbow', 'Right_wrist']

and compute the joint angles with

joint_angles = dlc2kinematics.compute_joint_angles(df,joints_dict)

Compute joint angular velocity with

joint_vel = dlc2kinematics.compute_joint_velocity(joint_angles)

Compute joint angular acceleration with

joint_acc = dlc2kinematics.compute_joint_acceleration(joint_angles)

Compute correlation of angular velocity

corr = dlc2kinematics.compute_correlation(joint_vel, plot=True)

Compute PCA of angular velocity with

pca = dlc2kinematics.compute_pca(joint_vel, plot=True)

PCA-based reconstruction of postures

Compute and plot PCA based on posture reconstruction with:

dlc2kinematics.plot_3d_pca_reconstruction(df_vel, n_components=10, framenumber=500,
                                     bodyparts2plot=bodyparts2plot, bp_to_connect=bp_to_connect)

UMAP Embeddings

embedding, transformed_data = dlc2kinematics.compute_umap(df, key=['LeftForelimb', 'RightForelimb'], chunk_length=30, fit_transform=True, n_neighbors=30, n_components=3,metric="euclidean")

dlc2kinematics.plot_umap(transformed_data, size=5, alpha=1, color="indigo", figsize=(10, 6))

Contributing

  • If you spot an issue or have a question, please open an issue with a suitable tag.
  • For code contributions:
    • please see the contributing guide.
    • Please reference all issues this PR addresses in the description text.
    • Before submitting your PR, ensure all code is formatted properly by running
      black .
      
      in the root directory.
    • Assign a reviewer, typically MMathisLab.
    • sign CLA.

Acknowledgements

This code is a collect of contributions from members of the Mathis Laboratory over the years. In particular (alphabetical): Michael Beauzile, Sebastien Hausmann, Jessy Lauer, Alexander Mathis, Mackenzie Mathis, Tanmay Nath, Kai Sandbrink, Steffen Schneider.

If you use this code, please cite:

@software{dlc2kinematics,
  author       = {Mathis, Mackenzie and
                  Lauer, Jessy and
                  Nath, Tanmay and
                  Sandbrink, Kai and
                  Beauzile, Michael and
                  Hausmann, Sébastien and
                  Schneider, Steffen and
                  Mathis, Alexander},
  title        = {{DLC2Kinematics: a post-deeplabcut module for 
                   kinematic analysis}},
  month        = feb,
  year         = 2020,
  publisher    = {Zenodo},
  version      = {v0.0.4},
  doi          = {10.5281/zenodo.6669074},
  url          = {https://doi.org/10.5281/zenodo.6669074}
}

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

dlc2kinematics-0.0.7.tar.gz (2.5 MB view details)

Uploaded Source

Built Distribution

dlc2kinematics-0.0.7-py3-none-any.whl (33.9 kB view details)

Uploaded Python 3

File details

Details for the file dlc2kinematics-0.0.7.tar.gz.

File metadata

  • Download URL: dlc2kinematics-0.0.7.tar.gz
  • Upload date:
  • Size: 2.5 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.11.4

File hashes

Hashes for dlc2kinematics-0.0.7.tar.gz
Algorithm Hash digest
SHA256 ff15faedcf8ca660ae30d3794329f1a195bfb1fba6eef601b84034daf2179710
MD5 0f2777dca4ced3215fdfbb0f435e7f5a
BLAKE2b-256 b5f79994dc634eeb09e27ee10cfabb515e855b97e2af28aacc9855058cf79c80

See more details on using hashes here.

Provenance

File details

Details for the file dlc2kinematics-0.0.7-py3-none-any.whl.

File metadata

File hashes

Hashes for dlc2kinematics-0.0.7-py3-none-any.whl
Algorithm Hash digest
SHA256 ace70aab8d6de7cfbff787e0cc367b41632def11208c845d1e381384de28d88b
MD5 184855581dc9a914bcd4a6f4b15c447a
BLAKE2b-256 78854e72c748bf954efcc93edea6d39c1f97d1fd11b91b885c711536ae481018

See more details on using hashes here.

Provenance

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page