building api

README.rst

@@ -0,0 +1,126 @@
+PyRASA - Spectral parameterization in python based on IRASA
+===========================================================
+
+.. image:: https://www.repostatus.org/badges/latest/wip.svg
+   :target: https://www.repostatus.org/#wip
+   :alt: Project Status: WIP – Initial development is in progress, but there has not yet been a stable, usable release suitable for the public.
+
+.. image:: https://img.shields.io/badge/License-BSD_2--Clause-orange.svg
+   :target: https://opensource.org/licenses/BSD-2-Clause
+   :alt: License
+
+.. image:: http://www.mypy-lang.org/static/mypy_badge.svg
+   :target: http://mypy-lang.org/
+   :alt: Checked with mypy
+
+.. image:: https://coveralls.io/repos/github/schmidtfa/pyrasa/badge.svg?branch=main
+   :target: https://coveralls.io/github/schmidtfa/pyrasa?branch=main
+   :alt: Coverage Status
+
+
+PyRASA is a Python library designed to separate and parametrize aperiodic (fractal) and periodic (oscillatory) components in time series data based on the IRASA algorithm (Wen & Liu, 2016).
+
+Features
+--------
+
+- **Aperiodic and Periodic Decomposition:** Utilize the IRASA algorithm to decompose power spectra into aperiodic and periodic components, enabling better interpretation of neurophysiological signals.
+- **Time Resolved Spectral Parametrization:** Perform time resolved spectral parametrization, allowing you to track changes in spectral components over time.
+- **Support for Raw and Epoched MNE Objects:** PyRASA provides functions designed for both continuous (Raw) and event-related (Epochs) data, making it versatile for various types of EEG/MEG analyses.
+- **Consistent Ontology:** PyRASA uses the same jargon to label parameters as specparam, the most commonly used tool to parametrize power spectra, to allow users to easily switch between tools depending on their needs, while keeping the labeling of features consistent.
+- **Custom Aperiodic Fit Models:** In addition to the built-in "fixed" and "knee" models for aperiodic fitting, users can specify their custom aperiodic fit functions, offering flexibility in how aperiodic components are modeled.
+
+Documentation
+-------------
+
+Documentation for PyRASA, including detailed descriptions of functions, parameters, and examples, will soon be available `here`_.
+
+.. _here: https://github.com/schmidtfa/pyrasa
+
+Installation
+------------
+
+To install the latest stable version of PyRASA, you can soon use pip::
+
+   $ pip install pyrasa
+
+or conda::
+
+   $ conda install pyrasa
+
+Dependencies
+------------
+
+PyRASA has the following dependencies:
+
+- **Core Dependencies:**
+  - `numpy <https://github.com/numpy/numpy>`_
+  - `scipy <https://github.com/scipy/scipy>`_
+  - `pandas <https://github.com/pandas-dev/pandas>`_
+
+- **Optional Dependencies for Full Functionality:**
+  - `mne <https://github.com/mne-tools/mne-python>`_: Required for directly working with EEG/MEG data in `Raw` or `Epochs` formats.
+
+Example Usage
+-------------
+
+Decompose spectra into periodic and aperiodic components::
+
+   from pyrasa.irasa import irasa
+
+   irasa_out = irasa(sig, 
+                     fs=fs, 
+                     band=(.1, 200), 
+                     psd_kwargs={'nperseg': duration*fs, 
+                                 'noverlap': duration*fs*overlap
+                                },
+                     hset_info=(1, 2, 0.05))
+
+.. image:: https://raw.githubusercontent.com/schmidtfa/pyrasa/main/simulations/example_knee.png
+   :alt: Example knee image
+
+
+Extract periodic parameters::
+
+   irasa_out.get_peaks()
+
++-----------+-----+--------+--------+
+|  ch_name  |  cf |   bw   |   pw   |
++===========+=====+========+========+
+|     0     | 9.5 | 1.4426 | 0.4178 |
++-----------+-----+--------+--------+
+
+Extract aperiodic parameters::
+
+   irasa_out.fit_aperiodic_model(fit_func='knee').aperiodic_params
+
++-----------+--------+--------------+--------------+-----------+--------------------+--------+-----------+
+|  Offset   |  Knee  | Exponent_1   | Exponent_2   | fit_type  | Knee Frequency (Hz) |   tau  |  ch_name |
++===========+========+==============+==============+===========+====================+========+===========+
+| 1.737e-16 | 60.94  | 0.0396       | 1.4727       | knee      | 14.131             | 0.0113 |     0     |
++-----------+--------+--------------+--------------+-----------+--------------------+--------+-----------+
+
+And the goodness of fit::
+
+   irasa_out.fit_aperiodic_model(fit_func='knee').gof
+
++------------+------------+------------+------------+-----------+-----------+
+|     mse    | r_squared  |     BIC    |     AIC    | fit_type  |  ch_name  |
++============+============+============+============+===========+===========+
+|  0.000051  | 0.999751   | -3931.840  | -3947.806  | knee      |     0     |
++------------+------------+------------+------------+-----------+-----------+
+
+How to Contribute
+-----------------
+
+Contributions to PyRASA are welcome! Whether it's raising issues, improving documentation, fixing bugs, or adding new features, your help is appreciated. Please refer to the `CONTRIBUTING.md <CONTRIBUTING.md>`_ file for more information on how to get involved.
+
+Reference
+---------
+
+If you are using IRASA, please cite the smart people who came up with the algorithm:
+
+Wen, H., & Liu, Z. (2016). Separating fractal and oscillatory components in the power spectrum of neurophysiological signal. *Brain Topography*, 29, 13-26. https://doi.org/10.1007/s10548-015-0448-0
+
+If you are using PyRASA, it would be nice if you could additionally cite us (whenever the paper is finally ready):
+
+Schmidt F., Hartmann T., & Weisz, N. (2049). PyRASA - Spectral parameterization in python based on IRASA. *SOME JOURNAL THAT LIKES US*

