PyMARE 0.0.12__tar.gz → 0.0.13__tar.gz

{pymare-0.0.12 → pymare-0.0.13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyMARE
-Version: 0.0.12
+Version: 0.0.13
 Summary: PyMARE: Python Meta-Analysis & Regression Engine
 Home-page: https://github.com/neurostuff/PyMARE
 Author: PyMARE developers
@@ -27,7 +27,7 @@ Requires-Dist: pandas
 Requires-Dist: scipy
 Requires-Dist: sympy
 Provides-Extra: doc
-Requires-Dist: m2r2; extra == "doc"
+Requires-Dist: m2r2>=1.1; extra == "doc"
 Requires-Dist: matplotlib; extra == "doc"
 Requires-Dist: mistune; extra == "doc"
 Requires-Dist: numpydoc; extra == "doc"
@@ -55,7 +55,7 @@ Requires-Dist: cmdstanpy<2,>=1.2; extra == "stan"
 Requires-Dist: arviz>=0.17; extra == "stan"
 Requires-Dist: scipy<1.13; python_version < "3.10" and extra == "stan"
 Provides-Extra: all
-Requires-Dist: m2r2; extra == "all"
+Requires-Dist: m2r2>=1.1; extra == "all"
 Requires-Dist: matplotlib; extra == "all"
 Requires-Dist: mistune; extra == "all"
 Requires-Dist: numpydoc; extra == "all"

{pymare-0.0.12 → pymare-0.0.13}/PyMARE.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyMARE
-Version: 0.0.12
+Version: 0.0.13
 Summary: PyMARE: Python Meta-Analysis & Regression Engine
 Home-page: https://github.com/neurostuff/PyMARE
 Author: PyMARE developers
@@ -27,7 +27,7 @@ Requires-Dist: pandas
 Requires-Dist: scipy
 Requires-Dist: sympy
 Provides-Extra: doc
-Requires-Dist: m2r2; extra == "doc"
+Requires-Dist: m2r2>=1.1; extra == "doc"
 Requires-Dist: matplotlib; extra == "doc"
 Requires-Dist: mistune; extra == "doc"
 Requires-Dist: numpydoc; extra == "doc"
@@ -55,7 +55,7 @@ Requires-Dist: cmdstanpy<2,>=1.2; extra == "stan"
 Requires-Dist: arviz>=0.17; extra == "stan"
 Requires-Dist: scipy<1.13; python_version < "3.10" and extra == "stan"
 Provides-Extra: all
-Requires-Dist: m2r2; extra == "all"
+Requires-Dist: m2r2>=1.1; extra == "all"
 Requires-Dist: matplotlib; extra == "all"
 Requires-Dist: mistune; extra == "all"
 Requires-Dist: numpydoc; extra == "all"

{pymare-0.0.12 → pymare-0.0.13}/PyMARE.egg-info/SOURCES.txt

@@ -32,6 +32,7 @@ pymare/resources/datasets/michael2013.json
 pymare/resources/datasets/michael2013.tsv
 pymare/tests/__init__.py
 pymare/tests/conftest.py
+pymare/tests/test_clubsandwich_alignment.py
 pymare/tests/test_combination_tests.py
 pymare/tests/test_core.py
 pymare/tests/test_datasets.py
@@ -39,12 +40,19 @@ pymare/tests/test_effectsize_base.py
 pymare/tests/test_effectsize_expressions.py
 pymare/tests/test_estimators.py
 pymare/tests/test_metafor_alignment.py
+pymare/tests/test_metafor_escalc.py
+pymare/tests/test_metafor_permutest.py
+pymare/tests/test_metafor_random_effects.py
 pymare/tests/test_results.py
 pymare/tests/test_robumeta_alignment.py
 pymare/tests/test_stan_estimators.py
 pymare/tests/test_stats.py
 pymare/tests/test_utils.py
 pymare/tests/utils.py
+pymare/tests/data/clubsandwich_reference.json
+pymare/tests/data/metafor_escalc_inputs.csv
+pymare/tests/data/metafor_escalc_reference.json
+pymare/tests/data/metafor_permutest_reference.json
 pymare/tests/data/metafor_reference.json
 pymare/tests/data/metafor_small_sample.csv
 pymare/tests/data/robumeta_correlated_effects.csv

{pymare-0.0.12 → pymare-0.0.13}/PyMARE.egg-info/requires.txt

@@ -4,7 +4,7 @@ scipy
 sympy
 
 [all]
-m2r2
+m2r2>=1.1
 matplotlib
 mistune
 numpydoc
@@ -33,7 +33,7 @@ arviz>=0.17
 scipy<1.13
 
 [doc]
-m2r2
+m2r2>=1.1
 matplotlib
 mistune
 numpydoc

{pymare-0.0.12 → pymare-0.0.13}/pymare/_version.py

@@ -8,11 +8,11 @@ import json
 
 version_json = '''
 {
- "date": "2026-08-22T11:31:11-0500",
+ "date": "2026-09-28T19:56:53-0500",
  "dirty": false,
  "error": null,
- "full-revisionid": "613c06ba432451ad536fb06877fe9fd653ceef85",
- "version": "0.0.12"
+ "full-revisionid": "9f8800eabf56b798820426c6439c111187409d55",
+ "version": "0.0.13"
 }
 '''  # END VERSION_JSON
 

{pymare-0.0.12 → pymare-0.0.13}/pymare/effectsize/base.py

@@ -250,6 +250,19 @@ class OneSampleEffectSizeConverter(EffectSizeConverter):
     summaries, and are _not_ individual data points. E.g., do not pass in
     a vector of point estimates as `m` and a scalar for the SDs `sd`.
     The lengths of all inputs must match.
+
+    .. versionchanged:: 0.0.13
+
+        The sampling variance of a raw correlation (``'R'``) is now
+        ``(1 - r**2)**2 / (n - 1)``, matching ``metafor::escalc(measure="COR")``.
+        It was ``(1 - r**2) / (n - 2)``, which is the squared standard error of
+        ``r`` under the null hypothesis of *no* correlation rather than its
+        sampling variance at the observed value. The two agree near ``r = 0``
+        and diverge by a factor of ``(n - 1) / ((n - 2)(1 - r**2))`` -- 51x at
+        ``r = 0.99``. Since that factor depends on the data, the old expression
+        did not simply inflate variances: it reweighted studies against one
+        another, pulling a pooled estimate toward those with the weakest
+        correlations. ``'ZR'`` is unaffected and remains the measure to prefer.
     """
 
     _type = 1
@@ -272,7 +285,12 @@ class OneSampleEffectSizeConverter(EffectSizeConverter):
                     a bias correction applied.
                 - 'D': Cohen's d. Note that no bias correction is applied
                     (use 'SM' instead).
-                - 'R': Raw correlation coefficient.
+                - 'R': Raw correlation coefficient. Prefer 'ZR' for
+                    meta-analysis: the sampling variance of a raw correlation
+                    depends strongly on the correlation itself, so studies are
+                    weighted very unequally by how large their correlations
+                    happen to be, which is the problem the Fisher transform
+                    exists to remove.
                 - 'ZR': Fisher z-transformed correlation coefficient.
         **kwargs
             Optional keyword arguments to pass onto the Dataset

{pymare-0.0.12 → pymare-0.0.13}/pymare/effectsize/expressions.json

@@ -15,7 +15,7 @@
         "description": "Cohen's d (one-sample)"
     },
     {
-        "expression": "v_d - ((n - 1)/(n - 3)) * (1 / n + d**2) - d**2 / j**2 * n",
+        "expression": "v_d - (((n - 1)/(n - 3)) * (1 / n + d**2) - d**2 / j**2)",
         "type": 1,
         "description": "Variance of Cohen's d"
     },
@@ -30,7 +30,7 @@
         "description": "Standardized mean (Hedges's g)"
     },
     {
-        "expression": "v_sm - ((n - 1)/(n - 3)) * j**2 * (1 / n + d**2) - d**2",
+        "expression": "v_sm - (((n - 1)/(n - 3)) * j**2 * (1 / n + d**2) - d**2)",
         "type": 1,
         "description": "Variance of standardized mean"
     },
@@ -40,7 +40,7 @@
         "description": "Raw correlation coefficient"
     },
     {
-        "expression": "v_r - (1 - r**2) / (n - 2)",
+        "expression": "v_r - (1 - r**2)**2 / (n - 1)",
         "type": 1,
         "description": "Variance of raw correlation coefficient"
     },
@@ -60,7 +60,7 @@
         "description": "Raw mean difference"
     },
     {
-        "expression": "v_rmd - (sd1**2 / n1) + (sd2**2 / n2)",
+        "expression": "v_rmd - ((sd1**2 / n1) + (sd2**2 / n2))",
         "type": 2,
         "description": "Variance of raw mean difference"
     },
@@ -75,7 +75,7 @@
         "description": "Cohen's d (two-sample)"
     },
     {
-        "expression": "v_d - ((n1 + n2)/(n1 * n2) + d**2 / 2 * (n1 + n2 - 2))",
+        "expression": "v_d - ((n1 + n2)/(n1 * n2) + d**2 / (2 * (n1 + n2 - 2)))",
         "type": 2,
         "description": "Variance of Cohen's d"
     },

{pymare-0.0.12 → pymare-0.0.13}/pymare/estimators/estimators.py

@@ -570,7 +570,9 @@ def _dersimonian_laird_tau2(y, v, X):
     Returns
     -------
     :obj:`numpy.ndarray` of shape (D,)
-        The tau^2 estimate per parallel dataset, floored at zero.
+        The tau^2 estimate per parallel dataset, floored at zero. Zero when the
+        design is saturated (``K <= P``), where there is no residual dispersion
+        to measure.
 
     Notes
     -----
@@ -585,6 +587,15 @@ def _dersimonian_laird_tau2(y, v, X):
     # Estimate initial betas with WLS, assuming tau^2=0
     beta_wls, model_cov = weighted_least_squares(y, v, X, return_cov=True)
 
+    if k <= p:
+        # A saturated design fits every observation exactly, so Q and A are both
+        # zero in exact arithmetic and the quotient below is one rounding
+        # residue over another -- 2.5e-31 / -8.9e-16 on one machine, and a
+        # positive numerator over an A that underflowed to zero on the next,
+        # which is +inf. There is no dispersion left to measure either way, so
+        # report none rather than let the residues decide.
+        return np.zeros(np.atleast_2d(y).shape[1])
+
     # Cochran's Q
     w = 1.0 / v
     w_sum = w.sum(0)
@@ -1134,9 +1145,19 @@ class Hedges(BaseEstimator):
     The ``X`` matrix must be identical for all iterates.
 
     Unlike the coefficients, tau^2 is derived from an *unweighted* fit: it is the excess of
-    the ordinary mean squared error over the mean sampling variance. The coefficients are
-    then refitted with ``1 / (v + tau^2)`` weights, and the reported covariance comes from
-    that second fit.
+    the ordinary mean squared error over what that error is expected to be when tau^2 is
+    zero, namely ``tr(PV) / (K - P)`` with ``P`` the ordinary-least-squares residual maker
+    and ``V`` the diagonal matrix of sampling variances. The coefficients are then refitted
+    with ``1 / (v + tau^2)`` weights, and the reported covariance comes from that second
+    fit.
+
+    .. versionchanged:: 0.0.13
+
+        The subtracted term was previously the mean sampling variance ``sum(v) / K``. That
+        is the same quantity when the intercept is the only predictor, but not otherwise,
+        so tau^2 was out by up to 0.14 relative in a meta-regression -- the divergence from
+        ``metafor``'s ``HE`` that ``validation/metafor/README.md`` recorded. Intercept-only
+        models are unaffected.
 
     .. versionchanged:: 0.0.11
 
@@ -1216,8 +1237,37 @@ class Hedges(BaseEstimator):
         # feeds the variance component only; the coefficients are refitted with
         # inverse-variance weights below.
         tau_beta = weighted_least_squares(tau_y, np.ones_like(tau_y), tau_X)
-        mse = ((tau_y - tau_X.dot(tau_beta)) ** 2).sum(0) / (tau_k - tau_p)
-        tau_ho = np.maximum(0, mse - tau_v.sum(0) / tau_k)
+        residual_ss = ((tau_y - tau_X.dot(tau_beta)) ** 2).sum(0)
+
+        # What that residual sum of squares is expected to be when tau^2 is
+        # zero, which is what has to be subtracted off. With P the OLS residual
+        # maker I - X (X'X)^-1 X' and V = diag(v), it is tr(PV) -- and since
+        # only P's diagonal is needed, that is sum_i (1 - h_i) v_i for the OLS
+        # leverages h_i.
+        #
+        # Not the mean sampling variance sum(v) / K, which is tr(PV) / (K - P)
+        # only when the intercept is the only predictor: P is then I - J/K,
+        # every h_i is 1/K, and the sum collapses to sum(v) (K - 1) / K. With a
+        # moderator the two part company, and using the intercept-only form put
+        # tau^2 out by up to 0.14 relative against metafor's HE.
+        leverage = np.einsum("ij,jk,ik->i", tau_X, np.linalg.pinv(tau_X.T @ tau_X), tau_X)
+        expected_ss = ((1.0 - leverage)[:, None] * tau_v).sum(0)
+
+        residual_dof = tau_k - tau_p
+        if residual_dof > 0:
+            # One division rather than two, which is also how metafor writes it.
+            tau_ho = np.maximum(0, (residual_ss - expected_ss) / residual_dof)
+        else:
+            # A saturated design fits every observation exactly, so there is no
+            # residual left to measure dispersion with and both terms above are
+            # zero to rounding. Dividing anyway lets the sign of that rounding
+            # decide the answer: the leverages come back as 1 +- 1e-16, so
+            # expected_ss lands either side of zero and tau^2 comes out +inf on
+            # one machine and NaN on the next, which is how this reached CI.
+            # Report no excess dispersion instead, which is what
+            # DerSimonianLaird and the likelihood estimators already do here,
+            # and what this estimator already did for K < P.
+            tau_ho = np.zeros_like(residual_ss)
 
         # Estimate beta with tau^2 estimate. The covariance has to come from
         # this fit rather than the OLS one above: (X'WX)^-1 is only the

{pymare-0.0.12 → pymare-0.0.13}/pymare/results.py

@@ -121,6 +121,46 @@ def _random_unit_order(classes, n_units):
     return order
 
 
+#: Relative slack allowed when deciding whether a permuted statistic is at least
+#: as extreme as the observed one. The permutation that reproduces the observed
+#: data -- the identity, always a member of the set -- must tie with it and so
+#: must count; but the observed statistic is computed by a different code path
+#: from the permuted ones, which refit every dataset in one batched call, and
+#: the two can disagree by a unit in the last place. Without slack that drops
+#: the identity, and with sign flipping its mirror too, understating the p-value
+#: by 2 / 2**m. The square root of machine epsilon is the same constant
+#: ``metafor::permutest`` uses for this, applied relatively rather than
+#: absolutely so that it does not depend on the scale of the statistic. It is
+#: seven orders of magnitude below the closest genuine near-tie observed on the
+#: designs in ``pymare/tests/data/metafor_small_sample.csv``.
+_PERMUTATION_TIE_RTOL = np.sqrt(np.finfo(np.float64).eps)
+
+
+def _at_least_as_extreme(permuted, observed):
+    """Return which permuted statistics are at least as extreme as the observed one.
+
+    Parameters
+    ----------
+    permuted : :obj:`numpy.ndarray`
+        Absolute permuted statistics, permutations along the last axis.
+    observed : :obj:`numpy.ndarray`
+        The absolute observed statistic, broadcastable against ``permuted``.
+
+    Returns
+    -------
+    :obj:`numpy.ndarray` of :obj:`bool`
+        Elementwise ``permuted >= observed``, to within
+        :data:`_PERMUTATION_TIE_RTOL`.
+
+    Notes
+    -----
+    ``>=`` and not ``>``: a permuted statistic that ties with the observed one is
+    at least as extreme, and excluding ties makes the test anti-conservative on
+    discrete or degenerate data.
+    """
+    return permuted >= observed - np.abs(observed) * _PERMUTATION_TIE_RTOL
+
+
 class MetaRegressionResults:
     """Container for results generated by PyMARE meta-regression estimators.
 
@@ -626,6 +666,24 @@ class MetaRegressionResults:
 
         Notes
         -----
+        The statistic permuted is the coefficient divided by its standard error,
+        not the coefficient itself, and the same for tau^2. Refitting a permuted
+        dataset re-estimates tau^2, which moves the weights and so the standard
+        error, so ``|beta|`` is not pivotal and its permutation distribution is
+        not the null this test needs. The two coincide only where the standard
+        error is invariant under the permutation -- a fixed-effects,
+        intercept-only model under sign flipping. This matches
+        ``metafor::permutest``.
+
+        .. versionchanged:: 0.0.13
+            Counted ``|beta|`` in earlier releases, and compared it against the
+            observed value exactly. Both are fixed: the statistic is now
+            ``|beta / se|``, and the comparison allows a relative slack of the
+            square root of machine epsilon so that the identity permutation --
+            which reproduces the observed data and must therefore count -- is not
+            dropped over a unit in the last place. Every permutation p-value this
+            method reports is affected.
+
         If the number of possible permutations is smaller than n_perm, an exact test will be
         conducted.
         Otherwise an approximate test will be conducted by randomly shuffling the outcomes n_perm
@@ -745,16 +803,37 @@ class MetaRegressionResults:
             # freedom (or raising on reshape).
             params = copy.copy(self.estimator).fit(**kwargs).params_
 
+            # The statistic is the coefficient over its standard error, not
+            # the coefficient: refitting a permuted dataset re-estimates tau^2,
+            # which moves the weights and hence the standard error, so |beta|
+            # is not pivotal and its permutation distribution is not the null
+            # the test needs. The two coincide only where the standard error
+            # happens to be invariant under the permutation -- a fixed-effects
+            # intercept-only model under sign flipping. This is what
+            # metafor::permutest counts.
             fe_obs = fe_stats["est"][:, i]
+            se_obs = fe_stats["se"][:, i]
             if fe_obs.ndim == 1:
-                fe_obs = fe_obs[:, None]
-            # <=, not <: a permuted statistic that ties with the observed one
-            # is at least as extreme, and excluding ties makes the test
-            # anti-conservative on discrete or degenerate data.
-            fe_p[:, i] = (np.abs(fe_obs) <= np.abs(params["fe_params"])).mean(1)
+                fe_obs, se_obs = fe_obs[:, None], se_obs[:, None]
+
+            # The permuted standard errors, taken from the covariance the
+            # estimator just reported, exactly as `fe_se` takes the observed
+            # one from `fe_cov` -- including whatever small-sample correction
+            # the estimator applies, which the observed statistic carries too.
+            # (P, P, n_perm) on every path this method can drive -- the
+            # closed-form estimators, the two likelihood ones, the sample
+            # size-based one and the cluster-robust branch all report a
+            # covariance per parallel dataset.
+            perm_cov = np.asarray(params["inv_cov"])
+            # A zero standard error divides to +-inf; the comparison below
+            # still orders those correctly, and a NaN counts as not extreme.
+            with np.errstate(invalid="ignore", divide="ignore"):
+                perm_se = np.sqrt(np.diagonal(perm_cov)).T
+                fe_p[:, i] = _at_least_as_extreme(
+                    np.abs(params["fe_params"] / perm_se), np.abs(fe_obs / se_obs)
+                ).mean(1)
             if rfx:
-                abs_obs = np.abs(tau2[i])
-                tau_p[i] = (abs_obs <= np.abs(params["tau2"])).mean()
+                tau_p[i] = _at_least_as_extreme(np.abs(params["tau2"]), np.abs(tau2[i])).mean()
 
         # p-values can't be smaller than 1/n_perm
         params = {"fe_p": np.maximum(1 / n_perm, fe_p)}

{pymare-0.0.12 → pymare-0.0.13}/pymare/stats.py

@@ -19,7 +19,7 @@ from typing import NamedTuple
 
 import numpy as np
 import scipy.stats as ss
-from scipy.optimize import Bounds, minimize
+from scipy.optimize import brentq
 from scipy.special import gammaln
 
 # At or below this many clusters, robust variance estimation is known to be
@@ -1515,6 +1515,27 @@ def _cr2_scores(X, w, resid, group_members, bread):
     above is the solution for :math:`\Phi = I` in the whitened metric, i.e.
     under the assumption that the weights are correct and the observations
     independent -- the same assumption the sandwich exists to avoid relying on.
+
+    That condition has many solutions, because it constrains :math:`A_j` only
+    through :math:`A_j B_j A_j'`. ``clubSandwich`` selects the symmetric one,
+    :math:`A_j = \Psi_j^{1/2} (\Psi_j^{1/2} B_j \Psi_j^{1/2})^{-1/2}
+    \Psi_j^{1/2}`; the form here is symmetric in the whitened metric instead,
+    and the two agree exactly when :math:`W_j` is a multiple of the identity --
+    that is, when the sampling variances are constant within the group. Both
+    satisfy the condition and both are exactly unbiased under the working model,
+    so the choice is not between a right and a wrong one.
+
+    It is made this way for the reason the next paragraph gives: in the whitened
+    metric :math:`I_j - H_j` is the identity minus a rank-:math:`p` term, so its
+    spectrum collapses to :math:`p` non-unit eigenvalues however large the group
+    is, and :func:`_cr2_low_rank_factors` can take the inverse square root in
+    :math:`p \times p` work. ``clubSandwich``'s matrix is
+    :math:`\Psi_j^2` minus a rank-:math:`p` term, whose diagonal part is not a
+    multiple of the identity, so it has :math:`n_j` distinct eigenvalues and
+    needs the full :math:`n_j \times n_j` eigendecomposition -- a factor of 400
+    more work at :math:`n_j = 200` and 5,900 at :math:`n_j = 800`. The square
+    root not commuting with an asymmetric congruence is at once why the two
+    forms differ and why only one of them factors.
     That is pragmatic rather than circular: simulation shows the correction
     helps substantially even when the working model is wrong
     :footcite:p:`tipton2015small,imbens2016robust`, and its influence fades as
@@ -1945,6 +1966,22 @@ def cluster_robust_cov(
         -   ``"CR2"`` (default) inflates each group's residuals by
             :math:`(I_j - H_j)^{-1/2}` to undo the shrinkage caused by fitting
             :math:`\beta` with that group included :footcite:p:`bell2002bias`.
+
+            .. note::
+
+                This is a CR2 in the defining sense -- it satisfies
+                :math:`A_j B_j A_j' = \Psi_j` exactly, and the resulting
+                sandwich is exactly unbiased for the model-based covariance
+                under the working model -- but it is not bit-for-bit
+                ``clubSandwich``'s ``CR2``. That condition does not pin
+                :math:`A_j` down uniquely: ``clubSandwich`` closes it by taking
+                :math:`A_j` symmetric, and this takes it symmetric in the
+                whitened metric instead. The two coincide exactly when the
+                weights are constant within a group, and differ otherwise --
+                by up to 1e-2 relative on the standard errors of the designs in
+                ``validation/clubsandwich``, which measures it. See
+                :func:`_cr2_scores` for why the whitened form is the one
+                implemented.
         -   ``"CR0"`` uses the raw residuals with the blunt ``m / (m - p)``
             scaling. This is the historical behaviour.
 
@@ -2291,6 +2328,76 @@ def ensure_2d(arr):
     return arr
 
 
+#: Doublings allowed when widening the bracket for a Q-profile bound. Q(tau^2)
+#: falls to zero as tau^2 grows, so a root exists whenever Q(0) exceeds the
+#: critical value and the search terminates long before this; it is a stop for
+#: the degenerate case of a zero critical value, which no root can reach.
+_Q_PROFILE_MAX_DOUBLINGS = 200
+
+#: Relative tolerance asked of the Q-profile root finder. Four times machine
+#: epsilon is the smallest :func:`scipy.optimize.brentq` accepts, which is what
+#: makes the bounds agree with metafor's ``confint.rma.uni`` to the last few
+#: bits rather than to the third decimal.
+_Q_PROFILE_RTOL = 4 * np.finfo(np.float64).eps
+
+
+def _invert_q(excess, crit, scale):
+    """Solve ``Q(tau^2) = crit`` for tau^2 >= 0.
+
+    Parameters
+    ----------
+    excess : callable
+        ``(tau2, crit) -> Q(tau2) - crit``.
+    crit : :obj:`float`
+        The chi-squared quantile being inverted.
+    scale : :obj:`float`
+        A point estimate of tau^2, used to size the first bracket tried.
+
+    Returns
+    -------
+    :obj:`float`
+        The root, ``0.0`` when ``Q(0) <= crit`` so that no positive root
+        exists, or :obj:`numpy.nan` when the bracket could not be widened far
+        enough to contain one.
+
+    Notes
+    -----
+    Solved as a root rather than as the minimum of ``(Q(tau^2) - crit)**2``,
+    which is what this function replaced. Squaring is what makes the difference:
+    it turns a transversal crossing into a tangential minimum, so the gradient
+    the minimizer follows vanishes as ``crit`` is approached and it stops while
+    still far from the root in the flat upper tail, where ``Q`` changes slowly.
+    The upper bound was wrong by up to 4% relative against
+    ``metafor::confint.rma.uni`` on the designs in
+    ``pymare/tests/data/metafor_small_sample.csv`` for that reason; it now
+    agrees to a few multiples of machine epsilon.
+
+    ``Q`` is monotonically decreasing in tau^2, but Brent's method needs only a
+    sign change over the bracket, so nothing here relies on that.
+    """
+    if excess(0.0, crit) <= 0:
+        # Q at tau^2 = 0 is already at or below the critical value, so the
+        # profile never crosses it. metafor reports the boundary here too.
+        return 0.0
+
+    # Q(tau^2) -> 0 as tau^2 -> infinity, since the weights approach a common
+    # 1 / tau^2 that scales the residual sum of squares away. So a root exists
+    # for any positive crit, and doubling finds it. What reaches the fallback
+    # below is a crit that is not a number at all: a saturated design has
+    # K - P = 0 degrees of freedom, `scipy.stats.chi2.ppf` returns NaN there,
+    # and every comparison against NaN is False, so the loop runs out. NaN
+    # bounds are the right answer for a design with no residual to profile.
+    upper = max(abs(scale), 1.0)
+    for _ in range(_Q_PROFILE_MAX_DOUBLINGS):
+        if excess(upper, crit) <= 0:
+            break
+        upper *= 2.0
+    else:
+        return np.nan
+
+    return brentq(excess, 0.0, upper, args=(crit,), rtol=_Q_PROFILE_RTOL, maxiter=200)
+
+
 def q_profile(y, v, X, alpha=0.05, groups=None):
     """Get the CI for tau^2 via the Q-Profile method.
 
@@ -2343,22 +2450,28 @@ def q_profile(y, v, X, alpha=0.05, groups=None):
     l_crit = ss.chi2.ppf(1 - alpha / 2, df)
     u_crit = ss.chi2.ppf(alpha / 2, df)
     args = (ensure_2d(y), ensure_2d(v), X)
-    bds = Bounds([0], [np.inf], keep_feasible=True)
 
-    # Use a point estimate of tau^2 as a starting point; when using a fixed
-    # value, minimize() sometimes fails to stay in bounds. It has to be the
-    # estimator that matches the Q being inverted, or the search can start on
-    # the wrong side of the upper root.
+    def excess(tau2, crit):
+        """Q(tau^2) - crit, the function whose root is a bound."""
+        return float(np.ravel(q_gen(*args, float(tau2), groups))[0]) - crit
+
+    # A scale for the bracket search, not a starting point: the root finder
+    # below needs an interval that contains the root, and the point estimate
+    # says what order of magnitude tau^2 lives at. It has to be the estimator
+    # that matches the Q being inverted, so that the first bracket tried is
+    # usually already wide enough.
     if groups is None:
         from .estimators import DerSimonianLaird
 
-        ub_start = 2 * DerSimonianLaird().fit(y, v, X).params_["tau2"]
+        scale = DerSimonianLaird().fit(y, v, X).params_["tau2"]
     else:
-        ub_start = 2 * correlated_effects_tau2(*args, groups)
+        scale = correlated_effects_tau2(*args, groups)
 
-    lb = minimize(lambda x: (q_gen(*args, x, groups) - l_crit) ** 2, [0], bounds=bds).x[0]
-    ub = minimize(lambda x: (q_gen(*args, x, groups) - u_crit) ** 2, ub_start, bounds=bds).x[0]
-    return {"ci_l": lb, "ci_u": ub}
+    scale = float(np.ravel(scale)[0])
+    return {
+        "ci_l": _invert_q(excess, l_crit, scale),
+        "ci_u": _invert_q(excess, u_crit, scale),
+    }
 
 
 #: Iterations allowed in the continued fraction of :func:`log_chi2_sf`. A safety

{pymare-0.0.12 → pymare-0.0.13}/pymare/tests/conftest.py

@@ -383,6 +383,18 @@ def robumeta_dataset():
     return frame, designs
 
 
+@pytest.fixture(scope="package")
+def clubsandwich_dataset():
+    """Load the dataset the clubSandwich reference values were computed on.
+
+    The same CSV :func:`robumeta_dataset` reads, and returning only the frame:
+    the clubSandwich alignment builds its designs through
+    :class:`~pymare.core.Dataset` so that the group labels travel with them,
+    rather than assembling a bare design matrix as the robumeta alignment does.
+    """
+    return pd.read_csv(op.join(get_test_data_path(), "robumeta_correlated_effects.csv"))
+
+
 @pytest.fixture(scope="package")
 def metafor_dataset():
     """Load the designs the metafor reference values were computed on."""