Help for package poth

Title:

Precision of Treatment Hierarchy (POTH)

Version:

0.3-0

Date:

2025-04-09

Depends:

R (≥ 3.5.0)

Imports:

ggplot2, stringr, netmeta, MASS

Suggests:

mvtnorm

Author:

Augustine Wigle

[aut, cre, cph], Guido Schwarzer

[aut]

Maintainer:

Augustine Wigle <amhwigle@uwaterloo.ca>

Description:

Calculate POTH for treatment hierarchies from frequentist and Bayesian network meta-analysis. POTH quantifies the certainty in a treatment hierarchy. Subset POTH, POTH residuals, and best k treatments POTH can also be calculated to improve interpretation of treatment hierarchies.

URL:

https://github.com/augustinewigle/poth

BugReports:

https://github.com/augustinewigle/poth/issues

License:

GPL-2 | GPL-3 [expanded from: GPL (≥ 2)]

Encoding:

UTF-8

LazyData:

true

RoxygenNote:

7.3.2

NeedsCompilation:

Packaged:

2025-04-17 13:48:44 UTC; augus

Repository:

CRAN

Date/Publication:

2025-04-17 16:00:02 UTC

poth: Brief overview of methods and general hints

Description

R package poth allows to calculate the precision of treatment hierarchy (POTH) metric to quantify the uncertainty in a treatment hierarchy in network meta-analysis (Wigle et al., 2024).

Details

R package poth provides the following methods:

Calculate the separation in ranking metric (poth)
Conduct leave-one-out analysis (loo.poth)

Type help(package = "poth") for a listing of R functions available in poth.

Type citation("poth") on how to cite poth in publications.

The development version of poth is available on GitHub https://github.com/augustinewigle/poth.

Author(s)

Augustine Wigle amhwigle@uwaterloo.ca, Guido Schwarzer guido.schwarzer@uniklinik-freiburg.de

References

Wigle A, Béliveau A, Salanti G, Rücker G, Schwarzer G, Mavridis D, Nikolakopoulou A (2024): Precision of treatment hierarchy: A metric for quantifying uncertainty in treatment hierarchies in network meta-analysis. Preprint on arXiv, doi:10.48550/arXiv.2501.11596

Safety of Immune Checkpoint Inhibitors in Cancer

Description

Data from a network meta-analysis on immune checkpoint inhibitors (ICIs) to assess the safety of ICI drugs as cancer treatment (Xu et al., 2018).

Format

A data frame with the following columns:

*studyID*	study id
*treatment*	treatment name
*adverse*	number of adverse events
n	group sample size

Details

Data were obtained from Rosenberger et al. (2021), who re-analysed the data. There are seven treatments and 23 studies. The outcome of interest is the number of treatment-related adverse events, so smaller values indicate a safer treatment.

Source

Rosenberger, K.J., Duan, R., Chen, Y. et al. (2021): Predictive P-score for treatment ranking in Bayesian network meta-analysis. BMC Med Res Methodol 21, 213. doi:10.1186/s12874-021-01397-5

Examples

data(Xu2018)
head(Xu2018)

library("netmeta")
pw <- pairwise(treat = treatment, event = adverse, n = n,
  studlab = studyID, data = Xu2018, sm = "OR")
#
net <- netmeta(pw, small.values = "desirable", method.tau = "REML",
  common = FALSE)
#
poth(net)

Best k treatments method for precision of treatment hierarchy (POTH) metric

Description

Best k treatments method for precision of treatment hierarchy (POTH) metric

Usage

## S3 method for class 'poth'
bestk(x, sort = TRUE, ...)

## S3 method for class 'bestk.poth'
print(x, digits = 3, legend = TRUE, ...)

bestk(x, ...)

Arguments

x

An R object of class poth.

sort

A logical indicating whether results should be sorted by decreasing ranking metric.

...

Additional arguments.

digits

Minimal number of significant digits, see print.default.

legend

A logical indicating whether a legend should be printed.

Value

A data frame with additional class bestk.poth and the following variables:

trt

Name of added treatment.

rank

Treatment rank (global).

score

Ranking metric (global).

poth_bestk

Best k treatments POTH.

Examples


library("netmeta")
data(Senn2013)
net1 <- netmeta(TE, seTE, treat1.long, treat2.long, studlab,
  data = Senn2013, sm = "MD", random = FALSE)

# Best k treatments method
bk1 <- bestk(poth(net1))
bk1
plot(bk1)
plot(bk1, labels = TRUE)
bk2 <- bestk(poth(net1), sort = FALSE)
bk2
plot(bk2)
plot(bk2, labels = TRUE)

Leave-one-out method for precision of treatment hierarchy (POTH) metric

