Skip to content

Commit

Permalink
Improved instructions. Fixes #84, #88, #89, #90, #95
Browse files Browse the repository at this point in the history 
- Added better Windows information.
- Added explicit install instructions for LaTeX, Python, Octave, etc.
- Added citation information.
  • Loading branch information
@moorepants
moorepants committed Jan 13, 2015
1 parent 3e538bc commit 723a4de
Showing 1 changed file with 190 additions and 74 deletions.
264 changes: 190 additions & 74 deletions README.rst
View file
Expand Up @@ -3,15 +3,96 @@ Introduction

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", 2014.
Moore, J.K., Hnat, S.K, van den Bogert, A. "An elaborate data set on human
gait and the effect of mechanical perturbations", 2014.

The latest rendered version of the PDF can be viewed via the ShareLaTeX CI
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:

.. image:: https://www.sharelatex.com/github/repos/csu-hmc/perturbed-data-paper/builds/latest/badge.svg
:target: https://www.sharelatex.com/github/repos/csu-hmc/perturbed-data-paper/builds/latest/output.pdf

.. _ShareLaTeX: http://sharelatex.com

The preprint can be obtained from the PeerJ preprint server:

http://peerj.com/preprints/700

License and Citation
====================

The contents of this repository is licensed under the `Creative Commons
Attribution 4.0 International License`_.

.. image:: https://i.creativecommons.org/l/by/4.0/80x15.png
:target: http://creativecommons.org/licenses/by/4.0

.. _Creative Commons Attribution 4.0 International License: http://creativecommons.org/licenses/by/4.0

If you make use of our work we ask that you cite us. The following are some
BibTeX formatted references that may be useful.

Data
----

::

@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}}

Software
--------

::

@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}}

Preprint
--------

Note that this citation will always be one version behind because the preprint
is published after this repository is pinned to a version. Visit the DOI for
the most up-to-date citation.

::

