SHELF: Tools to Support the Sheffield Elicitation Framework

Description

Implements various methods for eliciting a probability distribution for a single parameter from an expert or a group of experts. The expert provides a small number of probability judgements, corresponding to points on his or her cumulative distribution function. A range of parametric distributions can then be fitted and displayed, with feedback provided in the form of fitted probabilities and percentiles. For multiple experts, a weighted linear pool can be calculated. Also includes functions for eliciting beliefs about population distributions; eliciting multivariate distributions using a Gaussian copula; eliciting a Dirichlet distribution; eliciting distributions for variance parameters in a random effects meta-analysis model; survival extrapolation. R Shiny apps for most of the methods are included.

Author(s)

Maintainer: Jeremy Oakley j.oakley@sheffield.ac.uk

See Also

Useful links:

• https://github.com/OakleyJ/SHELF

• Report bugs at https://github.com/OakleyJ/SHELF/issues

Feedback for the elicited distribution of the population CDF

Description

Report the median and 100(1-alpha)% credible interval for point on the population CDF

Usage

cdffeedback(
  medianfit,
  precisionfit,
  quantiles = c(0.05, 0.95),
  vals = NA,
  alpha = 0.05,
  median.dist = "best",
  precision.dist = "gamma",
  n.rep = 10000
)

Arguments

Details

Denote the uncertain population CDF by

P(X \le x | \mu, \sigma^2),

where \mu is the uncertain population median and \sigma^(-2) is the uncertain population precision. Feedback can be reported in the form of the median and 100(1-alpha)% credible interval for (a) an uncertain probability P(X \le x | \mu, \sigma^2), where x is a specified population value and (b) an uncertain quantile x_q defined by P(X \le x_q | \mu, \sigma^2) = q, where q is a specified population probability.

Value

Fitted median and 100(1-alpha)% credible interval for population quantiles and probabilities.

Examples

## Not run: 
prfit <- fitprecision(interval = c(60, 70), propvals = c(0.2, 0.4), trans = "log")
medianfit <- fitdist(vals = c(50, 60, 70), probs = c(0.05, 0.5,  0.95), lower = 0)
cdffeedback(medianfit, prfit, quantiles = c(0.01, 0.99),
            vals = c(65, 75), alpha = 0.05, n.rep = 10000)
 
## End(Not run)  

Plot distribution of CDF

Description

Plot the elicited pointwise median and credible interval for an uncertain population CDF

Usage

cdfplot(
  medianfit,
  precisionfit,
  lower = NA,
  upper = NA,
  ql = 0.025,
  qu = 0.975,
  median.dist = "best",
  precision.dist = "gamma",
  n.rep = 10000,
  n.X = 100,
  fontsize = 18
)

Arguments

Examples

## Not run: 
prfit <- fitprecision(interval = c(60, 70), propvals = c(0.2, 0.4), trans = "log")
medianfit <- fitdist(vals = c(50, 60, 70), probs = c(0.05, 0.5,  0.95), lower = 0)
cdfplot(medianfit, prfit)
 
## End(Not run)

Compare individual elicited distributions with linear pool and RIO distribution

Description

Produce one of three plots to compare the individual elicited judgements with the final elicited distribution, chosen to represent the views of a "Rational Impartatial Observer" (RIO) as part of the SHELF process. A linear pool of fitted distributions from the individually elicited judgements is also obtained. The plot choices are a display of the quartiles, a display of the tertiles, and a plot of the various density functions.

Usage

compareGroupRIO(
  groupFit,
  RIOFit,
  type = "density",
  dLP = "best",
  dRIO = "best",
  xlab = "x",
  ylab = expression(f[X](x)),
  fs = 12
)

Arguments

Author(s)

Jeremy Oakley <j.oakley@sheffield.ac.uk>

Examples

## Not run: 
l <- c(2, 1, 5, 1)
u <- c(95, 90, 65, 40)
v <- matrix(c(15, 25, 40,
 10, 20, 40,
 10, 15, 25,
 5, 10, 20),
 3, 4)
p <- c(0.25, 0.5, 0.75)
group <- fitdist(vals = v, probs = p, lower = l, upper = u)
rio <- fitdist(vals = c(12, 20, 25), probs = p, lower = 1, upper = 100)
compareGroupRIO(groupFit = group, RIOFit = rio, dRIO = "gamma")

## End(Not run)

Plot fitted intervals for each expert

Description

Following elicitation of distributions from individual experts, plot fitted probability intervals for each expert.

Usage

compareIntervals(
  fit,
  interval = 0.95,
  dist = "best",
  fs = 12,
  xlab = "x",
  ylab = "expert",
  showDist = TRUE
)

Arguments

Examples

