Merge pull request #36 from corriporai/develop

DOC: Updates on docs and code docs for release 0.3

CHANGELOG.rst

@@ -6,4 +6,5 @@ The list of changes to RunPandas between each release can be found below.
 For full details see the commit logs at https://github.com/corriporai/runpandas.
 
 .. include:: docs/source/whatsnew/v0.1.0.txt
-.. include:: docs/source/whatsnew/v0.2.0.txt
+.. include:: docs/source/whatsnew/v0.2.0.txt
+.. include:: docs/source/whatsnew/v0.3.0.txt

README.rst

@@ -247,9 +247,122 @@ data or the distance ``dist`` data:
     4686.31103516
 
 
-Let’s play with the data. Let’s show distance vs as an example of what
-and how we can create visualizations. In this example, we will use the
-built in, matplotlib based plot function.
+The ``Activity`` dataframe also contains special properties that
+presents some statistics from the workout such as elapsed time, the
+moving time and the distance of workout in meters.
+
+.. code:: ipython3
+
+    #total time elapsed for the activity
+    print(activity.ellapsed_time)
+    #distance of workout in meters
+    print(activity.distance)
+
+
+.. parsed-literal::
+
+    0 days 00:33:11
+    4686.31103516
+
+
+Occasionally, some observations such as speed, distance and others must
+be calculated based on available data in the given activity. In
+runpandas there are special accessors (``runpandas.acessors``) that
+computes some of these metrics. We will compute the ``speed`` and the
+``distance per position`` observations using the latitude and longitude
+for each record and calculate the haversine distance in meters and the
+speed in meters per second.
+
+.. code:: ipython3
+
+    #compute the distance using haversine formula between two consecutive latitude, longitudes observations.
+    activity['distpos']  = activity.compute.distance()
+    activity['distpos'].head()
+
+
+
+
+.. parsed-literal::
+
+    time
+    00:00:00          NaN
+    00:00:01     0.333146
+    00:00:06     1.678792
+    00:00:12    11.639901
+    00:00:16     9.183847
+    Name: distpos, dtype: float64
+
+
+
+.. code:: ipython3
+
+    #compute the distance using haversine formula between two consecutive latitude, longitudes observations.
+    activity['speed']  = activity.compute.speed(from_distances=True)
+    activity['speed'].head()
+
+
+
+
+.. parsed-literal::
+
+    time
+    00:00:00         NaN
+    00:00:01    0.333146
+    00:00:06    0.335758
+    00:00:12    1.939984
+    00:00:16    2.295962
+    Name: speed, dtype: float64
+
+
+
+Sporadically, there will be a large time difference between consecutive
+observations in the same workout. This can happen when device is paused
+by the athlete or therere proprietary algorithms controlling the
+operating sampling rate of the device which can auto-pause when the
+device detects no significant change in position. In runpandas there is
+an algorithm that will attempt to calculate the moving time based on the
+GPS locations, distances, and speed of the activity.
+
+To compute the moving time, there is a special acessor that detects the
+periods of inactivity and returns the ``moving`` series containing all
+the observations considered to be stopped.
+
+.. code:: ipython3
+
+    activity_only_moving = activity.only_moving()
+    print(activity_only_moving['moving'].head())
+
+
+.. parsed-literal::
+
+    time
+    00:00:00    False
+    00:00:01    False
+    00:00:06    False
+    00:00:12     True
+    00:00:16     True
+    Name: moving, dtype: bool
+
+
+Now we can compute the moving time, the time of how long the user were
+active.
+
+.. code:: ipython3
+
+    activity_only_moving.moving_time
+
+
+
+
+.. parsed-literal::
+
+    Timedelta('0 days 00:33:05')
+
+
+
+Now, let’s play with the data. Let’s show distance vs as an example of
+what and how we can create visualizations. In this example, we will use
+the built in, matplotlib based plot function.
 
 .. code:: ipython3
 

