---
title: "Meta-Analysis of Proportions with ProMetaR"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Meta-Analysis of Proportions with ProMetaR}
  %\VignetteEngine{knitr::rmarkdown}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

## Introduction

ProMetaR performs meta-analysis of proportions using study-level event
counts and sample sizes.

The package supports transformation-based meta-analysis, random-effects
estimation, heterogeneity assessment, prediction intervals, subgroup
analysis, meta-regression, leave-one-out sensitivity analysis, influence
diagnostics, forest plots, funnel plots, small-study effect diagnostics,
and an optional binomial generalized linear mixed model interface.

## Basic analysis

A meta-analysis of proportions can be performed using the number of events
and the corresponding sample size from each study.

The following example uses four hypothetical studies.

```{r basic-analysis}
library(ProMetaR)

dat <- data.frame(
  study = paste0("Study ", 1:4),
  events = c(12, 25, 18, 40),
  n = c(100, 150, 120, 200)
)

fit <- meta_prop(
  events = dat$events,
  n = dat$n,
  studlab = dat$study
)

fit
```

A summary of the fitted model can be obtained with:

```{r summary}
summary_prop(fit)
```

Heterogeneity statistics can be obtained using:

```{r heterogeneity}
prop_heterogeneity(fit)
```

## Transformations

The logit transformation is the default transformation used by
`meta_prop()`.

Alternative transformations can be examined as sensitivity analyses,
particularly when proportions are close to zero or one. The
`prop_transform()` function uses study-level event counts and sample sizes.

```{r transformations}
prop_transform(
  events = dat$events,
  n = dat$n,
  method = "logit"
)

prop_transform(
  events = dat$events,
  n = dat$n,
  method = "arcsine"
)

prop_transform(
  events = dat$events,
  n = dat$n,
  method = "raw"
)
```

## Random-effects meta-analysis

The default random-effects model uses the REML estimator.

```{r reml}
fit_reml <- meta_prop(
  events = dat$events,
  n = dat$n,
  studlab = dat$study,
  method = "REML"
)

fit_reml
```

Alternative between-study variance estimators can be used for
sensitivity analyses.

```{r alternative-estimators}
fit_dl <- meta_prop(
  events = dat$events,
  n = dat$n,
  studlab = dat$study,
  method = "DL"
)

fit_pm <- meta_prop(
  events = dat$events,
  n = dat$n,
  studlab = dat$study,
  method = "PM"
)

fit_dl
fit_pm
```

## Prediction interval

A prediction interval accounts for between-study heterogeneity and
describes the expected range of the underlying proportion in a future
comparable study.

```{r prediction}
predict_prop(fit_reml)
```

## Forest plot

A forest plot displays the individual study proportions and the pooled
estimate.

```{r forest, fig.width=7, fig.height=5}
forest_prop(fit_reml)
```

## Funnel plot

A funnel plot can be used as a graphical assessment of possible
small-study effects.

```{r funnel, fig.width=6, fig.height=5}
funnel_prop(fit_reml)
```

Funnel-plot asymmetry can have several possible causes and should be
interpreted cautiously, particularly when the number of studies is small.

## Subgroup analysis

Subgroup analyses can be performed using a categorical variable with one
value for each study.

```{r subgroup}
dat$group <- c(
  "Group A",
  "Group A",
  "Group B",
  "Group B"
)

sub_fit <- subgroup_prop(
  fit_reml,
  subgroup = dat$group
)

sub_fit
```

Each subgroup is analysed separately using the ProMetaR meta-analysis
framework.

## Meta-regression

Study-level moderators can be examined using meta-regression.

```{r metareg}
moderators <- data.frame(
  region = factor(
    c("North", "North", "South", "South")
  ),
  sample_size = dat$n
)

mr <- metareg_prop(
  fit_reml,
  moderators = moderators
)

mr
```

Meta-regression should be interpreted cautiously, particularly when only a
small number of studies are available.

## Leave-one-out sensitivity analysis

The influence of individual studies can be assessed by repeating the
meta-analysis after omitting each study in turn.

```{r leave-one-out}
loo <- loo_prop(fit_reml)

loo
```

## Influence diagnostics

Influence measures based on the leave-one-out analyses can be obtained
using:

```{r influence}
influence_prop(fit_reml)
```

Large changes in the pooled estimate following removal of an individual
study may indicate substantial influence of that study on the overall
result.

## Small-study effect diagnostic

ProMetaR provides an Egger-type regression diagnostic for exploratory
assessment of small-study effects.

```{r bias}
bias_prop(fit_reml)
```

This diagnostic should be interpreted cautiously, especially when the
meta-analysis contains only a small number of studies.

## Freeman-Tukey double-arcsine transformation

The Freeman-Tukey double-arcsine transformation is available using
`transform = "pft"`.

```{r pft}
fit_pft <- meta_prop(
  events = dat$events,
  n = dat$n,
  studlab = dat$study,
  transform = "pft"
)

fit_pft
```

The Freeman-Tukey double-arcsine method is supplied primarily as a
sensitivity analysis because its back-transformation can be sensitive to
study sample sizes.

## Optional binomial GLMM

ProMetaR provides an optional interface to a binomial generalized linear
mixed model through the `metafor` package.

The following example demonstrates the GLMM interface without executing
the optional model during vignette rebuilding.

```{r glmm, eval=FALSE}
fit_glmm <- meta_prop_glmm(
  events = dat$events,
  n = dat$n,
  studlab = dat$study
)

fit_glmm

The GLMM approach provides an alternative modelling framework based
directly on the binomial distribution and can be useful as a sensitivity
analysis, particularly for proportions close to zero or one.

## Complete workflow

A basic ProMetaR workflow can be summarized as follows:

```{r complete-workflow}
fit <- meta_prop(
  events = dat$events,
  n = dat$n,
  studlab = dat$study,
  method = "REML",
  transform = "logit"
)

summary_prop(fit)

prop_heterogeneity(fit)

predict_prop(fit)

forest_prop(fit)
```

Additional sensitivity analyses can then be performed:

```{r sensitivity}
loo_prop(fit)

influence_prop(fit)

bias_prop(fit)
```

## Interpretation

Meta-analysis of proportions requires consideration of study design,
sample size, event frequency, transformation choice, and between-study
heterogeneity.

For proportions close to zero or one, results should preferably be
examined using more than one appropriate analytical approach. The choice
of transformation and between-study variance estimator can affect the
pooled estimate.

The optional binomial GLMM provides an alternative model-based sensitivity
analysis.

## Conclusion

ProMetaR provides a focused workflow for meta-analysis of proportions and
prevalence, including transformation-based random-effects models,
heterogeneity assessment, prediction intervals, subgroup analysis,
meta-regression, leave-one-out sensitivity analysis, influence
diagnostics, forest plots, funnel plots, small-study effect diagnostics,
and an optional binomial GLMM interface.