## Not run: 
v <- matrix(c(30, 40, 50, 20, 25, 35, 40, 50, 60, 35, 40, 50), 3, 4)
p <- c(0.25, 0.5, 0.75)
myfit <- fitdist(vals = v, probs = p, lower = 0, upper = 100)
compareIntervals(myfit, interval = 0.5)

## End(Not run)

Generate correlated samples from elicited marginal distributions using a multivariate normal copula

Description

Takes elicited marginal distributions and elicited concordance probabilities: pairwise probabilities of two uncertain quantities being greater than their medians, and generates a correlated sample, assuming the elicited marginal distributions and a multivariate normal copula. A vignette explaining this method is available at https://oakleyj.github.io/SHELF/Multivariate-normal-copula.html

Usage

copulaSample(..., cp, n, d = NULL, ex = 1)

Arguments

Value

A matrix of sampled values, one row per sample.

Author(s)

Jeremy Oakley j.oakley@sheffield.ac.uk

Examples

## Not run: 
p1 <- c(0.25, 0.5, 0.75)
v1 <- c(0.5, 0.55, 0.6)
v2 <- c(0.22, 0.3, 0.35)
v3 <- c(0.11, 0.15, 0.2)
myfit1 <- fitdist(v1, p1, 0, 1)
myfit2 <- fitdist(v2, p1, 0, 1)
myfit3 <- fitdist(v3, p1, 0, 1)
quad.probs <- matrix(0, 3, 3)
quad.probs[1, 2] <- 0.4
quad.probs[1, 3] <- 0.4
quad.probs[2, 3] <- 0.3
copulaSample(myfit1, myfit2, myfit3, cp=quad.probs, n=100, d=NULL)

## End(Not run)

Elicit judgements and fit distributions interactively

Description

Opens up a web browser (using the shiny package), from which you can specify judgements, fit distributions and plot the fitted density functions with additional feedback. Probabilities can be specified directly, or the roulette elicitation method can be used.

Usage

elicit(lower = 0, upper = 100, gridheight = 10, nbins = 10, method = "general")

Arguments

Details

All input arguments are optional, and can be set/changed within the app itself. Click on the "Help" tab for instructions. Click the "Quit" button to exit the app and return the results from the fitdist command. Click "Download report" to generate a report of all the fitted distributions.

Value

An object of class elicitation, which is returned once the Quit button has been clicked. See fitdist for details.

Author(s)

Jeremy Oakley <j.oakley@sheffield.ac.uk>

Examples

## Not run: 

elicit()


## End(Not run)

Elicit a bivariate distribution using a Gaussian copula

Description

Opens up a web browser (using the shiny package), from which you can specify judgements, fit distributions, plot the fitted density functions, and plot samples from the joint distributions. A joint distribution is constructed using a Gaussian copula, whereby the correlation parameter is determined via the elicitation of a concordance probability (a probability that the two uncertain quantities are either both greater than their medians, or both less than their medians.)

Usage

elicitBivariate()

Details

Click on the "Help" tab for instructions. Click the "Quit" button to exit the app and return the results from the fitdist command. Click "Download report" to generate a report of all the fitted distributions for each uncertain quantity, and "Download sample" to generate a csv file with a sample from the joint distribution.

Value

A list, with two objects of class elicitation, and the elicited concordance probability. See fitdist for details.

Author(s)

Jeremy Oakley <j.oakley@sheffield.ac.uk>

Examples

## Not run: 

elicitBivariate()


## End(Not run)

Elicit a Dirichlet distribution interactively

Description

Opens up a web browser (using the shiny package), from which you can elicit a Dirichlet distribution

Usage

elicitDirichlet()

Details

Click on the "Help" tab for instructions. Click the "Quit" button to exit the app and return the results from the fitdist command. Click "Download report" to generate a report of all the fitted distributions.

Value

The parameters of the fitted Dirichlet distribution, which are returned once the Quit button has been clicked.

Author(s)

Jeremy Oakley <j.oakley@sheffield.ac.uk>

Examples

## Not run: 

elicitDirichlet()


## End(Not run)

Elicitation with the extension method

Description

Opens up a web browser (using the shiny package), from which you can specify judgements, fit distributions, and produce various plots. Judgements are specified for the distribution of the conditioning variable Y, the median function (median of X given Y), and the distribution of X given that Y takes its median value. Plots are provided for the two elicited distributions, the median function, the conditional distribution of X for any specified Y, and the marginal distribution of X.

Usage

elicitExtension()

Details

Click the "Quit" button to exit the app and return the results from the fitdist command. Click "Download report" to generate a report of all the fitted distributions for each uncertain quantity, and "Download sample" to generate a csv file with a sample from the marginal distribution of X.

Value

A list, with two objects of class elicitation. See fitdist for details.

Author(s)

Jeremy Oakley <j.oakley@sheffield.ac.uk>

Examples

## Not run: 

elicitExtension()


## End(Not run)

Elicit a prior distribution for a random effects variance parameter

Description

