From cc7f3bd4b3ce11bbcb61da1b783dc2795f5a437f Mon Sep 17 00:00:00 2001 From: Marc Weitz Date: Fri, 2 Feb 2024 11:20:32 +0100 Subject: [PATCH] updates documentation (#21) * updates documentation * updates poetry version for actions --- .github/workflows/python-test.yml | 2 +- .gitignore | 1 + docs/source/background.rst | 7 ++++ docs/source/{about.rst => credits.rst} | 4 +- docs/source/examples.rst | 4 +- docs/source/index.rst | 57 +++++++++++++++++++++++++- docs/source/paat.rst | 4 +- pyproject.toml | 38 ++++++++--------- 8 files changed, 89 insertions(+), 28 deletions(-) create mode 100644 docs/source/background.rst rename docs/source/{about.rst => credits.rst} (97%) diff --git a/.github/workflows/python-test.yml b/.github/workflows/python-test.yml index 08db7b0..ef7ed45 100644 --- a/.github/workflows/python-test.yml +++ b/.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: diff --git a/.gitignore b/.gitignore index 6c01de5..e646466 100644 --- a/.gitignore +++ b/.gitignore @@ -11,6 +11,7 @@ tests/__pycache__ # Documentation docs/build/ docs/source/_static/copybutton.js +source/ .ipynb_checkpoints/ diff --git a/docs/source/background.rst b/docs/source/background.rst new file mode 100644 index 0000000..403e725 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/docs/source/about.rst b/docs/source/credits.rst similarity index 97% rename from docs/source/about.rst rename to docs/source/credits.rst index b2757f6..d4083ba 100644 --- a/docs/source/about.rst +++ b/docs/source/credits.rst @@ -1,5 +1,5 @@ -About -===== +Credits +======= Authors ------- diff --git a/docs/source/examples.rst b/docs/source/examples.rst index cd81ef4..3fadbf4 100644 --- a/docs/source/examples.rst +++ b/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 diff --git a/docs/source/index.rst b/docs/source/index.rst index f8265bf..fa91657 100644 --- a/docs/source/index.rst +++ b/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) `_ + and `Weitz et al. (2022) `_ and activity + thresholds of `Sanders et al. (2019) `_. + 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. diff --git a/docs/source/paat.rst b/docs/source/paat.rst index 8a31e94..882d0fe 100644 --- a/docs/source/paat.rst +++ b/docs/source/paat.rst @@ -1,5 +1,5 @@ -Package overview -================ +API Documentation +================= .. automodule:: paat diff --git a/pyproject.toml b/pyproject.toml index 42b5212..709fea5 100644 --- a/pyproject.toml +++ b/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]