diff --git a/docs/_static/css/custom.css b/docs/_static/css/custom.css new file mode 100644 index 00000000..09792118 --- /dev/null +++ b/docs/_static/css/custom.css @@ -0,0 +1,36 @@ +/* -------------------- THEME OVERRIDES -------------------- */ + +html[data-theme="light"], +html[data-theme="dark"] { + --pst-color-primary: #4583ec; + --pst-color-secondary: #d46700; + --pst-color-table-row-zebra-low-bg: var(--bs-table-bg); + --pst-color-table-row-hover-bg: transparent; + --pst-color-inline-code: var(--pst-color-text-base); +} + +html[data-theme="light"] { + --pst-color-inline-code-links: #00358f; +} + +html[data-theme="dark"] { + --pst-color-inline-code-links: #00caeb; +} + +#pst-back-to-top:hover { + background-color: #a95200; +} + +table caption { + text-align: left; +} + +/* -------------------- NAV BAR-------------------- */ + +html[data-theme="dark"] .navbar-brand p { + color: white; +} + +html[data-theme="dark"] .navbar-brand img { + filter: invert(1); +} diff --git a/docs/_static/style.css b/docs/_static/style.css deleted file mode 100644 index 6ee0946c..00000000 --- a/docs/_static/style.css +++ /dev/null @@ -1,51 +0,0 @@ -/* */ -body { - color: #444444 !important; - font-family: Sans-Serif !important; -} - -h1 { font-size: 36px !important; } -h2 { font-size: 28px !important; } -h3 { font-size: 24px !important; } -h4 { font-size: 18px !important; } -h5 { font-size: 14px !important; } -h6 { font-size: 10px !important; } - -footer a{ - color: #4c72b0 !important; -} -a.reference { - color: #4c72b0 !important; -} - -blockquote p { - font-size: 14px !important; -} - -blockquote { - padding-top: 4px !important; - padding-bottom: 4px !important; - margin: 4 4 4px !important; -} - -code { - color: #49759c !important; - background-color: #ffffff !important; -} - -.alert-info { - background-color: #adb8cb !important; - border-color: #adb8cb !important; - color: #2c3e50 !important; -} - -.function dt { - padding-top: 150px; - margin-top: -150px; - -webkit-background-clip: content-box; - background-clip: content-box; -} - -.wy-nav-content { - max-width: None !important; -} \ No newline at end of file diff --git a/docs/api.rst b/docs/api.rst index 8253339e..43a1f895 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -5,8 +5,6 @@ Functions ######### -.. contents:: Table of Contents - :depth: 2 ANOVA and T-test ---------------- diff --git a/docs/changelog.rst b/docs/changelog.rst index 2ea80d34..627eda3c 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -3,11 +3,6 @@ What's new ########## -.. contents:: Table of Contents - :depth: 2 - -************* - v0.5.4 (January 2024) --------------------- diff --git a/docs/citing.rst b/docs/citing.rst new file mode 100644 index 00000000..95eb2048 --- /dev/null +++ b/docs/citing.rst @@ -0,0 +1,47 @@ +.. _citing: + +Citation and logo +################# + +Citing +****** + +If you want to cite Pingouin, please use the publication in JOSS: + + Vallat, R. (2018). Pingouin: statistics in Python. *Journal of Open Source Software*, 3(31), 1026, `https://doi.org/10.21105/joss.01026 `_ + +Here is a ready-made BibTeX entry: + +.. highlight:: none + +:: + + @article{Vallat2018, + title = {Pingouin: statistics in Python}, + volume = {3}, + DOI = {10.21105/joss.01026}, + number = {31}, + journal = {Journal of Open Source Software}, + publisher = {The Open Journal}, + author = {Vallat, Raphael}, + year = {2018}, + month = nov, + pages = {1026} + } + + +Logo +**** + +Wide logo +========= +.. figure:: /pictures/logo_pingouin.png + :align: left + :alt: pingouin logo + +Quadratic logo +============== +.. figure:: /pictures/pingouin.png + :align: left + :alt: pingouin logo quadratic + \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py index e99dad8a..7868ed58 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,37 +1,42 @@ -#!/usr/bin/env python3 -# -*- coding: utf-8 -*- +# Configuration file for the Sphinx documentation builder. # -# pingouin documentation build configuration file, created by -# sphinx-quickstart on Sun Apr 1 17:42:21 2018. -# -# This file is execfile()d with the current directory set to its -# containing dir. -# -# Note that not all possible configuration values are present in this -# autogenerated file. -# -# All configuration values have a default; values that are commented out -# serve to show the default. +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html -# -- General configuration ------------------------------------------------ -# If your documentation needs a minimal Sphinx version, state it here. -# -# needs_sphinx = '1.0' +# -- Path setup -------------------------------------------------------------- + import os import sys import time import pingouin -import sphinx_bootstrap_theme -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. sys.path.insert(0, os.path.abspath("sphinxext")) + + +# -- Project information ----------------------------------------------------- + +project = "pingouin" +author = "Raphael Vallat" +copyright = "2018-{}, Raphael Vallat".format(time.strftime("%Y")) + +# sys.path.insert(0, os.path.abspath(os.path.pardir)) +version = pingouin.__version__ +release = pingouin.__version__ + +# Sphinx-issues configuration +issues_github_path = "raphaelvallat/pingouin" + + +# -- 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.mathjax", "sphinx.ext.doctest", - # 'sphinx.ext.viewcode', + "sphinx.ext.viewcode", "sphinx.ext.githubpages", "sphinx.ext.autosummary", "sphinx.ext.autodoc", @@ -39,20 +44,30 @@ "matplotlib.sphinxext.plot_directive", "numpydoc", "sphinx_copybutton", - "sphinx_panels", + "sphinx_design", + "notfound.extension", ] -# configure sphinx-copybutton -# https://github.com/executablebooks/sphinx-copybutton -copybutton_prompt_text = r">>> |\.\.\. |\$ " -copybutton_prompt_is_regexp = True +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +language = "en" + +# Path to templates +templates_path = ["_templates"] + +# The master toctree document. +master_doc = "index" + +# List of patterns, that match files and directories +# to ignore when looking for source files. +exclude_patterns = ["_build", "docstrings", "nextgen", "Thumbs.db", ".DS_Store"] -# sphinx_panels -panels_add_bootstrap_css = False +# The suffix(es) of source filenames. +source_suffix = ".rst" # Generate the API documentation when building autosummary_generate = True -numpydoc_show_class_members = False +numpydoc_show_class_members = True # FALSE ? # Include the example source for plots in API docs plot_include_source = True @@ -60,100 +75,69 @@ plot_html_show_formats = False plot_html_show_source_link = False -# The suffix(es) of source filenames. -# You can specify multiple suffix as a list of string: -# -# source_suffix = ['.rst', '.md'] -source_suffix = ".rst" - -# The master toctree document. -master_doc = "index" - -# General information about the project. -project = "pingouin" -author = "Raphael Vallat" -copyright = "2018-{}, Raphael Vallat".format(time.strftime("%Y")) - -# The version info for the project you're documenting, acts as replacement for -# |version| and |release|, also used in various other places throughout the -# built documents. -# -# The short X.Y version. -# The full version, including alpha/beta/rc tags. -sys.path.insert(0, os.path.abspath(os.path.pardir)) -version = pingouin.__version__ -release = pingouin.__version__ -# 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 patterns also effect to html_static_path and html_extra_path -exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] +# -- Options for HTML output ---------------------------------------------- -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = "sphinx" +html_theme = "pydata_sphinx_theme" +html_favicon = "pictures/pingouin_blue.svg" -# If true, `todo` and `todoList` produce output, else they produce nothing. -todo_include_todos = False +html_static_path = ["_static"] +html_css_files = ["css/custom.css"] -# -- Options for HTML output ---------------------------------------------- +html_show_sourcelink = True +html_copy_source = False -# Bootstrap theme -html_theme = "bootstrap" -html_theme_path = sphinx_bootstrap_theme.get_html_theme_path() html_theme_options = { - "source_link_position": "footer", - # 'navbar_title': ' ', # we replace this with an image - "bootswatch_theme": "readable", - "navbar_sidebarrel": False, - # 'nosidebar': True, - # 'navbar_site_name': "", - "navbar_pagenav": False, - "bootstrap_version": "3", - "navbar_class": "navbar", - "navbar_links": [ - ("Functions", "api"), - ("Guidelines", "guidelines"), - ("FAQ", "faq"), - ("What's new", "changelog"), - ("Contribute", "contributing"), + "logo": { + "text": project, + "image_light": "pictures/pingouin.svg", + "image_dark": "pictures/pingouin.svg", + "alt_text": "pingouin homepage", + }, + "navbar_persistent": ["search-button"], + "navbar_end": ["navbar-icon-links", "theme-switcher"], + "navbar_align": "left", + "header_links_before_dropdown": 3, + "back_to_top_button": True, + "show_prev_next": False, + "navigation_depth": 2, + "icon_links": [ + { + "name": "GitHub", + "url": "https://github.com/raphaelvallat/pingouin", + "icon": "fa-brands fa-github", + }, ], + "use_edit_page_button": True, + "pygments_light_style": "vs", + "pygments_dark_style": "monokai", } -html_logo = "pictures/pingouin.png" -html_favicon = "pictures/pingouin_blue.svg" - -# IMPORTANT: There is a misalignement of the Navbar when using Sphinx > 3.0! - -# -- Options for HTML output ------------------------------------------ - -# Output file base name for HTML help builder. -htmlhelp_basename = "pingouindoc" -html_static_path = ["_static"] -html_show_sourcelink = False -html_copy_source = False -templates_path = ["templates"] # To remove the searchbar - +html_sidebars = { + "citing": [], + "contributing": [], + "changelog": [], + "faq": [], + "guidelines": [], + "index": [], +} -def setup(app): - """Add custom CSS""" - app.add_css_file("style.css") +html_context = { + "github_user": "raphaelvallat", + "github_repo": "pingouin", + "github_version": "main", + "doc_path": "docs", +} # -- Intersphinx ------------------------------------------------ intersphinx_mapping = { - "numpy": ("http://docs.scipy.org/doc/numpy/", None), - "scipy": ("http://docs.scipy.org/doc/scipy/reference/", None), - "matplotlib": ("http://matplotlib.org/", None), + "numpy": ("https://numpy.org/doc/stable/", None), + "scipy": ("https://docs.scipy.org/doc/scipy/reference/", None), + "matplotlib": ("https://matplotlib.org/", None), "pandas": ("https://pandas.pydata.org/pandas-docs/stable/", None), - "statsmodels": ("http://www.statsmodels.org/stable/", None), + "statsmodels": ("https://www.statsmodels.org/stable/", None), "seaborn": ("https://seaborn.pydata.org/", None), - "sklearn": ("http://scikit-learn.org/stable", None), + "sklearn": ("https://scikit-learn.org/stable", None), } diff --git a/docs/contributing.rst b/docs/contributing.rst index e615f73b..1af1f985 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -1,7 +1,7 @@ .. _Contribute: Contribute to Pingouin -********************** +###################### There are many ways to contribute to Pingouin: reporting bugs or results that are inconsistent with other statistical softwares, adding new functions, improving the documentation, etc... @@ -45,11 +45,11 @@ All changes to the codebase must be properly documented. To ensure that document Build locally ^^^^^^^^^^^^^ -If you want to test the documentation locally, you will need to install the following packages: +If you want to test the documentation locally, you will need to install additional dependencies. They can be installed with the docs extra: .. code-block:: bash - $ pip install --upgrade sphinx sphinx_bootstrap_theme numpydoc sphinx-copybutton + $ pip install --upgrade pingouin[docs] and then within the ``pingouin/docs`` directory do: diff --git a/docs/faq.rst b/docs/faq.rst index 428e64f4..093480ee 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -4,20 +4,12 @@ FAQ ### Installation ------------- +************ .. ----------------------------- INTRO ----------------------------- -.. raw:: html - -
-
-
-
- How can I install Pingouin on my computer? -
-
-
-
+ +How can I install Pingouin on my computer? +========================================== To install Pingouin, open a command prompt (or Terminal or Anaconda Prompt) and type: @@ -44,20 +36,9 @@ Now, let's do a simple paired T-test using Pingouin: .. ----------------------------- IMPORT ----------------------------- -.. raw:: html - -
-
-
-
-
-
- How to import and use Pingouin? -
-
-
-
+How to import and use Pingouin? +=============================== .. code-block:: python @@ -72,38 +53,16 @@ Now, let's do a simple paired T-test using Pingouin: ttest(x, y) .. ----------------------------- STATSMODELS ----------------------------- -.. raw:: html -
-
-
- -
-
-
- What are the differences between statsmodels and Pingouin? -
-
-
-
+What are the differences between statsmodels and Pingouin? +========================================================== `Statsmodels `_ is a great statistical Python package that provides several advanced functions (regression, GLM, time-series analysis) as well as an R-like syntax for fitting models. However, statsmodels can be quite hard to grasp and use for Python beginners and/or users who just want to perform simple statistical tests. The goal of Pingouin is not to replace statsmodels but rather to provide some easy-to-use functions to perform the most widely-used statistical tests. In addition, Pingouin also provides some novel functions (to cite but a few: effect sizes, pairwise T-tests and correlations, ICC, repeated measures correlation, circular statistics...). .. ----------------------------- SCIPY ----------------------------- -.. raw:: html - -
-
-
-
-
-
- What are the differences between scipy.stats and Pingouin? -
-
-
-
+What are the differences between scipy.stats and Pingouin? +========================================================== The `scipy.stats `_ module provides several low-level statistical functions. However, most of these functions do not return a very detailed output (e.g. only the T- and p-values for a T-test). Most Pingouin functions are using the low-level SciPy funtions to provide a richer, more exhaustive, output. See for yourself!: @@ -118,11 +77,6 @@ The `scipy.stats `_ modul print(pg.ttest(x, y)) # Pingouin: returns a DataFrame with T-value, p-value, degrees of freedom, tail, Cohen d, power and Bayes Factor print(ttest_ind(x, y)) # SciPy: returns only the T- and p-values -.. raw:: html - -
-
- .. ############################################################################ .. ############################################################################ .. DATA @@ -130,19 +84,12 @@ The `scipy.stats `_ modul .. ############################################################################ Data ----- +**** .. ----------------------------- READING ----------------------------- -.. raw:: html -
-
-
- How can I load a .csv or .xlsx file in Python? -
-
-
-
+How can I load a .csv or .xlsx file in Python? +============================================== You need to use the :py:func:`pandas.read_csv` or :py:func:`pandas.read_excel` functions: @@ -153,40 +100,18 @@ You need to use the :py:func:`pandas.read_csv` or :py:func:`pandas.read_excel` f pd.read_excel('myfile.xlsx') # Load an Excel file .. ----------------------------- MISSING VALUES ----------------------------- -.. raw:: html - -
-
-
-
-
-
- How does Pingouin deal with missing values? -
-
-
-
+How does Pingouin deal with missing values? +=========================================== Pingouin hates missing values as much as you do! Most functions of Pingouin will automatically remove the missing values. In the case of paired measurements (e.g. paired T-test, correlation, or repeated measures ANOVA), a listwise deletion of missing values is performed, meaning that the entire row is removed. This is generally the best strategy if you have a large sample size and only a few missing values. However, this can be quite drastic if there are a lot of missing values in your data. In that case, it might be useful to look at `imputation methods (see Pandas documentation) `_, or use a linear mixed effect model instead, which natively supports missing values. However, the latter is not implemented in Pingouin. .. ----------------------------- LONG <--> WIDE FORMAT ----------------------------- -.. raw:: html -
-
-
- -
-
-
- What's the difference between wide format and long format data and how can I convert my data from one to the other? -
-
-
-
+What's the difference between wide format and long format data and how can I convert my data from one to the other? +=================================================================================================================== In wide format, each row represent a subject, and each column a measurement (e.g. "Pre", "Post"). This is the most convenient way for humans to look at repeated measurements. It typically results in spreadsheet with a larger number of columns than rows. An example of wide-format dataframe is shown below: @@ -220,20 +145,9 @@ The `Pandas `_ package provides some convenient func * From long-format to wide-format, use the :py:func:`pandas.pivot_table` function. .. ----------------------------- DESCRIPTIVE ----------------------------- -.. raw:: html - -
-
-
-
-
-
- Can I compute descriptive statistics with Pingouin? -
-
-
-
+Can I compute descriptive statistics with Pingouin? +=================================================== No, the central idea behind Pingouin is that all data manipulations and descriptive statistics should be first performed in Pandas (or NumPy). For example, to compute the mean, standard deviation, and quartiles of all the numeric columns of a pandas DataFrame, one can easily use the :py:meth:`pandas.DataFrame.describe` method: @@ -241,10 +155,6 @@ No, the central idea behind Pingouin is that all data manipulations and descript data.describe() -.. raw:: html - -
-
.. ############################################################################ .. ############################################################################ @@ -253,38 +163,20 @@ No, the central idea behind Pingouin is that all data manipulations and descript .. ############################################################################ Others ------- +****** .. ----------------------------- LICENSE ----------------------------- -.. raw:: html -
-
-
- Why is Pingouin licensed under the GNU-GPL v3? -
-
-
-
+Why is Pingouin licensed under the GNU-GPL v3? +============================================== Pingouin is licensed under the GNU General Public License v3.0 (GPL-3), which is less permissive than the BSD or MIT licenses. The reason for this is that Pingouin borrows extensively from R packages, which are all licensed under the GPL-3. To read more about what you can do and cannot do with a GPL-3 license, please visit `tldrlegal.com `_ or `choosealicense.com `_. .. ----------------------------- NEW RELEASES ----------------------------- -.. raw:: html -
-
-
- -
-
-
- How can I be notified of new releases? -
-
-
-
+How can I be notified of new releases? +====================================== You can click "Watch" on the `GitHub `_ of Pingouin: @@ -298,61 +190,14 @@ Whenever a new release is available, you can simply upgrade your version by typi pip install --upgrade pingouin .. ----------------------------- DONATION ----------------------------- -.. raw:: html - -
-
-
-
-
-
- I am not a programmer, how can I contribute to Pingouin? -
-
-
-
+I am not a programmer, how can I contribute to Pingouin? +======================================================== There are many ways to contribute to Pingouin, even if you are not a programmer, for example, reporting bugs or results that are inconsistent with other statistical softwares, improving the documentation and examples, or, even `buying the developers a coffee `_! .. ----------------------------- CITING PINGOUIN ----------------------------- -.. raw:: html - -
-
-
- -
-
-
- How can I cite Pingouin? -
-
-
-
- -To cite Pingouin, please use the publication in JOSS: - -* Vallat, R. (2018). Pingouin: statistics in Python. *Journal of Open Source Software*, 3(31), 1026, `https://doi.org/10.21105/joss.01026 `_ - -BibTeX: - -.. code-block:: latex - - @ARTICLE{Vallat2018, - title = "Pingouin: statistics in Python", - author = "Vallat, Raphael", - journal = "The Journal of Open Source Software", - volume = 3, - number = 31, - pages = "1026", - month = nov, - year = 2018 - } - -.. ----------------------------- END ----------------------------- -.. raw:: html - -
-
-
+ +How can I cite Pingouin? +======================== +Please go to :ref:`citing`. \ No newline at end of file diff --git a/docs/guidelines.rst b/docs/guidelines.rst index 76ed4811..bcaaaf5e 100644 --- a/docs/guidelines.rst +++ b/docs/guidelines.rst @@ -7,11 +7,8 @@ In this page, you will find a collection of flowcharts designed to help you choo which functions of Pingouin are adequate for your analysis. Click on the desired flowchart to view a full scale image with hyperlinks to the relevant documentation. -.. contents:: Table of Contents - :depth: 2 - ANOVA ------ +***** .. figure:: /pictures/flowchart/flowchart_one_way_ANOVA.svg :align: center @@ -40,7 +37,7 @@ Example code | Correlation ------------ +*********** .. figure:: /pictures/flowchart/flowchart_correlations.svg :align: center @@ -70,7 +67,7 @@ Example code | Non-parametric --------------- +************** .. figure:: /pictures/flowchart/flowchart_nonparametric.svg :align: center diff --git a/docs/index.rst b/docs/index.rst index d2c534f9..b6b72815 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -529,13 +529,6 @@ This program is provided with NO WARRANTY OF ANY KIND. Pingouin is still under h - `Johannes Elfner `_ - `Stefan Appelhoff `_ -How to cite Pingouin? -===================== - -If you want to cite Pingouin, please use the publication in JOSS: - -* Vallat, R. (2018). Pingouin: statistics in Python. *Journal of Open Source Software*, 3(31), 1026, `https://doi.org/10.21105/joss.01026 `_ - Acknowledgement =============== @@ -548,3 +541,15 @@ Several functions of Pingouin were inspired from R or Matlab toolboxes, includin - `robust correlations (Matlab) `_ - `repeated-measure correlation (R) `_ - `real-statistics.com `_ + + +.. toctree:: + :maxdepth: 1 + :hidden: + + Functions + Guidelines + FAQ + Changelog + Contribute + Cite \ No newline at end of file diff --git a/docs/pictures/pingouin.svg b/docs/pictures/pingouin.svg index c8a53cb2..8533f63e 100644 --- a/docs/pictures/pingouin.svg +++ b/docs/pictures/pingouin.svg @@ -1,11 +1,8 @@ - - Artboard 5 Copy - Created with Sketch. - - - - - + + + + + + + diff --git a/docs/pictures/pingouin_blue.svg b/docs/pictures/pingouin_blue.svg index 5de56af8..cab3a280 100644 --- a/docs/pictures/pingouin_blue.svg +++ b/docs/pictures/pingouin_blue.svg @@ -1,17 +1,12 @@ - - - + + Created with Sketch. - - - - - - + + + + + + \ No newline at end of file diff --git a/docs/templates/navbarsearchbox.html b/docs/templates/navbarsearchbox.html deleted file mode 100644 index e69de29b..00000000 diff --git a/docs/templates/search.html b/docs/templates/search.html deleted file mode 100644 index e69de29b..00000000 diff --git a/docs/templates/searchbox.html b/docs/templates/searchbox.html deleted file mode 100644 index e69de29b..00000000 diff --git a/docs/templates/searchresults.html b/docs/templates/searchresults.html deleted file mode 100644 index e69de29b..00000000 diff --git a/pyproject.toml b/pyproject.toml index 7a2f1782..f93d0593 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -48,6 +48,14 @@ test = [ # Ensure coverage is new enough for `source_pkgs`. "coverage[toml]>=5.3", ] +docs = [ + "sphinx>7.0.0", + "pydata_sphinx_theme", + "numpydoc", + "sphinx-copybutton", + "sphinx-design", + "sphinx-notfound-page", +] [project.urls] Homepage = "https://pingouin-stats.org/index.html"