From 5f7a6dc779142c6058880ce705ae4e39ae64d724 Mon Sep 17 00:00:00 2001 From: Mathieu Scheltienne Date: Wed, 16 Aug 2023 15:41:44 +0200 Subject: [PATCH 1/9] add furo doc configuration --- .gitignore | 1 + docs/_static/css/style.css | 4 ++ .../nigsp_picto_circle_dark_background.svg | 71 ++++++++++++++++++ .../nigsp_picto_circle_light_background.svg | 71 ++++++++++++++++++ docs/conf.py | 72 ++++++++++++------- docs/index.rst | 23 +++--- nigsp/operations/surrogates.py | 2 +- setup.cfg | 9 ++- 8 files changed, 214 insertions(+), 39 deletions(-) create mode 100644 docs/_static/css/style.css create mode 100644 docs/_static/logos/nigsp_picto_circle_dark_background.svg create mode 100644 docs/_static/logos/nigsp_picto_circle_light_background.svg diff --git a/.gitignore b/.gitignore index 0896862..13c6e7a 100644 --- a/.gitignore +++ b/.gitignore @@ -74,6 +74,7 @@ instance/ # Sphinx documentation docs/_build/ +docs/generated docs/api/ docs/api/generated diff --git a/docs/_static/css/style.css b/docs/_static/css/style.css new file mode 100644 index 0000000..77e7db1 --- /dev/null +++ b/docs/_static/css/style.css @@ -0,0 +1,4 @@ +div.sphx-glr-download-link-note { + height: 0px; + visibility: hidden; +} diff --git a/docs/_static/logos/nigsp_picto_circle_dark_background.svg b/docs/_static/logos/nigsp_picto_circle_dark_background.svg new file mode 100644 index 0000000..a2748c2 --- /dev/null +++ b/docs/_static/logos/nigsp_picto_circle_dark_background.svg @@ -0,0 +1,71 @@ + + + + + + + + + + + + + + + + + diff --git a/docs/_static/logos/nigsp_picto_circle_light_background.svg b/docs/_static/logos/nigsp_picto_circle_light_background.svg new file mode 100644 index 0000000..9103770 --- /dev/null +++ b/docs/_static/logos/nigsp_picto_circle_light_background.svg @@ -0,0 +1,71 @@ + + + + + + + + + + + + + + + + + diff --git a/docs/conf.py b/docs/conf.py index 7a7d41c..b25f26e 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -31,24 +31,32 @@ version = nigsp.__version__ # The full version, including alpha/beta/rc tags release = nigsp.__version__ - +package = nigsp.__name__ +gh_url = "https://github.com/MIPLabCH/nigsp" # -- General configuration --------------------------------------------------- +needs_sphinx = "2.0" # based on setup.cfg requirements + # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones.import sphinx_rtd_theme # noqa extensions = [ "sphinx.ext.autodoc", - "sphinx.ext.autosummary", "sphinx.ext.autosectionlabel", + "sphinx.ext.autosummary", "sphinx.ext.doctest", "sphinx.ext.intersphinx", + "sphinx.ext.mathjax", "sphinx.ext.napoleon", "sphinx.ext.viewcode", "sphinxarg.ext", "myst_parser", + "sphinxcontrib.bibtex", + "sphinx_copybutton", + "sphinx_design", + "sphinx_issues", ] # Generate the API documentation when building @@ -77,38 +85,45 @@ # 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" - -# Integrate GitHub -html_context = { - "display_github": True, # Integrate GitHub - "github_user": "MIPLabCH", # Username - "github_repo": "nigsp", # Repo name - "github_version": "master", # Version - "conf_py_path": "/docs/", # Path in the checkout to the docs root -} +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "**.ipynb_checkpoints"] # -- Options for HTML output ------------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = "sphinx_rtd_theme" +html_theme = "furo" 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 = {} +html_show_sphinx = False # 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"] +html_css_files = [ + "css/style.css", +] +# 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 = { + "light_logo": "logos/nigsp_picto_circle_light_background.svg", + "dark_logo": "logos/nigsp_picto_circle_dark_background.svg", + "footer_icons": [ + { + "name": "GitHub", + "url": gh_url, + "html": """ + + + + """, + "class": "", + }, + ], + "sidebar_hide_name": True, +} # html_favicon = '_static/logo.png' # html_logo = '_static/logo.png' @@ -119,12 +134,21 @@ htmlhelp_basename = "nigsp" -# -- Extension configuration ------------------------------------------------- +# -- intersphinx ------------------------------------------------------------- intersphinx_mapping = { - "python": ("https://docs.python.org/3.6", None), - "numpy": ("https://docs.scipy.org/doc/numpy", None), + "python": ("https://docs.python.org/3", None), + "numpy": ("https://numpy.org/doc/stable", None), } +intersphinx_timeout = 5 + +# -- sphinx-issues ----------------------------------------------------------- +issues_github_path = gh_url.split("https://github.com/")[-1] + +# -- autosectionlabels ------------------------------------------------------- +autosectionlabel_prefix_document = True +# -- sphinxcontrib-bibtex ---------------------------------------------------- +bibtex_bibfiles = [] # -- Generate API automagically ----------------------------------------------- def run_apidoc(_): diff --git a/docs/index.rst b/docs/index.rst index 838e65b..6dc586d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -3,6 +3,8 @@ You can adapt this file completely to your liking, but it should at least contain the root ``toctree`` directive. +:hide-toc: + NiGSP (NeuroImaging Graph Signal Processing) ============================================ @@ -32,7 +34,7 @@ Cite ---- If you use ``nigsp`` in your work, please cite either the all-time -Zenodo DOI |general Zenodo DOI| or the Zenodo DOI related to the version +Zenodo DOI |general Zenodo :hide-toc:DOI| or the Zenodo DOI related to the version you are using. Please cite the following paper(s) too: Preti, M.G., Van De Ville, D. *Decoupling of brain function from @@ -77,16 +79,10 @@ cite also: .. |general Zenodo DOI| image:: https://zenodo.org/badge/DOI/10.5281/zenodo.6373436.svg :target: https://zenodo.org/badge/latestdoi/446805866 - -.. toctree:: - :titlesonly: - :maxdepth: 0 - - NiGSP - .. toctree:: :caption: Usage - :maxdepth: 5 + :hidden: + :maxdepth: 2 Installation User Guide @@ -96,20 +92,23 @@ cite also: .. toctree:: :caption: API - :maxdepth: 5 + :hidden: + :maxdepth: 1 :glob: api/* .. toctree:: :caption: Graph Signal Processing - :maxdepth: 5 + :hidden: + :maxdepth: 1 About GSP .. toctree:: :caption: Developers - :maxdepth: 5 + :hidden: + :maxdepth: 1 How to Contribute Contributor Guide diff --git a/nigsp/operations/surrogates.py b/nigsp/operations/surrogates.py index eaf4e05..efd5508 100644 --- a/nigsp/operations/surrogates.py +++ b/nigsp/operations/surrogates.py @@ -289,7 +289,7 @@ def test_significance( ------ ValueError If data is not None and the surrogate shape (except last axis) is - different from the data shape + different from the data shape. NotImplementedError If any other method rather than those listed above is selected. diff --git a/setup.cfg b/setup.cfg index 4cc67d2..6ff609f 100644 --- a/setup.cfg +++ b/setup.cfg @@ -48,10 +48,15 @@ all = %(mat)s %(viz)s doc = + furo + memory-profiler + myst-parser sphinx>=2.0 sphinx-argparse - sphinx_rtd_theme - myst-parser + sphinxcontrib-bibtex + sphinx-copybutton + sphinx-design + sphinx-issues style = flake8>=4.0 black<23.0.0 From 1c58a47a18c868cda82c70d9dfb6b2b4440846d0 Mon Sep 17 00:00:00 2001 From: Mathieu Scheltienne Date: Wed, 16 Aug 2023 15:54:10 +0200 Subject: [PATCH 2/9] fix typo and rm sphinx-gallery elements --- docs/_static/css/style.css | 4 ---- docs/index.rst | 2 +- setup.cfg | 1 - 3 files changed, 1 insertion(+), 6 deletions(-) delete mode 100644 docs/_static/css/style.css diff --git a/docs/_static/css/style.css b/docs/_static/css/style.css deleted file mode 100644 index 77e7db1..0000000 --- a/docs/_static/css/style.css +++ /dev/null @@ -1,4 +0,0 @@ -div.sphx-glr-download-link-note { - height: 0px; - visibility: hidden; -} diff --git a/docs/index.rst b/docs/index.rst index 6dc586d..ccd13e4 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -34,7 +34,7 @@ Cite ---- If you use ``nigsp`` in your work, please cite either the all-time -Zenodo DOI |general Zenodo :hide-toc:DOI| or the Zenodo DOI related to the version +Zenodo DOI |general Zenodo DOI| or the Zenodo DOI related to the version you are using. Please cite the following paper(s) too: Preti, M.G., Van De Ville, D. *Decoupling of brain function from diff --git a/setup.cfg b/setup.cfg index 6ff609f..bb01dab 100644 --- a/setup.cfg +++ b/setup.cfg @@ -49,7 +49,6 @@ all = %(viz)s doc = furo - memory-profiler myst-parser sphinx>=2.0 sphinx-argparse From 51edef7497d2863bee719a8f3b19d20a58e41983 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Wed, 16 Aug 2023 13:54:37 +0000 Subject: [PATCH 3/9] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/conf.py | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/conf.py b/docs/conf.py index b25f26e..c3b41e7 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -150,6 +150,7 @@ # -- sphinxcontrib-bibtex ---------------------------------------------------- bibtex_bibfiles = [] + # -- Generate API automagically ----------------------------------------------- def run_apidoc(_): from sphinx.ext.apidoc import main From 06aac785e4cc361b87ce3a96373b4eb04410baa3 Mon Sep 17 00:00:00 2001 From: Mathieu Scheltienne Date: Wed, 16 Aug 2023 15:55:10 +0200 Subject: [PATCH 4/9] rm ref to css files for sphinx-gallery --- docs/conf.py | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index b25f26e..34520bd 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -100,9 +100,6 @@ # 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"] -html_css_files = [ - "css/style.css", -] # 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 From 1a87f81188c0a90abb5a28cc3c789a3706a157fd Mon Sep 17 00:00:00 2001 From: Mathieu Scheltienne Date: Thu, 17 Aug 2023 12:01:46 +0200 Subject: [PATCH 5/9] add changelog entry --- docs/index.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/index.rst b/docs/index.rst index ccd13e4..717e84c 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -89,6 +89,7 @@ cite also: Command Line Interface (CLI) Output Licence + Changelog .. toctree:: :caption: API From 9e31f997226eb5707e53289a8348e3568e5c71ac Mon Sep 17 00:00:00 2001 From: Mathieu Scheltienne Date: Thu, 17 Aug 2023 13:21:50 +0200 Subject: [PATCH 6/9] change log and add configuration for sphinx-gallery, numpydoc and nitpick --- docs/_static/css/style.css | 4 + .../nigsp_picto_circle_coral_background.svg | 71 ++++++++++++++++ docs/conf.py | 83 +++++++++++++++++-- setup.cfg | 3 + tutorials/README.rst | 2 + 5 files changed, 155 insertions(+), 8 deletions(-) create mode 100644 docs/_static/css/style.css create mode 100644 docs/_static/logos/nigsp_picto_circle_coral_background.svg create mode 100644 tutorials/README.rst diff --git a/docs/_static/css/style.css b/docs/_static/css/style.css new file mode 100644 index 0000000..77e7db1 --- /dev/null +++ b/docs/_static/css/style.css @@ -0,0 +1,4 @@ +div.sphx-glr-download-link-note { + height: 0px; + visibility: hidden; +} diff --git a/docs/_static/logos/nigsp_picto_circle_coral_background.svg b/docs/_static/logos/nigsp_picto_circle_coral_background.svg new file mode 100644 index 0000000..fb1018a --- /dev/null +++ b/docs/_static/logos/nigsp_picto_circle_coral_background.svg @@ -0,0 +1,71 @@ + + + + + + + + + + + + + + + + + diff --git a/docs/conf.py b/docs/conf.py index 2547517..d9a1333 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -13,7 +13,9 @@ import os import sys -import nigsp # noqa +from sphinx_gallery.sorting import FileNameSortKey + +import nigsp sys.path.insert(0, os.path.abspath("..")) @@ -49,13 +51,14 @@ "sphinx.ext.doctest", "sphinx.ext.intersphinx", "sphinx.ext.mathjax", - "sphinx.ext.napoleon", "sphinx.ext.viewcode", - "sphinxarg.ext", "myst_parser", + "numpydoc", + "sphinxarg.ext", "sphinxcontrib.bibtex", "sphinx_copybutton", "sphinx_design", + "sphinx_gallery.gen_gallery", "sphinx_issues", ] @@ -87,6 +90,10 @@ # This pattern also affects html_static_path and html_extra_path. exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "**.ipynb_checkpoints"] +# Sphinx will warn about all references where the target cannot be found. +nitpicky = True +nitpick_ignore = [] + # -- Options for HTML output ------------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for @@ -100,13 +107,16 @@ # 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"] +html_css_files = [ + "css/style.css", +] # 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 = { - "light_logo": "logos/nigsp_picto_circle_light_background.svg", - "dark_logo": "logos/nigsp_picto_circle_dark_background.svg", + "light_logo": "logos/nigsp_picto_circle_coral_background.svg", + "dark_logo": "logos/nigsp_picto_circle_coral_background.svg", "footer_icons": [ { "name": "GitHub", @@ -123,14 +133,12 @@ } # html_favicon = '_static/logo.png' -# html_logo = '_static/logo.png' # -- Options for HTMLHelp output --------------------------------------------- # Output file base name for HTML help builder. htmlhelp_basename = "nigsp" - # -- intersphinx ------------------------------------------------------------- intersphinx_mapping = { "python": ("https://docs.python.org/3", None), @@ -147,6 +155,66 @@ # -- sphinxcontrib-bibtex ---------------------------------------------------- bibtex_bibfiles = [] +# -- numpydoc ---------------------------------------------------------------- +numpydoc_class_members_toctree = False +numpydoc_attributes_as_param_list = False + +# x-ref +numpydoc_xref_param_type = True +numpydoc_xref_aliases = { + # Matplotlib + "Axes": "matplotlib.axes.Axes", + "Figure": "matplotlib.figure.Figure", + # Python + "bool": ":class:`python:bool`", + "Path": "pathlib.Path", + "TextIO": "io.TextIOBase", +} +numpydoc_xref_ignore = { + "of", + "optional", + "or", + "shape", +} + +# validation +# https://numpydoc.readthedocs.io/en/latest/validation.html#validation-checks +error_ignores = { + "GL01", # docstring should start in the line immediately after the quotes + "EX01", # section 'Examples' not found + "ES01", # no extended summary found + "SA01", # section 'See Also' not found + "RT02", # The first line of the Returns section should contain only the type, unless multiple values are being returned # noqa +} +numpydoc_validate = True +numpydoc_validation_checks = {"all"} | set(error_ignores) +numpydoc_validation_exclude = { # regex to ignore during docstring check + r"\.__getitem__", + r"\.__contains__", + r"\.__hash__", + r"\.__mul__", + r"\.__sub__", + r"\.__add__", + r"\.__iter__", + r"\.__div__", + r"\.__neg__", +} + +# -- sphinx-gallery ---------------------------------------------------------- +sphinx_gallery_conf = { + "backreferences_dir": "generated/backreferences", + "doc_module": (f"{package}",), + "examples_dirs": ["../tutorials"], + "exclude_implicit_doc": {}, # set + "filename_pattern": r"\d{2}_", + "gallery_dirs": ["generated/tutorials"], + "line_numbers": False, + "plot_gallery": True, + "reference_url": {f"{package}": None}, + "remove_config_comments": True, + "show_memory": True, + "within_subsection_order": FileNameSortKey, +} # -- Generate API automagically ----------------------------------------------- def run_apidoc(_): @@ -164,7 +232,6 @@ def run_apidoc(_): # -- Final Setup ------------------------------------------------------------- - # https://github.com/rtfd/sphinx_rtd_theme/issues/117 # launch setup def setup(app): # noqa diff --git a/setup.cfg b/setup.cfg index bb01dab..9c45b12 100644 --- a/setup.cfg +++ b/setup.cfg @@ -49,12 +49,15 @@ all = %(viz)s doc = furo + memory-profiler myst-parser + numpydoc sphinx>=2.0 sphinx-argparse sphinxcontrib-bibtex sphinx-copybutton sphinx-design + sphinx-gallery sphinx-issues style = flake8>=4.0 diff --git a/tutorials/README.rst b/tutorials/README.rst new file mode 100644 index 0000000..0c7e28c --- /dev/null +++ b/tutorials/README.rst @@ -0,0 +1,2 @@ +Tutorials +========= From 4e016be9adb56871003eeb8c105af1fd4edf3a8a Mon Sep 17 00:00:00 2001 From: Mathieu Scheltienne Date: Thu, 17 Aug 2023 13:25:15 +0200 Subject: [PATCH 7/9] fix a couple of warnings --- docs/conf.py | 7 ++++++- docs/usage/licence.md | 22 +++++++++++----------- nigsp/io.py | 2 +- nigsp/operations/metrics.py | 8 ++++---- nigsp/operations/surrogates.py | 34 ++++++++++++++++------------------ nigsp/operations/timeseries.py | 29 +++++++++++++++-------------- nigsp/utils.py | 34 +++++++++++++++++----------------- 7 files changed, 70 insertions(+), 66 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index d9a1333..9e89a55 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -141,8 +141,9 @@ # -- intersphinx ------------------------------------------------------------- intersphinx_mapping = { - "python": ("https://docs.python.org/3", None), + "nibabel": ("https://nipy.org/nibabel/", None), "numpy": ("https://numpy.org/doc/stable", None), + "python": ("https://docs.python.org/3", None), } intersphinx_timeout = 5 @@ -165,6 +166,10 @@ # Matplotlib "Axes": "matplotlib.axes.Axes", "Figure": "matplotlib.figure.Figure", + # Nibabel + "Nifti1Image": "nibabel.nifti1.Nifti1Image", + # Numpy + "array": "numpy.ndarray", # Python "bool": ":class:`python:bool`", "Path": "pathlib.Path", diff --git a/docs/usage/licence.md b/docs/usage/licence.md index b62a9b5..b0a19a4 100644 --- a/docs/usage/licence.md +++ b/docs/usage/licence.md @@ -4,9 +4,9 @@ Apache License _Version 2.0, January 2004_ _<>_ -### Terms and Conditions for use, reproduction, and distribution +## Terms and Conditions for use, reproduction, and distribution -#### 1. Definitions +### 1. Definitions “License” shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document. @@ -60,7 +60,7 @@ owner as “Not a Contribution.” of whom a Contribution has been received by Licensor and subsequently incorporated within the Work. -#### 2. Grant of Copyright License +### 2. Grant of Copyright License Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, @@ -68,7 +68,7 @@ irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form. -#### 3. Grant of Patent License +### 3. Grant of Patent License Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, @@ -83,7 +83,7 @@ Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed. -#### 4. Redistribution +### 4. Redistribution You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, @@ -117,7 +117,7 @@ distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License. -#### 5. Submission of Contributions +### 5. Submission of Contributions Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and @@ -126,14 +126,14 @@ Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions. -#### 6. Trademarks +### 6. Trademarks This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file. -#### 7. Disclaimer of Warranty +### 7. Disclaimer of Warranty Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an “AS IS” BASIS, @@ -144,7 +144,7 @@ solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License. -#### 8. Limitation of Liability +### 8. Limitation of Liability In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate @@ -156,7 +156,7 @@ damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages. -#### 9. Accepting Warranty or Additional Liability +### 9. Accepting Warranty or Additional Liability While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or @@ -169,7 +169,7 @@ accepting any such warranty or additional liability. _END OF TERMS AND CONDITIONS_ -### APPENDIX: How to apply the Apache License to your work +## APPENDIX: How to apply the Apache License to your work To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets `[]` replaced with your own diff --git a/nigsp/io.py b/nigsp/io.py index 9b36077..d9b3767 100644 --- a/nigsp/io.py +++ b/nigsp/io.py @@ -47,7 +47,7 @@ def check_ext(all_ext, fname, scan=False, remove=False): ---------- all_ext : list All possible extensions to check within - fname : str or os.PathLikeLike + fname : str or os.PathLike The filename to check scan : bool, optional Scan the given path to see if there is a file with that extension diff --git a/nigsp/operations/metrics.py b/nigsp/operations/metrics.py index 4555c3e..6f447f8 100644 --- a/nigsp/operations/metrics.py +++ b/nigsp/operations/metrics.py @@ -38,14 +38,14 @@ def sdi(ts_split, mean=False, keys=None): Parameters ---------- - ts_split : dict or numpy.ndarrays + ts_split : dict or numpy.ndarray A dictionary containing two entries. If the two entries are "low" and "high", then SDI will be computed as the norm of the high vs the norm of the low, otherwise as the ratio between the second (second key in sorted keys) and the first. mean : bool, optional If True, compute mean over the last axis (e.g. between subjects) - keys : None or list of strings, optional + keys : None or list of str, optional Can be used to select two entries from a bigger dictionary and/or to specify the order in which the keys should be read (e.g. forcing a different order from the sorted keys). @@ -101,14 +101,14 @@ def gsdi(ts_split, mean=False, keys=None): Parameters ---------- - ts_split : dict or numpy.ndarrays + ts_split : dict or numpy.ndarray A dictionary containing two entries. If the two entries are "low" and "high", then SDI will be computed as the norm of the high vs the norm of the low, otherwise as the ratio between the second (second key in sorted keys) and the first. mean : bool, optional If True, compute mean over the last axis (e.g. between subjects) - keys : None or list of strings, optional + keys : None or list of str, optional Can be used to select two entries from a bigger dictionary and/or to specify the order in which the keys should be read (e.g. forcing a different order from the sorted keys). diff --git a/nigsp/operations/surrogates.py b/nigsp/operations/surrogates.py index efd5508..d057d7f 100644 --- a/nigsp/operations/surrogates.py +++ b/nigsp/operations/surrogates.py @@ -23,25 +23,24 @@ def random_sign(eigenvec, n_surr=1000, seed=42, stack=False): - """ - Create surrogates by randomly switching signs of eigenvectors. + """Create surrogates by randomly switching signs of eigenvectors. Parameters ---------- eigenvec : numpy.ndarray - A matrix of eigenvectors + A matrix of eigenvectors. n_surr : int, optional - Number of surrogates to create + Number of surrogates to create. seed : int or None, optional - Random seed (for repeatability) + Random seed (for repeatability). stack : bool, optional If True, add original eigenvec as last entry of the last dimension - of the created surrogate matrix + of the created surrogate matrix. Returns ------- numpy.ndarray - The matrix of surrogates, of shape eigenvec * n_surr(+1) + The matrix of surrogates, of shape ``(eigenvec * n_surr(+1),)``. Raises ------ @@ -92,7 +91,7 @@ def _create_surr(timeseries, eigenvec, n_surr, seed, stack): eigenvec : numpy.ndarray The eigenvector matrix from a previous Laplacian decomposition. n_surr : int - The number of surrogates to create + The number of surrogates to create. seed : int or None The seed to reinitialise the RNG - used for replicability. stack : bool @@ -101,7 +100,7 @@ def _create_surr(timeseries, eigenvec, n_surr, seed, stack): Returns ------- numpy.ndarray - The surrogate matrix, of shape timeseries.shape, n_surr + The surrogate matrix, of shape ``(timeseries.shape, n_surr)``. Raises ------ @@ -152,7 +151,7 @@ def sc_informed(timeseries, eigenvec, n_surr=1000, seed=124, stack=False): eigenvec : numpy.ndarray The eigenvector matrix from a previous Laplacian decomposition. n_surr : int, optional - The number of surrogates to create + The number of surrogates to create. seed : int or None, optional The seed to reinitialise the RNG - used for replicability. stack : bool, optional @@ -161,7 +160,7 @@ def sc_informed(timeseries, eigenvec, n_surr=1000, seed=124, stack=False): Returns ------- numpy.ndarray - The surrogate matrix, of shape timeseries.shape, n_surr + The surrogate matrix, of shape ``(timeseries.shape, n_surr)``. Raises ------ @@ -189,7 +188,7 @@ def sc_uninformed(timeseries, lapl_mtx, n_surr=1000, seed=98, stack=False): lapl_mtx : numpy.ndarray A symmetrically normalised laplacian matrix. n_surr : int, optional - The number of surrogates to create + The number of surrogates to create. seed : int or None, optional The seed to reinitialise the RNG - used for replicability. stack : bool, optional @@ -198,7 +197,7 @@ def sc_uninformed(timeseries, lapl_mtx, n_surr=1000, seed=98, stack=False): Returns ------- numpy.ndarray - The surrogate matrix, of shape timeseries.shape, n_surr + The surrogate matrix, of shape ``(timeseries.shape, n_surr)``. Raises ------ @@ -233,14 +232,14 @@ def test_significance( return_masked=False, mean=False, ): - """ - Test the significance of the empirical data against surrogates. + """Test the significance of the empirical data against surrogates. Two methods are implemented, 'Bernoulli' and 'frequentist'. - - 'frequentist' is a group or single subject test. It tests that the + + * 'frequentist' is a group or single subject test. It tests that the empirical data are in the highest (or lowest) percentile (where the percentile is defined by p/2). - - 'Bernoulli' is a group test. It tests that the number of subjects for + * 'Bernoulli' is a group test. It tests that the number of subjects for which the empirical data is higher (or lower) than a set of surrogates (frequentist approach) is at the tail of a binomial cumulative distribution (where 'tail' is defined by p). @@ -292,7 +291,6 @@ def test_significance( different from the data shape. NotImplementedError If any other method rather than those listed above is selected. - """ # #!# Check that the surrogate shape has parcels in the first axis! # If provided, append data to surr diff --git a/nigsp/operations/timeseries.py b/nigsp/operations/timeseries.py index 9351222..23d260b 100644 --- a/nigsp/operations/timeseries.py +++ b/nigsp/operations/timeseries.py @@ -31,7 +31,7 @@ def normalise_ts(timeseries, globally=False): timeseries : numpy.ndarray The input timeseries. It is assumed that the second dimension is time. globally : bool, optional - If True, normalise timeseries across the first two axes + If True, normalise timeseries across the first two axes. Returns ------- @@ -71,7 +71,8 @@ def spc_ts(timeseries, globally=False): timeseries : numpy.ndarray The input timeseries. It is assumed that the second dimension is time. globally : bool, optional - If True, SPC timeseries across the first two axes (mainly for similarity with other functions.) + If True, SPC timeseries across the first two axes (mainly for similarity with + other functions.) Returns ------- @@ -143,11 +144,11 @@ def rescale_ts(timeseries, vmin=0, vmax=1, globally=False): timeseries : numpy.ndarray The input timeseries. It is assumed that the second dimension is time. vmin : float, optional - The minimum value to scale between + The minimum value to scale between. vmax : float, optional - The maximum value to scale between + The maximum value to scale between. globally : bool, optional - If True, rescale timeseries across the first two axes + If True, rescale timeseries across the first two axes. Returns ------- @@ -185,14 +186,14 @@ def resize_ts(timeseries, resize=None, globally=False): The input timeseries. It is assumed that the second dimension is time. resize : 'spc', 'norm', 'gnorm', 'demean', 'gdemean' tuple, list, or None, optional Whether to resize the signal or not before plotting. - If 'spc', compute signal percentage change - If 'norm', normalise signals (z-score) - If 'demean', remove signal average - If 'gsr', remove global signal (average across points) - If tuple or list, rescale signals between those two values - If None, don't do anything (default) + If 'spc', compute signal percentage change. + If 'norm', normalise signals (z-score). + If 'demean', remove signal average. + If 'gsr', remove global signal (average across points). + If tuple or list, rescale signals between those two values. + If None, don't do anything (default). globally : bool, optional - If True, rescale timeseries across the first two axes + If True, rescale timeseries across the first two axes. Returns ------- @@ -359,12 +360,12 @@ def graph_filter(timeseries, eigenvec, freq_idx, keys=["low", "high"]): (more or less) equal parts - i.e. the index of the first frequency in the "high" component. keys : list, optional - The keys to call the split parts with + The keys to call the split parts with. Returns ------- dict of numpy.ndarray - Return first the split eigenvectors + Return first the split eigenvectors. dict of numpy.ndarray Return second the projected split eigenvectors onto the timeseries. diff --git a/nigsp/utils.py b/nigsp/utils.py index 61060f7..4933614 100644 --- a/nigsp/utils.py +++ b/nigsp/utils.py @@ -23,18 +23,19 @@ def pairwise(iterable): Parameters ---------- iterable : any iterable object - The object to iterate through + The object to iterate through. Returns ------- tuple - The couple of adjacent elements + The couple of adjacent elements. Notes ----- The original function is: https://docs.python.org/3/library/itertools.html#itertools.pairwise Credit to the Python Software Foundation, this function is under BSD licence. - To be replaced by itertools' pairwise import once support for python < 3.10 is dropped + To be replaced by itertools' pairwise import once support for python < 3.10 is + dropped. """ a, b = tee(iterable, 2) next(b, None) @@ -48,27 +49,27 @@ def change_var_type(var, dtype, varname="an input variable", stop=True, silent=F Parameters ---------- var : str, int, or float - Variable to change type of + Variable to change type of. dtype : type - Type to change `var` to + Type to change ``var`` to. varname : str, optional - The name of the variable + The name of the variable. stop : bool, optional - If True, raises TypeError if `var` is not of `dtype` + If True, raises TypeError if ``var`` is not of ``dtype``. silent : bool, optional - If True, don't return any message + If True, don't return any message. Returns ------- int, float, str, list, or var - The given `var` in the given `dtype`, or `var` if '' or None + The given `var` in the given ``dtype``, or ``var`` if ``''`` or None Raises ------ NotImplementedError - If dtype is not int, float, str, or list + If dtype is not int, float, str, or list. TypeError - If variable var is not of type and stop is True + If variable var is not of type and stop is True. """ if type(var) is not dtype and stop: if varname != "an input variable": @@ -105,22 +106,21 @@ def change_var_type(var, dtype, varname="an input variable", stop=True, silent=F def prepare_ndim_iteration(data, idx): - """ - Reshape data to have idx+1 dimensions. + """Reshape data to have ``idx+1`` dimensions. This should allow iterations over unknown numbers of dimensions above idx when needed. Parameters ---------- - data : np.ndarray - The data to reiterate over + data : array + The data to reiterate over. idx : int - The number of dimensions that should be fixed + The number of dimensions that should be fixed. Returns ------- - np.ndarray, np.ndarray + array The reshaped data and an empty array like it. """ if data.ndim > idx + 1: From 170d51375e5e9f165f6cf40e85d67aee86f948fa Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Thu, 17 Aug 2023 11:34:17 +0000 Subject: [PATCH 8/9] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/conf.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/conf.py b/docs/conf.py index 9e89a55..ba0a1a8 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -221,6 +221,7 @@ "within_subsection_order": FileNameSortKey, } + # -- Generate API automagically ----------------------------------------------- def run_apidoc(_): from sphinx.ext.apidoc import main @@ -237,6 +238,7 @@ def run_apidoc(_): # -- Final Setup ------------------------------------------------------------- + # https://github.com/rtfd/sphinx_rtd_theme/issues/117 # launch setup def setup(app): # noqa From f4f835184311e6d6c7a18d7ec517ffc0968de661 Mon Sep 17 00:00:00 2001 From: Mathieu Scheltienne Date: Thu, 17 Aug 2023 14:12:14 +0200 Subject: [PATCH 9/9] Update nigsp/utils.py fix typo --- nigsp/utils.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/nigsp/utils.py b/nigsp/utils.py index 4933614..bd94013 100644 --- a/nigsp/utils.py +++ b/nigsp/utils.py @@ -120,7 +120,7 @@ def prepare_ndim_iteration(data, idx): Returns ------- - array + array, array The reshaped data and an empty array like it. """ if data.ndim > idx + 1: