evaluate_estimator {adestr} | R Documentation |

## 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

```
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 |

`data_distribution` |
object of class |

`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 |

`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

PointEstimator IntervalEstimator

### 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
)
```

*adestr*version 1.0.0 Index]