Package: gaitmap
gaitmap - The Gait and Movement Analysis Packagegaitmapprovides a set of algorithms to analyze your IMU movement data (with a focus on foot-worn IMUs) without
getting into your way.💻20+ Algorithmsfrom 17+ publications📚 Extensivedocumentation📝 Build to beeasily extendable⚙️ Familiar API inspired by scikit-learn🤝 Interoperable with the other libraries from the gaitmap ecosystem (gaitmap-dataset,tpcp, ...)Documentation:gaitmap.readthedocs.ioLearn More about the gaitmap ecosystem:Coming soon!InstallationGaitmap is split into two packages:gaitmapandgaitmap_mad(Learn more).
To get access to all available algorithms, you need to install both packages:pipinstallgaitmapgaitmap_mad--upgradeBoth packages are always released together and have the same version number.
We don't recommend mixing different versions ofgaitmapandgaitmap_mad.Note:gaitmap-mad is published under a AGPL-3.0 license, while gaitmap is published under a MIT license.
Please, check theLicensesection below for more details.In case you are sure that AGPL-3.0 is compatible with your project, you can installgaitmap_madwithout any downsides.
Otherwise, just installgaitmapand check the API-docu page of the individual algorithms if they are available ingaitmaponly.Installing from GithubIf you want to install the latest version from Github, you can use the following command:# For gaitmappipinstall"git+https://github.com/mad-lab-fau/gaitmap.git"--upgrade# For gaitmap_madpipinstall"git+https://github.com/mad-lab-fau/gaitmap.git#subdirectory=gaitmap_mad"Note, that we don't guarantee that the latest version on Github is stable.Enabling specific featuresHidden Markov ModelsTo use the HMM (anything imported fromgaitmap.stride_segmentation.hmm) based algorithms make sure you installgaitmapwith thehmmextra.pipinstallgaitmap_mad"gaitmap[hmm]"--upgradeThis installs thepomegranatepackage, which is the basis for the HMM implementation.
Note, that we only support thepomegranateversion>=0.14.2,<=0.14.6and thatpomegranteis not compatible with
Python 3.10.We are working on upgrading to a newer version ofpomegranate, but this is not a priority at the moment.
You can track the progress in thepull request.Supported Python versionsgaitmapis tested against Python 3.8 and 3.9 at the moment.
We expect most features to work with all Python versions >= 3.8, but because of some known issues
(see specific features above) we do not officially support them.Working with Algorithmsgaitmapis designed to be a toolbox and not a single algorithm.
This means, that you are expected to pick and use individual algorithms.To get started withgaitmapwe recommend to follow these steps:Have a look at our example to get an understanding of whatgaitmapcan do:ExampleUnderstand the common datatypes we use:Common Datatypes,Coordinate SystemsLearn how to prepare your own data (or play around with example data):Prepare DataCheck the API docs and examples for available algorithms:API Docs,ExamplesEach algorithm is implemented as a class, which is initialized with the required parameters.
In many cases the default parameters are sufficient, but to get the best results on your data, you should adapt them.fromgaitmap.stride_segmentationimportBarthDtwstride_segmenter=BarthDtw(max_cost=2.5)After initialization, you can apply the algorithm to your data (each group of algorithm has a different action method):my_imu_data=...stride_segmenter.segment(my_imu_data,sampling_rate_hz=204.8)Results are stored as parameters of the algorithm object (with a trailing underscore):segmented_strides=stride_segmenter.stride_list_Most algorithms have additional results available to provide further information.dtw_warping_path=stride_segmenter.paths_To build a full gait analysis pipeline you can combine multiple algorithms (Example).
You can even substitute your own algorithms (Guide) or use the provided tooling to validate
and optimize your algorithms using tpcp (General Guide,Example).ContributingWe want to hear from you (and we want your algorithms)!👍 We are always happy to receive feedback and contributions.
If you run into any issues or have any questions, please open anissue on Githubor start adiscussions.📚 If you are usinggaitmapin your research or project, we would love to hear about it and link your work here! Theshow and tell sectionin the discussions is a great place for this.💻 And most importantly, we want your algorithms!
If you have an algorithm that you think would be a good fit forgaitmap, open an issue, and we can discuss how to integrate it.
We are happy to help you with the integration process.
Even if you are not confident in your Python skills, we can discuss ways to get your algorithm intogaitmap.For all these topics check out ourcontributing guidefor more details.CitationIf you usegaitmapin your research we would appreciate a citation.
This helps us to justify the time we invest in the development and maintenance of the library.We currently prepare a paper to describe thegaitmaplibrary in detail.
Until then, please simply cite the repository.If you use a specific algorithm please also make sure you cite the original paper of the algorithm!
We recommend the following citation style:We used the algorithm proposed by Author et al. [paper-citation], implemented by the Gaitmap package [gaitmap-citation].LicenseThegaitmap(which includes most algorithms) is published under aMIT license.
This is a permissive license, which allows you to use the code in nearly any way you want, as long as you include the
original license in you modified version.gaitmap_madis published under a AGPL-3.0 license.
This only affects algorithms that were developed by theMaD Labin collaboration with industry partners.
The AGPL-3.0 license is a copyleft license, which if you integrategaitmap_madinto your software and provide it to
others (either as a service or as a product), you have to publish your software under a compatible open source license.
Please, check theAGPL-3.0 licensefor more details and make sure
you understand the implications.If you need to usegaitmap_madin a closed source project, please contact us for a potential commercial license.For DevelopersTheDevelopment Guideshave detailed information for all new developers.Here some quick references
Install Python >=3.8 andpoetry.
Then run the commands below to get the latest source and install the dependencies:gitclonehttps://github.com/mad-lab-fau/gaitmap.git# For Python 3.8 and 3.9 (and if you need to work on hmm)poetryinstall--all-extras# For Python >=3.10 (you can not work on hmm stuff with this)poetryinstall-EstatsWarning: Building the docs currently only works in 3.8 and 3.9 with all extras installed.Note, that you don't need to care about thegaitmap_madsubpackage.
All dependencies are specified in the mainpyproject.tomland thegaitmap_madwill be installed in editable mode
when runningpoetry install.To run any of the tools required for the development workflow, use the poe commands:poetryrunpoe
...
CONFIGUREDTASKSformatlintLintallfileswithProspector.checkCheckallpotentialformatandlintingissues.testRunPytestwithcoverage.docsBuildthehtmldocsusingSphinx.register_jupyterRegisterthegaitmapenvironmentasaJupyterkernelfortesting.versionBumpversioninallrelevantplaces.bump_devUpdatealldevdependenciestotheir@latestversion.