Metadata-Version: 2.1
Name: gaitalytics
Version: 0.2.1.post7
Summary: easy gait-metrics for everyone
Author-email: André Böni <andre.boeni@llui.org>
Maintainer-email: André Böni <andre.boeni@llui.org>
License: MIT License
        
        Copyright (c) 2024 André Böni
        
        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 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 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/DART-Lab-LLUI/python-gaitalytics
Project-URL: Documentation, https://python-gaitalytics.readthedocs.io
Project-URL: Repository, https://github.com/DART-Lab-LLUI/python-gaitalytics
Project-URL: Issues, https://github.com/DART-Lab-LLUI/python-gaitalytics/issues
Project-URL: Changelog, https://github.com/me/spam/blob/master/CHANGELOG.md
Keywords: gait-analysis,mocap,c3d,gait-metrics,biomechanics
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Utilities
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/x-rst
License-File: LICENSE
License-File: AUTHORS.rst
Requires-Dist: h5netcdf>=1.3.0
Requires-Dist: pandas>=1.5
Requires-Dist: pyyaml>=6.0.1
Requires-Dist: scipy>=1.13
Requires-Dist: numpy>=1.23
Requires-Dist: pyomeca>=2021.0
Requires-Dist: ezc3d>=1.5
Requires-Dist: xarray>=20.6
Provides-Extra: dev
Requires-Dist: ruff; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: pip; extra == "dev"
Requires-Dist: types-PyYAML; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Provides-Extra: build
Requires-Dist: build; extra == "build"
Requires-Dist: setuptools>=64; extra == "build"
Requires-Dist: setuptools_scm>=8; extra == "build"
Provides-Extra: docs
Requires-Dist: sphinx; extra == "docs"
Requires-Dist: setuptools>=64; extra == "docs"
Requires-Dist: sphinx-rtd-theme; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints; extra == "docs"
Requires-Dist: sphinx_github_changelog; extra == "docs"
Requires-Dist: sphinx-codeautolink; extra == "docs"
Requires-Dist: sphinxcontrib-bibtex; extra == "docs"

Gaitalytics
===========

.. start-badges

.. list-table::
    :stub-columns: 1

    * - docs
      - |docs|
    * - tests
      - | |github-actions|
    * - package
      - | |pypi|
        | |conda|
    * - development
      - | |MIT|
        | |last-commit|
        | |commits-since|
        | |pixi-badge|

.. |docs| image:: https://img.shields.io/readthedocs/python-gaitalytics?logo=readthedocs
    :target: https://python-gaitalytics.readthedocs.io/
    :alt: Documentation Status

.. |github-actions| image:: https://img.shields.io/github/actions/workflow/status/DART-Lab-LLUI/python-gaitalytics/on_push_test.yaml?logo=pytest
    :alt: GitHub Actions Build Status
    :target: https://github.com/DART-Lab-LLUI/python-gaitalytics/actions/

.. |last-commit| image:: https://img.shields.io/github/last-commit/DART-Lab-LLUI/python-gaitalytics
   :alt: GitHub last commit
   :target: https://github.com/DART-Lab-LLUI/python-gaitalytics

.. |commits-since| image:: https://img.shields.io/github/commits-since/DART-Lab-LLUI/python-gaitalytics/latest.svg
    :alt: Commits since latest release
    :target: https://github.com/DART-Lab-LLUI/python-gaitalytics/compare/

.. |pixi-badge| image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/prefix-dev/pixi/main/assets/badge/v0.json
    :alt: Pixi Badge
    :target: https://pixi.sh

.. |pypi| image:: https://img.shields.io/pypi/dm/gaitalytics?logo=pypi
   :alt: PyPI - Downloads
   :target: https://pypi.org/project/gaitalytics/

.. |conda| image:: https://img.shields.io/conda/dn/DartLab-LLUI/gaitalytics?logo=anaconda
   :alt: Conda Downloads
   :target: https://anaconda.org/dartlab-llui/gaitalytics

.. |MIT| image:: https://img.shields.io/github/license/DART-Lab-LLUI/python-gaitalytics?logo=opensourceinitiative
   :alt: GitHub License






.. end-badges

This Python package provides a comprehensive set of tools and advanced algorithms for analyzing 3D motion capture data.
It is specifically designed to process gait data stored in c3d format. Prior to utilizing the features of gaitalytics,
it is necessary to perform data labeling, modeling, and filtering procedures.

The library's versatility allows it to be adaptable to various marker sets and modeling algorithms,
offering high configurability.

Quickstart
----------

Installation
^^^^^^^^^^^^

Fast install with anaconda:

.. code:: shell

    conda install gaitalytics -c DartLab-LLUI
..

Or with pip:

.. code:: shell

    pip install gaitalytics
..

..

.. warning::
        | Manual installation of the `pyomeca <https://pyomeca.github.io/>`_ package is required. when using the pip installation method.

Configuration
^^^^^^^^^^^^^

Gaitalytics can be used with any marker set, which at least includes
three or for hip markers (front left/right, back left/right or sacrum) and four foot
markers (left heel/toe, right heel/toe).

Additionally markers can be defined on which standard time-series features such as min max mean etc.
will be calculated.

All functionalities in the libraries only take points into account which
are configured in as specific yaml file.



Minimal requirements would look like this:

.. code-block:: yaml

    analysis:
      markers:
        - "LHipAngles"
        - "LKneeAngles"
        - "LAnkleAngles"
        - "LPelvisAngles"
        - "LThoraxAngles"
    mapping:
      markers:
        # Foot
        l_heel: "LHEE"
        r_heel: "RHEE"
        l_toe: "LTOE"
        r_toe: "RTOE"

        # Hip
        l_ant_hip: "LASI"
        r_ant_hip: "RASI"
        l_post_hip: "LPSI"
        r_post_hip: "RPSI"
        sacrum: "SACR"
..



Simple Pipeline
^^^^^^^^^^^^^^^^
.. code-block:: python

    from gaitalytics import api
    # Load configuration (yaml file from above)
    config = api.load_config("./pig_config.yaml")

    # Load trial from c3d file
    trial = api.load_c3d_trial("./test_small.c3d", config)

    # Detect events
    events = api.detect_events(trial, config)
    try:
        # check events
        api.check_events(events)

        # write events to c3d in the same file
        api.write_events_to_c3d("./test_small.c3d", events, './test.c3d')

        # add events to trial
        trial.events = events

        # segment trial to gait cycles. (Events are already existing in the c3d file)
        trial_segmented = api.segment_trial(trial)

        # calculate features
        features = api.calculate_features(trial_segmented, config)

        # normalise time
        trial_normalized = api.time_normalise_trial(trial_segmented)

        # save features
        features.to_netcdf("features.nc")

        # export segmented trial to netcdf
        api.export_trial(trial_segmented, "output_segments")
        api.export_trial(trial_normalized, "output_norm")

    except ValueError as e:
        print(e)
..

Documentation
-------------
https://python-gaitalytics.readthedocs.org