Description

Leave-one-out method for precision of treatment hierarchy (POTH) metric

Usage

## S3 method for class 'poth'
loo(x, ...)

loo(x, ...)

## S3 method for class 'loo.poth'
print(x, digits = 3, legend = TRUE, ...)

Arguments

x

An R object of class poth.

...

Additional arguments.

digits

Minimal number of significant digits, see print.default.

legend

A logical indicating whether a legend should be printed.

Value

A data frame with additional class loo.poth and the following variables:

trt

Treatment names.

rank

Treatment rank (global).

score

Ranking metric (global).

poth_loo

Leave-one-out POTH.

resid

Residuals (global POTH minus leave-one-out POTH.

ratio

Ratio of residual devided by absolute sum of residuals.

Examples

library("netmeta")
data(smokingcessation)
p1 <- pairwise(list(treat1, treat2, treat3),
  event = list(event1, event2, event3), n = list(n1, n2, n3),
  data = smokingcessation, sm = "OR")
net1 <- netmeta(p1, random = FALSE)

# Leave-one-out method
loo1 <- loo(poth(net1))
loo1

Plot best k treatments precision of treatment hierarchy (POTH) values

Description

Plot best k treatments precision of treatment hierarchy (POTH) values

Usage

## S3 method for class 'bestk.poth'
plot(x, labels = FALSE, nchar.trts = 4, digits = 3, ...)

Arguments

x

R object of class bestk.poth.

labels

A logical indicating whether treatment names should be shown in the plot.

nchar.trts

Number of characters to keep for each treatment name if labels = TRUE.

digits

Minimal number of significant digits for best k treatments POTH, see print.default.

...

Additional arguments (ignored).

Details

Plot results of best k treatments method for precision of treatment hierarchy (POTH) metric (Wigle et al., 2024).

Value

A ggplot2 object.

Author(s)

Augustine Wigle amhwigle@uwaterloo.ca, Guido Schwarzer guido.schwarzer@uniklinik-freiburg.de

References

Examples


library("netmeta")
data(Senn2013)
net1 <- netmeta(TE, seTE, treat1.long, treat2.long, studlab,
  data = Senn2013, sm = "MD", random = FALSE)

# Best k treatments method
bk1 <- bestk(poth(net1))
bk1
plot(bk1)
plot(bk1, labels = TRUE)
bk2 <- bestk(poth(net1), sort = FALSE)
bk2
plot(bk2)
plot(bk2, labels = TRUE)

Plot results of leave-one-out method

Description

Plot results of leave-one-out method for precision of treatment hierarchy (POTH) metric

Usage

## S3 method for class 'loo.poth'
plot(x, labels = TRUE, digits = 3, ...)

Arguments

x

R object of class poth.

labels

A logical indicating whether treatment names should be shown in the plot.

digits

Minimal number of significant digits for global POTH, see print.default.

...

Additional arguments (ignored).

Details

Plot results of leave-one-out method for precision of treatment hierarchy (POTH) metric (Wigle et al., 2024).

Value

A ggplot2 object.

Author(s)

Augustine Wigle amhwigle@uwaterloo.ca, Guido Schwarzer guido.schwarzer@uniklinik-freiburg.de

References

Examples

library("netmeta")
data(smokingcessation)
p1 <- pairwise(list(treat1, treat2, treat3),
  event = list(event1, event2, event3), n = list(n1, n2, n3),
  data = smokingcessation, sm = "OR")
net1 <- netmeta(p1, random = FALSE)

# Leave-one-out method
loo1 <- loo(poth(net1))
loo1
plot(loo1)


data(Senn2013)
net2 <- netmeta(TE, seTE, treat1.long, treat2.long, studlab,
                data = Senn2013, sm = "MD", random = FALSE)

# Leave-one-out method (without sorting by ranking metric)
loo2 <- loo(poth(net2), sort = FALSE)
loo2
plot(loo2)

Plot reference distribution for given network

Description

Plot a histogram of simulated reference distribution for POTH

Usage

## S3 method for class 'refdist'
plot(x, observed = TRUE, probability = FALSE, ...)

Arguments

x

R object of class refdist.

observed

A logical indicating whether a line with the observed POTH should be drawn in the plot.

probability

A logical indicating whether the probability of a POTH greater than the observed POTH should be printed in the legend. This argument is ignored if observed = FALSE.

...

Additional arguments (ignored).

Details

Plots a histogram of the simulated POTH values from the reference distribution. (Wigle et al., 2024).

Value

A ggplot2 object.

Author(s)

Augustine Wigle amhwigle@uwaterloo.ca, Guido Schwarzer guido.schwarzer@uniklinik-freiburg.de

References

Examples


library("netmeta")
data(smokingcessation)
p1 <- pairwise(list(treat1, treat2, treat3),
  event = list(event1, event2, event3), n = list(n1, n2, n3),
  data = smokingcessation, sm = "OR")
net1 <- netmeta(p1, random = FALSE)

# Reference distribution
dist1 <- refdist(net1, pooled = "common", nsim = 2)
plot(dist1, observed = FALSE)

data(Senn2013)
net2 <- netmeta(TE, seTE, treat1.long, treat2.long, studlab,
                data = Senn2013, sm = "MD", random = FALSE)

# Reference distribution
dist2 <- refdist(net2, pooled = "common", nsim = 25)
plot(dist2, probability = TRUE)

Calculate precision of treatment hierarchy (POTH) metric

Description

Precision of treatment hierarchy (POTH) is a metric to quantify the uncertainty in a treatment hierarchy in network meta-analysis

Usage

poth(x, se = NULL, small.values, pooled, trts = NULL)

## S3 method for class 'poth'
print(x, sort = TRUE, digits = 3, ...)

## S3 method for class 'poth'
summary(object, ...)

## S3 method for class 'summary.poth'
print(x, sort = TRUE, digits = 3, ...)

Arguments

x

Mandatory argument with suitable information on the treatment hierarchy (see Details).

se

Matrix of estimated standard errors for relative effects.

small.values

A character string specifying whether small outcome values indicate a beneficial ("desirable") or harmful ("undesirable") effect, can be abbreviated.

pooled

A character string indicating whether the treatment hierarchy is based on a common or random effects model. Either "common" or "random", can be abbreviated.

trts

An optional vector with treatment names. Must match the order of treatments provided for argument x.

sort

A logical indicating whether printout should be sorted by decreasing ranking metric.

digits

Minimal number of significant digits, see print.default.

...

Additional arguments (ignored).

object

An object of class summary.poth.

Details

This function calculates the precision of treatment hierarchy (POTH) metric to quantify the uncertainty in a treatment hierarchy in network meta-analysis (Wigle et al., 2024).

Argument x providing information on the treatment hierarchy is the only mandatory argument. The following input formats can be provided:

vector representing a ranking metric, i.e., SUCRAs or P-scores,
square matrix with the probabilities for each possible rank (with treatments in rows and ranks in columns),
MCMC samples (with samples in rows and treatments in columns),
relative effect matrix,
R object created with netmeta, netrank, or rankogram object from R package netmeta.

Argument se must be provided if argument x is a matrix with relative effects. Otherwise, argument se is ignored.

Argument small.values must be provided if argument x contains MCMC samples, relative effects, or is an object created with netmeta. This argument can be provided for an R object created with netrank or rankogram and is ignored otherwise.

For a netmeta, netrank, or rankogram object, argument pooled is by default equal to "random" if only the random effects model was considered in the analysis.

Argument trts is ignored for netmeta, netrank, and rankogram objects.

Value

An object of class poth with corresponding print function. The object is a list containing the following components:

poth

Separation in ranking metric.

ranking

A named numeric vector with rankings, i.e., SUCRAs or P-scores.

ranking.matrix

A square matrix with the probabilities for each possible rank (if information is available).

pooled

As defined above.

Author(s)

Augustine Wigle amhwigle@uwaterloo.ca, Guido Schwarzer guido.schwarzer@uniklinik-freiburg.de

References

Examples


library("netmeta")
data(smokingcessation)
p1 <- pairwise(list(treat1, treat2, treat3),
  event = list(event1, event2, event3), n = list(n1, n2, n3),
  data = smokingcessation, sm = "OR")
net1 <- netmeta(p1, random = FALSE)

# Calculate probabilities for each possible rank
set.seed(1909) # make results reproducible
rg1 <- rankogram(net1)
rg1

# Calculate POTH
s1 <- poth(rg1)
s1

# Also print probabilities for each possible rank
summary(s1)

# Use SUCRAs to calculate POTH
nr1 <- netrank(rg1)
nr1
poth(nr1)
poth(nr1$ranking.common)

data(Senn2013)
net2 <- netmeta(TE, seTE, treat1.long, treat2.long, studlab,
                data = Senn2013, sm = "MD", random = FALSE)

# Use P-scores to calculate POTH
nr2 <- netrank(net2)
nr2
poth(nr2)

Calculate P-scores from a set of relative effects and standard errors

Description

Calculate P-scores from a set of relative effects and standard errors

Usage

pscores(TE, seTE, small.values = "desirable", trts = NULL)

Arguments

TE

Matrix of relative effects

seTE

Matrix of estimated standard errors for relative effects

small.values

A character string specifying whether small outcome values indicate a beneficial ("desirable") or harmful ("undesirable") effect, can be abbreviated.

trts

optional; vector of treatment names matching order in TE and sds

Value

named vector of P-scores

Calculate a ranking probabilities matrix from MCMC samples

Description

Calculate a ranking probabilities matrix from MCMC samples

Usage

rankMCMC(x, small.values = "desirable", trts = NULL)

Arguments

x

a matrix or data.frame of MCMC samples, where rows are MCMC samples and columns are relative effects (relative to anchor) for treatments. must have column names that are the name of each treatment.

small.values

A character string specifying whether small outcome values indicate a beneficial ("desirable") or harmful ("undesirable") effect, can be abbreviated.

trts

character vector of treatment names, optional if samples has column names

Value

A matrix of ranking probabilities where rows are treatments and columns are ranks

Generate reference distribution for POTH for a given network structure

Description

Generate reference distribution for POTH for a given network structure

Usage

refdist(x, d, pooled, nsim = 25, verbose = TRUE)

## S3 method for class 'refdist'
print(x, ...)

## S3 method for class 'refdist'
summary(object, ...)

Arguments

x

A netmeta object.

d

A vector of the desired relative effects, must be in the same order as x$trts.

pooled

A character string indicating whether the treatment hierarchy is based on a common or random effects model. Either "common" or "random", can be abbreviated.

nsim

Number of samples from reference distribution.

verbose

A logical indicating whether progress information should be printed.

...

Additional arguments passed on to print or summary function.

object

A refdist object.

Details

By default, argument pooled is equal to "random" if only the random effects model was considered in the network meta-analysis x. Otherwise, argument pooled is equal to "common".

If argument d is missing, the respective relative effects are taken to be all 0.

Value

A vector of POTH values.

Examples


library("netmeta")
data(Senn2013)
net1 <- netmeta(TE, seTE, treat1.long, treat2.long, studlab,
  data = Senn2013,
  sm = "MD")

# POTH (based on common effects model)
poth(net1)

# Sample POTH values from reference distribution (common effects model)
set.seed(1909)
poths <- refdist(net1)
summary(poths)

# POTH (based on random effects model)
poth(net1, pooled = "random")

# Sample POTH values from reference distribution (common effect model)
poths.r <- refdist(net1, pooled = "random")
summary(poths.r)

Calculate the local POTH for a subset of treatments

Description

Calculate the local POTH for a subset of treatments

Usage

## S3 method for class 'poth'
subset(x, subset, top, bottom, ...)

Arguments

x

An object of class poth.

subset

A character vector of treatment names to consider as the set of competing treatments.

top

A single integer to define the number of treatments with the largest ranking metric to consider in subset.

bottom

A single integer to define the number of treatments with the smallest ranking metric to consider in subset.

...

Additional arguments (ignored).

Value

An R object of class poth.

Examples

library("netmeta")
data(smokingcessation)
p1 <- pairwise(list(treat1, treat2, treat3),
  event = list(event1, event2, event3), n = list(n1, n2, n3),
  data = smokingcessation, sm = "OR")
net1 <- netmeta(p1, random = FALSE)

# Use P-scores to calculate local POTH for treatments "A" and "C"
subset(poth(net1), subset = c("A", "C"))

# Use P-scores to calculate local POTH for first three treatments
subset(poth(net1), top = 3)

# Use P-scores to calculate local POTH for first three treatments
subset(poth(net1), bottom = 3)

poth: Brief overview of methods and general hints

Description

Details

Author(s)

References

See Also

Safety of Immune Checkpoint Inhibitors in Cancer

Description

Format

Details

Source

See Also

Examples

Best k treatments method for precision of treatment hierarchy (POTH) metric

Description

Usage

Arguments

Value

Examples

Leave-one-out method for precision of treatment hierarchy (POTH) metric

Description

Usage

Arguments

Value

Examples

Plot best k treatments precision of treatment hierarchy (POTH) values

Description

Usage

Arguments

Details

Value

Author(s)

References

Examples

Plot results of leave-one-out method

Description

Usage

Arguments

Details

Value

Author(s)

References

Examples

Plot reference distribution for given network

Description

Usage

Arguments

Details

Value

Author(s)

References

Examples

Calculate precision of treatment hierarchy (POTH) metric

Description

Usage

Arguments

Details

Value

Author(s)

References

Examples

Calculate P-scores from a set of relative effects and standard errors

Description

Usage

Arguments

Value

Calculate a ranking probabilities matrix from MCMC samples

Description

Usage

Arguments

Value

Generate reference distribution for POTH for a given network structure

Description

Usage

Arguments

Details

Value

See Also

Examples

Calculate the local POTH for a subset of treatments