Opens a shiny app for the roulette elicitation method. The user clicks in the grid to allocate 'probs' to 'bins'. The elicited probability inside each bin is the proportion of probs in each bin. This will fit a distribution to the ratio R of the 'largest' (97.5th percentile) to 'smallest' (2.5th percentile) treatment effect. A distribution for the variance effects variance parameter is inferred from the distribution of R, assuming that the random effects are normally distributed.

Usage

elicitHeterogen(
  lower = 1,
  upper = 10,
  gridheight = 10,
  nbins = 9,
  scale.free = TRUE,
  sigma = 1
)

Arguments

Value

BUGS code for incorporating the prior within a BUGS model. Additionally, a list with outputs

Note

Regarding the option “spread end probs over empty bins” (unchecked as the default): suppose for example, the leftmost and rightmost non-empty bins are [10,20] and [70,80], and each contain one prob, with 20 probs used in total. If the option is unchecked, it is assumed P(X<20) = P(X>70) = 0.05 and P(X<10) = P(X>80) = 0. If the option is checked, it is assumed P(X<20) = P(X>70) = 0.05 only.

Author(s)

Jeremy Oakley <j.oakley@sheffield.ac.uk>

Examples

## Not run: 
elicitHeterogen()

## End(Not run)

Elicit a mixture distribution using the extension method

Description

Opens up a web browser (using the shiny package), from which you can specify judgements, fit distributions and plot the fitted density function.

Usage

elicitMixture()

Details

Click the "Quit" button to exit the app and return the fitted distributions. Click "Download report" to generate a report of all the fitted distributions.

Value

When the Quit button is clicked, a list, with elements

Author(s)

Jeremy Oakley <j.oakley@sheffield.ac.uk>

Examples

## Not run: 

elicitMixture()


## End(Not run)

Elicit individual judgements and fit distributions for multiple experts

Description

Opens up a web browser (using the shiny package), from which you can specify judgements, fit distributions and plot the fitted density functions and a (weighted) linear pool with additional feedback.

Usage

elicitMultiple()

Details

Click the "Quit" button to exit the app and return the results from the fitdist command. Click "Download report" to generate a report of all the fitted distributions.

Value

An object of class elicitation, which is returned once the Finish button has been clicked. See fitdist for details.

Author(s)

Jeremy Oakley <j.oakley@sheffield.ac.uk>

Examples

## Not run: 

elicitMultiple()


## End(Not run)

Elicitation for survival extrapolation

Description

Opens up a web browser in which you can implement the SHELF protocol for survival extrapolation. Start with uploading a .csv file of individual patient survival data (time, event to indicate censoring, and treatment group). Then elicit individual judgements, perform scenario testing as required, and elicit a RIO distribution. Judgements for two treatment groups can be elicited in the same session.

Usage

elicitSurvivalExtrapolation()

Author(s)

Jeremy Oakley <j.oakley@sheffield.ac.uk>

Examples

## Not run: 

# make a suitable csv file using a built in data set from the survival package
sdf <- survival::veteran[, c("time", "status", "trt")]
colnames(sdf) <- c("time", "event", "treatment")
sdf$treatment <- factor(sdf$treatment, labels = c("standard", "test"))

# write the data frame sdf to a .csv file in the current working directory
write.csv(sdf, file = "testFile.csv", row.names = FALSE)

# Run the app and upload testFile.csv in the first tab, and change unit of time to "days"

elicitSurvivalExtrapolation()


## End(Not run)

Report quantiles and probabilities from the fitted probability distributions

Description

Having fitted appropriate distributions to one or more expert's judgements individually using the fitdist command, use this command to get quantiles and probabilities from the fitted distributions

Usage

feedback(fit, quantiles = NA, values = NA, dist = "best", ex = NA, sf = 3)

Arguments

Value

Author(s)

Jeremy Oakley <j.oakley@sheffield.ac.uk>

Examples

## Not run: 
# Two experts
# Expert 1 states P(X<30)=0.25, P(X<40)=0.5, P(X<50)=0.75
# Expert 2 states P(X<20)=0.25, P(X<25)=0.5, P(X<35)=0.75
# Both experts state 0<X<100.

v <- matrix(c(30, 40, 50, 20, 25, 35), 3, 2)
p <- c(0.25, 0.5, 0.75)
myfit <- fitdist(vals = v, probs = p, lower = 0, upper = 100)

feedback(myfit)

# Feedback P(X<60) and the tertiles
feedback(myfit, values=60, quantiles=c(0.33,0.66))

# Compare fitted tertiles for different distributions, expert 2 only
feedback(myfit, quantiles=c(0.33,0.66), ex=2)

## End(Not run)

Calculate quantiles for the marginal distributions of a Dirichlet distribution

Description

Given a (elicited) Dirichlet distribution, calculate quantiles for each marginal beta distribution corresponding to the elicited quantiles