docs/source/_version.txt

@@ -1 +1 @@
-Version: **0.2.0** Date: **January 12, 2021**
+Version: **0.2.0 (+18, 23d03a8)** Date: **March 13, 2021**

docs/source/conf.py

@@ -45,7 +45,7 @@
 
 
 source_parsers = {
-    '.md': 'recommonmark.parser.CommonMarkParser',
+    ".md": "recommonmark.parser.CommonMarkParser",
 }
 
 source_suffix = [".rst", ".md", ".ipynb"]
@@ -75,7 +75,7 @@
     version_file.write(f"Version: **{version}** Date: **{doc_date}**\n")
 
 # Default language for syntax highlighting in reST and Markdown cells:
-highlight_language = 'none'
+highlight_language = "none"
 
 language = None
 
@@ -90,7 +90,7 @@
 todo_include_todos = True
 
 # Don't add .txt suffix to source files:
-html_sourcelink_suffix = ''
+html_sourcelink_suffix = ""
 
 # -- Options for HTML output -------------------------------------------------
 
@@ -117,6 +117,7 @@
 html_logo = "./_static/images/runpandas_banner.png"
 html_favicon = "./_static/images/favicon.ico"
 
+
 def setup(app):
     app.add_css_file("custom.css")  # may also be an URL
 
@@ -158,7 +159,6 @@ def setup(app):
 """
 
 
-
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).

docs/source/getting_started.rst

@@ -31,6 +31,7 @@ RunPandas depends on the following packages:
 - ``pandas``
 - ``fitparse``
 - ``stravalib``
+- ``haversine``
 
 ^^^^^^^^^^^^^^^^^^^^^
 Detailed instructions
@@ -45,7 +46,7 @@ What now
 
 - If you don’t have Runpandas yet, check :doc:`Installation <getting_started/install>`.
 
-- If you have never used RunPandas and want to get familiar with it and its core functionality quickly, see our Runpandas book.
+- If you have never used RunPandas and want to get familiar with it and its core functionality quickly, see our `Runpandas book <https://corriporai.github.io/runpandasbook/intro.html>`_.
 
 - Detailed instructions about how to work with Runpandas, how to read files or perform activity analysis are part of our :doc:`User Guide <user_guide/user_guide>`.
 

docs/source/reference/acessors.rst

@@ -0,0 +1,25 @@
+========
+Acessors
+========
+.. currentmodule:: runpandas.types.acessors
+
+
+Special acessors to perform activity transformations or derived observations based on activity data.
+
+Moving
+------
+
+.. autosummary::
+   :toctree: api/
+
+   moving._InactivityAssessor
+
+Metrics
+-------
+
+.. autosummary::
+   :toctree: api/
+
+   metrics.MetricsAcessor
+   metrics.MetricsAcessor.speed
+   metrics.MetricsAcessor.distance

docs/source/reference/api/runpandas.types.Activity.distance.rst

@@ -0,0 +1,6 @@
+runpandas.types.Activity.distance
+=================================
+
+.. currentmodule:: runpandas.types
+
+.. autoproperty:: Activity.distance

docs/source/reference/api/runpandas.types.Activity.ellapsed_time.rst

@@ -0,0 +1,6 @@
+runpandas.types.Activity.ellapsed\_time
+=======================================
+
+.. currentmodule:: runpandas.types
+
+.. autoproperty:: Activity.ellapsed_time

docs/source/reference/api/runpandas.types.Activity.from_file.rst

@@ -0,0 +1,6 @@
+runpandas.types.Activity.from\_file
+===================================
+
+.. currentmodule:: runpandas.types
+
+.. automethod:: Activity.from_file

docs/source/reference/api/runpandas.types.Activity.moving_time.rst

@@ -0,0 +1,6 @@
+runpandas.types.Activity.moving\_time
+=====================================
+
+.. currentmodule:: runpandas.types
+
+.. autoproperty:: Activity.moving_time