Transformations¶

Transformation functions, used as transf= or atransf= in predict, confint and the plot functions. metafor's transf.ilogit is metafopy.transf.ilogit, and transf.ipft.hm is metafopy.transf.ipft_hm. Each is also a top-level function with the mechanical translation of the R name, metafopy.transf_ilogit and metafopy.transf_ipft_hm. Functions with _int and _mode suffixes integrate over or find the mode of the distribution of the true effects, and take targs={'tau2': ...} (some also accept other targs keys, see each function).

Transformation functions (metafor's transf.*).

A port of R/transf.r from metafor 5.2-1. metafor's transf.rtoz is metafopy.transf.rtoz here, transf.ipft.hm is metafopy.transf.ipft_hm, and so on (the remaining . becomes _); the same functions are also metafopy.transf_rtoz, metafopy.transf_ipft_hm, ..., the mechanical translation of the R names. Argument names and defaults are metafor's. The functions are documented on metafor's help page, ?transf (https://wviechtb.github.io/metafor/reference/transf.html). Sources cited there:

Fisher (1921), r-to-z (Metron, 1, 1-32; the link on metafor's help page, https://hdl.handle.net/2440/15169, no longer resolves);
Freeman & Tukey (1950), double arcsine and incidence-rate transformations, doi:10.1214/aoms/1177729756, inverted as in Miller (1978), doi:10.1080/00031305.1978.10479283 (ipft_hm uses the harmonic mean of the sample sizes);
Hakstian & Whalen (1976), doi:10.1007/BF02291840, and Bonett (2002), doi:10.3102/10769986027004335, for coefficient alpha;
Olkin & Finn (1995), doi:10.1037/0033-2909.118.1.155, for R-squared;
Cohen (1988) U1-U3, Inman & Bradley (1989), doi:10.1080/03610928908830127, and Grice & Barrett (2014), doi:10.2466/03.pr0.115c29z4, for overlap; McGraw & Wong (1992), doi:10.1037/0033-2909.111.2.361, for the CLES; Rosenthal & Rubin (1982), doi:10.1037/0022-0663.74.2.166, for the BESD;
Jacobs & Viechtbauer (2017), doi:10.1002/jrsm.1218, for (point-)biserial correlations;
Cox & Snell (1989) and Chinn (2000), doi:10.1002/1097-0258(20001130)19:22<3127::aid-sim784>3.0.co;2-m, for log odds ratios to SMDs; Pearson (1900), doi:10.1098/rsta.1900.0022, and Digby (1983), doi:10.2307/2531104, for tetrachoric approximations.

Every function accepts array-likes or scalars (NaN or None for R's NA) and returns a float ndarray that is at least 1-d (R has no scalars), with the broadcast shape of the inputs.

The *_int functions integrate with SciPy's QUADPACK qags/qagi, the routines behind R's integrate(), using R's defaults (rel.tol = abs.tol = .Machine$double.eps^0.25, 100 subdivisions); where R's integrate() stops with an error, metafor returns NA and so do these. ilogit_mode uses the line-for-line port of R's uniroot(), exp_mode is a closed form and the other *_mode functions use the port of R's optimize(). exp_int is the closed form exp(xi + tau2/2).

Behaviour kept from R, including its quirks:

iarcsin_int, iahw_int and iabt_int bound the integral below by max(0, xi - 10*tau) taken over all xi (and iarcsin_int and iahw_int above by min(pi/2 or 1, xi + 10*tau), also over all xi), so a vector call can differ from elementwise calls, and one NaN in xi makes every value NaN;
ztor_mode(NaN) and similar return a number, as R's optimize() replaces non-finite values by the largest double.

Differences from R:

with tau2 = 0 the *_mode functions return the plain back-transform elementwise (in R a vector xi then yields every value length(xi) times);
targs is a mapping with metafor's list names (tau2, lower, upper, ni, sd) or, as in R, a scalar or a positional vector; ipft_hm also accepts the sample sizes directly (R errors);
R's NA and NaN are both NaN.

rtoz ¶

rtoz(xi: ArrayLike) -> NDArray[float64]

Fisher's r-to-z transformation of correlation coefficients, atanh(xi); xi is truncated to [-1, 1] first.

Parameters:

Name	Type	Description	Default
`xi`	`ArrayLike`	values to transform, scalar or array-like (NaN or None for a missing value).	required

Returns:

Type	Description
`NDArray[float64]`	Float array (at least 1-d) with the shape of `xi`.

Metafor reference

Name	Type	Description	Default
`xi`	`ArrayLike`	proportions (`x / n`), scalar or array-like.	required
`ni`	`ArrayLike`	sample sizes, scalar or array-like. `xi` and `ni` are recycled to the longer length, with a warning if it is not a multiple.	required

Name	Type	Description	Default
`xi`	`ArrayLike`	transformed values, scalar or array-like.	required
`ni`	`ArrayLike`	sample sizes, scalar or array-like, recycled with `xi` to the longer length.	required

Name	Type	Description	Default
`xi`	`ArrayLike`	incidence rates (`x / t`), scalar or array-like.	required
`ti`	`ArrayLike`	person-times, scalar or array-like.	required

Name	Type	Description	Default
`xi`	`ArrayLike`	standardized mean differences, scalar or array-like.	required
`targs`	`ArrayLike \| Mapping[str, Any] \| None`	mapping with `tau2` (required, >= 0: the variance of the distribution of the true effects) and optionally `lower` and `upper` (bounds of the integration; default: 10 standard deviations around each value). Also accepted, as in R: a scalar or a positional sequence (`tau2`, `lower`, `upper`). For example `predict` and `confint` fill in `tau2` of the model when `targs` is None.	`None`

Name	Type	Description	Default
`xi`	`ArrayLike`	point-biserial correlations, scalar or array-like.	required
`pi`	`ArrayLike \| None`	proportion of cases in the first group, a single value or one per value of `xi`, in [0, 1]. Default None: 0.5.	`None`

Name	Type	Description	Default
`xi`	`ArrayLike`	Pearson correlations, scalar or array-like.	required
`pi`	`ArrayLike \| None`	proportion of cases in the first group after dichotomizing, a single value or one per value of `xi`, in [0, 1]. Default None: 0.5.	`None`

Name	Type	Description	Default
`xi`	`ArrayLike`	log odds ratios, scalar or array-like.	required
`pc`	`ArrayLike`	control group risk, a single value or one per value of `xi`, in [0, 1].	required

Transformations¶

rtoz ¶

ztor ¶

ztor_int ¶

ztor_mode ¶

r2toz ¶

ztor2 ¶

exp_int ¶

exp_mode ¶

logit ¶

ilogit ¶

ilogit_int ¶

ilogit_mode ¶

arcsin ¶

iarcsin ¶

iarcsin_int ¶

iarcsin_mode ¶

probit ¶

iprobit ¶

iprobit_int ¶

iprobit_mode ¶

pft ¶

ipft ¶

ipft_hm ¶

isqrt ¶

irft ¶

iirft ¶

ahw ¶

iahw ¶

iahw_int ¶

iahw_mode ¶

abt ¶

iabt ¶

iabt_int ¶

iabt_mode ¶

dtou1 ¶

dtou2 ¶

dtou3 ¶

dtoovl ¶

dtocles ¶

clestod ¶

dtocles_int ¶

dtocliffd ¶

dtobesd ¶

dtomd ¶

dtorpb ¶

dtorbis ¶

rpbtorbis ¶

rtorpb ¶

rtod ¶

rpbtod ¶

lnortord ¶

lnortorr ¶

lnortod_norm ¶

lnortod_logis ¶

dtolnor_norm ¶

dtolnor_logis ¶

lnortortet_pearson ¶

lnortortet_digby ¶

R's distribution functions¶