Usage

feedbackDirichlet(d, quantiles = c(0.1, 0.9), sf = 2)

Arguments

Value

Quantiles for each marginal distribution

Author(s)

Jeremy Oakley <j.oakley@sheffield.ac.uk>

Examples

## Not run: 
feedbackDirichlet(d = c(20, 10, 5),
                  quantiles = c(0.1, 0.33, 0.66, 0.9))

## End(Not run)

Fit a Dirichlet distribution to elicited marginal distributions for proportions

Description

Takes elicited beta distributions for a set of proportions as inputs, and fits a Dirichlet distribution. The beta parameters are adjusted so that the expectations sum to 1, and then the sum of the Dirichlet parameters is chosen based on the sums of the beta parameters for each elicited marginal

Usage

fitDirichlet(
  ...,
  categories = NULL,
  n.fitted = "opt",
  plotBeta = TRUE,
  xlab = "x",
  ylab = expression(f[X](x)),
  fs = 12,
  silent = FALSE
)

Arguments

Value

The parameters of the fitted Dirichlet distribution.

Author(s)

Jeremy Oakley <j.oakley@sheffield.ac.uk>

References

Zapata-Vazquez, R., O'Hagan, A. and Bastos, L. S. (2014). Eliciting expert judgements about a set of proportions. Journal of Applied Statistics 41, 1919-1933.

Examples

## Not run: 
p1 <- c(0.25, 0.5, 0.75)
v1 <- c(0.5, 0.55, 0.6)
v2 <- c(0.22, 0.3, 0.35)
v3 <- c(0.11, 0.15, 0.2)
myfit1 <- fitdist(v1, p1, 0, 1)
myfit2 <- fitdist(v2, p1, 0, 1)
myfit3 <- fitdist(v3, p1, 0, 1)
d <- fitDirichlet(myfit1, myfit2, myfit3,
                  categories = c("A","B","C"),
                  n.fitted = "opt")

# Note that this will also work:
d <- fitDirichlet(list(myfit1, myfit2, myfit3),
                  categories = c("A","B","C"),
                  n.fitted = "opt")


## End(Not run)

Fit distributions to elicited probabilities

Description

Takes elicited probabilities as inputs, and fits parametric distributions using least squares on the cumulative distribution function. If separate judgements from multiple experts are specified, the function will fit one set of distributions per expert.

Usage

fitdist(
  vals,
  probs,
  lower = -Inf,
  upper = Inf,
  weights = 1,
  tdf = 3,
  expertnames = NULL,
  excludelogt = FALSE
)

Arguments

Value

An object of class elicitation. This is a list containing the elements

Note

The least squares parameter values are found numerically using the optim command. Starting values for the distribution parameters are chosen based on a simple normal approximation: linear interpolation is used to estimate the 0.4, 0.5 and 0.6 quantiles, and starting parameter values are chosen by setting E(X) equal to the 0.5th quantile, and Var(X) = (0.6 quantile - 0.4 quantile)^2 / 0.25. Note that the arguments lower and upper are not included as elicited values on the cumulative distribution function. To include a judgement such as P(X<=a)=0, the values a and 0 must be included in vals and probs respectively.

Author(s)

Jeremy Oakley <j.oakley@sheffield.ac.uk>

Examples

## Not run: 
# One expert, with elicited probabilities
# P(X<20)=0.25, P(X<30)=0.5, P(X<50)=0.75
# and X>0.
v <- c(20,30,50)
p <- c(0.25,0.5,0.75)
fitdist(vals=v, probs=p, lower=0)

# Now add a second expert, with elicited probabilities
# P(X<55)=0.25, P(X<60=0.5), P(X<70)=0.75
v <- matrix(c(20,30,50,55,60,70),3,2)
p <- c(0.25,0.5,0.75)
fitdist(vals=v, probs=p, lower=0)

# Two experts, different elicited quantiles and limits.
# Expert A: P(X<50)=0.25, P(X<60=0.5), P(X<65)=0.75, and provides bounds 10<X<100
# Expert B: P(X<40)=0.33, P(X<50=0.5), P(X<60)=0.66, and provides bounds 0<X
v <- matrix(c(50,60,65,40,50,60),3,2)
p <- matrix(c(.25,.5,.75,.33,.5,.66),3,2)
l <- c(10,0)
u <- c(100, Inf)
fitdist(vals=v, probs=p, lower=l, upper=u)

## End(Not run)

Fit a distribution to judgements about a population precision

Description

Takes elicited probabilities about proportion of a population lying in a specfied interval as inputs, converts the judgements into probability judgements about the population precision, and fits gamma and lognormal distributions to these judgements using the fitdist function.

Usage

fitprecision(
  interval,
  propvals,
  propprobs = c(0.05, 0.95),
  med = interval[1],
  trans = "identity",
  pplot = TRUE,
  tdf = 3,
  fontsize = 12
)

