V0.0.1 -- hello world! (#4)

Co-authored-by: Jessy Lauer <[email protected]>

Author: MMathisLab

.github/workflows/greetings.yml

@@ -0,0 +1,16 @@
+name: Greetings
+
+on: [pull_request, issues]
+
+jobs:
+  greeting:
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+      pull-requests: write
+    steps:
+    - uses: actions/first-interaction@v1
+      with:
+        repo-token: ${{ secrets.GITHUB_TOKEN }}
+        issue-message: 'Welcome! Thank you for your contribution!'
+        pr-message: 'Welcome! Thank you for your contribution!'

.github/workflows/python-package.yml

@@ -0,0 +1,38 @@
+name: Python package
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
+
+jobs:
+  build:
+    runs-on: ${{ matrix.os }}
+
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-11, windows-latest]
+        python-version: [3.8, 3.9]
+        include:
+          - os: ubuntu-latest
+            path: ~/.cache/pip
+          - os: macos-11
+            path: ~/Library/Caches/pip
+          - os: windows-latest
+            path: ~\AppData\Local\pip\Cache
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v2
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v2
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip setuptools wheel
+          python setup.py install

.github/workflows/python-publish.yml

@@ -0,0 +1,36 @@
+# This workflow will upload a Python Package using Twine when a release is created
+# For more information see: https://help.github.com/en/actions/language-and-framework-guides/using-python-with-github-actions#publishing-to-package-registries
+
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+
+name: Upload Python Package
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  deploy:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Python
+      uses: actions/setup-python@v2
+      with:
+        python-version: '3.x'
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install build
+    - name: Build package
+      run: python -m build
+    - name: Publish package
+      uses: pypa/gh-action-pypi-publish@27b31702a0e7fc50959f5ad993c78deac1bdfc29
+      with:
+        user: __token__
+        password: ${{ secrets.PYPI_API_TOKEN }}

LICENSE

@@ -0,0 +1,8 @@
+Copyright 2020-2022 by The Mathis Laboratory of Adaptive Motor Control, Mackenzie Mathis, & contributors. All rights reserved.
+This project and all its files are available for non-commercial use only. This software may not be used to harm any person or animal deliberately.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, 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.
+
+THE SOFTWARE 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 NON-INFRINGEMENT. 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 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

README.md

@@ -6,18 +6,123 @@
 
 #### A post-deeplabcut module for kinematic analysis
 
