apatools 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
apatools/__init__.py ADDED
@@ -0,0 +1,15 @@
1
+ """A toolbox for meta-analysis and APA-compliant reporting.
2
+
3
+ Modules: ``calc`` (conversions, bootstrap), ``lm`` (OLS/RLM/GLM/QuantReg/MixedLM), ``slm`` (spatial
4
+ models), ``plm`` (panel models), ``sem`` (structural equation models), ``psm`` (propensity score
5
+ matching) and ``format`` (APA formatting). Import the modules you need, e.g.
6
+ ``from apatools.lm import lm, lm_report``.
7
+ """
8
+ from importlib.metadata import PackageNotFoundError, version
9
+
10
+ try:
11
+ __version__ = version("apatools")
12
+ except PackageNotFoundError: # running from a source tree that is not installed
13
+ __version__ = "0+unknown"
14
+
15
+ __all__ = ["__version__"]
apatools/_deps.py ADDED
@@ -0,0 +1,25 @@
1
+ """Helper for the optional dependencies of the apatools modules (installed through extras)."""
2
+
3
+
4
+ def missing_dependency(module, extra, error, hint=None):
5
+ """
6
+ Raise an ``ImportError`` that tells which extra provides the missing package.
7
+
8
+ Parameters
9
+ ----------
10
+ module : str
11
+ Name of the apatools module that was imported, e.g. ``"lm"``.
12
+ extra : str
13
+ Name of the extra that installs its dependencies, e.g. ``"lm"``
14
+ (``pip install "apatools[lm]"``).
15
+ error : ImportError
16
+ The original error; its ``name`` is the missing package.
17
+ hint : str, optional
18
+ Replaces the ``pip install "apatools[<extra>]"`` suggestion.
19
+ """
20
+ package = (getattr(error, "name", None) or str(error)).split(".")[0] # "statsmodels.api" -> "statsmodels"
21
+ how = hint or f'pip install "apatools[{extra}]"'
22
+ raise ImportError(
23
+ f"apatools.{module} needs the package '{package}', which is an optional dependency "
24
+ f"and is not installed. Install it with: {how}"
25
+ ) from error
apatools/calc.py ADDED
@@ -0,0 +1,366 @@
1
+ """Statistical conversions (r, d, t, z, F, p, odds ratios), confidence intervals and bootstrapping.
2
+
3
+ Conventions
4
+ -----------
5
+ * ``n`` is the *total* sample size; degrees of freedom for t are ``n - 2``.
6
+ * ``d`` conversions assume two equal-sized groups unless stated otherwise.
7
+ * ``method`` is ``"two-tailed"`` (default) or any other string for one-tailed.
8
+ * ``z`` denotes a standard-normal deviate unless the name says "Fisher's z".
9
+ * All conversions are approximate.
10
+ """
11
+ import numpy as np
12
+ import scipy
13
+ import scipy.stats
14
+
15
+ ###############
16
+ # bootstrap #
17
+ ###############
18
+
19
+
20
+ def bootstrap(*args, func=np.mean, alpha=0.95, n_rep=1000, seed=13):
21
+ """Percentile bootstrap confidence interval for a statistic.
22
+
23
+ Parameters
24
+ ----------
25
+ *args : array-like
26
+ One or more equally long samples (resampled jointly by row).
27
+ func : callable
28
+ Statistic computed on the resampled arrays, called as ``func(*samples)``.
29
+ alpha : float
30
+ Confidence level (e.g. 0.95), not a significance level.
31
+ n_rep : int
32
+ Number of bootstrap replications.
33
+ seed : int
34
+ Seed for numpy's global random generator.
35
+
36
+ Returns
37
+ -------
38
+ numpy.ndarray
39
+ ``[lower, median, upper]`` percentiles of the bootstrap distribution.
40
+ """
41
+ np.random.seed(seed)
42
+ data = np.asanyarray(args)
43
+ idx = np.arange(0, data.shape[1], 1)
44
+ sample = [
45
+ func(*np.take(data, np.random.choice(idx, size=data.shape[1], replace=True), 1))
46
+ for _ in range(n_rep)
47
+ ]
48
+ lp, m, rp = (1 - alpha) / 2, 0.5, 1 - (1 - alpha) / 2
49
+ return np.percentile(sample, [lp * 100, m * 100, rp * 100])
50
+
51
+
52
+ ##############
53
+ # conversion #
54
+ ##############
55
+
56
+
57
+ def d_from_r(r):
58
+ """Cohen's d from correlation r (equal groups): ``2r / sqrt(1 - r^2)``.
59
+
60
+ https://stats.stackexchange.com/questions/390549
61
+ """
62
+ return 2 * r / np.sqrt(1 - r * r)
63
+
64
+
65
+ def r_from_d(d, n_groups=2):
66
+ """Correlation r from Cohen's d (equal groups): ``d / sqrt(d^2 + 2 * n_groups)``.
67
+
68
+ https://easystats.github.io/effectsize/reference/d_to_r.html
69
+ """
70
+ return d / np.sqrt(d * d + 2 * n_groups)
71
+
72
+
73
+ def t_from_r(r, n):
74
+ """t-statistic of a correlation: ``r / sqrt((1 - r^2) / (n - 2))``."""
75
+ df = n - 2
76
+ return r / np.sqrt((1 - r * r) / df)
77
+
78
+
79
+ def r_from_t(t, n):
80
+ """Correlation r from a t-statistic: ``t / sqrt(t^2 + df)``, df = n - 2."""
81
+ df = n - 2
82
+ return t / np.sqrt(t * t + df)
83
+
84
+
85
+ def d_from_t(t, n):
86
+ """Cohen's d from a t-statistic (equal groups): ``2t / sqrt(df)``, df = n - 2.
87
+
88
+ Fritz, C. O., Morris, P. E., & Richler, J. J. (2012). Journal of Experimental
89
+ Psychology: General, 141(1), 2-18. https://doi.org/10.1037/a0024338
90
+ """
91
+ df = n - 2
92
+ return 2 * t / np.sqrt(df)
93
+
94
+
95
+ def t_from_d(d, n):
96
+ """t-statistic from Cohen's d (equal groups): ``d * sqrt(df) / 2``, df = n - 2.
97
+
98
+ Inverse of :func:`d_from_t` (Fritz et al., 2012).
99
+ """
100
+ df = n - 2
101
+ return d * np.sqrt(df) / 2
102
+
103
+
104
+ def z_from_r(r):
105
+ """Fisher's z-transformation of r: ``atanh(r)``."""
106
+ return np.atanh(r)
107
+
108
+
109
+ def r_from_z(z):
110
+ """Correlation r (Cohen's r) from Fisher's z: ``tanh(z)``."""
111
+ r = np.sqrt(1 - np.square(1 / np.cosh(z)))
112
+ return np.copysign(r, z)
113
+
114
+
115
+ def d_from_f(f, df_num, df_denom, n_groups=2):
116
+ """Cohen's d from an F-statistic (Fritz et al., 2012).
117
+
118
+ Goes via eta squared and Cohen's f squared: ``d = sqrt(2 * n_groups * f_sq)``.
119
+ """
120
+ eta_sq = (f * df_num) / (f * df_num + df_denom)
121
+ f_sq = eta_sq / (1 - eta_sq)
122
+ return np.sqrt(f_sq * 2 * n_groups)
123
+
124
+
125
+ def r_from_f(f, df_num, df_denom):
126
+ """Correlation r from an F-statistic (``R^2 = 1 - 1 / (1 + F * df_num / df_denom)``).
127
+
128
+ https://statproofbook.github.io/P/fstat-rsq.html
129
+ """
130
+ r_sq = 1 - (1 / (1 + f * df_num / df_denom))
131
+ return np.sqrt(r_sq)
132
+
133
+
134
+ ###########
135
+ # p-value #
136
+ ###########
137
+
138
+
139
+ def p_from_f(f, df_num, df_denom):
140
+ """Upper-tail p-value of an F-statistic."""
141
+ return scipy.stats.f.sf(f, df_num, df_denom)
142
+
143
+
144
+ def z_from_p(p, method="two-tailed"):
145
+ """Absolute standard-normal deviate (not Fisher's z) for a p-value."""
146
+ p = p / 2 if method == "two-tailed" else p
147
+ return np.abs(scipy.stats.norm.ppf(p))
148
+
149
+
150
+ def p_from_z(z, method="two-tailed"):
151
+ """p-value of a standard-normal deviate ``z`` (sign is ignored)."""
152
+ p = scipy.stats.norm.sf(np.abs(z))
153
+ return p * 2 if method == "two-tailed" else p
154
+
155
+
156
+ def p_from_t(t, n, method="two-tailed"):
157
+ """p-value of a t-statistic with df = n - 2 (sign is ignored)."""
158
+ df = n - 2
159
+ p = scipy.stats.t.sf(np.abs(t), df)
160
+ return p * 2 if method == "two-tailed" else p
161
+
162
+
163
+ def t_from_p(p, n, method="two-tailed"):
164
+ """Absolute t-statistic (df = n - 2) for a p-value; the sign is lost."""
165
+ df = n - 2
166
+ p = p / 2 if method == "two-tailed" else p
167
+ return np.abs(scipy.stats.t.ppf(p, df))
168
+
169
+
170
+ def r_from_p(p, n, method="two-tailed"):
171
+ """Correlation r from a p-value via t. Always non-negative (the sign is lost).
172
+
173
+ Cohen's guidelines: .1 small, .3 medium, .5 large. See Fritz et al. (2012).
174
+ """
175
+ return r_from_t(t_from_p(p, n, method=method), n)
176
+
177
+
178
+ def p_from_r(r, n, method="two-tailed"):
179
+ """p-value of a correlation r with sample size n."""
180
+ return p_from_t(t_from_r(r, n), n, method=method)
181
+
182
+
183
+ def d_from_p(p, n, method="two-tailed"):
184
+ """Cohen's d from a p-value (via r). Always non-negative."""
185
+ return d_from_r(r_from_p(p, n, method=method))
186
+
187
+
188
+ def p_from_d(d, n, method="two-tailed"):
189
+ """p-value of Cohen's d (via r), equal groups."""
190
+ return p_from_r(r_from_d(d), n, method=method)
191
+
192
+
193
+ ##############
194
+ # conflicted #
195
+ ##############
196
+
197
+
198
+ def z_from_t(t, n, method=None):
199
+ """z from a t-statistic.
200
+
201
+ Without ``method``: Fisher's z of the corresponding r.
202
+ With ``method``: the standard-normal deviate with the same p-value.
203
+ The two branches are *not* interchangeable.
204
+ """
205
+ if method:
206
+ p = p_from_t(t, n, method=method)
207
+ return z_from_p(p, method=method)
208
+ return z_from_r(r_from_t(t, n))
209
+
210
+
211
+ def t_from_z(z, n, method=None):
212
+ """t-statistic from z; inverse of :func:`z_from_t` (same two interpretations)."""
213
+ if method:
214
+ p = p_from_z(z, method=method)
215
+ return t_from_p(p, n, method=method)
216
+ return t_from_r(r_from_z(z), n)
217
+
218
+
219
+ def d_from_z(z):
220
+ """Cohen's d from Fisher's z (via r), equal groups."""
221
+ return d_from_r(r_from_z(z))
222
+
223
+
224
+ def z_from_d(d):
225
+ """Fisher's z from Cohen's d (via r), equal groups."""
226
+ return z_from_r(r_from_d(d))
227
+
228
+
229
+ ########################
230
+ # Confidence intervals #
231
+ ########################
232
+
233
+
234
+ def p_from_ci(estimate, cil, cir, n=None, alpha=0.95, method="two-tailed"):
235
+ """p-value from an estimate and its confidence interval.
236
+
237
+ ``alpha`` is the confidence level of the interval (e.g. 0.95). With ``n`` a
238
+ t-distribution (df = n - 2) is used, otherwise the normal distribution.
239
+ For ratios (OR, RR) pass log-transformed values.
240
+ https://genometoolbox.blogspot.com/2013/11/how-to-estimate-p-value-from-confidence.html
241
+ """
242
+ se = (cir - cil) / 2
243
+ if n is None:
244
+ se /= z_from_p(1 - alpha, method=method)
245
+ return p_from_z(estimate / se, method=method)
246
+ se /= t_from_p(1 - alpha, n, method=method)
247
+ return p_from_t(estimate / se, n, method=method)
248
+
249
+
250
+ def ci_from_r(r, n, alpha=0.95, method="two-tailed"):
251
+ """Confidence interval of a correlation via Fisher's transformation.
252
+
253
+ ``alpha`` is the confidence level (e.g. 0.95). Returns ``(lower, upper)``.
254
+ https://en.wikipedia.org/wiki/Fisher_transformation
255
+ """
256
+ se = z_from_p(1 - alpha, method=method) / np.sqrt(n - 3)
257
+ return np.tanh(np.atanh(r) - se), np.tanh(np.atanh(r) + se)
258
+
259
+
260
+ def ci_from_p(p, n, alpha=0.95, method="two-tailed"):
261
+ """Confidence interval of r reconstructed from a p-value (r is non-negative)."""
262
+ r = r_from_p(p, n, method=method)
263
+ return ci_from_r(r, n, alpha=alpha, method=method)
264
+
265
+
266
+ ##############
267
+ # Cohen r, d #
268
+ ##############
269
+
270
+
271
+ def cohen_r_from_p(p, n, method="two-tailed"):
272
+ """Alias of :func:`r_from_p`."""
273
+ return r_from_p(p, n, method=method)
274
+
275
+
276
+ def cohen_r_from_d(d, n_groups=2):
277
+ """Alias of :func:`r_from_d`."""
278
+ return r_from_d(d, n_groups=n_groups)
279
+
280
+
281
+ def cohen_r_from_z(z):
282
+ """Alias of :func:`r_from_z`."""
283
+ return r_from_z(z)
284
+
285
+
286
+ def cohen_r_from_t(t, n):
287
+ """Alias of :func:`r_from_t`."""
288
+ return r_from_t(t, n)
289
+
290
+
291
+ def cohen_r_from_f(f, df_num, df_denom):
292
+ """Alias of :func:`r_from_f`."""
293
+ return r_from_f(f, df_num, df_denom)
294
+
295
+
296
+ def cohen_d_from_p(p, n, method="two-tailed"):
297
+ """Alias of :func:`d_from_p`."""
298
+ return d_from_p(p, n, method=method)
299
+
300
+
301
+ def cohen_d_from_r(r):
302
+ """Alias of :func:`d_from_r`."""
303
+ return d_from_r(r)
304
+
305
+
306
+ def cohen_d_from_z(z):
307
+ """Alias of :func:`d_from_z`."""
308
+ return d_from_z(z)
309
+
310
+
311
+ def cohen_d_from_t(t, n):
312
+ """Alias of :func:`d_from_t`."""
313
+ return d_from_t(t, n)
314
+
315
+
316
+ def cohen_d_from_f(f, df_num, df_denom, n_groups=2):
317
+ """Alias of :func:`d_from_f`."""
318
+ return d_from_f(f, df_num, df_denom, n_groups=n_groups)
319
+
320
+
321
+ ###########
322
+ # other #
323
+ ###########
324
+
325
+
326
+ def t_from_b(b, se):
327
+ """t-statistic of a regression coefficient: ``b / se``."""
328
+ return b / se
329
+
330
+
331
+ def unbiased_z(r, n):
332
+ """Fisher's z of the bias-corrected correlation (Hedges & Olkin, 1985).
333
+
334
+ ``r_u = r * (1 + (1 - r^2) / (2 * (n - 3)))``, then ``atanh(r_u)``.
335
+ Recommended for small samples (< 20, Nakagawa & Cuthill, 2007).
336
+ """
337
+ r_u = r * (1 + (1 - r * r) / (2 * (n - 3)))
338
+ return np.atanh(r_u)
339
+
340
+
341
+ def logit_from_probit(x):
342
+ """Approximate logit coefficient from a probit coefficient (``1.7 * x``).
343
+
344
+ https://statmodeling.stat.columbia.edu/2006/06/06/take_logit_coef/
345
+ """
346
+ return 1.7 * x
347
+
348
+
349
+ def OR_from_logit(x):
350
+ """Odds ratio from a log odds ratio: ``exp(x)``."""
351
+ return np.exp(x)
352
+
353
+
354
+ def logit_from_cohen_d(d):
355
+ """Log odds ratio from Cohen's d: ``pi * d / sqrt(3)``."""
356
+ return np.pi * d / np.sqrt(3)
357
+
358
+
359
+ def cohen_d_from_logit(x):
360
+ """Cohen's d from a log odds ratio: ``x * sqrt(3) / pi``."""
361
+ return x * np.sqrt(3) / np.pi
362
+
363
+
364
+ def logit_from_OR(x):
365
+ """Log odds ratio from an odds ratio: ``log(x)``."""
366
+ return np.log(x)
apatools/citation.py ADDED
@@ -0,0 +1,5 @@
1
+ from typing import NamedTuple
2
+
3
+
4
+ class Citation(NamedTuple):
5
+ APA: str
apatools/format.py ADDED
@@ -0,0 +1,88 @@
1
+ from numbers import Number
2
+
3
+ import numpy as np
4
+
5
+ ###############
6
+ # formating #
7
+ ###############
8
+
9
+
10
+ def get_stars(p, p001="***", p01="**", p05="*", p10="⁺", p_=""):
11
+ """Significance marker for a p-value.
12
+
13
+ Thresholds: p < .001, p < .01, p < .05, p < .10, otherwise ``p_``.
14
+ Non-numeric input is returned unchanged.
15
+ """
16
+ if not isinstance(p, Number):
17
+ return p
18
+ if p < 0.001:
19
+ return p001
20
+ if p < 0.010:
21
+ return p01
22
+ if p < 0.050:
23
+ return p05
24
+ if p < 0.100:
25
+ return p10
26
+ return p_
27
+
28
+
29
+ def format_p(p, use_letter="p", keep_spaces=True, no_equals=False):
30
+ """Format a p-value in APA style, e.g. ``p = .009``, ``p < .001``.
31
+
32
+ Parameters
33
+ ----------
34
+ use_letter : str or False
35
+ Prefix such as ``"p"``; falsy omits it.
36
+ keep_spaces : bool
37
+ ``False`` removes all spaces (``p<.001``).
38
+ no_equals : bool
39
+ ``True`` drops the ``=`` sign (``p .009``).
40
+
41
+ Values below .001 are reported as ``< .001`` and values that would round to
42
+ 1.000 as ``> .999``. Non-numeric input is returned unchanged; NaN, inf and
43
+ negative values are reported as ``= NaN``.
44
+ """
45
+ if not isinstance(p, Number):
46
+ return p
47
+ if not np.isfinite(p) or p < 0.0:
48
+ p = "= NaN"
49
+ elif p < 0.001:
50
+ p = "< .001" # APA: never report p = .000
51
+ elif p >= 0.9995: # would round to 1.000; a p-value is never exactly 1
52
+ p = "> .999"
53
+ else:
54
+ p = "= " + f"{p:.3f}"[1:]
55
+ if use_letter:
56
+ p = use_letter + " " + p
57
+ if not keep_spaces:
58
+ p = p.replace(" ", "")
59
+ if no_equals:
60
+ p = p.replace(" =", "").replace("=", "")
61
+ return p
62
+
63
+
64
+ def format_r(r, use_letter="r", keep_spaces=True, no_equals=False):
65
+ """Format a correlation / R² in APA style without a leading zero, e.g. ``r = -.34``.
66
+
67
+ Values with |r| < .01 are shown as ``0.`` and |r| > .99 as ``1.`` (or ``-1.``).
68
+ Parameters are as in :func:`format_p`. Non-numeric input is returned unchanged;
69
+ NaN and inf are reported as ``= NaN``.
70
+ """
71
+ if not isinstance(r, Number):
72
+ return r
73
+ sign = "-" if r < 0.0 else ""
74
+ if not np.isfinite(r):
75
+ r = "= NaN"
76
+ elif np.abs(r) < 0.01:
77
+ r = "= 0."
78
+ elif np.abs(r) > 0.99:
79
+ r = "= " + sign + "1."
80
+ else:
81
+ r = "= " + sign + f"{np.abs(r):.2f}"[1:]
82
+ if use_letter:
83
+ r = use_letter + " " + r
84
+ if not keep_spaces:
85
+ r = r.replace(" ", "")
86
+ if no_equals:
87
+ r = r.replace(" =", "").replace("=", "")
88
+ return r