EHN compute gradients for an activity (#24)

* EHN compute gradients for an activity

* DOC update API documentation

doc/api.rst

@@ -33,6 +33,7 @@ Extraction
 
    extraction.activity_power_profile
    extraction.acceleration
+   extraction.gradient_activity
    extraction.gradient_elevation
    extraction.gradient_heart_rate
 

skcycling/extraction/__init__.py

@@ -8,13 +8,15 @@
 # License: BSD 3 clause
 
 from .gradient import acceleration
+from .gradient import gradient_activity
 from .gradient import gradient_elevation
 from .gradient import gradient_heart_rate
 
 from .power_profile import activity_power_profile
 
 
 __all__ = ['acceleration',
+           'gradient_activity',
            'gradient_elevation',
            'gradient_heart_rate',
            'activity_power_profile']

skcycling/extraction/gradient.py

@@ -6,6 +6,10 @@
 
 from __future__ import division
 
+from collections import Iterable
+
+import pandas as pd
+
 from ..exceptions import MissingDataError
 
 
@@ -119,3 +123,48 @@ def gradient_heart_rate(activity, periods=5, append=True):
         return activity
     else:
         return gradient_heart_rate
+
+
+def gradient_activity(activity, periods=1, append=True, columns=None):
+    """Compute the gradient for all given columns.
+
+    Parameters
+    ----------
+    activity : DataFrame
+        The activity to use to compute the gradient.
+
+    periods : int or array-like, default=1
+        Periods to shift to compute the gradient. If an array-like is given,
+        several gradient will be computed.
+
+    append : bool, optional
+        Whether to append the gradients to the original activity.
+
+    columns : list, optional
+        The name of the columns to use to compute the gradient. By default, all
+        the columns are used.
+
+    Returns
+    -------
+    gradient : DataFrame
+        The computed gradient from the activity.
+
+    """
+    if columns is not None:
+        data = activity[columns]
+    else:
+        data = activity
+
+    if isinstance(periods, Iterable):
+        gradient = [data.diff(periods=p) for p in periods]
+        gradient_name = ['gradient_{}'.format(p) for p in periods]
+    else:
+        gradient = [data.diff(periods=periods)]
+        gradient_name = ['gradient_{}'.format(periods)]
+
+    if append:
+        # prepend the original information
+        gradient = [activity] + gradient
+        gradient_name = ['original'] + gradient_name
+
+    return pd.concat(gradient, axis=1, keys=gradient_name)

skcycling/extraction/tests/test_gradients.py → skcycling/extraction/tests/test_gradient.py

@@ -10,6 +10,7 @@
 import pytest
 
 from skcycling.extraction import acceleration
+from skcycling.extraction import gradient_activity
 from skcycling.extraction import gradient_elevation
 from skcycling.extraction import gradient_heart_rate
 from skcycling.exceptions import MissingDataError
@@ -72,3 +73,29 @@ def test_gradient_heart_rate(activity, append, type_output, shape):
     output = gradient_heart_rate(activity, append=append)
     assert isinstance(output, type_output)
     assert output.shape == shape
+
+
+@pytest.mark.parametrize(
+    "activity, periods, append, columns, shape",
+    [(pd.DataFrame({'elevation': np.random.random(100),
+                    'distance': np.random.random(100)}),
+      1, True, None, (100, 4)),
+     (pd.DataFrame({'elevation': np.random.random(100),
+                    'distance': np.random.random(100)}),
+      1, False, None, (100, 2)),
+     (pd.DataFrame({'elevation': np.random.random(100),
+                    'distance': np.random.random(100)}),
+      1, False, ['elevation'], (100, 1)),
+     (pd.DataFrame({'elevation': np.random.random(100),
+                    'distance': np.random.random(100)}),
+      [1, 2], True, None, (100, 6)),
+     (pd.DataFrame({'elevation': np.random.random(100),
+                    'distance': np.random.random(100)}),
+      [1, 2], False, None, (100, 4)),
+     (pd.DataFrame({'elevation': np.random.random(100),
+                    'distance': np.random.random(100)}),
+      [1, 2], True, ['elevation'], (100, 4))])
+def test_gradient_activity(activity, periods, append, columns, shape):
+    output = gradient_activity(activity, periods=periods, append=append,
+                               columns=columns)
+    assert output.shape == shape