doc/source/_autoexamples/pyrasa.irasa.irasa.rst

@@ -0,0 +1,11 @@
+pyrasa.irasa.irasa
+==================
+
+.. currentmodule:: pyrasa.irasa
+
+.. autofunction:: irasa
+
+.. _sphx_glr_backreferences_pyrasa.irasa.irasa:
+
+.. minigallery:: pyrasa.irasa.irasa
+    :add-heading:

doc/source/_autoexamples/pyrasa.irasa.irasa_sprint.rst

@@ -0,0 +1,11 @@
+pyrasa.irasa.irasa\_sprint
+==========================
+
+.. currentmodule:: pyrasa.irasa
+
+.. autofunction:: irasa_sprint
+
+.. _sphx_glr_backreferences_pyrasa.irasa.irasa_sprint:
+
+.. minigallery:: pyrasa.irasa.irasa_sprint
+    :add-heading:

doc/source/_autoexamples/pyrasa.irasa_mne.irasa_epochs.rst

@@ -0,0 +1,11 @@
+pyrasa.irasa\_mne.irasa\_epochs
+===============================
+
+.. currentmodule:: pyrasa.irasa_mne
+
+.. autofunction:: irasa_epochs
+
+.. _sphx_glr_backreferences_pyrasa.irasa_mne.irasa_epochs:
+
+.. minigallery:: pyrasa.irasa_mne.irasa_epochs
+    :add-heading:

doc/source/_autoexamples/pyrasa.irasa_mne.irasa_raw.rst

@@ -0,0 +1,11 @@
+pyrasa.irasa\_mne.irasa\_raw
+============================
+
+.. currentmodule:: pyrasa.irasa_mne
+
+.. autofunction:: irasa_raw
+
+.. _sphx_glr_backreferences_pyrasa.irasa_mne.irasa_raw:
+
+.. minigallery:: pyrasa.irasa_mne.irasa_raw
+    :add-heading:

doc/source/_autoexamples/pyrasa.utils.aperiodic_utils.compute_aperiodic_model.rst

@@ -0,0 +1,11 @@
+pyrasa.utils.aperiodic\_utils.compute\_aperiodic\_model
+=======================================================
+
+.. currentmodule:: pyrasa.utils.aperiodic_utils
+
+.. autofunction:: compute_aperiodic_model
+
+.. _sphx_glr_backreferences_pyrasa.utils.aperiodic_utils.compute_aperiodic_model:
+
+.. minigallery:: pyrasa.utils.aperiodic_utils.compute_aperiodic_model
+    :add-heading:

doc/source/_static/style.css

@@ -0,0 +1,33 @@
+a[class^="sphx-glr-backref-module-mne_bids"] {
+    /* make all MNE-BIDS backrefs bold */
+    font-weight: 800;
+  }
+
+  span.option {
+    /* avoid breaking lines in our command-line parameters */
+    white-space: nowrap;
+  }
+
+  /* ************************************************* Previous / Next buttons */
+  .prev-next-bottom a.left-prev:before {
+    content:"❮\00A0"
+  }
+  .prev-next-bottom a.right-next:after {
+    content:"\00A0❯"
+  }
+  .prev-next-bottom a.right-next {
+    text-align: right;
+  }
+
+  /* ************************************************* truncate version string */
+  div.navbar-item:first-child {
+    overflow-x: hidden;
+  }
+  a.navbar-brand.logo {
+    flex-shrink: 1;
+    overflow-x: hidden;
+  }
+  p.logo__title {
+    overflow-x: hidden;
+    text-overflow: ellipsis;
+  }

