Merge pull request #7 from corriporai/develop

ENH: Added support to columns metadata registration
CLN: Black and flake8 cleanup
DOC: Added examples with overview jupyter notebook
DOC: Updated README with QuickStart.
BLD: Fixes in docummentations makefile and requirements

docs/environment.yml

@@ -0,0 +1,18 @@
+name: runpandas_docs
+dependencies:
+- python=3.8
+- sphinx_rtd_theme
+- jinja2
+- tornado
+- nbformat
+- jupyter_client
+- ipykernel
+- sphinx
+- terminado
+- pip:
+  - nbsphinx
+  - pydata_sphinx_theme
+  - requests_cache
+  - Send2Trash
+  - prometheus_client
+  - sphinxcontrib_github_alt

docs/requirements.txt

@@ -1,3 +1,7 @@
 sphinx
+ipython
 sphinx_rtd_theme
-ipython
+requests_cache
+pydata_sphinx_theme
+nbsphinx
+sphinxcontrib_github_alt

docs/source/_version.txt

@@ -0,0 +1 @@
+Version: **0 (+untagged, 7)** Date: **November 21, 2020**

docs/source/conf.py

@@ -14,7 +14,7 @@
 # import sys
 # sys.path.insert(0, os.path.abspath('.'))
 import runpandas as rp
-import sphinx_rtd_theme
+import datetime as dt
 
 # -- Project information -----------------------------------------------------
 
@@ -32,18 +32,23 @@
     "sphinx.ext.intersphinx",
     "sphinx.ext.extlinks",
     "sphinx.ext.napoleon",
+    "sphinx.ext.autosummary",
     "sphinx.ext.todo",
     "IPython.sphinxext.ipython_directive",
     "IPython.sphinxext.ipython_console_highlighting",
+    "nbsphinx",
+    "sphinxcontrib_github_alt",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
 
-source_suffix = ".rst"
+source_suffix = [".rst", ".ipynb"]
 master_doc = "index"
 
+github_project_url = "https://github.com/corriporai/runpandas"
+
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -60,6 +65,12 @@
 # The full version, including alpha/beta/rc tags.
 release = rp.__version__
 
+# Write version and build date
+with open("_version.txt", "w") as version_file:
+    doc_date = dt.datetime.now().strftime("%B %-d, %Y")
+    version_file.write(f"Version: **{version}** Date: **{doc_date}**\n")
+
+
 language = None
 
 
@@ -78,14 +89,18 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = "sphinx_rtd_theme"
-html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
-
+html_theme = "pydata_sphinx_theme"
+html_theme_options = {
+    "external_links": [],
+    "github_url": "https://github.com/corriporai/runpandas",
+}
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
 
+html_logo = "./_static/images/runpandas_banner.png"
+
 html_sidebars = {
     "**": [
         "relations.html",  # needs 'show_related': True theme option to display
@@ -101,7 +116,13 @@
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, "runpandas.tex", "runpandas Documentation", "corriporai", "manual",)
+    (
+        master_doc,
+        "runpandas.tex",
+        "runpandas Documentation",
+        "corriporai",
+        "manual",
+    )
 ]
 
 