Arguments

Details

The expert provides a pair of probability judgements

P(\theta < \theta_1 ) = p_1,

and

P(\theta < \theta_2) = p_2,

where \theta is the proportion of the population that lies in the interval [k_1, k_2], conditional on the population median taking some hypothetical value (k_1 by default). k_1 can be set to -Inf, or k_2 can be set to Inf; in either case, the hypothetical median value must be specified. If both k_1 and k_2 are finite, the hypothetical median must be one of the interval endpoints. Note that, unlike the fitdist command, a 'best fitting' distribution is not reported, as the distributions are fitted to two elicited probabilities only.

Value

Examples

## Not run: 
fitprecision(interval=c(60, 70), propvals=c(0.2, 0.4), trans = "log")
  
## End(Not run)

Generate a report to show the fitted distributions

Description

Renders an Rmarkdown document to display the density function of each fitted distribution, the parameter values, and the R command required to sample from each distribution.

Usage

generateReport(
  fit,
  output_format = "html_document",
  sf = 3,
  expert = 1,
  view = TRUE,
  clean = TRUE
)

Arguments

Examples

## Not run: 
# One expert, with elicited probabilities
# P(X<20)=0.25, P(X<30)=0.5, P(X<50)=0.75
# and X>0.
v <- c(20,30,50)
p <- c(0.25,0.5,0.75)
myfit <- fitdist(vals=v, probs=p, lower=0)

generateReport(myfit)

## End(Not run)

Obtain points on the density function of a linear pool

Description

Takes an object of class elicitation, evaluates a (weighted) linear pool, and returns points on the density function at a sequence of values of the elicited parameter

Usage

linearPoolDensity(fit, xl = -Inf, xu = Inf, d = "best", lpw = 1, nx = 200)

Arguments

Value

A list, with elements

Author(s)

Jeremy Oakley <j.oakley@sheffield.ac.uk>

Examples

## Not run: 
# Two experts
# Expert 1 states P(X<30)=0.25, P(X<40)=0.5, P(X<50)=0.75
# Expert 2 states P(X<20)=0.25, P(X<25)=0.5, P(X<35)=0.75
# Both experts state 0<X<100. 

v <- matrix(c(30, 40, 50, 20, 25, 35), 3, 2)
p <- c(0.25, 0.5, 0.75)
myfit <- fitdist(vals = v, probs = p, lower = 0, upper = 100)
linearPoolDensity(myfit)

## End(Not run)

Plot the elicited cumulative probabilities

Description

Plots the elicited cumulative probabilities and, optionally, a fitted CDF. Elicited are shown as filled circles, and limits are shown as clear circles.

Usage

makeCDFPlot(
  lower,
  v,
  p,
  upper,
  fontsize = 12,
  fit = NULL,
  dist = NULL,
  showFittedCDF = FALSE,
  showQuantiles = FALSE,
  ql = 0.05,
  qu = 0.95,
  ex = 1,
  sf = 3,
  xaxisLower = lower,
  xaxisUpper = upper,
  xlab = "x",
  ylab = expression(P(X <= x))
)

Arguments

Examples

## Not run: 
vQuartiles <- c(30, 35, 45)
pQuartiles<- c(0.25, 0.5, 0.75)
myfit <- fitdist(vals = vQuartiles, probs = pQuartiles, lower = 0)
makeCDFPlot(lower = 0, v = vQuartiles, p = pQuartiles,
 upper = 100, fit = myfit, dist = "gamma",
 showFittedCDF = TRUE, showQuantiles = TRUE)



## End(Not run)

Tabulate Summary Data for Survival Extrapolation

Description

Tabulates the Kaplan Meier survivor function and within interval hazard at discrete equally spaced time points t_1,...,t_n "Within interval hazard" is defined as (1-S(t_[n+1])) / S_(t_n), using the Kaplan Meier estimate of S(). The table is intended to be included on a summary sheet provided to experts when eliciting judgements about extrapolated survival probabilities.

Usage

makeSurvivalTable(
  survDf,
  breakTime,
  truncationTime,
  timeUnit,
  useWeights = FALSE,
  dp = 2
)

Arguments

Value

a data frame with survivor function estimates, 95 and within interval hazard estimates for each time interval.

Examples

## Not run: 
sdf <- survival::veteran[, c("time", "status", "trt")]
colnames(sdf) <- c("time", "event", "treatment")
sdf$treatment <- factor(sdf$treatment, labels = c("standard", "test"))
makeSurvivalTable(sdf, breakTime = 50, truncationTime = 250, timeUnit = "months")

## End(Not run)

Plot fitted population pdfs

Description

Plot fitted population pdfs at combinations of two different values of the population mean and variance.

Usage

pdfplots(
  medianfit,
  precisionfit,
  alpha = 0.05,
  tails = 0.05,
  lower = NA,
  upper = NA,
  n.x = 100,
  d = "best",
  fontsize = 18
)