-### under construction ...
+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](http://deeplabcut.org/). Currently, this code requires python 3.8 onwards. We recommend using the [DEEPLABCUT conda file](https://deeplabcut.github.io/DeepLabCut/docs/installation.html), and then simply run `pip install dlc2kinematics` within your environment.
 
-Currently this is not yet publicly available, but feel free to "watch" or "star" to be notified of updates.
 
 ## Quick start
 
-`pip install dlc2kinematics`
+``` bash
+pip install dlc2kinematics
+```
+## Useage
 
-## License
+``` python
+import dlc2kinematics
+```
 
-DLC2Kinematics is freely available for non-commercial use, and may be redistributed under these conditions. Please, see the license for further details.
+Load data:
 
-## Contact
+``` python
+df, bodyparts, scorer = dlc2kinematics.load_data(<path of the h5 file>)
+```
 
-Mackenzie Mathis - [email protected]
+### Basic Operations
+
+Compute velocity:
+
+  - For all bodyparts:
+    ``` python
+    df_vel = dlc2kinematics.compute_velocity(df,bodyparts=['all'])
+    ```
+  - For only few bodyparts:
+    ``` python
+    df_vel = dlc2kinematics.compute_velocity(df,bodyparts=['nose','joystick'])
+    ```
+
+Compute acceleration:
+
+- For all bodyparts:
+  ``` python
+  df_acc = dlc2kinematics.compute_acceleration(df,bodyparts=['all'])
+  ```
+- For only few bodyparts:
+  ``` python
+  df_vel = dlc2kinematics.compute_acceleration(df,bodyparts=['nose','joystick'])
+  ```
+
+Compute speed:
+
+``` python
+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:
+
+``` python
+joint_dict= {}
+joints_dict['R-Elbow']  = ['R_shoulder', 'Right_elbow', 'Right_wrist']
+```
+
+and compute the joint angles with
+
+``` python
+joint_angles = dlc2kinematics.compute_joint_angles(df,joints_dict)
+```
+
+Compute joint angular velocity with
+
+``` python
+joint_vel = dlc2kinematics.compute_joint_velocity(joint_angles)
+```
+
+Compute joint angular acceleration with
+
+``` python
+joint_acc = dlc2kinematics.compute_joint_acceleration(joint_angles)
+```
+
+Compute correlation of angular velocity
+
+``` python
+corr = dlc2kinematics.compute_correlation(joint_vel, plot=True)
+```
+
+Compute PCA of angular velocity with
+
+``` python
+pca = dlc2kinematics.compute_pca(joint_vel, plot=True)
+```
+### PCA-based reconstruction of postures
+
+Compute and plot PCA based on posture reconstruction with: 
+
+``` python
+dlc2kinematics.plot_3d_pca_reconstruction(df_vel, n_components=10, framenumber=500,
+                                     bodyparts2plot=bodyparts2plot, bp_to_connect=bp_to_connect)
+```
+
+### UMAP Embeddings
+``` python
+dlc2kinematics.compute_umap(df, key=['LeftForelimb', 'RightForelimb'], chunk_length=30, fit_transform=True, n_neighbors=30, n_components=3,metric="euclidean")
+```
+
+## Contributing
+
+- If you spot an issue or have a question, please open an [issue](https://github.com/AdaptiveMotorControlLab/dlc2kinematics/issues) with a suitable tag.
+- For [code contributions](https://github.com/AdaptiveMotorControlLab/dlc2kinematics/pulls):
+  - please see the [contributing guide](docs/CONTRIBUTING.md).
+  - Please reference all issues this PR addresses in the description text.
+  - Before submitting your PR, ensure all code is formatted properly by running
+    ``` bash
+    black .
+    ```
+    in the root directory.
+  - Assign a reviewer, typically [MMathisLab](https://github.com/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, Mackenzie Mathis, Tanmay Nath, Steffen Schneider.

dlc2kinematics/__init__.py

@@ -1,6 +1,58 @@
 """
-DLC2Kinematics
-©M. Mathis Labs
+dlc2kinematics
+© M. Mathis Lab
+https://github.com/AdaptiveMotorControlLab/dlc2kinematics/
 """
 
-from dlc2kinamtics.version import __version__
+from dlc2kinematics.version import __version__, VERSION
+from dlc2kinematics.preprocess import load_data, smooth_trajectory
+from dlc2kinematics.mainfxns import (
+    compute_velocity,
+    compute_acceleration,
+    compute_speed,
+    extract_kinematic_synergies,
+    compute_umap,
+)
+from dlc2kinematics.plotting import (
+    plot_joint_angles,
+    plot_velocity,
+    pca_plot,
+    plot_3d_pca_reconstruction,
+    visualize_synergies,
+    plot_umap,
+)
+from dlc2kinematics.utils import auxiliaryfunctions
+
+from dlc2kinematics.joint_analysis import (
+    load_joint_angles,
+    compute_joint_angles,
+    compute_joint_velocity,
+    compute_joint_acceleration,
+    compute_correlation,
+    compute_pca,
+)
+from dlc2kinematics.quaternions import (
+    compute_joint_quaternions,
+    compute_joint_doubleangles,
+    plot_joint_quaternions,
+    compute_joint_quaternion_velocity,
+    compute_joint_quaternion_acceleration,
+    _load_quaternions,
+)
+
+try:
+    from dlc2kinematics.plotting import (
+        plot_joint_angles,
+        plot_velocity,
+        pca_plot,
+        plot_3d_pca_reconstruction,
+        visualize_synergies,
+    )
+    from dlc2kinematics.visualization import (
+        Visualizer3D,
+        MinimalVisualizer3D,
+        MultiVisualizer,
+        Visualizer2D,
+    )
+except:
+    print("Could not import plotting and visualization functions.")