updated docs, fixed rtd, improved test cov

.flake8

@@ -0,0 +1,7 @@
+[flake8]
+exclude =
+    docs
+    examples/compute_*.py
+per-file-ignores =
+    __init__.py: F401,
+    *.py: E203, E741

.readthedocs.yaml

@@ -9,7 +9,7 @@ version: 2
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.10"
+    python: "3.11"
 
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
@@ -20,6 +20,6 @@ sphinx:
 # Optionally declare the Python requirements required to build your docs
 python:
    install:
-   - method: setuptools
+   - method: pip
      path: .
    - requirements: requirements_rtd.txt

docs/source/_static/css/custom.css

@@ -0,0 +1,7 @@
+div {
+    text-align: justify;
+}
+
+ul {
+    text-align: left
+}

docs/source/conf.py

@@ -31,12 +31,12 @@
     "sphinx.ext.linkcode",
     "sphinx.ext.intersphinx",
     "numpydoc",
-    "nbsphinx",
-    "nbsphinx_link",
     "sphinxcontrib.bibtex",
     "sphinx_gallery.gen_gallery",
 ]
 
+source_suffix = [".rst", ".md"]
+
 bibtex_bibfiles = ["refs.bib"]
 
 sphinx_gallery_conf = {
@@ -45,7 +45,7 @@
 }
 
 templates_path = ["_templates"]
-exclude_patterns = []
+exclude_patterns = ["_build"]
 
 
 # -- Options for HTML output -------------------------------------------------
@@ -54,6 +54,10 @@
 html_theme = "pydata_sphinx_theme"
 html_static_path = ["_static"]
 