Arguments

Details

Four pdfs are plotted, using each combination of the alpha/2 and 1-alpha/2 quantiles of the fitted distributions for the population median and standard deviation

Value

A plot and a list, containing

References

multiplot function obtained from http://www.cookbook-r.com/Graphs/Multiple_graphs_on_one_page_(ggplot2)/

Examples

## Not run: 
prfit <- fitprecision(interval = c(60, 70), propvals = c(0.2, 0.4), trans = "log")
medianfit <- fitdist(vals = c(50, 60, 70), probs = c(0.05, 0.5,  0.95), lower = 0)
pdfplots(medianfit, prfit, alpha = 0.01)
 
## End(Not run)

Probabilities quantiles and samples from a (weighted) linear pool

Description

Calculates a linear pool given a set of elicited judgements in a fit object. Then calculates required probabilities or quantiles from the pooled cumulative distribution function, or generates a random sample.

Usage

plinearpool(fit, x, d = "best", w = 1)
qlinearpool(fit, q, d = "best", w = 1)
rlinearpool(fit, n, d = "best", w = 1)

Arguments

Details

Quantiles are calculate by first calculating the pooled cumulative distribution function at 100 points, and then using linear interpolation to invert the CDF.

Value

A probability or quantile, calculate from a (weighted) linear pool (arithmetic mean) of the experts' individual fitted probability.

Author(s)

Jeremy Oakley <j.oakley@sheffield.ac.uk>

Examples

## Not run: 
# Expert 1 states P(X<30)=0.25, P(X<40)=0.5, P(X<50)=0.75
# Expert 2 states P(X<20)=0.25, P(X<25)=0.5, P(X<35)=0.75
# Both experts state 0<X<100.

v <- matrix(c(30, 40, 50, 20, 25, 35), 3, 2)
p <- c(0.25, 0.5, 0.75)
myfit <- fitdist(vals = v, probs = p, lower = 0, upper = 100)

plinearpool(myfit, x=c(20, 50, 80))
qlinearpool(myfit, q=c(0.05, 0.5, 0.95))

# give more weight to first expert
plinearpool(myfit, x=c(20, 50, 80), w=c(0.7, 0.3)) 

# force the use of gamma distributions for each expert
qlinearpool(myfit, q=c(0.05, 0.5, 0.95), d="gamma") 

## End(Not run)

Plot density of the target variable, conditional on the extension variable

Description

Plots kernel density estimates of the target variable, conditional on each of a set of specified values of the extension variable. The plot makes use of the function ggridges::geom_density_ridges(), and so uses kernel density estimates rather than the exact conditional density function.

Usage

plotConditionalDensities(
  y,
  fitX,
  yCP,
  xMed,
  medianY,
  link = "identity",
  dist = "best",
  N = 1e+05,
  xLimits = NULL,
  fs = 12
)

Arguments

Examples

## Not run: 

myfitX <- fitdist(vals = c(5.5, 9, 14),
 probs = c(0.25, 0.5, 0.75),
 lower = 0)

plotConditionalDensities(y = c(2, 6, 10),
 fitX = myfitX,
 yCP = c(3, 5, 7, 9.5, 13.5),
 xMed = c(2, 6.5, 9, 13, 20),
 medianY = 7,
 link = "log",
 dist = "lognormal",
 xLimits = c(0, 60))

  
# Example with the logit link

myfitXlogit <- fitdist(vals = c(0.2, 0.25, 0.3),
 probs = c(0.25, 0.5, 0.75),
 lower = 0, 
 upper = 1)
 
 plotConditionalDensities(y = c(2, 6, 10),
  fitX = myfitXlogit, 
  yCP = c(2, 4, 6, 8, 10),
  xMed = c(0.1, 0.3, 0.5, 0.7, 0.9),
  medianY = 6,
  link = "logit",
  dist = "beta")
 

## End(Not run)

Plot the conditional median function

Description

Produces a plot of the conditional median function, given a set of conditioning points for the extension variable, a set of corresponding medians of the target variable, given the extension variable, and a choice of link. The identity link is the default, a log link can be used for non-negative target variables, and a logit link can be used for target variables constrained to lie between 0 and 1.

Usage

plotConditionalMedianFunction(
  yCP,
  xMed,
  yLimits = NULL,
  link = "identity",
  xlab = "Y",
  ylab = "median of X given Y",
  fs = 12,
  ybreaks = NULL,
  xbreaks = NULL
)

Arguments

Author(s)

Jeremy Oakley <j.oakley@sheffield.ac.uk>

Examples

## Not run: 
plotConditionalMedianFunction(yCP = c(3, 5, 7, 9.5, 13.5),
 xMed = c(2, 6.5, 9, 13, 20),
 yLimits = c(0, 20),
 link = "log")
 
