evaluate_estimator-methods {adestr}

Evaluate performance characteristics of an estimator

Description

This function evaluates an EstimatorScore for a PointEstimator or and IntervalEstimator by integrating over the sampling distribution.

Usage

## S4 method for signature 'PointEstimatorScore,IntervalEstimator'
evaluate_estimator(
  score,
  estimator,
  data_distribution,
  use_full_twoarm_sampling_distribution = FALSE,
  design,
  true_parameter = mu,
  mu,
  sigma,
  tol = getOption("adestr_tol_outer", default = .adestr_options[["adestr_tol_outer"]]),
  maxEval = getOption("adestr_maxEval_outer", default =
    .adestr_options[["adestr_maxEval_outer"]]),
  absError = getOption("adestr_absError_outer", default =
    .adestr_options[["adestr_absError_outer"]]),
  exact = FALSE,
  early_futility_part = TRUE,
  continuation_part = TRUE,
  early_efficacy_part = TRUE,
  conditional_integral = FALSE
)

## S4 method for signature 'IntervalEstimatorScore,PointEstimator'
evaluate_estimator(
  score,
  estimator,
  data_distribution,
  use_full_twoarm_sampling_distribution = FALSE,
  design,
  true_parameter = mu,
  mu,
  sigma,
  tol = getOption("adestr_tol_outer", default = .adestr_options[["adestr_tol_outer"]]),
  maxEval = getOption("adestr_maxEval_outer", default =
    .adestr_options[["adestr_maxEval_outer"]]),
  absError = getOption("adestr_absError_outer", default =
    .adestr_options[["adestr_absError_outer"]]),
  exact = FALSE,
  early_futility_part = TRUE,
  continuation_part = TRUE,
  early_efficacy_part = TRUE,
  conditional_integral = FALSE
)

## S4 method for signature 'list,Estimator'
evaluate_estimator(
  score,
  estimator,
  data_distribution,
  use_full_twoarm_sampling_distribution = FALSE,
  design,
  true_parameter = mu,
  mu,
  sigma,
  tol = getOption("adestr_tol_outer", default = .adestr_options[["adestr_tol_outer"]]),
  maxEval = getOption("adestr_maxEval_outer", default =
    .adestr_options[["adestr_maxEval_outer"]]),
  absError = getOption("adestr_absError_outer", default =
    .adestr_options[["adestr_absError_outer"]]),
  exact = FALSE,
  early_futility_part = TRUE,
  continuation_part = TRUE,
  early_efficacy_part = TRUE,
  conditional_integral = FALSE
)

## S4 method for signature 'Expectation,PointEstimator'
evaluate_estimator(
  score,
  estimator,
  data_distribution,
  use_full_twoarm_sampling_distribution = FALSE,
  design,
  true_parameter = mu,
  mu,
  sigma,
  tol = getOption("adestr_tol_outer", default = .adestr_options[["adestr_tol_outer"]]),
  maxEval = getOption("adestr_maxEval_outer", default =
    .adestr_options[["adestr_maxEval_outer"]]),
  absError = getOption("adestr_absError_outer", default =
    .adestr_options[["adestr_absError_outer"]]),
  exact = FALSE,
  early_futility_part = TRUE,
  continuation_part = TRUE,
  early_efficacy_part = TRUE,
  conditional_integral = FALSE
)

## S4 method for signature 'Bias,PointEstimator'
evaluate_estimator(
  score,
  estimator,
  data_distribution,
  use_full_twoarm_sampling_distribution = FALSE,
  design,
  true_parameter = mu,
  mu,
  sigma,
  tol = getOption("adestr_tol_outer", default = .adestr_options[["adestr_tol_outer"]]),
  maxEval = getOption("adestr_maxEval_outer", default =
    .adestr_options[["adestr_maxEval_outer"]]),
  absError = getOption("adestr_absError_outer", default =
    .adestr_options[["adestr_absError_outer"]]),
  exact = FALSE,
  early_futility_part = TRUE,
  continuation_part = TRUE,
  early_efficacy_part = TRUE,
  conditional_integral = FALSE
)

## S4 method for signature 'Variance,PointEstimator'
evaluate_estimator(
  score,
  estimator,
  data_distribution,
  use_full_twoarm_sampling_distribution = FALSE,
  design,
  true_parameter = mu,
  mu,
  sigma,
  tol = getOption("adestr_tol_outer", default = .adestr_options[["adestr_tol_outer"]]),
  maxEval = getOption("adestr_maxEval_outer", default =
    .adestr_options[["adestr_maxEval_outer"]]),
  absError = getOption("adestr_absError_outer", default =
    .adestr_options[["adestr_absError_outer"]]),
  exact = FALSE,
  early_futility_part = TRUE,
  continuation_part = TRUE,
  early_efficacy_part = TRUE,
  conditional_integral = FALSE
)