+html_css_files = [
+    "css/custom.css",
+]
+
 html_theme_options = {
     "icon_links": [
         dict(

docs/source/development.rst

@@ -14,14 +14,12 @@ If you want to make changes to PyPARRM, you may wish to install it in editable
 mode. To do so, first clone the `GitHub repository
 <https://github.com/neuromodulation/pyparrm/tree/main>`_ to your desired
 location. Once cloned, navigate to this location and install the package
-alongside its `development requirements
-<https://github.com/neuromodulation/pyparrm/tree/main/requirements_dev.txt>`_
-using pip:
+alongside its development requirements using pip:
 
 .. code-block:: console
     
     $ pip install -e .
-    $ pip install -r requirements_dev.txt
+    $ pip install pybispectra[dev]
 
 
 Contributing to PyPARRM
@@ -36,12 +34,12 @@ the package, consider submitting a `pull request
 <https://github.com/neuromodulation/pyparrm/pulls>`_. When submitting a pull
 request, please check that the existing test suite passes, and if you add new
 features, please make sure that these are covered in the unit tests. The tests
-can be run by navigating to the ``/tests`` directory and calling `pytest
-<https://docs.pytest.org/en/7.3.x/>`_:
+can be run by calling `coverage <https://coverage.readthedocs.io/en/>`_ with
+`pytest <https://docs.pytest.org/en/>`_ in the base directory:
 
 .. code-block:: console
     
-    $ pytest test_parrm.py
+    $ coverage run --source=pyparrm -m pytest -v tests && coverage report -m
 
 Please also check that the documentation can be built following any changes,
 which can be done using `Sphinx <https://www.sphinx-doc.org/en/master/>`_ in
@@ -58,6 +56,6 @@ check that there are no egregious errors from the following commands:
 
 .. code-block:: console
     
-    $ pycodestyle
+    $ flake8
     $ pydocstyle
     $ codespell

docs/source/examples.rst

@@ -1,6 +1,8 @@
 Examples
 ========
 
+Find out how to get started with the package using the provided examples:
+
 .. toctree::
    :maxdepth: 1
    :caption: Contents:

docs/source/index.rst

@@ -1,5 +1,10 @@
 .. title:: Home
 
+.. define new line for html
+.. |br| raw:: html
+
+   <br />
+
 =======
 PyPARRM
 =======

docs/source/installation.rst

@@ -8,7 +8,7 @@ package, then install it using pip:
     
     $ pip install pyparrm
 
-PyPARRM requires Python :math:`\ge` 3.10. Other requirements are listed `here
+PyPARRM requires Python >= 3.10. Other requirements are listed `here
 <_static/requirements.txt>`_.
 
 If you need to create an environment in which to install PyPARRM, you can do so

examples/plot_example_dbs_data.py

@@ -18,7 +18,8 @@
 import numpy as np
 from matplotlib import pyplot as plt
 
-from pyparrm import PARRM
+from pyparrm import get_example_data_paths, PARRM
+from pyparrm._utils._power import compute_psd
 
 ###############################################################################
 # Background
@@ -41,7 +42,7 @@
 
 # %%
 
-data_ecog_lfp = np.load("ecog_lfp_data.npy")
+data_ecog_lfp = np.load(get_example_data_paths("ecog_lfp_data"))
 
 sampling_freq = 1000  # Hz
 artefact_freq = 130  # Hz
@@ -136,8 +137,6 @@
 inset_start_idx = 30 * sampling_freq
 inset_end_idx = int(30.5 * sampling_freq)
 
-from pyparrm._utils._power import compute_psd
-
 n_freqs = sampling_freq / 2
 psd_freqs, psd_unfiltered = compute_psd(
     data_ecog_lfp, sampling_freq, int(n_freqs * 2)

examples/plot_use_param_explorer.py

@@ -92,7 +92,7 @@
 # below shows the different aspects of the parameter explorer window.
 
 ###############################################################################
-# .. figure:: ../../_static/param_explorer.png
+# .. figure:: ../_static/param_explorer.png
 #    :alt: parameter explorer window overview
 #
 #    An overview of the parameter explorer window features

examples/plot_use_parrm.py

@@ -16,7 +16,8 @@
 import numpy as np
 from matplotlib import pyplot as plt
 
-from pyparrm import PARRM
+from pyparrm import get_example_data_paths, PARRM
+from pyparrm._utils._power import compute_psd
 
 ###############################################################################
 # Background
@@ -41,7 +42,7 @@
 
 # %%
 
-data = np.load("example_data.npy")
+data = np.load(get_example_data_paths("example_data"))
 sampling_freq = 200  # Hz
 artefact_freq = 150  # Hz
 
@@ -166,7 +167,7 @@
 # %%
 
 # comparison to true artefact-free data
-artefact_free = np.load("example_data_artefact_free.npy")
+artefact_free = np.load(get_example_data_paths("example_data_artefact_free"))
 start = 598  # same start time as MATLAB example
 end = 1011  # same end time as MATLAB example
 times = np.arange(end - start) / sampling_freq
@@ -193,8 +194,6 @@
 inset_axis.patch.set_alpha(0.7)
 
 # power spectral density plot
-from pyparrm._utils._power import compute_psd
-
 n_freqs = sampling_freq / 2
 psd_freqs, psd_raw = compute_psd(
     data[0, start:end], sampling_freq, int(n_freqs * 2)
@@ -234,7 +233,7 @@
 # %%
 
 # filtered data computed in MATLAB
-matlab_filtered = np.load("matlab_filtered.npy")
+matlab_filtered = np.load(get_example_data_paths("matlab_filtered"))
 
 fig, axis = plt.subplots(1, 1)
 inset_axis = axis.inset_axes((0.12, 0.6, 0.5, 0.35))

pyproject.toml

@@ -27,20 +27,36 @@ dependencies = [
 [project.optional-dependencies]
 dev = [
     "pytest",
+    "coverage",
     "flake8",
     "black",
     "codespell",
-    "pydocstyle",
     "pycodestyle",
+    "pydocstyle",
     "sphinx",
     "numpydoc",
-    "nbsphinx",
-    "nbsphinx_link",
     "sphinxcontrib-bibtex",
     "sphinx-gallery",
-    "pydata-sphinx-theme"
+    "pydata-sphinx-theme",
+    "notebook",
+    "ipykernel",
+    "ipywidgets",
+    "ipython"
 ]
 
 [project.urls]
 "Homepage" = "https://github.com/neuromodulation/PyPARRM"
-"Bug Tracker" = "https://github.com/neuromodulation/PyPARRM/issues"
+"Bug Tracker" = "https://github.com/neuromodulation/PyPARRM/issues"
+
+[tool.coverage.run]
+omit = [
+    "tests/*",
+    "__init__.py",
+    "src/pyparrm/utils/_docs.py"
+]
+
+[tool.codespell]
+skip = "./docs/build,./docs/source/auto_examples,./docs/source/refs.bib,./.*"
+
+[tool.pydocstyle]
+match-dir = "^(?!(examples|docs|tests)).*"

requirements_dev.txt

@@ -1,13 +1,16 @@
 pytest
+coverage
 flake8
 black
 codespell
-pydocstyle
 pycodestyle
+pydocstyle
 sphinx
 numpydoc
-nbsphinx
-nbsphinx_link
 sphinxcontrib-bibtex
 sphinx-gallery
-pydata-sphinx-theme
+pydata-sphinx-theme
+notebook
+ipykernel
+ipywidgets
+ipython

requirements_rtd.txt

@@ -4,8 +4,10 @@ matplotlib
 pqdm
 sphinx
 numpydoc
-nbsphinx
-nbsphinx_link
 sphinxcontrib-bibtex
 sphinx-gallery
-pydata-sphinx-theme
+pydata-sphinx-theme
+notebook
+ipykernel
+ipywidgets
+ipython

src/pyparrm/__init__.py

@@ -3,3 +3,4 @@
 __version__ = "1.1.1dev"
 
 from .parrm import PARRM
+from .data import get_example_data_paths

src/pyparrm/_utils/_power.py

@@ -18,7 +18,7 @@ def compute_psd(
 
     Parameters
     ----------
-    data : numpy.ndarray, shape of (channels, times)
+    data : ~numpy.ndarray, shape of [channels, times]
         Data for which power should be computed (assumed to be real-valued).
 
     sampling_freq : int
@@ -29,18 +29,18 @@ def compute_psd(
         be double the desired number of frequencies in the power spectra.
 
     max_freq : int | float | None (default None)
-        The maximum frequency that should be returned. If ``None``, values for
-        all computed frequencies returned.
+        The maximum frequency that should be returned. If :obj:`None`, values
+        for all computed frequencies returned.
 
-    n_jobs : int (default 1)
+    n_jobs : int (default ``1``)
         Number of jobs to run in parallel.
 
     Returns
     -------
-    freqs :numpy.ndarray, shape of (frequencies)
+    freqs : ~numpy.ndarray, shape of [frequencies]
         Frequencies in `psd`.
 
-    psd : numpy.ndarray, shape of (channels, frequencies)
+    psd : ~numpy.ndarray, shape of [channels, frequencies]
         Power spectral density of `data`.
 
     Notes

src/pyparrm/data/__init__.py

@@ -0,0 +1,5 @@
+"""Storage and tools for handling data files."""
+
+__version__ = "1.1.1dev"
+
+from .example_data import get_example_data_paths, DATASETS

src/pyparrm/data/example_data.py

@@ -0,0 +1,30 @@
+"""Tools for fetching example data."""
+
+import os
+from pathlib import Path
+
+DATASETS = {}
+DATASETS["example_data"] = "example_data.npy"
+DATASETS["example_data_artefact_free"] = "example_data_artefact_free.npy"
+DATASETS["matlab_filtered"] = "matlab_filtered.npy"
+DATASETS["ecog_lfp_data"] = "ecog_lfp_data.npy"
+
+
+def get_example_data_paths(name: str) -> str:
+    """Return the path to the requested example data.
+
+    Parameters
+    ----------
+    name : str
+        Name of the example data.
+
+    Returns
+    -------
+    path : str
+        Path to the example data.
+    """
+    if name not in DATASETS.keys():
+        raise ValueError(f"`name` must be one of: {list(DATASETS.keys())}")
+
+    filepath_upper = Path(os.path.abspath(__file__)).parent
+    return os.path.join(filepath_upper, "example_data", DATASETS[name])