plotConditionalMedianFunction(yCP = c(2, 4, 6, 8, 10),
 xMed = c(0.1, 0.3, 0.5, 0.7, 0.9),
 yLimits = c(0, 15),
 link = "logit")
 

## End(Not run)

Plot elicited quartiles, median and plausible range for each expert

Description

Displays a horizontal bar for each expert, to represent the expert's plausible range. The coloured sections indicate the experts' quartiles: four intervals judged by the expert to be equally likely. The experts' medians are shown as dashed lines.

Usage

plotQuartiles(
  vals,
  lower,
  upper,
  fs = 12,
  expertnames = NULL,
  xl = NULL,
  xlabel = "X"
)

Arguments

Author(s)

Jeremy Oakley <j.oakley@sheffield.ac.uk>

Examples

## Not run: 
l <- c(2, 1, 5, 1)
u <- c(95, 90, 65, 40)
v <- matrix(c(15, 25, 40,
 10, 20, 40,
 10, 15, 25,
 5, 10, 20),
 3, 4)
plotQuartiles(vals = v, lower = l, upper  = u)

## End(Not run)

Plot elicted tertiles, median and plausible range for each expert

Description

Displays a horizontal bar for each expert, to represent the expert's plausible range. The coloured sections indicate the experts' tertiles: three intervals judged by the expert to be equally likely. The experts' medians are shown as dashed lines.

Usage

plotTertiles(
  vals,
  lower,
  upper,
  fs = 12,
  percentages = FALSE,
  expertnames = NULL,
  xl = NULL,
  xlabel = "X"
)

Arguments

Author(s)

Jeremy Oakley <j.oakley@sheffield.ac.uk>

Examples

## Not run: 
l <- c(-5, 0, 5, -10)
u <- c(15, 35, 50, 35)
v <- matrix(c(5, 8, 10,
 10, 15, 20,
 15, 18, 25,
 10, 20, 30),
 3, 4)
plotTertiles(vals = v, lower = l, upper  = u)

## End(Not run)

Plot the fitted density function for one or more experts

Description

Plots the fitted density function for one or more experts. Can also plot a fitted linear pool if more than one expert. If plotting the density function of one expert, or the linear pool only, can also indicated desired lower and upper fitted quantiles.

Usage

plotfit(
  fit,
  d = "best",
  xl = -Inf,
  xu = Inf,
  yl = 0,
  yu = NA,
  ql = NA,
  qu = NA,
  lp = FALSE,
  ex = NA,
  sf = 3,
  ind = TRUE,
  lpw = 1,
  fs = 12,
  lwd = 1,
  xlab = "x",
  ylab = expression(f[X](x)),
  legend_full = TRUE,
  percentages = FALSE,
  returnPlot = FALSE,
  showPlot = TRUE
)

Arguments

Author(s)

Jeremy Oakley <j.oakley@sheffield.ac.uk>

Examples

## Not run: 
# Two experts
# Expert 1 states P(X<30)=0.25, P(X<40)=0.5, P(X<50)=0.75
# Expert 2 states P(X<20)=0.25, P(X<25)=0.5, P(X<35)=0.75
# Both experts state 0<X<100. 

v <- matrix(c(30, 40, 50, 20, 25, 35), 3, 2)
p <- c(0.25, 0.5, 0.75)
myfit <- fitdist(vals = v, probs = p, lower = 0, upper = 100)

# Plot both fitted densities, using the best fitted distribution
plotfit(myfit)

# Plot a fitted beta distribution for expert 2, and show 5th and 95th percentiles
plotfit(myfit, d = "beta", ql = 0.05, qu = 0.95, ex = 2)


# Plot a linear pool, giving double weight to expert 1
plotfit(myfit,  lp = T, lpw = c(2,1))


# Plot a linear pool, giving double weight to expert 1, 
# show 5th and 95th percentiles, surpress plotting of individual distributions, 
# and force use of Beta distributions
plotfit(myfit, d = "beta",  lp = T, lpw = c(2,1), ql = 0.05, qu = 0.95, ind=FALSE )

## End(Not run)

Sample from the elicited distributions

Description

Generates a random sample from all distributions specified within an object of class elicitation

Usage

sampleFit(fit, n, expert = 1)

Arguments

Value

A matrix of sampled values, one column per distribution. Column names are given to label the distributions.

Examples

## Not run: 
v <- c(20,30,50)
p <- c(0.25,0.5,0.75)
myfit <- fitdist(vals = v, probs = p, lower = 0, upper = 100)
sampleFit(myfit, n = 10)

## End(Not run)

Sample from the marginal distribution of the target variable

Description

As part of the Extension Method, this function will generate a random sample from the marginal distribution of the target variable, using a sample from the marginal distribution of the extension variable, the specified c-distribution, and the appropriate judgements used to construct the median model.

Usage

