Select Statistics to Summarize

Description

When the results of each simulation with run.scenarios are saved as a dataframe (e.g. from predict()) it is necessary to select estimates of just one parameter for numerical summarization. This does the job. find.param is a helper function to quickly display the parameters available for summarisation.

Usage

1
2
3
select.stats(object, parameter = "D", statistics, true)
find.param(object)
find.stats(object)

Arguments

object

‘estimatetables’ object from run.scenarios

parameter

character name of parameter to extract

statistics

character vector of statistic names

true

numeric vector of ''true' values of parameter, one per scenario

Details

select.stats is used to select a particular vector of numeric values for summarization. The ‘parameter’ argument indexes a row in the data.frame for one replicate (i.e., one ‘real’ parameter). Each ‘statistic’ is either a column in that data.frame or a statistic derived from a column.

If statistics is not specified, the default is to use all numeric columns in the input (i.e., c(‘estimate’, ‘SE.estimate’, ‘lcl’, ‘ucl’) for predict and c(‘beta’, ‘SE.beta’, ‘lcl’, ‘ucl’) for coef).

statistics may include any of ‘estimate’, ‘SE.estimate’, ‘lcl’, ‘ucl’, 'true', ‘RB’, ‘RSE’, ‘COV’ and ‘ERR’ (for outputtype ‘coef’ use ‘beta’ and ‘SE.beta’ instead of ‘estimate and 'SE.estimate’). ‘true’ refers to the known parameter value used to generate the data.

The computed statistics are:

Statistic Name Value
RB Relative bias (estimate - true) / true
RSE Relative SE SE.estimate / estimate
ERR Absolute deviation abs(estimate - true)
COV Coverage (estimate > lcl) & (estimate < ucl)

‘RB’, ‘COV’ and ‘ERR’ relate an estimate to the known (true) value of the parameter in object$scenarios. They are computed only when a model has been fitted without method = ‘none’.

‘COV’ remains binary (0/1) in the output from select.stats; the result of interest is the mean of this statistic across replicates (see summary.secrdesign). Similarly, ‘ERR’ is used with field ‘rms’ in summary.secrdesign to compute the root-mean-squared-error RMSE.

find.param and find.stats may be used to ‘peek’ at objects of class ‘estimatetables’ and ‘selectedstatistics’ respectively to recall the available parameter estimates or ‘statistics’.

An attempt is made to extract true automatically if it is not provided. This does not always work (e.g. with extractfn region.N, region differing from the mask, and a heterogeneous density model). Check this by including “true” as a statistic to summarise (see Examples).

Value

For select.stats, an object with class c(‘selectedstatistics’,‘secrdesign’, ‘list’) suitable for numerical summarization with summary.selectedstatistics. The value of ‘parameter’ is stored as an attribute.

For find.param, a character vector of the names of parameters with estimates in object.

See Also

run.scenarios, validate

Examples

1
2
3
4
5
6
7
8
## using nrepl = 2 just for checking
scen1 <- make.scenarios(D = c(5,10), sigma = 25, g0 = 0.2)
traps1 <- make.grid()
tmp1 <- run.scenarios(nrepl = 2, trapset = traps1, scenarios = scen1,
    fit = TRUE, extractfn = secr::trim)
tmp2 <- predict(tmp1)
tmp3 <- select.stats(tmp2, 'D', c('estimate','true','RB','RSE','COV'))
summary(tmp3)