doc/source/_templates/autosummary/class.rst

@@ -0,0 +1,12 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :special-members: __contains__,__getitem__,__iter__,__len__,__add__,__sub__,__mul__,__div__,__neg__,__hash__
+   :members:
+
+.. _sphx_glr_backreferences_{{ fullname }}:
+
+.. minigallery:: {{ fullname }}
+    :add-heading:

doc/source/_templates/autosummary/function.rst

@@ -0,0 +1,10 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autofunction:: {{ objname }}
+
+.. _sphx_glr_backreferences_{{ fullname }}:
+
+.. minigallery:: {{ fullname }}
+    :add-heading:

doc/source/_templates/layout.html

@@ -0,0 +1,18 @@
+{%- extends "pydata_sphinx_theme/layout.html" %}
+
+{% block fonts %}
+    <!-- add `style` or `link` tags with your CSS `@font-face` declarations here -->
+    <!-- ... and a `style` tag with setting `font-family` in `body` and `.header-style` -->
+    <!-- ... and optionally preload the `woff2` for snappier page loads -->
+    <!-- or add a `style` tag with a font fallback chain with good cross-platform coverage -->
+    <style>
+        body,.header-style {font-family: 'Source Sans Pro', sans-serif;}
+        code,kbd,pre,samp {font-family: 'Source Code Pro', monospace;}
+    </style>
+{% endblock %}
+
+{% block extrahead %}
+    <script type="text/javascript" src="{{ pathto('_static/copybutton.js', 1) }}"></script>
+    <script type="text/javascript" src="{{ pathto('_static/scrollfix.js', 1) }}"></script>
+{{ super() }}
+{% endblock %}

doc/source/api.rst

@@ -1,15 +1,54 @@
-API Documentation
+:orphan:
+
+.. _api_documentation:
+
+=================
+API Reference
 =================
 
-pyrasa
+irasa
 ------
+:py:mod:`pyrasa.irasa`
+
+.. automodule:: pyrasa.irasa
+   :no-members:
+   :no-inherited-members:
+
+.. currentmodule:: pyrasa.irasa
+
+.. autosummary::
+   :toctree: _autoexamples/
+
+   irasa
+   irasa_sprint
+
+irasa_mne
+---------
+:py:mod:`pyrasa.irasa_mne`
+
+.. automodule:: pyrasa.irasa_mne
+   :no-members:
+   :no-inherited-members:
+
+.. currentmodule:: pyrasa.irasa_mne
+
+.. autosummary::
+   :toctree: _autoexamples/
+
+   irasa_raw
+   irasa_epochs
+
+aperiodic_utils
+----------------
+:py:mod:`pyrasa.utils.aperiodic_utils`
+
+.. automodule:: pyrasa.utils.aperiodic_utils
+   :no-members:
+   :no-inherited-members:
+
+.. currentmodule:: pyrasa.utils.aperiodic_utils
+
+.. autosummary::
+   :toctree: _autoexamples/
 
-.. automodule:: pyrasa
-   :members:
-   :undoc-members:
-   :show-inheritance:
-   :inherited-members:
-   :exclude-members: __weakref__
-   :private-members:
-   :special-members:
-   :noindex:
+   compute_aperiodic_model

doc/source/auto_examples/searchindex.bak

@@ -1,3 +1,6 @@
 '/home/th/git/science/pyrasa/doc/build/index.html', (0, 14753)
 '/home/th/git/science/pyrasa/doc/build/_static/documentation_options.js', (14848, 351)
 '/home/th/git/science/pyrasa/doc/build/searchindex.js', (15360, 1566)
+'/Users/fabian.schmidt/git/pyrasa/doc/build/index.html', (17408, 13751)
+'/Users/fabian.schmidt/git/pyrasa/doc/build/_static/documentation_options.js', (31232, 351)
+'/Users/fabian.schmidt/git/pyrasa/doc/build/searchindex.js', (31744, 3704)

doc/source/auto_examples/searchindex.dir

@@ -1,3 +1,6 @@
 '/home/th/git/science/pyrasa/doc/build/index.html', (0, 14753)
 '/home/th/git/science/pyrasa/doc/build/_static/documentation_options.js', (14848, 351)
 '/home/th/git/science/pyrasa/doc/build/searchindex.js', (15360, 1566)
+'/Users/fabian.schmidt/git/pyrasa/doc/build/index.html', (17408, 13751)
+'/Users/fabian.schmidt/git/pyrasa/doc/build/_static/documentation_options.js', (31232, 351)
+'/Users/fabian.schmidt/git/pyrasa/doc/build/searchindex.js', (31744, 3704)