This is the source repository for the paper:
Moore, J.K., Hnat, S.K, van den Bogert, A. "An elaborate data set on human gait and the effect of mechanical perturbations", 2015.
This repository contains or links to all of the information needed to reproduce the results in the paper.
The latest rendered version of the PDF can be viewed via the ShareLaTeX CI system:
The peer reviewed article can be obtained from PeerJ:
https://peerj.com/articles/918
The preprint can be obtained from the PeerJ preprint server:
http://peerj.com/preprints/700
The contents of this repository is licensed under the Creative Commons Attribution 4.0 International License.
If you make use of our work we ask that you cite us. The following are some BibTeX formatted references that may be useful.
@article{10.7717/peerj.918,
title = {An elaborate data set on human gait and the effect of mechanical perturbations},
author = {Moore, Jason K. and Hnat, Sandra K. and van den Bogert, Antonie J.},
year = {2015},
month = {4},
keywords = {Gait, Data, Control, Perturbation},
volume = {3},
pages = {e918},
journal = {PeerJ},
issn = {2167-8359},
url = {https://dx.doi.org/10.7717/peerj.918},
doi = {10.7717/peerj.918}
}
You may want to cite the particular version. See the PeerJ website for details.
@article{10.7287/peerj.preprints.700,
title = {An elaborate data set on human gait and the effect of mechanical perturbations},
author = {Moore, Jason K and Hnat, Sandra K. and van den Bogert, Antonie J.},
year = {2014},
month = {12},
keywords = {gait, data, control, perturbation},
volume = {2},
pages = {e700},
journal = {PeerJ PrePrints},
issn = {2167-9843},
url = {http://dx.doi.org/10.7287/peerj.preprints.700},
doi = {10.7287/peerj.preprints.700}}
@misc{Moore2014,
title={An elaborate data set on human gait and the effect of mechanical perturbations},
url={http://dx.doi.org/10.5281/zenodo.13030},
DOI={10.5281/zenodo.13030},
publisher={ZENODO},
author={Moore, Jason K. and Hnat, Sandra K. and van den Bogert, Antonie},
year={2014}}
@misc{Hnat2015,
author={Hnat, Sandra K. and Moore, Jason K. and van den Bogert, Antonie J.},
title={{Commanded Treadmill Motions for Perturbation Experiments}},
month=mar,
year=2015,
doi={10.5281/zenodo.16064},
url={http://dx.doi.org/10.5281/zenodo.16064}}
@misc{DTK2014,
title={DynamicistToolKit: Version 0.3.5},
url={http://dx.doi.org/10.5281/zenodo.13253},
DOI={10.5281/zenodo.13253},
publisher={ZENODO},
author={Jason K. Moore and Christopher Dembia},
year={2014}}
@misc{GATK2014,
title={GaitAnalysisToolKit: Version 0.1.2},
url={http://dx.doi.org/10.5281/zenodo.13159},
DOI={10.5281/zenodo.13159}, publisher={ZENODO},
author={Jason K. Moore and Nwanna, Obinna and Hnat, Sandra K. and van den Bogert, Antonie},
year={2014}}
The data presented in the paper is available for download from Zenodo under the Creative Commons CC0 license.
The scripts used for the analysis is available in the src directory of this
repository and depend primarily on two open source Python packages developed
for this paper. The snapshots of the DynamicistToolKit 0.3.5 and the
GaitAnalysisToolKit 0.1.2 are available via both Zenodo and PyPi:
Be sure to read the installation instructions for the two packages.
- DynamicistToolKit
- GaitAnalysisToolKit
There are a variety of dependencies that must be installed on your system to run the scripts. It is best to follow the installation instructions provided by each of the following software packages for your operating system.
- Various unix tools [1]: cd, bash, gzip, make, mkdir, rm, tar, unzip, curl, wget
- The Anaconda Python distribution with Python 2.7 for ease of download and management of Python packages.
- Various Python packages: pip, numpy 1.9.1, scipy 0.14.0, matplotlib 1.4.2, pytables 3.1.1, pandas 0.15.1, pyyaml 3.11, seaborn 0.5.0, pygments 2.0.1, oct2py 2.4.2, DynamicistToolKit 0.3.5, GaitAnalysisToolKit 0.1.2
- Octave 3.6.4-3.8.2
- A LaTeX distribution which includes pdflatex. For example: MikTeX [Win], TeX Live [Linux], MacTeX [Mac].
- Various LaTeX Packages [2]: minted, lineno, graphicx, booktabs, cprotect, siunitx, inputenc, babel, ifthen, calc, microtype, times, mathptmx, ifpdf, amsmath, amsfonts, amssymb, xcolor, authblk, geometry, caption, natbib, fancyhdr, lastpage, titlesec, enumitem, bibtex
- Git (optional)
- MATLAB Version 7.9 (R2009b) and Simulink Toolbox Version 7.4, including the Signal Processing Blockset Version 6.10 and Communications Blockset Version 4.3
| [1] | These are available by default in Linux distributions, provided by Xcode on the Mac, and can be obtained via Cygwin, MinGW, or individual install on Windows. |
| [2] | Most packages will likely be installed with your LaTeX distribution,
otherwise follow the installation instructions provided by the package. Note
that minted has abnormal dependencies: Python and Pygments. On Debian based
systems you will need to install texlive-humanities and
texlive-science to get all of the necessary packages. |
Install the TeXLive LaTeX distribution and some subpackages:
$ sudo apt-get install texlive texlive-humanities texlive-science
Install Octave:
$ sudo apt-get install octave
Install Matlab by purchasing it from http://mathworks.com and following their recommended installation procedure for your operating system. Make sure Matlab is on the system PATH.
Install the Anaconda Python distribution, following the instructions on the website, for example for 64 bit Linux:
$ wget http://09c8d0b2229f813c1b93-c95ac804525aac4b6dba79b00b39d1d3.r79.cf1.rackcdn.com/Anaconda-2.1.0-Linux-x86_64.sh $ bash Anaconda-2.1.0-Linux-x86_64.sh
Now create and activate a Conda [3] environment with the main Python dependencies.:
$ conda create -n gait python=2.7 pip numpy=1.9.1 scipy=0.14.0 \ matplotlib=1.4.2 pytables=3.1.1 pandas=0.15.1 pyyaml=3.11 seaborn=0.5.0 \ pygments=2.0.1 $ source activate gait
| [3] | Conda is a lightweight package manager that is used to download the exact versions of software into an isolated user installed environment. |
Finally, install the remaining dependencies with pip [4] which grabs the correct versions from the Python Package Index (PyPi):
(gait)$ pip install oct2py==2.4.2 (gait)$ pip install DynamicistToolKit==0.3.5 (gait)$ pip install GaitAnalysisToolKit==0.1.2
| [4] | pip is also a lightweight package manager and is used here instead of Conda because the three packages listed do not yet have Conda binaries available. |
The following is a recommended dependency installation procedure for Windows.
Install msysgit from http://msysgit.github.io to provide a Unix compatible BASH terminal. Use the default options and select "Use Git from Git Bash Only" and "Checkout windows-style, commit unix-style line endings". This puts a command "Git Bash" in the start menu that opens a shell which can be used for most commands.
Install Anaconda from http://continuum.io/downloads to provide Python and many
standard Python packages. Select install for "Just Me" unless you want to
install it system wide with adminstrator priveleges. Be sure both "Add anaconda
to my PATH environment variable" and "Register Anaconda as my default
python2.7" are checked. At this point Python is now available both in Git Bash
and the Windows Command Prompt (cmd.exe).
Download the lastest SWC Installer from
https://github.com/swcarpentry/windows-installer/releases. Install it by double
clicking the exe file and then make sure to click "launch installer" in the
last dialog. You'll then see a command prompt briefly listing the things it
installs. GNU Make is now available in Git Bash.
Download the "Basic Miktek" from http://miktex.org/download. Install with the
default options and after the install run "Update" from the Start Menu to
update the packages. pdflatex and other LaTeX tools are now available in
Git Bash and the Windows command prompt. Either use the package manager to
install all of the necessary LaTeX packages or wait to be prompted for them
during the first document compilation.
Download Octave 3.8.2 from http://mxeoctave.osuv.de [5].
Install the exe file (this requires a Java VM runtime to be installed). Now
add Octave's bin directory to the Windows PATH so that the octave
command can be run from Git Bash and the Windows command prompt. In the
computer system properties advanced tab, select "Environment Variables" and
prepend C:\Users\<your-user-name>\.swc\bin;C:\Octave\Octave-3.8.2\bin; to
the contents of PATH. The SWC bin must come before the Octave bin
because Octave contains a command called make that will override the
.swc\bin\make executable, which is undesirable.
| [5] | The 3.6.4 MinGW binary from http://sourceforge.net/projects/octave/files/Octave%20Windows%20binaries will also work. |
Install Matlab by purchasing it from http://mathworks.com and following their recommended installation procedure for your operating system. Make sure Matlab is on the system PATH.
The conda environment can be created from Git Bash or the Windows command prompt with the same commands as above:
$ conda create -n gait python=2.7 pip numpy=1.9.1 scipy=0.14.0 \ matplotlib=1.4.2 pytables=3.1.1 pandas=0.15.1 pyyaml=3.11 seaborn=0.5.0 \ pygments=2.0.1
But the environment activation and subsequent Python commands must be run from the Windows command prompt [6]:
> activate gait [gait] > pip install oct2py==2.4.2 [gait] > pip install DynamicistToolKit==0.3.5 [gait] > pip install GaitAnalysisToolKit==0.1.2
| [6] | They can be run from Git Bash but the activate command does not work and the full path to the environment's Python would need to be specified to run the Python scripts, see conda/conda#747 for more details. |
First, navigate to a desired location on your file system in the terminal (Git Bash on Windows) and either clone the repository with Git [7] and change into the new directory:
$ git clone https://github.com/csu-hmc/perturbed-data-paper.git $ cd perturbed-data-paper
or download with curl, unpack the zip file, and change into the new directory:
$ curl -o perturbed-data-paper-master.zip https://github.com/csu-hmc/perturbed-data-paper/archive/master.zip $ unzip perturbed-data-paper-master.zip $ cd perturbed-data-paper-master
| [7] | Please use Git if you wish to contribute back to the repository. See CONTRIBUTING.rst for information on how to contribute. |
The only dependencies for the basic build are: LaTeX + required packages, Python + pygments, and a PDF viewer. Make sure pygments is installed in the root conda environment:
$ conda install pygments
To build the pdf from the LaTeX source using the pre-generated figures and
tables in the repository run make from the root of the repository. The
default make target will build the document, i.e.:
$ make
You can then view the document with your preferred PDF viewer. For example, Evince can be used on Linux:
$ evince paper.pdf
The full build instructions allow you to both generate the figures and tables from raw data and compile the LaTeX document.
Any command that runs Python will have to be run in the Windows command prompt on Windows. Otherwise, run the commands in the Git Bash on Windows.
The data is available for download from Zenodo. It consists of two gzipped tar balls of approximately 1.2GB each and one of 2.6MB. Create a directory to house the data, download, and unpack:
$ mkdir raw-data $ cd raw-data $ curl -o perturbed-walking-data-01.tar.gz https://zenodo.org/record/13030/files/perturbed-walking-data-01.tar.gz $ curl -o perturbed-walking-data-02.tar.gz https://zenodo.org/record/13030/files/perturbed-walking-data-02.tar.gz $ curl -o perturbation-signals.tar.gz https://zenodo.org/record/16064/files/perturbation-signals.tar.gz $ tar -zxvf perturbed-walking-data-01.tar.gz $ tar -zxvf perturbed-walking-data-02.tar.gz $ tar -zxvf perturbation-signals.tar.gz $ rm perturbed-walking-data-01.tar.gz $ rm perturbed-walking-data-02.tar.gz $ rm perturbation-signals.tar.gz $ cd ..
The above commands can also be run with the make target:
$ make download
If custom paths are needed, copy the default configuration to a file called
config.yml:
$ cp default-config.yml config.yml
and edit the new file to suit.
The plots can be generated by running the following scripts from the src
directory. The gait conda environment should be activated first.
The figures can be generated with:
$ source activate gait
(gait)$ python src/unperturbed_perturbed_comparison.py
(gait)$ matlab -nodisplay -nosplash -nodesktop -r "run('src/input_output_plot.m');exit;"
(gait)$ matlab -nodisplay -nosplash -nodesktop -r "run('src/frequency_analysis.m');exit;"
(gait)$ matlab -nodisplay -nosplash -nodesktop -r "run('src/lateral_perturbation_plot.m');exit;"
The tables can be generated with:
(gait)$ python src/subject_table.py
This can also be performed with a make target:
(gait)$ make figures (gait)$ make tables
The figures can be generated with in cmd.exe:
> activate gait
[gait] > python src/unperturbed_perturbed_comparison.py
[gait] > matlab -nodisplay -nosplash -nodesktop -r "run('src/input_output_plot.m');exit;"
[gait] > matlab -nodisplay -nosplash -nodesktop -r "run('src/frequency_analysis.m');exit;"
[gait] > matlab -nodisplay -nosplash -nodesktop -r "run('src/lateral_perturbation_plot.m');exit;"
The tables can be generated with:
[gait] > python src/subject_table.py
The figures and tables make targets will fail in the Windows command
prompt because make is only available in Git Bash.
After the figures and tables are generated, the PDF can be built as before:
$ make pdf
The entire process described above, i.e. from data download to PDF compilation, can also be run with a single make target (only Linux/Mac):
(gait)$ make pdfraw