@article{10.7287/peerj.preprints.700v2,
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 = {e700v2},
journal = {PeerJ PrePrints},
issn = {2167-9843},
url = {http://dx.doi.org/10.7287/peerj.preprints.700v2},
doi = {10.7287/peerj.preprints.700v2}
}

Data
====

Expand All @@ -24,124 +105,156 @@ Creative Commons CC0 license.
Software
========

The software used for the analysis is availabe in the ``src`` directory and as
as an open source Python package developed for this paper. The snapshot of the
GaitAnalysisToolKit_ is available via Zenodo and PyPi:

.. image:: https://zenodo.org/badge/doi/10.5281/zenodo.13159.svg
:target: http://dx.doi.org/10.5281/zenodo.13159

.. image:: https://pypip.in/version/GaitAnalysisToolKit/badge.svg
:target: https://pypi.python.org/pypi/GaitAnalysisToolKit/
:alt: Latest Version
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:

.. _DynamicistToolKit: http://github.com/moorepants/DynamicistToolKit
.. _GaitAnalysisToolKit: http://github.com/csu-hmc/GaitAnalysisToolKit

License
=======

This repository is licensed under the `Creative Commons Attribution 4.0
International License`_.

.. image:: https://i.creativecommons.org/l/by/4.0/80x15.png
:target: http://creativecommons.org/licenses/by/4.0

.. _Creative Commons Attribution 4.0 International License: http://creativecommons.org/licenses/by/4.0
Be sure to read the installation instructions for the two packages.

DynamicistToolKit
.. image:: https://zenodo.org/badge/doi/10.5281/zenodo.13253.svg
:target: http://dx.doi.org/10.5281/zenodo.13253

.. image:: https://pypip.in/version/DynamicistToolKit/badge.svg
:target: https://pypi.python.org/pypi/DynamicistToolKit/
:alt: Latest Version
GaitAnalysisToolKit
.. image:: https://zenodo.org/badge/doi/10.5281/zenodo.13159.svg
:target: http://dx.doi.org/10.5281/zenodo.13159

.. image:: https://pypip.in/version/GaitAnalysisToolKit/badge.svg
:target: https://pypi.python.org/pypi/GaitAnalysisToolKit/
:alt: Latest Version

Furthermore, 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 [#]_: cd, bash, gzip, make, mkdir, rm, tar, unzip, 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.0, DynamicistToolKit 0.3.5, GaitAnalysisToolKit 0.1.2
- Octave_ >= 3.6.4
- A LaTeX distribution which includes pdflatex. For example: MikTeX_ [Win],
`TeX Live`_ [Linux], MacTeX_ [Mac].
- Various LaTeX Packages [#]_: 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)

.. [#] 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.
.. [#] 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.
Notes on editing the files
==========================

- Wrap text files to 79 characters.
- No tabs, use 2 spaces for indentation in LaTeX, 3 in RestructuredText, and 4
in Python and Octave.
- Please edit in new Git branch and submit a Pull Request since we have
multiple authors.
- The README is in RestructuredText format. See
http://docutils.sourceforge.net/docs/user/rst/quickref.html for tips on the
syntax.
- Figures belong in the ``figures`` directory, tables in the ``tables``
directory and the source code used to generate them should be in the ``src``
directory along with any instructions in ``README.rst``.The figures should be
correctly sized plots in the PDF format. The generated figures and tables can
be committed to the Git repo so that the ShareLatex CI builds. Be careful
about uploading (lots) of giant binaries. Do not add data to the Git repo,
use a data hosting repository.
.. _Anaconda Python Distribution: http://continuum.io/downloads
.. _Octave: http://octave.org
.. _MikTeX: http://miktex.org
.. _TeX Live: https://www.tug.org/texlive
.. _MacTeX: https://tug.org/mactex
.. _minted: https://github.com/gpoore/minted
.. _Git: http://git-scm.com

Get the source
==============

Either clone the repository with Git::
First, navigate to a desired location on your file system and either clone the
repository with Git [#]_ and change into the new directory::

$ git clone https://github.com/csu-hmc/perturbed-data-paper.git
$ cd perturbed-data-paper

Or download and unpack the zip file::
or download with wget, unpack the zip file, and change into the new directory::

$ wget https://github.com/csu-hmc/perturbed-data-paper/archive/master.zip
$ unzip master.zip
$ unzip perturbed-data-paper-master.zip
$ cd perturbed-data-paper-master

Change into the source directory::

$ cd perturbed-data-paper
.. [#] Please use Git if you wish to contribute back to the repository. See
CONTRIBUTING.rst for information on how to contribute.
Basic LaTeX Build Instructions
==============================

To build the pdf from the latex source using the pregenerated figures and
tables in the repository, make sure you have an up-to-date latex suite
installed [1]_, download the source, and run ``make``.

.. [1] The minted package requires Python and the Pygments packaged. See the
minted documentation for installation details or installation instructions
for building from the raw data.
The default ``make`` target will build the document::
To build the pdf from the LaTeX source using the pre-generated figures and
tables in the repository, make sure you have an up-to-date LaTeX distribution
installed and run ``make`` from within the repository. The default ``make``
target will build the document, i.e.::

$ make

View with your preferred PDF viewer::
You can then view the document with your preferred PDF viewer. For example,
Evince can be used::

$ evince paper.pdf

Full build instructions
=======================

The full build instructions allow you to generate the figures and tables from
raw data and compile the LaTeX document.
The full build instructions allow you to both generate the figures and tables
from raw data and compile the LaTeX document.

These commands should work as is on Unix based systems (Linux, Mac, etc).
Windows users should install Cygwin, MinGW, or each Unix tool separately to
make use of those commands. If Cygwin or MinGW is used, the Unix tools will
have to be executed in their respective terminal applications. All other
commands will need to be executed in the Windows CMD prompt.

Install dependencies
--------------------

In addition to the basic LaTeX dependency install the following Octave and
Python software.
In addition to the LaTeX dependencies described above, install the following
Octave and Python software.

Install Octave_ (>=3.8) from your system package manager or other binary
method, for example on Debian based Linux systems::
Install Octave from your system package manager or other binary method, for
example on Debian based Linux systems::

$ sudo apt-get install octave

.. _Octave: http://www.octave.org

Install the `Anaconda Python Distribution`_, following the instructions on the
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.sh

.. _Anaconda Python Distribution: http://continuum.io/downloads
$ bash Anaconda-2.1.0-Linux-x86_64.sh

Now create and activate a Conda environment with the main Python dependencies::
Now create and activate a Conda [#]_ 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

Finally, install the remaining dependencies with pip::
.. [#] Conda is a lightweight package manager that is used to download the
exact versions of software into an isolated user installed environment.
On Windows, the last command does not need to be prepended with ``source``::

$ activate gait

Finally, install the remaining dependencies with pip [#]_ which grabs the
correct versions from the `Python Package Index`_ (PyPi)::

(gait)$ pip install oct2py==2.4.0
(gait)$ pip install DynamicistToolKit==0.3.5
(gait)$ pip install GaitAnalysisToolKit==0.1.2

.. [#] 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.
.. _Python Package Index: https://pypi.python.org/pypi

Get the data
------------

Expand All @@ -166,7 +279,7 @@ The above commands can also be run with the make target::
Configuration file
------------------

Copy the default configuration file to a file called ``config.yml``::
Copy the default configuration to a file called ``config.yml``::

(gait)$ cp default-config.yml config.yml

Expand Down Expand Up @@ -198,7 +311,10 @@ Build the pdf

(gait)$ make pdf

The entire process from data download to pdf compilation can be run with a
single make target::
Complete Build
--------------

The entire process described above, i.e from data download to pdf compilation,
can also be run with a single make target::

(gait)$ make pdfraw

0 comments on commit 723a4de

Please sign in to comment.