diff --git a/.gitignore b/.gitignore index 2f9c7b5..ce00b68 100644 --- a/.gitignore +++ b/.gitignore @@ -10,3 +10,4 @@ dist/* localtest .pytest_cache/ __pycache__/ +_build/ diff --git a/README.md b/README.md deleted file mode 100644 index efc90f8..0000000 --- a/README.md +++ /dev/null @@ -1,57 +0,0 @@ -# peakdet -This package provide a Python interface for reproducible physiological data analysis - -## Status -[![Build Status](https://travis-ci.org/rmarkello/peakdet.svg?branch=master)](https://travis-ci.org/rmarkello/peakdet) -[![Coverage Status](https://coveralls.io/repos/github/rmarkello/peakdet/badge.svg?branch=master)](https://coveralls.io/github/rmarkello/peakdet?branch=master) - -## Table of Contents -If you know where you're going, feel free to jump ahead: -* [Purpose](#purpose) - * [Overview](#overview) - * [Background](#background) - * [Development](#development) -* [Installation](#installation-and-setup) -* [Example usage](#usage) -* [How to get involved](#how-to-get-involved) -* [Credit](#credit) - -## Purpose -#### Overview -This package is designed for use in the reproducible processing and analysis of physiological data, like those collected from respiratory belts, pulse photoplethysmography, or electrocardiogram (ECG/EKG) monitors. - -#### Background -Physiological data are messy and prone to artifact (e.g., movement in respiration and pulse, ectopic beats in ECG), and despite leaps and bounds in recent algorithms for processing these data there still exists a need for manual inspection to ensure such artifacts have been appropriately removed. -Because of this manual intervention step, understanding exactly what happened to go from "raw" data to processed or "analysis-ready" data can often be difficult (or impossible!). -This toolbox aims to provide a set of tools that will work with a variety of input data to reproducibly generate manually-corrected, analysis-ready physiological data. - -#### Development -This package has largely been developed in the spare time of a single graduate student ([`@rmarkello`](https://github.com/rmarkello)), so while it would be :sparkles: amazing :sparkles: if anyone else finds it helpful, this package is not currently accepting requests for new features. -Contributions of new feature via are certainly welcome, but please first see our [contributing guidelines](CONTRIBUTING.md) for instructions on the preferred process to do so. - -## Installation and setup -This package requires Python >= 3.5. -Assuming you have the correct version of Python installed, you can install this package by opening a terminal and running the following: - -```bash -git clone https://github.com/rmarkello/peakdet.git -cd peakdet -python setup.py install -``` - -## Usage -The API of `peakdet` is under active development, so it's not quite stable enough for example usage instructions. -If you're *super eager* to get started I would recommend creating an issue to let the developers know there's external interest in these sorts of things. -Otherwise, check back soon! - -## How to get involved -We're thrilled to welcome new contributors! -If you're interesting in getting involved, you should start by reading our [contributing guidelines](CONTRIBUTING.md) and [code of conduct](CODE_OF_CONDUCT.md). - -Once you're done with that, you can take a look at our list of active [issues](https://github.com/rmarkello/peakdet/issues) and let us know if there's something you'd like to begin working on. - -If you've found a bug, are experiencing a problem, or have a question, create a new issue with some information about it! - -## Credit -Many of the behind-the-scenes functions in `peakdet` are imperfect translations of code from the [`PhysIO`](https://github.com/translationalneuromodeling/tapas/tree/master/PhysIO) MATLAB toolbox, and the toolbox is therefore licensed under the [GPLv3](LICENSE). -Please be sure to cite their paper if you use this tool ([Kasper et al., 2017](http://www.sciencedirect.com/science/article/pii/S016502701630259X)). diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..834dc45 --- /dev/null +++ b/README.rst @@ -0,0 +1,82 @@ +peakdet: A toolbox for physiological peak detection analyses +============================================================ + +This package is designed for use in the reproducible processing and analysis of +physiological data, like those collected from respiratory belts, pulse +photoplethysmography, or electrocardiogram (ECG/EKG) monitors. + +.. image:: https://travis-ci.org/rmarkello/peakdet.svg?branch=master + :target: https://travis-ci.org/rmarkello/peakdet +.. image:: https://codecov.io/gh/rmarkello/peakdet/branch/master/graph/badge.svg + :target: https://codecov.io/gh/rmarkello/peakdet +.. image:: https://readthedocs.org/projects/peakdet/badge/?version=latest + :target: http://peakdet.readthedocs.io/en/latest +.. image:: https://img.shields.io/badge/License-GPL%20v3-blue.svg + :target: https://www.gnu.org/licenses/gpl-3.0 + +.. _overview: + +Overview +-------- + +Physiological data are messy and prone to artifact (e.g.,) movement in +respiration and pulse, ectopic beats in ECG). Despite leaps and bounds in +recent algorithms for processing these data there still exists a need for +manual inspection to ensure such artifacts have been appropriately removed. +Because of this manual intervention step, understanding exactly what happened +to go from "raw" data to processed, "analysis-ready" data can often be +difficult or impossible. This toolbox aims to provide a set of tools that will +work with a variety of input data to reproducibly generate manually-corrected, +analysis-ready physiological data. + +.. _development: + +Development and getting involved +-------------------------------- + +This package has been largely developed in the spare time of a single graduate +student (`@rmarkello `_) with help from some +incredible `contributors `_. While it would be |sparkles| amazing |sparkles| if anyone else +finds it helpful, given the limited time constraints of graduate school, the +current package is not currently accepting requests for new features. + +However, if you're interested in getting involved in the project, we're +thrilled to welcome new contributors! You should start by reading our +`contributing guidelines `_ and `code of conduct `_. Once you're done with that, take a look at +our `issues `_ to see if there's +anything you might like to work on. Alternatively, if you've found a bug, are +experiencing a problem, or have a question, create a new issue with some +information about it! + +.. _acknowledgments: + +Acknowledgments +--------------- + +While this package was initially created in 2016, some of the behind-the-scenes +functions in the project were translated from the `PhysIO `_ MATLAB toolbox. As such, +if you use this code it would be good to (1) provide a link back to the +``peakdet`` repostiory with the version of the code used, and (2) cite `their +paper `_: + +.. [1] Kasper, L., Bollmann, S., Diaconescu, A. O., Hutton, C., Heinzle, J., + Iglesias, S., ... & Stephan, K. E. (2017). The PhysIO toolbox for modeling + physiological noise in fMRI data. Journal of Neuroscience Methods, 276, + 56-72. + +.. _licensing: + +License Information +------------------- + +This codebase is licensed under the GNU General Public License version 3. +The full license can be found in the `LICENSE `_ file in the ``peakdet`` distribution. + +All trademarks referenced herein are property of their respective holders. + +.. |sparkles| replace:: ✨ diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..6790a64 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +SPHINXPROJ = peakdet +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/api.rst b/docs/api.rst new file mode 100644 index 0000000..4e27855 --- /dev/null +++ b/docs/api.rst @@ -0,0 +1,33 @@ +.. _api_ref: + +.. currentmodule:: peakdet + +API +=== + +Physiological data +------------------ + +.. autoclass:: peakdet.Physio + +Loading data +------------ + +.. autofunction:: peakdet.load_physio +.. autofunction:: peakdet.load_history +.. autofunction:: peakdet.load_rtpeaks + +Processing data +--------------- + +.. autofunction:: peakdet.interpolate_physio +.. autofunction:: peakdet.filter_physio +.. autofunction:: peakdet.peakfind_physio +.. autofunction:: peakdet.edit_physio +.. autofunction:: peakdet.plot_physio + +Saving data +----------- + +.. autofunction:: peakdet.save_physio +.. autofunction:: peakdet.save_history diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..1cbf71e --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,105 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +# +# Configuration file for the Sphinx documentation builder. + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +import os +import sys + +# -- Project information ----------------------------------------------------- + +# Add project name, copyright holder, and author(s) +project = 'peakdet' +copyright = '2018, peakdet developers' +author = 'Ross Markello' + +# Import project to get version info +sys.path.insert(0, os.path.abspath(os.path.pardir)) +import peakdet # noqa +# The short X.Y version +version = peakdet.__version__ +# The full version, including alpha/beta/rc tags +release = peakdet.__version__ + + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.autosummary', + 'sphinx.ext.doctest', + 'sphinx.ext.intersphinx', + 'sphinx.ext.mathjax', + 'sphinx.ext.napoleon', + 'sphinx.ext.viewcode', +] + +# Generate the API documentation when building +autosummary_generate = True +numpydoc_show_class_members = False +autoclass_content = "class" + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path . +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +import sphinx_rtd_theme # noqa +html_theme = 'sphinx_rtd_theme' +html_show_sourcelink = False + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +html_theme_options = {} + +# 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'] + + +# -- Options for HTMLHelp output --------------------------------------------- + +# Output file base name for HTML help builder. +htmlhelp_basename = 'peakdetdoc' + + +# -- Extension configuration ------------------------------------------------- +intersphinx_mapping = { + 'matplotlib': ('https://matplotlib.org', None), + 'numpy': ('https://docs.scipy.org/doc/numpy', None), + 'scipy': ('https://docs.scipy.org/doc/scipy/reference', None), + 'sklearn': ('http://scikit-learn.org/stable', None), +} diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..590f394 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,11 @@ +.. include:: ../README.rst + +Contents +-------- + +.. toctree:: + :maxdepth: 1 + + installation + usage + api diff --git a/docs/installation.rst b/docs/installation.rst new file mode 100644 index 0000000..a36dc55 --- /dev/null +++ b/docs/installation.rst @@ -0,0 +1,19 @@ +.. _installation_setup: + +Installation and setup +====================== + +.. _basic_installation: + +Basic installation +-------------------- + +This package requires Python >= 3.6. Assuming you have the correct version of +Python installed, you can install ``peakdet`` by opening a terminal and running +the following: + +.. code-block:: bash + + git clone https://github.com/rmarkello/peakdet.git + cd peakdet + python setup.py install diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..36c0c77 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,4 @@ +-r ../requirements.txt +sphinx>=1.2 +sphinx_rtd_theme + diff --git a/docs/usage.rst b/docs/usage.rst new file mode 100644 index 0000000..6e4041f --- /dev/null +++ b/docs/usage.rst @@ -0,0 +1,11 @@ +.. _usage: + +Using peakdet +============= + +The API of ``peakdet`` is under active development, so it's not quite stable +enough for example usage instructions. Try taking a look at the :ref:`api_ref` +to get an idea about the available functions and methods. If you're *super +eager* to get started, try `opening an issue `_ to let the developers know there's external interest in these +sorts of things. Otherwise, check back soon! diff --git a/peakdet/info.py b/peakdet/info.py index c7f29c5..46645c6 100644 --- a/peakdet/info.py +++ b/peakdet/info.py @@ -9,8 +9,8 @@ DESCRIPTION = """\ A toolbox for reproducible physiological data analysis\ """ -LONG_DESCRIPTION = 'README.md' -LONG_DESCRIPTION_CONTENT_TYPE = 'text/markdown' +LONG_DESCRIPTION = 'README.rst' +LONG_DESCRIPTION_CONTENT_TYPE = 'text/x-rst' URL = 'https://github.com/rmarkello/{name}'.format(name=NAME) DOWNLOAD_URL = ('http://github.com/rmarkello/{name}/archive/{ver}.tar.gz' .format(name=NAME, ver=__version__)) @@ -29,8 +29,16 @@ ] EXTRAS_REQUIRES = { + 'doc': [ + 'sphinx>=1.2', + 'sphinx_rtd_theme' + ] } +EXTRAS_REQUIRES['all'] = list( + set([v for deps in EXTRAS_REQUIRES.values() for v in deps]) +) + PACKAGE_DATA = { 'peakdet.tests': [ 'data/*' diff --git a/setup.cfg b/setup.cfg index a1ed299..cf37a41 100644 --- a/setup.cfg +++ b/setup.cfg @@ -1,5 +1,5 @@ [metadata] -description-file = README.md +description-file = README.rst [flake8] ignore = E402