## S4 method for signature 'MSE,PointEstimator'
evaluate_estimator(
  score,
  estimator,
  data_distribution,
  use_full_twoarm_sampling_distribution = FALSE,
  design,
  true_parameter = mu,
  mu,
  sigma,
  tol = getOption("adestr_tol_outer", default = .adestr_options[["adestr_tol_outer"]]),
  maxEval = getOption("adestr_maxEval_outer", default =
    .adestr_options[["adestr_maxEval_outer"]]),
  absError = getOption("adestr_absError_outer", default =
    .adestr_options[["adestr_absError_outer"]]),
  exact = FALSE,
  early_futility_part = TRUE,
  continuation_part = TRUE,
  early_efficacy_part = TRUE,
  conditional_integral = FALSE
)

## S4 method for signature 'OverestimationProbability,PointEstimator'
evaluate_estimator(
  score,
  estimator,
  data_distribution,
  use_full_twoarm_sampling_distribution = FALSE,
  design,
  true_parameter = mu,
  mu,
  sigma,
  tol = getOption("adestr_tol_outer", default = .adestr_options[["adestr_tol_outer"]]),
  maxEval = getOption("adestr_maxEval_outer", default =
    .adestr_options[["adestr_maxEval_outer"]]),
  absError = getOption("adestr_absError_outer", default =
    .adestr_options[["adestr_absError_outer"]]),
  exact = FALSE,
  early_futility_part = TRUE,
  continuation_part = TRUE,
  early_efficacy_part = TRUE,
  conditional_integral = FALSE
)

## S4 method for signature 'Coverage,IntervalEstimator'
evaluate_estimator(
  score,
  estimator,
  data_distribution,
  use_full_twoarm_sampling_distribution = FALSE,
  design,
  true_parameter = mu,
  mu,
  sigma,
  tol = getOption("adestr_tol_outer", default = .adestr_options[["adestr_tol_outer"]]),
  maxEval = getOption("adestr_maxEval_outer", default =
    .adestr_options[["adestr_maxEval_outer"]]),
  absError = getOption("adestr_absError_outer", default =
    .adestr_options[["adestr_absError_outer"]]),
  exact = FALSE,
  early_futility_part = TRUE,
  continuation_part = TRUE,
  early_efficacy_part = TRUE,
  conditional_integral = FALSE
)

## S4 method for signature 'SoftCoverage,IntervalEstimator'
evaluate_estimator(
  score,
  estimator,
  data_distribution,
  use_full_twoarm_sampling_distribution = FALSE,
  design,
  true_parameter = mu,
  mu,
  sigma,
  tol = getOption("adestr_tol_outer", default = .adestr_options[["adestr_tol_outer"]]),
  maxEval = getOption("adestr_maxEval_outer", default =
    .adestr_options[["adestr_maxEval_outer"]]),
  absError = getOption("adestr_absError_outer", default =
    .adestr_options[["adestr_absError_outer"]]),
  exact = FALSE,
  early_futility_part = TRUE,
  continuation_part = TRUE,
  early_efficacy_part = TRUE,
  conditional_integral = FALSE
)

## S4 method for signature 'Width,IntervalEstimator'
evaluate_estimator(
  score,
  estimator,
  data_distribution,
  use_full_twoarm_sampling_distribution = FALSE,
  design,
  true_parameter = mu,
  mu,
  sigma,
  tol = getOption("adestr_tol_outer", default = .adestr_options[["adestr_tol_outer"]]),
  maxEval = getOption("adestr_maxEval_outer", default =
    .adestr_options[["adestr_maxEval_outer"]]),
  absError = getOption("adestr_absError_outer", default =
    .adestr_options[["adestr_absError_outer"]]),
  exact = FALSE,
  early_futility_part = TRUE,
  continuation_part = TRUE,
  early_efficacy_part = TRUE,
  conditional_integral = FALSE
)

## S4 method for signature 'TestAgreement,IntervalEstimator'
evaluate_estimator(
  score,
  estimator,
  data_distribution,
  use_full_twoarm_sampling_distribution = FALSE,
  design,
  true_parameter = mu,
  mu,
  sigma,
  tol = getOption("adestr_tol_outer", default = .adestr_options[["adestr_tol_outer"]]),
  maxEval = getOption("adestr_maxEval_outer", default =
    .adestr_options[["adestr_maxEval_outer"]]),
  absError = getOption("adestr_absError_outer", default =
    .adestr_options[["adestr_absError_outer"]]),
  exact = FALSE,
  early_futility_part = TRUE,
  continuation_part = TRUE,
  early_efficacy_part = TRUE,
  conditional_integral = FALSE
)