sampleMarginalFit(
  fitX,
  sampleY,
  medianY,
  yCP,
  xMed,
  dist = "best",
  link = "identity"
)

Arguments

Value

a vector containing a sample from the marginal distribution of the target variable.

Examples

## Not run: 

myfitX <- fitdist(vals = c(5.5, 9, 14),
 probs = c(0.25, 0.5, 0.75),
 lower = 0)
ry <- rgamma(10, 5.19, 0.694)
sampleMarginalFit(fitX = myfitX, 
 sampleY = ry,
 medianY = 7,
 yCP = c(3, 5, 7, 9.5, 13.5),
 xMed = c(2, 6.5, 9, 13, 20),
 dist = "lognormal",
 link = "log")
 
## End(Not run)

Plot survival data and elicited extrapolated intervals

Description

Show Kaplan-Meier plot of available data, and credible interval for extrapolated survivor function value S(T)

Usage

survivalExtrapolatePlot(
  survDf,
  myfit1,
  myfit2 = NULL,
  fqDist1 = "best",
  fqDist2 = NULL,
  tTruncate = max(survDf$time),
  tTarget,
  alpha = 0.95,
  useWeights = FALSE,
  groups = levels(survDf$treatment),
  xl = "Time (t)",
  fontsize = 12,
  breakTime = NULL,
  showPlot = TRUE,
  returnPlot = FALSE
)

Arguments

Value

a ggplot object, if returnPlot is TRUE

Examples

## Not run: 
sdf <- survival::veteran[, c("time", "status", "trt")]
colnames(sdf) <- c("time", "event", "treatment")
sdf$treatment <- factor(sdf$treatment, labels = c("standard", "test"))

sdf <- survival::veteran[, c("time", "status", "trt")]
colnames(sdf) <- c("time", "event", "treatment")
sdf$treatment <- factor(sdf$treatment, labels = c("standard", "test"))
groupStandardElicitation <- fitdist(vals = c(0.15, 0.2, 0.25),
                                    probs = c(0.25, 0.5, 0.75),
                                    lower = 0,
                                    upper = 1)

groupTestElicitation <- fitdist(vals = c(0.1, 0.15, 0.2),
                                probs = c(0.25, 0.5, 0.75),
                                lower = 0,
                                upper = 1)

survivalExtrapolatePlot(sdf,
                        myfit1 = groupStandardElicitation,
                        myfit2 = groupTestElicitation,
                        fqDist1 = "beta",
                        fqDist2 = "beta",
                        tTruncate = 150,
                        tTarget=200,
                        alpha = 0.95)

## End(Not run)

Compare Multiple Fitted Models for Survival Extrapolation

Description

Fits seven parametric models to an individual patient survival data set (using the flexsurv package), displays extrapolations, and report the time point at which there is the widest range in estimated extrapolated survival probabilities. This function is intended to be used only as an informal exploratory tool to support elicitation for survival extrapolation, specifically, to inform the choice of target extrapolation time. The fitted models are exponential, weibull, gamma, gompertz, log logistic, log normal and geneneralised gamma.

Usage

survivalModelExtrapolations(
  survDf,
  tOffset = 0,
  tEnd,
  group,
  tTruncate = NULL,
  dists = c("exp", "weibull", "gamma", "gompertz", "llogis", "lnorm", "gengamma"),
  nModels = length(dists),
  showPlot = TRUE
)

Arguments

Value

A list containing the elements

Examples

## Not run: 

# Make a data frame using the survival::veteran data frame
sdf <- survival::veteran[, c("time", "status", "trt")]
colnames(sdf) <- c("time", "event", "treatment")
sdf$treatment <- factor(sdf$treatment, labels = c("standard", "test"))

survivalModelExtrapolations(sdf, tEnd = 1000, group = "test", tTruncate = 100)

## End(Not run)

Scenario Testing for Survival Extrapolation

Description

Provides a plot and approximate 95 extrapolated surival time, based on a assumption of constant hazard after some specified time. Intended to be used as part of the SHELF protocol for elicitation for survival extrapolation.

Usage

survivalScenario(
  tLower = 0,
  tUpper,
  expLower,
  expUpper,
  tTarget,
  survDf,
  groups = unique(survDf$treatment),
  expGroup = unique(survDf$treatment)[1],
  useWeights = FALSE,
  xl = "Time",
  fontsize = 12,
  showPlot = TRUE
)

Arguments

Value

A list containing the elements

Examples

## Not run: 
sdf <- survival::veteran[, c("time", "status", "trt")]
colnames(sdf) <- c("time", "event", "treatment")
sdf$treatment <- factor(sdf$treatment, labels = c("standard", "test"))
survivalScenario(tLower = 0,tUpper = 150, expLower = 100, expUpper = 150,
tTarget = 250, survDf = sdf,
expGroup = "standard")

## End(Not run)