Use BibTeX for references and improve docstrings (#86)

* Use BibTeX and enhance docstrings.

* Update estimators.py

* More improvements.

Author: tsalo

docs/api.rst

@@ -91,7 +91,6 @@ API
 
    :template: function.rst
    effectsize.solve_system
-   effectsize.Expression
    effectsize.select_expressions
    effectsize.compute_measure
 

docs/conf.py

@@ -53,6 +53,7 @@
     "sphinx_copybutton",  # for copying code snippets
     "sphinx_gallery.gen_gallery",  # example gallery
     "sphinxarg.ext",  # argparse
+    "sphinxcontrib.bibtex",  # for foot-citations
     "recommonmark",  # markdown parser
 ]
 
@@ -188,6 +189,14 @@
 # Generate the plots for the gallery
 plot_gallery = True
 
+# -----------------------------------------------------------------------------
+# sphinxcontrib-bibtex
+# -----------------------------------------------------------------------------
+bibtex_bibfiles = ["./references.bib"]
+bibtex_style = "unsrt"
+bibtex_reference_style = "author_year"
+bibtex_footbibliography_header = ""
+
 
 def setup(app):
     """From https://github.com/rtfd/sphinx_rtd_theme/issues/117."""

docs/references.bib

@@ -0,0 +1,136 @@
+@article{brockwell2001comparison,
+  title={A comparison of statistical methods for meta-analysis},
+  author={Brockwell, Sarah E and Gordon, Ian R},
+  journal={Statistics in medicine},
+  volume={20},
+  number={6},
+  pages={825--840},
+  year={2001},
+  publisher={Wiley Online Library},
+  url={https://doi.org/10.1002/sim.650},
+  doi={10.1002/sim.650}
+}
+
+@article{cochran1954combination,
+  title={The combination of estimates from different experiments},
+  author={Cochran, William G},
+  journal={Biometrics},
+  volume={10},
+  number={1},
+  pages={101--129},
+  year={1954},
+  publisher={JSTOR}
+}
+
+@article{dersimonian1986meta,
+  title={Meta-analysis in clinical trials},
+  author={DerSimonian, Rebecca and Laird, Nan},
+  journal={Controlled clinical trials},
+  volume={7},
+  number={3},
+  pages={177--188},
+  year={1986},
+  publisher={Elsevier},
+  url={https://doi.org/10.1093/biomet/asx001},
+  doi={10.1093/biomet/asx001}
+}
+
+@article{fisher1946statistical,
+  title={Statistical methods for research workers.},
+  author={Fisher, Ronald Aylmer and others},
+  journal={Statistical methods for research workers.},
+  number={10th. ed.},
+  year={1946},
+  publisher={Oliver and Boyd}
+}
+
+@book{hedges2014statistical,
+  title={Statistical methods for meta-analysis},
+  author={Hedges, Larry V and Olkin, Ingram},
+  year={2014},
+  publisher={Academic press}
+}
+
+@article{higgins2002quantifying,
+  title={Quantifying heterogeneity in a meta-analysis},
+  author={Higgins, Julian PT and Thompson, Simon G},
+  journal={Statistics in medicine},
+  volume={21},
+  number={11},
+  pages={1539--1558},
+  year={2002},
+  publisher={Wiley Online Library}
+}
+
+@article{kosmidis2017improving,
+  title={Improving the accuracy of likelihood-based inference in meta-analysis and meta-regression},
+  author={Kosmidis, Ioannis and Guolo, Annamaria and Varin, Cristiano},
+  journal={Biometrika},
+  volume={104},
+  number={2},
+  pages={489--496},
+  year={2017},
+  publisher={Oxford University Press},
+  url={https://doi.org/10.1093/biomet/asx001},
+  doi={10.1093/biomet/asx001}
+}
+
+@article{sangnawakij2019meta,
+  title={Meta-analysis without study-specific variance information: Heterogeneity case},
+  author={Sangnawakij, Patarawan and B{\"o}hning, Dankmar and Niwitpong, Sa-Aat and Adams, Stephen and Stanton, Michael and Holling, Heinz},
+  journal={Statistical Methods in Medical Research},
+  volume={28},
+  number={1},
+  pages={196--210},
+  year={2019},
+  publisher={SAGE Publications Sage UK: London, England},
+  url={https://doi.org/10.1177/0962280217718867},
+  doi={10.1177/0962280217718867}
+}
+
+@article{stouffer1949american,
+  title={The american soldier: Adjustment during army life.(studies in social psychology in world war ii), vol. 1},
+  author={Stouffer, Samuel A and Suchman, Edward A and DeVinney, Leland C and Star, Shirley A and Williams Jr, Robin M},
+  journal={Studies in social psychology in World War II},
+  year={1949},
+  publisher={Princeton Univ. Press}
+}
+
+@article{veroniki2016methods,
+  title={Methods to estimate the between-study variance and its uncertainty in meta-analysis},
+  author={Veroniki, Areti Angeliki and Jackson, Dan and Viechtbauer, Wolfgang and Bender, Ralf and Bowden, Jack and Knapp, Guido and Kuss, Oliver and Higgins, Julian PT and Langan, Dean and Salanti, Georgia},
+  journal={Research synthesis methods},
+  volume={7},
+  number={1},
+  pages={55--79},
+  year={2016},
+  publisher={Wiley Online Library},
+  url={https://doi.org/10.1002/jrsm.1164},
+  doi={10.1002/jrsm.1164}
+}
+
+@article{viechtbauer2007confidence,
+  title={Confidence intervals for the amount of heterogeneity in meta-analysis},
+  author={Viechtbauer, Wolfgang},
+  journal={Statistics in medicine},
+  volume={26},
+  number={1},
+  pages={37--52},
+  year={2007},
+  publisher={Wiley Online Library},
+  url={https://doi.org/10.1002/sim.2514},
+  doi={10.1002/sim.2514}
+}
+
+@article{winkler2016non,
+  title={Non-parametric combination and related permutation tests for neuroimaging},
+  author={Winkler, Anderson M and Webster, Matthew A and Brooks, Jonathan C and Tracey, Irene and Smith, Stephen M and Nichols, Thomas E},
+  journal={Human brain mapping},
+  volume={37},
+  number={4},
+  pages={1486--1511},
+  year={2016},
+  publisher={Wiley Online Library},
+  url={https://doi.org/10.1002/hbm.23115},
+  doi={10.1002/hbm.23115}
+}

pymare/core.py

@@ -24,34 +24,34 @@ class Dataset:
     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.
+        Default = 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.
+        Default = 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.
+        Default = 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.
+        Default = 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.
+        Default = 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.
+        Default = 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.
+        Default = True.
     """
 
     def __init__(
@@ -114,19 +114,19 @@ def meta_regression(
     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.
+        Default = 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.
+        Default = 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.
+        Default = 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.
+        Default = 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.
@@ -138,13 +138,13 @@ def meta_regression(
     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.
+        Default = 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.
+        Default = True.
     method : {"ML", "REML", "DL", "HE", "WLS", "FE", "Stan"}, optional
-        Name of estimation method. Default is 'ML'.
+        Name of estimation method. Default = 'ML'.
         Supported estimators include:
 
             - 'ML': Maximum-likelihood estimator
@@ -155,10 +155,10 @@ def meta_regression(
             - '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'.
+        Currently only 'QP' is supported. Default = 'QP'.
         Ignored if ``method == 'Stan'``.
     alpha : :obj:`float`, optional
-        Desired alpha level (CIs will have 1 - alpha coverage). Default is 0.05.
+        Desired alpha level (CIs will have 1 - alpha coverage). Default = 0.05.
     **kwargs
         Optional keyword arguments to pass onto the chosen estimator.
 

pymare/effectsize/base.py

@@ -25,7 +25,7 @@ def solve_system(system, known_vars=None):
         A dictionary of known variables to use
         when evaluating the solution. Keys are the names of parameters
         (e.g., 'sem', 't'), values are numerical data types (including
-        numpy arrays). Default is None.
+        numpy arrays). Default = None.
 
     Returns
     -------
@@ -134,7 +134,7 @@ def update_data(self, incremental=False, **kwargs):
         incremental : :obj:`bool`, optional
             If True, updates data incrementally (i.e., existing data will be preserved unless
             they're overwritten by incoming keys). If False, all existing data is dropped first.
-            Default is False.
+            Default = False.
         **kwargs
             Data values or arrays; keys are the names of the quantities.
             All inputs to ``__init__`` are valid.
@@ -231,7 +231,7 @@ class OneSampleEffectSizeConverter(EffectSizeConverter):
         Column names must match the controlled names listed below for
         kwargs. If additional kwargs are provided, they will take
         precedence over the values in the data frame.
-        Default is None.
+        Default = None.
     m : None or :obj:`numpy.ndarray`, optional
         Means or other continuous estimates
     sd : None or :obj:`numpy.ndarray`, optional

pymare/estimators/combination.py

@@ -62,14 +62,15 @@ def summary(self):
 class StoufferCombinationTest(CombinationTest):
     """Stouffer's Z-score meta-analysis method.
 
-    Takes a set of independent z-scores and combines them via Stouffer's method
-    to produce a fixed-effect estimate of the combined effect.
+    Takes a set of independent z-scores and combines them via Stouffer's
+    :footcite:p:`stouffer1949american` method to produce a fixed-effect estimate of the combined
+    effect.
 
     Parameters
     ----------
     mode : {"directed", "undirected", "concordant"}, optional
-        The type of test to perform-- i.e., what null hypothesis to
-        reject. See Winkler et al. (2016) for details.
+        The type of test to perform-- i.e., what null hypothesis to reject.
+        See :footcite:t:`winkler2016non` for details.
         Valid options are:
 
         -   'directed': tests a directional hypothesis--i.e., that the
@@ -99,6 +100,10 @@ class StoufferCombinationTest(CombinationTest):
         users should instead opt for 'directed' or 'concordant'.
     (3) This estimator does not support meta-regression; any moderators
         passed in to fit() as the X array will be ignored.
+
+    References
+    ----------
+    .. footbibliography::
     """
 
     # Maps Dataset attributes onto fit() args; see BaseEstimator for details.
@@ -119,14 +124,18 @@ def p_value(self, z, w=None):
 class FisherCombinationTest(CombinationTest):
     """Fisher's method for combining p-values.
 
-    Takes a set of independent z-scores and combines them via Fisher's method
-    to produce a fixed-effect estimate of the combined effect.
+    Takes a set of independent z-scores and combines them via Fisher's
+    :footcite:p:`fisher1946statistical` method to produce a fixed-effect estimate of the combined
+    effect.
 
+    Parameters
+    ----------
     mode : {"directed", "undirected", "concordant"}, optional
-        The type of test to perform-- i.e., what null hypothesis to
-        reject. See Winkler et al. (2016) for details. Valid options are:
+        The type of test to perform-- i.e., what null hypothesis to reject.
+        See :footcite:t:`winkler2016non` for details.
+        Valid options are:
 
-            -  'directed': tests a directional hypothesis--i.e., that the
+            -   'directed': tests a directional hypothesis--i.e., that the
                 observed value is consistently greater than 0 in the input
                 studies. This is the default.
             -   'undirected': tests an undirected hypothesis--i.e., that the
@@ -153,6 +162,10 @@ class FisherCombinationTest(CombinationTest):
         users should instead opt for 'directed' or 'concordant'.
     (3) This estimator does not support meta-regression; any moderators
         passed in to fit() as the X array will be ignored.
+
+    References
+    ----------
+    .. footbibliography::
     """
 
     # Maps Dataset attributes onto fit() args; see BaseEstimator for details.