updates documentation (#21)

* updates documentation

* updates poetry version for actions

.github/workflows/python-test.yml

@@ -19,7 +19,7 @@ jobs:
           macOS-latest
           ]
         python-version: ['3.9', '3.10']
-        poetry-version: [1.1.13]
+        poetry-version: [1.7.1]
       fail-fast: false
     runs-on: ${{ matrix.os }}
     steps:

.gitignore

@@ -11,6 +11,7 @@ tests/__pycache__
 # Documentation
 docs/build/
 docs/source/_static/copybutton.js
+source/
 
 .ipynb_checkpoints/
 

docs/source/background.rst

@@ -0,0 +1,7 @@
+Background 
+==========
+
+
+.. warning::
+
+    This page is currently under construction. Soon you find useful background info here as well as links to relevant papers.

docs/source/about.rst → docs/source/credits.rst

@@ -1,5 +1,5 @@
-About
-=====
+Credits
+=======
 
 Authors
 -------

docs/source/examples.rst

@@ -1,5 +1,5 @@
-Examples
-========
+Usage Examples
+==============
 
 To ease working with PAAT and to make you able to analyze your GT3X files as soon
 as possible, we made a collection of code snippets and jupyter notebooks. Feel

docs/source/index.rst

@@ -4,10 +4,63 @@
 
 .. toctree::
    :maxdepth: 2
+   :hidden:
    :caption: Contents
 
-   quickstart
+   background
    examples
    paat
    development
-   about
+   credits
+
+
+Quickstart
+----------
+
+Installation
+~~~~~~~~~~~~
+
+At the moment, the easiest way to install *paat* directly from GitHub by running:
+
+.. code:: bash
+
+    pip install git+https://github.com/Trybnetic/paat.git
+
+
+Usage
+~~~~~
+
+For now, several functions to work with raw data from ActiGraph devices are
+implemented while others are still work in progress. The following code snippet
+should give you a brief overview and idea on how to use this package. Further
+examples and more information on the functions can be found in the documentation.
+
+.. code-block:: python
+
+    # Load data from file
+    data, sample_freq = paat.read_gt3x('path/to/gt3x/file')
+
+    # Detect non-wear time
+    data.loc[:, "Non Wear Time"] = paat.detect_non_wear_time_syed2021(data, sample_freq)
+
+    # Detect sleep episodes
+    data.loc[:, "Sleep"] = paat.detect_sleep_weitz2022(data, sample_freq)
+
+    # Classify moderate-to-vigorous and sedentary behavior
+    data.loc[:, ["MVPA", "SB"]] = paat.calculate_pa_levels(data, sample_freq)
+
+    # Merge the activity columns into one labelled column. columns indicates the
+    # importance of the columns, later names are more important and will be kept
+    data.loc[:, "Activity"] = paat.create_activity_column(data, columns=["SB", "MVPA", "Sleep", "Non Wear Time"])
+
+    # Remove the other columns after merging
+    data =  data[["X", "Y", "Z", "Activity"]]
+
+.. note::
+
+    In this example, methods of `Syed et al. (2021) <https://doi.org/10.1038/s41598-021-87757-z>`_
+    and `Weitz et al. (2022) <https://www.medrxiv.org/content/10.1101/2022.03.07.22270992>`_ and activity
+    thresholds of `Sanders et al. (2019) <https://doi.org/10.1080/02640414.2018.1555904>`_.
+    However, these are only examples. There are multiple methods implemented in PAAT
+    and the processing pipeline can easily be adjusted to individual needs. More examples
+    can be found in the examples section.

docs/source/paat.rst

@@ -1,5 +1,5 @@
-Package overview
-================
+API Documentation
+=================
 
 .. automodule:: paat
 

pyproject.toml

@@ -42,26 +42,26 @@ agcounts = "^0.1.1"
 toml = "^0.10.2"
 tables = "^3.7.0"
 
-
-[tool.poetry.dev-dependencies]
-pytest = "^7.0"
-pytest-cov = "^2.4"
-pydocstyle = "^6.1.1"
-flake8 = "^4.0.1"
-sphinx = "^1.4"
-sphinx_rtd_theme = "1.0.0"
-notebook = "^6.4.10"
-seaborn = "^0.11.2"
-numpydoc = "1.2"
-easydev = "0.9.35"
-pylint = "^2.0.0"
-nbsphinx = "0.8.8"
-vulture = "^2.3"
-pygt3x = "^0.1.1"
-
 [tool.poetry.extras]
-docs = ["sphinx", "sphinx_rtd_theme", "numpydoc", "easydev", "nbsphinx"]
-
+docs = ["sphinx", "sphinx_rtd_theme", "numpydoc", "easydev", "nbsphinx", "docutils"]
+
+
+[tool.poetry.group.dev.dependencies]
+sphinx = "^7.2.6"
+sphinx-rtd-theme = "^2.0.0"
+pytest = "^8.0.0"
+pytest-cov = "^4.1.0"
+pycodestyle = "^2.11.1"
+flake8 = "^7.0.0"
+notebook = "^7.0.7"
+seaborn = "^0.13.2"
+numpydoc = "^1.6.0"
+easydev = "^0.12.1"
+pylint = "^3.0.3"
+nbsphinx = "^0.9.3"
+vulture = "^2.11"
+pygt3x = "^0.5.2"
+jinja2 = "<3.1.0"
 
 [tool.pylint]
   [tool.pylint.basic]