## S4 method for signature 'TestAgreement,PValue'
evaluate_estimator(
  score,
  estimator,
  data_distribution,
  use_full_twoarm_sampling_distribution = FALSE,
  design,
  true_parameter = mu,
  mu,
  sigma,
  tol = getOption("adestr_tol_outer", default = .adestr_options[["adestr_tol_outer"]]),
  maxEval = getOption("adestr_maxEval_outer", default =
    .adestr_options[["adestr_maxEval_outer"]]),
  absError = getOption("adestr_absError_outer", default =
    .adestr_options[["adestr_absError_outer"]]),
  exact = FALSE,
  early_futility_part = TRUE,
  continuation_part = TRUE,
  early_efficacy_part = TRUE,
  conditional_integral = FALSE
)

## S4 method for signature 'Centrality,PointEstimator'
evaluate_estimator(
  score,
  estimator,
  data_distribution,
  use_full_twoarm_sampling_distribution = FALSE,
  design,
  true_parameter = mu,
  mu,
  sigma,
  tol = getOption("adestr_tol_outer", default = .adestr_options[["adestr_tol_outer"]]),
  maxEval = getOption("adestr_maxEval_outer", default =
    .adestr_options[["adestr_maxEval_outer"]]),
  absError = getOption("adestr_absError_outer", default =
    .adestr_options[["adestr_absError_outer"]]),
  exact = FALSE,
  early_futility_part = TRUE,
  continuation_part = TRUE,
  early_efficacy_part = TRUE,
  conditional_integral = FALSE
)

Arguments

score

performance measure to evaluate.

estimator

object of class PointEstimator, IntervalEstimator or PValue.

data_distribution

object of class Normal or Student.

use_full_twoarm_sampling_distribution

logical indicating whether this estimator is intended to be used with the full sampling distribution in a two-armed trial.

design

object of class TwoStageDesign.

true_parameter

true value of the parameter (used e.g. when evaluating bias).

mu

expected value of the underlying normal distribution.

sigma

assumed standard deviation.

tol

relative tolerance.

maxEval

maximum number of iterations.

absError

absolute tolerance.

exact

logical indicating usage of exact n2 function.

early_futility_part

include early futility part of integral.

continuation_part

include continuation part of integral.

early_efficacy_part

include early efficacy part of integral.

conditional_integral

treat integral as a conditional integral.

Details

General

First, a functional representation of the integrand is created by combining information from the EstimatorScore object (score) and the PointEstimator or IntervalEstimator object (estimator). The sampling distribution of a design is determined by the TwoStageDesign object (design) and the DataDistribution object (data_distribution), as well as the assumed parameters \mu (mu) and \sigma (sigma). The other parameters control various details of the integration problem.

Other parameters

For a two-armed data_distribution, if use_full_twoarm_sampling_distribution is TRUE, the sample means for both groups are integrated independently. If use_full_twoarm_sampling_distribution is FALSE, only the difference in sample means is integrated.

true_parameter controls which parameters is supposed to be estimated. This is usually mu, but could be set to sigma if one is interested in estimating the standard deviation.

If the parameter exact is set to FALSE (the default), the continuous version of the second-stage sample-size function n2 is used. Otherwise, an integer valued version of that function will be used, though this is considerably slower.

The parameters early_futility_part, continuation_part and early_efficacy_part control which parts of the sample-space should be integrated over (all default to TRUE). They can be used in conjunction with the parameter conditional_integral, which enables the calculation of the expected value of performance score conditional on reaching any of the selected integration regions.

Lastly, the paramters tol, maxEval, and absError control the integration accuracy. They are handed down to the hcubature function.

Value

an object of class EstimatorScoreResult containing the values of the evaluated EstimatorScore and information about the setting for which they were calculated (e.g. the estimator, data_distribution, design, mu, and sigma).

See Also

EstimatorScore

PointEstimator IntervalEstimator

plot

Examples

evaluate_estimator(
  score = MSE(),
  estimator = SampleMean(),
  data_distribution = Normal(FALSE),
  design = get_example_design(),
  mu = c(0, 0.3, 0.6),
  sigma = 1,
  exact = FALSE
)

evaluate_estimator(
  score = Coverage(),
  estimator = StagewiseCombinationFunctionOrderingCI(),
  data_distribution = Normal(FALSE),
  design = get_example_design(),
  mu = c(0, 0.3),
  sigma = 1,
  exact = FALSE
)