@@ -131,8 +152,13 @@
 
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {"http://docs.python.org/": None}
-
+intersphinx_mapping = {
+    "http://docs.python.org/": None,
+    "ipython": ("https://ipython.readthedocs.io/en/stable/", None),
+    "nbconvert": ("https://nbconvert.readthedocs.io/en/latest/", None),
+    "nbformat": ("https://nbformat.readthedocs.io/en/latest/", None),
+    "jupyter": ("https://jupyter.readthedocs.io/en/latest/", None),
+}
 
 extlinks = {
     "issue": ("https://github.com/corriporai/runpandas/issues/%s", "GH"),

docs/source/index.rst

@@ -5,12 +5,75 @@
 
 Welcome to runpandas's documentation!
 =====================================
+.. include:: _version.txt
+
+Runpandas is a python package focused on adding support for data collected by GPS-enabled tracking
+devices, heart rate monitors data to [pandas](http://pandas.pydata.org) objects.
+Its goal is to fill the gap between the tracking data collection and their manual analyses.
+
+
+.. warning::
+   The current state of the project is "early beta": features might be
+   added, removed or changed in backwards incompatible ways.
+   Report bugs, suggest features or view the source code `on GitHub`_.
+
+.. _on GitHub: https://github.com/corriporai/runpandas
 
 .. toctree::
-   :maxdepth: 2
-   :caption: Contents:
+   :hidden:
+
+   Home <self>
+
+
+Quick Start
+-----------
+
+Install using ``pip``
+
+.. code-block:: shell
 
+   pip install runpandas
 
+and then import and use one of the tracking readers. This example
+loads a local file.tcx.
+
+>>> import runpandas as rpd
+>>> activity = rpd.read('/path/to/file.tcx')
+>>> activity.head(5)
+alt	dist	hr	lon	lat   time
+00:00:00	178.942627	0.000000	62.0	-79.093187	35.951880
+00:00:01	178.942627	0.000000	62.0	-79.093184	35.951880
+00:00:06	178.942627	1.106947	62.0	-79.093172	35.951868
+00:00:12	177.500610	13.003035	62.0	-79.093228	35.951774
+00:00:16	177.500610	22.405027	60.0	-79.093141	35.951732
+
+The data frames that are returned by runpandas when
+loading files is similar for different file types.
+The dataframe in the above example is a subclass of the
+``pandas.DataFrame`` and provides some additional features.
+Certain columns also return specific ``pandas.Series`` subclasses,
+which provides useful methods:
+
+
+   >>> print (type(activity))
+   <class 'runpandas.types.frame.Activity'>
+   >>> print(type(activity.alt))
+   <class 'runpandas.types.columns.Altitude'>
+
+For instance, if you want to get the base unit for the altitude ``alt`` data or the distance ``dist`` data:
+
+   >>> activity.alt.base_unit
+   m
+   >>> activity.alt.sum()
+   65883.68151855901
+   >>> activity.dist.base_unit
+   m
+   >>> activity.dist[-1]  #moving distance
+   4686.31103516
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents:
 
 Indices and tables
 ==================

examples/overview.ipynb

@@ -0,0 +1,162 @@
+{
+ "metadata": {
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.8.3-final"
+  },
+  "orig_nbformat": 2,
+  "kernelspec": {
+   "name": "python3",
+   "display_name": "Python 3"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2,
+ "cells": [
+  {
+   "source": [
+    "#%%\n",
+    "%load_ext autoreload\n",
+    "%autoreload 2"
+   ],
+   "cell_type": "code",
+   "metadata": {},
+   "execution_count": 1,
+   "outputs": []
+  },
+  {
+   "source": [
+    "# Quick Start\n",
+    "Install using ``pip`` and then import and use one of the tracking readers. This example\n",
+    "loads a local file.tcx.\n"
+   ],
+   "cell_type": "markdown",
+   "metadata": {}
+  },
+  {
+   "source": [
+    "# !pip install runpandas\n",
+    "import runpandas as rpd\n",
+    "activity = rpd.read_file('./sample.tcx')"
+   ],
+   "cell_type": "code",
+   "metadata": {},
+   "execution_count": 27,
+   "outputs": []
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 28,
+   "metadata": {},
+   "outputs": [
+    {
+     "output_type": "execute_result",
+     "data": {
+      "text/plain": [
+       "                 alt       dist    hr        lon        lat\n",
+       "time                                                       \n",
+       "00:00:00  178.942627   0.000000  62.0 -79.093187  35.951880\n",
+       "00:00:01  178.942627   0.000000  62.0 -79.093184  35.951880\n",
+       "00:00:06  178.942627   1.106947  62.0 -79.093172  35.951868\n",
+       "00:00:12  177.500610  13.003035  62.0 -79.093228  35.951774\n",
+       "00:00:16  177.500610  22.405027  60.0 -79.093141  35.951732"
+      ],
+      "text/html": "<div>\n<style scoped>\n    .dataframe tbody tr th:only-of-type {\n        vertical-align: middle;\n    }\n\n    .dataframe tbody tr th {\n        vertical-align: top;\n    }\n\n    .dataframe thead th {\n        text-align: right;\n    }\n</style>\n<table border=\"1\" class=\"dataframe\">\n  <thead>\n    <tr style=\"text-align: right;\">\n      <th></th>\n      <th>alt</th>\n      <th>dist</th>\n      <th>hr</th>\n      <th>lon</th>\n      <th>lat</th>\n    </tr>\n    <tr>\n      <th>time</th>\n      <th></th>\n      <th></th>\n      <th></th>\n      <th></th>\n      <th></th>\n    </tr>\n  </thead>\n  <tbody>\n    <tr>\n      <th>00:00:00</th>\n      <td>178.942627</td>\n      <td>0.000000</td>\n      <td>62.0</td>\n      <td>-79.093187</td>\n      <td>35.951880</td>\n    </tr>\n    <tr>\n      <th>00:00:01</th>\n      <td>178.942627</td>\n      <td>0.000000</td>\n      <td>62.0</td>\n      <td>-79.093184</td>\n      <td>35.951880</td>\n    </tr>\n    <tr>\n      <th>00:00:06</th>\n      <td>178.942627</td>\n      <td>1.106947</td>\n      <td>62.0</td>\n      <td>-79.093172</td>\n      <td>35.951868</td>\n    </tr>\n    <tr>\n      <th>00:00:12</th>\n      <td>177.500610</td>\n      <td>13.003035</td>\n      <td>62.0</td>\n      <td>-79.093228</td>\n      <td>35.951774</td>\n    </tr>\n    <tr>\n      <th>00:00:16</th>\n      <td>177.500610</td>\n      <td>22.405027</td>\n      <td>60.0</td>\n      <td>-79.093141</td>\n      <td>35.951732</td>\n    </tr>\n  </tbody>\n</table>\n</div>"
+     },
+     "metadata": {},
+     "execution_count": 28
+    }
+   ],
+   "source": [
+    "activity.head(5)"
+   ]
+  },
+  {
+   "source": [
+    "The data frames that are returned by runpandas when\n",
+    "loading files is similar for different file types.\n",
+    "The dataframe in the above example is a subclass of the\n",
+    "``pandas.DataFrame`` and provides some additional features.\n",
+    "Certain columns also return specific ``pandas.Series`` subclasses,\n",
+    "which provides useful methods:"
+   ],
+   "cell_type": "markdown",
+   "metadata": {}
+  },
+  {
+   "source": [
+    "print (type(activity))\n",
+    "print(type(activity.alt))"
+   ],
+   "cell_type": "code",
+   "metadata": {},
+   "execution_count": 29,
+   "outputs": [
+    {
+     "output_type": "stream",
+     "name": "stdout",
+     "text": [
+      "<class 'runpandas.types.frame.Activity'>\n<class 'runpandas.types.columns.Altitude'>\n"
+     ]
+    }
+   ]
+  },
+  {
+   "source": [
+    "For instance, if you want to get the base unit for the altitude ``alt`` data or the distance ``dist`` data:"
+   ],
+   "cell_type": "markdown",
+   "metadata": {}
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 41,
+   "metadata": {},
+   "outputs": [
+    {
+     "output_type": "execute_result",
+     "data": {
+      "text/plain": [
+       "65883.68151855901"
+      ]
+     },
+     "metadata": {},
+     "execution_count": 41
+    }
+   ],
+   "source": [
+    "activity.alt.base_unit\n",
+    "activity.alt.sum()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 43,
+   "metadata": {},
+   "outputs": [
+    {
+     "output_type": "execute_result",
+     "data": {
+      "text/plain": [
+       "4686.31103516"
+      ]
+     },
+     "metadata": {},
+     "execution_count": 43
+    }
+   ],
+   "source": [
+    "activity.dist.base_unit\n",
+    "activity.dist[-1]"
+   ]
+  }
+ ]
+}