activityio 0.0.3
Exercise data handling library
License: MIT
Keywords: exercise cycling running garmin data

==========================================
activityio: Exercise data handling library
==========================================

Exercise/activity data has become a prolific resource, but applying any kind of sophisticated analyses is made difficult by the variety of file formats. This ``python`` library is intended to munge a number of these formats and present the data in a predictable and useable form. Moreover, the API is both closely intertwined with, and an extension of, the awesome `Pandas library <https://github.com/pandas-dev/pandas>`_.

Stability
---------
Please note this package is still very much an *alpha* release, so **breaking changes** are likely.

Installation
------------

The package is available on PyPI::

	$ pip install activityio


Example Usage
-------------

There is a ``read`` function at the top-level of ``activityio`` that dispatches the appropriate reader based on file extension:

>>> import activityio as aio
>>> data = aio.read('example.srm')

**NOTE** substitute ``'example.srm'`` with a path to your own activity file.

But you can also call sub-packages directly:

>>> from activityio import srm
>>> data = srm.read('example.srm')

``data`` in the above example is a subclass of the ``pandas.DataFrame`` and provides some neat additional functionality. Most notably, certain columns are "magic" in that they return specific ``pandas.Series`` subclasses. These subclasses make unit-switching easy, and provide other useful methods:

>>> type(data)
<class 'activityio._types.activitydata.ActivityData'>

>>> data.head(5)
          temp  lap   dist  alt  cad  pwr  speed  hr
time
00:00:00  26.1    1  1.027   67    0    0  1.027  71
00:00:01  26.1    1  2.721   67    0    0  1.694  71
00:00:02  26.2    1  4.415   67    0    0  1.694  71
00:00:03  26.2    1  6.331   67    0    0  1.916  71
00:00:04  26.2    1  8.469   67    0    0  2.138  75

>>> data.normpwr()
249.54104255943844

>>> type(data.speed)
<class 'activityio._types.columns.Speed'>

>>> data.speed.base_unit
'm/s'
>>> data.speed.kph.mean()  # use a different unit
38.485063801685477

>>> data.dist.base_unit
'm'
>>> data.dist.miles[-1]
134.78580023361226

>>> data.alt.base_unit
'm'
>>> data.alt.ascent.sum()
1898.0
```

But **NOTE** you lose this functionality if you go changing column names

>>> data = data.rename(columns={'alt': 'altitude'})
>>> type(data.altitude)
<class 'pandas.core.series.Series'>

API Notes
---------

The main package is composed of sub-packages that contain the reading logic for the file format after which they're named. (e.g. ``activityio.fit`` is for parsing ANT/Garmin FIT files.)

The ultimate logic is defined in a ``_reading`` module, which provides two functions: ``gen_records`` and ``read_and_format``.

+ ``gen_records`` is a generator function for iterating over the data-points in a file. The rows of the data table if you like. A "record" is a dictionary object.
+ ``read_and_format`` uses the above generator to return an ``ActivityData`` object.

``read_and_format`` is available at the top-level of a sub-package aliased as ``read``; so reading in a file looks like ``srm.read('path_to_file.srm')``. ``gen_records`` is imported under the same name.

There are also some useful ``tools`` provided in module by the same name.