Convert docstrings to numpydoc convention. (#72)

* Start converting docstrings to numpydoc convention.

* Mark a few more to change.

* Add linting job.

* Docstrings!

* Fix kwargs.

* Update core.py

* Some docstrings for tests.

* More work.

* More docstrings.

* More docstrings.

* Fix up examples.

* Fix up docstrings more.

Author: tsalo

.github/workflows/testing.yml

@@ -59,3 +59,26 @@ jobs:
       - name: 'Upload coverage to CodeCov'
         uses: codecov/codecov-action@v1
         if: success()
+
+  flake8-lint:
+    runs-on: ubuntu-latest
+    name: Lint with flake8
+    steps:
+      - name: Check out source repository
+        uses: actions/checkout@v2
+
+      - name: Set up Python environment
+        uses: actions/setup-python@v2
+        with:
+          python-version: "3.7"
+
+      - name: "Install the package"
+        shell: bash {0}
+        run: |
+          python -m pip install --progress-bar off --upgrade pip setuptools wheel
+          python -m pip install -e .[tests]
+
+      - name: "Run flake8"
+        shell: bash {0}
+        run: |
+          flake8 pymare

docs/Makefile

@@ -15,6 +15,11 @@ help:
 clean:
 	rm -r _build generated auto_examples
 
+html-noplot:
+	$(SPHINXBUILD) -D plot_gallery=0 -b html $(ALLSPHINXOPTS) $(SOURCEDIR) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
 .PHONY: help clean Makefile
 
 # Catch-all target: route all unknown targets to Sphinx using the new

docs/api.rst

@@ -44,8 +44,9 @@ API
    estimators.SampleSizeBasedLikelihoodEstimator
    estimators.StanMetaRegression
    estimators.Hedges
-   estimators.Stouffers
-   estimators.Fishers
+   estimators.StoufferCombinationTest
+   estimators.FisherCombinationTest
+   estimators.estimators.BaseEstimator
 
 
 .. _api_results_ref:

docs/conf.py

@@ -191,8 +191,8 @@
 
 def setup(app):
     """From https://github.com/rtfd/sphinx_rtd_theme/issues/117."""
-    app.add_stylesheet("theme_overrides.css")
-    app.add_stylesheet("pymare.css")
+    app.add_css_file("theme_overrides.css")
+    app.add_css_file("pymare.css")
     app.connect("autodoc-process-docstring", generate_example_rst)
     # Fix to https://github.com/sphinx-doc/sphinx/issues/7420
     # from https://github.com/life4/deal/commit/7f33cbc595ed31519cefdfaaf6f415dada5acd94

examples/01_basic_io/plot_create_dataset.py

@@ -7,16 +7,17 @@
  Creating a dataset
 ===================
 
-In PyMARE, operations are performed on :class:`pymare.core.Dataset` objects.
+In PyMARE, operations are performed on :class:`~pymare.core.Dataset` objects.
 Datasets are very lightweight objects that store the data used for
 meta-analyses, including study-level estimates (y), variances (v),
 predictors (X), and sample sizes (n).
 """
+from pprint import pprint
+
 ###############################################################################
 # Start with the necessary imports
 # --------------------------------
 import pandas as pd
-from pprint import pprint
 
 from pymare import core
 

examples/02_meta-analysis/plot_meta-analysis_walkthrough.py

@@ -113,7 +113,7 @@ def var_to_ci(y, v, n):
 ###############################################################################
 # Create a Dataset object containing the data
 # --------------------------------------------
-dset = pymare.Dataset(y=y, X=None, v=v, n=n, add_intercept=True)
+dset = pymare.core.Dataset(y=y, X=None, v=v, n=n, add_intercept=True)
 
 # Here is a dictionary to house results across models
 results = {}
@@ -123,8 +123,8 @@ def var_to_ci(y, v, n):
 # -----------------------------------------------------------------------------
 # When you have ``z`` or ``p``:
 #
-# - :class:`pymare.estimators.Stouffers`
-# - :class:`pymare.estimators.Fishers`
+# - :class:`pymare.estimators.StoufferCombinationTest`
+# - :class:`pymare.estimators.FisherCombinationTest`
 #
 # When you have ``y`` and ``v`` and don't want to estimate between-study variance:
 #
@@ -149,7 +149,7 @@ def var_to_ci(y, v, n):
 # `````````````````````````````````````````````````````````````````````````````
 # The two combination models in PyMARE are Stouffer's and Fisher's Tests.
 #
-# Notice that these models don't use :class:`pymare.core.Dataset` objects.
+# Notice that these models don't use :class:`~pymare.core.Dataset` objects.
 stouff = pymare.estimators.StoufferCombinationTest()
 stouff.fit(z[:, None])
 print("Stouffers")

pymare/__init__.py

@@ -1,4 +1,4 @@
-"""PyMARE: Python Meta-Analysis & Regression Engine"""
+"""PyMARE: Python Meta-Analysis & Regression Engine."""
 from .core import Dataset, meta_regression
 from .effectsize import OneSampleEffectSizeConverter, TwoSampleEffectSizeConverter
 
@@ -12,3 +12,4 @@
 from . import _version
 
 __version__ = _version.get_versions()["version"]
+del _version

pymare/core.py

@@ -19,26 +19,39 @@
 class Dataset:
     """Container for input data and arguments to estimators.
 
-    Args:
-        y (array-like, str): 1d array of study-level estimates with length K,
-            or the name of the column in data containing the y values.
-        v (array-like, str, optional): 1d array of study-level variances with
-            length K, or the name of the column in data containing v values.
-        X (array-like, list, optional): 1d or 2d array containing study-level
-            predictors (dimensions K x P), or a list of strings giving the
-            names of the columns in data containing the X values.
-        n (array-like, str, optional): 1d array of study-level sample sizes
-            (length K), or the name of the corresponding column in data.
-        data (pandas.DataFrame, optional): A pandas DataFrame containing y, v,
-            X, and/or n values. By default, columns are expected to have the
-            same names as arguments (e.g., the y values will be expected in the
-            'y' column). This can be modified by passing strings giving column
-            names to any of the y, v, X, or n arguments.
-        X_names ([str], optional): List of length P containing the names of the
-            predictors. Ignored if data is provided (use X to specify columns).
-        add_intercept (bool, optional): If True, an intercept column is
-            automatically added to the predictor matrix. If False, the
-            predictors matrix is passed as-is to estimators.
+    Parameters
+    ----------
+    y : None or :obj:`numpy.ndarray` of shape (K,) or :obj:`str`, optional
+        1d array of study-level estimates with length K, or the name of the column in data
+        containing the y values.
+        Default is None.
+    v : None or :obj:`numpy.ndarray` of shape (K,) or :obj:`str`, optional
+        1d array of study-level variances with length K, or the name of the column in data
+        containing v values.
+        Default is None.
+    X : None or :obj:`numpy.ndarray` of shape (K,[P]) or :obj:`list` of :obj:`str`, optional
+        1d or 2d array containing study-level predictors (dimensions K x P),
+        or a list of strings giving the names of the columns in data containing the X values.
+        Default is None.
+    n : None or :obj:`numpy.ndarray` of shape (K,) or :obj:`str`, optional
+        1d array of study-level sample sizes (length K), or the name of the corresponding column
+        in ``data``.
+        Default is None.
+    data : None or :obj:`pandas.DataFrame`, optional
+        A pandas DataFrame containing y, v, X, and/or n values.
+        By default, columns are expected to have the same names as arguments
+        (e.g., the y values will be expected in the 'y' column).
+        This can be modified by passing strings giving column names to any of the ``y``, ``v``,
+        ``X``, or ``n`` arguments.
+        Default is None.
+    X_names : None or :obj:`list` of :obj:`str`, optional
+        List of length P containing the names of the predictors.
+        Ignored if ``data`` is provided (use ``X`` to specify columns).
+        Default is None.
+    add_intercept : :obj:`bool`, optional
+        If True, an intercept column is automatically added to the predictor matrix.
+        If False, the predictors matrix is passed as-is to estimators.
+        Default is True.
     """
 
     def __init__(
@@ -94,47 +107,65 @@ def meta_regression(
     alpha=0.05,
     **kwargs,
 ):
-    """Fits the standard meta-regression/meta-analysis model to provided data.
-
-    Args:
-        y (array-like, str): 1d array of study-level estimates with length K,
-            or the name of the column in data containing the y values.
-        v (array-like, str, optional): 1d array of study-level variances with
-            length K, or the name of the column in data containing v values.
-        X (array-like, list, optional): 1d or 2d array containing study-level
-            predictors (dimensions K x P), or a list of strings giving the
-            names of the columns in data containing the X values.
-        n (array-like, str, optional): 1d array of study-level sample sizes
-            (length K), or the name of the corresponding column in data.
-        data (pandas.DataFrame, pymare.Dataset, optional): If a Dataset
-            instance is passed, the y, v, X, n and associated arguments are
-            ignored, and data is passed directly to the selected estimator.
-            If a pandas DataFrame, y, v, X and/or n values are taken from the
-            DF columns. By default, columns are expected to have the same names
-            as arguments (e.g., the y values will be expected in the 'y'
-            column). This can be modified by passing strings giving column
-            names to any of the y, v, X, or n arguments.
-        X_names ([str], optional): List of length P containing the names of the
-            predictors. Ignored if data is provided (use X to specify columns).
-        add_intercept (bool, optional): If True, an intercept column is
-            automatically added to the predictor matrix. If False, the
-            predictors matrix is passed as-is to estimators.
-        method (str, optional): Name of estimation method. Defaults to 'ML'.
-            Supported estimators include:
-                * 'ML': Maximum-likelihood estimator
-                * 'REML': Restricted maximum-likelihood estimator
-                * 'DL': DerSimonian-Laird estimator
-                * 'HE': Hedges estimator
-                * 'WLS' or 'FE': Weighted least squares (fixed effects only)
-                * 'Stan': Full Bayesian MCMC estimation via Stan
-        ci_method (str, optional): Estimation method to use when computing
-            uncertainty estimates. Currently only 'QP' is supported. Defaults
-            to 'QP'. Ignored if method == 'Stan'.
-        alpha (float, optional): Desired alpha level (CIs will have 1 - alpha
-            coverage). Defaults to 0.05.
-        kwargs: Optional keyword arguments to pass onto the chosen estimator.
-
-    Returns:
+    """Fit the standard meta-regression/meta-analysis model to provided data.
+
+    Parameters
+    ----------
+    y : None or :obj:`numpy.ndarray` of shape (K,) or :obj:`str`, optional
+        1d array of study-level estimates with length K, or the name of the column in data
+        containing the y values.
+        Default is None.
+    v : None or :obj:`numpy.ndarray` of shape (K,) or :obj:`str`, optional
+        1d array of study-level variances with length K, or the name of the column in data
+        containing v values.
+        Default is None.
+    X : None or :obj:`numpy.ndarray` of shape (K,[P]) or :obj:`list` of :obj:`str`, optional
+        1d or 2d array containing study-level predictors (dimensions K x P),
+        or a list of strings giving the names of the columns in data containing the X values.
+        Default is None.
+    n : None or :obj:`numpy.ndarray` of shape (K,) or :obj:`str`, optional
+        1d array of study-level sample sizes (length K), or the name of the corresponding column
+        in ``data``.
+        Default is None.
+    data : None or :obj:`pandas.DataFrame` or :obj:`~pymare.core.Dataset`, optional
+        If a Dataset instance is passed, the y, v, X, n and associated arguments are ignored,
+        and data is passed directly to the selected estimator.
+        If a pandas DataFrame, y, v, X and/or n values are taken from the DF columns.
+        By default, columns are expected to have the same names as arguments
+        (e.g., the y values will be expected in the 'y' column).
+        This can be modified by passing strings giving column names to any of the y, v, X, or n
+        arguments.
+    X_names : None or :obj:`list` of :obj:`str`, optional
+        List of length P containing the names of the predictors.
+        Ignored if ``data`` is provided (use ``X`` to specify columns).
+        Default is None.
+    add_intercept : :obj:`bool`, optional
+        If True, an intercept column is automatically added to the predictor matrix.
+        If False, the predictors matrix is passed as-is to estimators.
+        Default is True.
+    method : {"ML", "REML", "DL", "HE", "WLS", "FE", "Stan"}, optional
+        Name of estimation method. Default is 'ML'.
+        Supported estimators include:
+
+            - 'ML': Maximum-likelihood estimator
+            - 'REML': Restricted maximum-likelihood estimator
+            - 'DL': DerSimonian-Laird estimator
+            - 'HE': Hedges estimator
+            - 'WLS' or 'FE': Weighted least squares (fixed effects only)
+            - 'Stan': Full Bayesian MCMC estimation via Stan
+    ci_method : {"QP"}, optional
+        Estimation method to use when computing uncertainty estimates.
+        Currently only 'QP' is supported. Default is 'QP'.
+        Ignored if ``method == 'Stan'``.
+    alpha : :obj:`float`, optional
+        Desired alpha level (CIs will have 1 - alpha coverage). Default is 0.05.
+    **kwargs
+        Optional keyword arguments to pass onto the chosen estimator.
+
+    Returns
+    -------
+    :obj:`~pymare.results.MetaRegressionResults` or \
+        :obj:`~pymare.results.BayesianMetaRegressionResults`
         A MetaRegressionResults or BayesianMetaRegressionResults instance,
         depending on the specified method ('Stan' will return the latter; all
         other methods return the former).

pymare/effectsize/__init__.py

@@ -1,3 +1,4 @@
+"""Tools for converting between effect-size measures."""
 from .base import (
     OneSampleEffectSizeConverter,
     TwoSampleEffectSizeConverter,