stats.meta¶

Meta-analysis of a parameter over studies: effect sizes, fixed effect and random effects pooling.

An effect size per study (Hedges' g, the mean difference or the log ratio of the geometric means, the effect native to pharmacokinetics) is pooled with inverse variance weights: the fixed effect model assumes one true effect, the random effects model of DerSimonian & Laird (1986) adds the between-study variance \(\tau^2\) to every weight. The heterogeneity statistics \(Q\), \(I^2\) and \(H^2\) follow Higgins & Thompson (2002).

EffectKind ¶

Bases: StrEnum

Effect size of a study.

EffectSize `dataclass` ¶

EffectSize(
    estimate,
    variance,
    se,
    ci_low,
    ci_high,
    ci_level,
    kind,
    n_control,
    n_treatment,
    label,
)

Effect size of one study.

Attributes:

Name	Type	Description
`estimate`	`float`	the effect
`variance`	`float`	its variance
`se`	`float`	its standard error
`ci_low`	`float`	lower bound of the normal interval
`ci_high`	`float`	upper bound of the normal interval
`ci_level`	`float`	level of the interval
`kind`	`EffectKind`	the kind of effect
`n_control`	`int`	size of the control group
`n_treatment`	`int`	size of the treatment group
`label`	`str`	label of the study

to_dict ¶

to_dict()

The fields as a dictionary with the kind as a string.

Returns:

Type	Description
`dict[str, Any]`	Field name to value.

Heterogeneity `dataclass` ¶

Heterogeneity(q, df, p_value, i2, h2, tau2)

Heterogeneity of the effects of the studies.

Attributes:

Name	Type	Description
`q`	`float`	Cochran's \(Q = \sum w_i (\theta_i - \hat\theta_F)^2\)
`df`	`int`	\(k - 1\)
`p_value`	`float`	p value of \(Q\) under \(\chi^2_{k-1}\), `NaN` for one study
`i2`	`float`	\(I^2 = \max(0, (Q - df) / Q)\) in percent
`h2`	`float`	\(H^2 = Q / df\), `NaN` for one study
`tau2`	`float`	between-study variance \(\tau^2 = \max(0, (Q - df) / C)\), \(C = \sum w_i - \sum w_i^2 / \sum w_i\)

to_dict ¶

to_dict()

The fields as a dictionary.

Returns:

Type	Description
`dict[str, Any]`	Field name to value.

PooledEffect `dataclass` ¶

PooledEffect(
    estimate,
    se,
    ci_low,
    ci_high,
    ci_level,
    z,
    p_value,
    weights,
    model,
    tau2,
)

Pooled effect of a meta-analysis.

Attributes:

Name	Type	Description
`estimate`	`float`	the pooled effect \(\sum w_i \theta_i / \sum w_i\)
`se`	`float`	its standard error \(1 / \sqrt{\sum w_i}\)
`ci_low`	`float`	lower bound of the normal interval
`ci_high`	`float`	upper bound
`ci_level`	`float`	level of the interval
`z`	`float`	\(\hat\theta / \mathrm{se}\)
`p_value`	`float`	two-sided p value of `z`
`weights`	`ndarray`	the weights of the studies, normalized to 1
`model`	`str`	`"fixed"` or `"random"`
`tau2`	`float`	between-study variance used in the weights (0 for the fixed effect)

to_dict ¶

to_dict()

The scalar fields as a dictionary.

Returns:

Type	Description
`dict[str, Any]`	Field name to value.

Study `dataclass` ¶

Study(label, control, treatment, category=None)

A study with a control and a treatment sample of one parameter.

Attributes:

Name	Type	Description
`label`	`str`	label of the study
`control`	`ParameterSample`	the control sample
`treatment`	`ParameterSample`	the treatment sample
`category`	`str \| None`	category of the study for `meta_analysis_by`

to_dict ¶

to_dict()

The label, the category and the sizes of the two samples.

Returns:

Type	Description
`dict[str, Any]`	Field name to value.

MetaResult `dataclass` ¶

MetaResult(
    kind, effects, fixed, random, heterogeneity, ci_level
)

Result of a meta-analysis.

Attributes:

Name	Type	Description
`kind`	`EffectKind`	the kind of effect
`effects`	`tuple[EffectSize, ...]`	the effect per study
`fixed`	`PooledEffect`	the fixed effect pooling
`random`	`PooledEffect`	the random effects pooling
`heterogeneity`	`Heterogeneity`	the heterogeneity statistics
`ci_level`	`float`	level of the intervals

labels `property` ¶

labels

The labels of the studies.

n_studies `property` ¶

n_studies

Number of studies.

to_dict ¶

to_dict()

The kind, the labels and the pooled results as nested dictionaries.

The per study effects are to_dataframe.

Returns:

Type	Description
`dict[str, Any]`	`kind`, `n_studies`, `labels`, `ci_level` and the dictionaries
`dict[str, Any]`	of `fixed`, `random` and `heterogeneity`.

to_dataframe ¶

to_dataframe()

One row per study with its effect, interval, sizes and weights.

Returns:

Type	Description
`DataFrame`	The dataframe.

effect_size ¶

effect_size(
    control,
    treatment,
    kind=HEDGES_G,
    *,
    ci_level=0.95,
    label="",
)

Effect size of a treatment against a control.

The control comes first, the convention of the meta-analysis literature (Hedges 1981; Borenstein et al. 2009) and of Study(label, control, treatment); the comparisons of pkpdutils.stats.tests, pkpdutils.stats.ratio and pkpdutils.stats.bioequivalence put the test or treatment sample first, as their own literature does.

Hedges' g: \(d = (\bar x_T - \bar x_C) / s_p\) with the pooled standard deviation, \(\mathrm{var}(d) = N / (n_C n_T) + d^2 / (2N)\), \(g = J d\), \(\mathrm{var}(g) = J^2 \mathrm{var}(d)\) (Hedges 1981). Mean difference: \(\bar x_T - \bar x_C\) with \(s_T^2 / n_T + s_C^2 / n_C\). Log ratio: \(\mu_T - \mu_C\) of the log moments with \(\sigma_T^2 / n_T + \sigma_C^2 / n_C\).

A degenerate group leaves the effect undefined and gives NaN rather than raising: a group without a finite value has no effect and no variance, a group of a single value has no variance to propagate, and two groups without variance have no standardized difference. The pooling drops such a study with a warning, see _arrays.

Parameters:

Name	Type	Description	Default
`control`	`ParameterSample`	the control sample.	required
`treatment`	`ParameterSample`	the treatment sample.	required
`kind`	`EffectKind \| str`	the kind of effect, as the member or as its string.	`HEDGES_G`
`ci_level`	`float`	level of the interval.	`0.95`
`label`	`str`	label of the study.	`''`

Returns:

Type	Description
`EffectSize`	The effect size.

Raises:

Type	Description
`ValueError`	if `kind` is not an `EffectKind`.

effects_from_arrays ¶

effects_from_arrays(
    estimates,
    variances,
    *,
    labels=None,
    kind=HEDGES_G,
    ci_level=0.95,
)

Effect sizes from estimates and variances computed elsewhere.

Parameters:

Name	Type	Description	Default
`estimates`	`ArrayLike`	the effects.	required
`variances`	`ArrayLike`	their variances.	required

Other Parameters:

Name	Type	Description
`labels`	`Sequence[str] \| None`	labels of the studies, the positions by default.
`kind`	`EffectKind \| str`	the kind of effect, as the member or as its string.
`ci_level`	`float`	level of the intervals.

Returns:

Type	Description
`list[EffectSize]`	The effect sizes (`n_control` and `n_treatment` are 0).

Raises:

Type	Description
`ValueError`	if `kind` is not an `EffectKind` or the lengths differ.

fixed_effect ¶

fixed_effect(effects, *, ci_level=0.95)

Fixed effect pooling with the weights \(w_i = 1 / v_i\).

Parameters:

Name	Type	Description	Default
`effects`	`Sequence[EffectSize]`	the effect sizes.	required
`ci_level`	`float`	level of the interval.	`0.95`

Returns:

Type	Description
`PooledEffect`	The pooled effect.

A study whose effect could not be estimated is dropped with a warning, see _arrays.

Raises:

Type	Description
`ValueError`	as `_arrays`, without effects, for a study with a variance which is not positive, or without a usable study.

heterogeneity ¶

heterogeneity(effects)

Heterogeneity statistics of the effects.

\(Q = \sum w_i (\theta_i - \hat\theta_F)^2\) with \(w_i = 1/v_i\), \(C = \sum w_i - \sum w_i^2 / \sum w_i\), \(\tau^2 = \max(0, (Q - (k-1)) / C)\) (DerSimonian & Laird 1986), \(I^2 = \max(0, (Q - (k-1)) / Q)\), \(H^2 = Q / (k-1)\) (Higgins & Thompson 2002).

A study whose effect could not be estimated is dropped with a warning, see _arrays, so \(k\) counts the pooled studies.

Parameters:

Name	Type	Description	Default
`effects`	`Sequence[EffectSize]`	the effect sizes.	required

Returns:

Type	Description
`Heterogeneity`	The statistics.

Raises:

Type	Description
`ValueError`	as `_arrays`, without effects, for a study with a variance which is not positive, or without a usable study.

random_effects ¶

random_effects(effects, *, ci_level=0.95)

Random effects pooling of DerSimonian & Laird with the weights \(w_i^* = 1 / (v_i + \tau^2)\).

Parameters:

Name	Type	Description	Default
`effects`	`Sequence[EffectSize]`	the effect sizes.	required
`ci_level`	`float`	level of the interval.	`0.95`

A study whose effect could not be estimated is dropped with a warning, see _arrays.

Returns:

Type	Description
`PooledEffect`	The pooled effect.

Raises:

Type	Description
`ValueError`	as `_arrays`, without effects, for a study with a variance which is not positive, or without a usable study.

meta_analysis ¶

meta_analysis(studies, kind=HEDGES_G, *, ci_level=0.95)

Meta-analysis of a parameter over studies.

A study whose effect could not be estimated keeps its NaN effect in effects and in to_dataframe, with a NaN weight, and is dropped from the pooling with a warning naming it (see _arrays).

Parameters:

Name	Type	Description	Default
`studies`	`Sequence[Study]`	the studies.	required
`kind`	`EffectKind \| str`	the kind of effect, as the member or as its string.	`HEDGES_G`
`ci_level`	`float`	level of the intervals.	`0.95`

Returns:

Type	Description
`MetaResult`	The per study effects, the fixed effect and random effects pooling and the heterogeneity.

Raises:

Type	Description
`ValueError`	without studies, for an unknown `kind`, for a study whose effect has a variance which is not positive, or when no study is left to pool.

meta_analysis_by ¶

meta_analysis_by(studies, kind=HEDGES_G, *, ci_level=0.95)

One meta-analysis per category of the studies.

Parameters:

Name	Type	Description	Default
`studies`	`Sequence[Study]`	the studies; a study without a category is grouped under `""`.	required
`kind`	`EffectKind \| str`	the kind of effect, as the member or as its string.	`HEDGES_G`
`ci_level`	`float`	level of the intervals.	`0.95`

Returns:

Type	Description
`dict[str, MetaResult]`	Category to result, in the order of first appearance.

Raises:

Type	Description
`ValueError`	as `meta_analysis`.

stats.meta¶

EffectKind ¶

EffectSize dataclass ¶

to_dict ¶

Heterogeneity dataclass ¶

to_dict ¶

PooledEffect dataclass ¶

to_dict ¶

Study dataclass ¶

to_dict ¶

MetaResult dataclass ¶

labels property ¶

n_studies property ¶

to_dict ¶

to_dataframe ¶

effect_size ¶

effects_from_arrays ¶

fixed_effect ¶

heterogeneity ¶

random_effects ¶

meta_analysis ¶

meta_analysis_by ¶

EffectSize `dataclass` ¶

Heterogeneity `dataclass` ¶

PooledEffect `dataclass` ¶

Study `dataclass` ¶

MetaResult `dataclass` ¶

labels `property` ¶

n_studies `property` ¶