ztest.calibrate: Calibrating 'ztest' for ABC
In olli0601/abc.star: abc.star

Description Usage Arguments Value Note References See Also Examples

Calibrate the one-sample equivalence test for population means of normal summary values with known population variance for ABC inference. This is an asymptotic test that can be used for several testing problems, for example testing if autocorrelations are similar.

Different types of calibrations are available, see Notes for details:

(what=ALPHA) compute the ABC false positive rate for given critical region,
(what=CR) calibrate the critical region for given ABC false positive rate,
(what=MXPW) calibrate the critical region and the equivalence region for given ABC false positive rate and maximum power,
(what=KL) calibrate the critical region, the equivalence region and the number of simulated summary values for given ABC false positive rate, maximum power and sample standard deviation of the observed data.

The calibration KL should be used. Here, the KL calibration does not require multiple i. i. d. instances of observed summary statistics at each ABC iteration because this is an asymptotic test.

Depending on the type of calibration, some of the following inputs must be specified (see Examples).

ztest.calibrate(n.of.x = NA, n.of.y = NA, n2s = NULL, s2n = NULL,
  what = "MXPW", mx.pw = 0.9, alpha = 0.01, c.u = NA, tau.u = NA,
  tol = 1e-05, max.it = 100, pow_scale = 1.5, debug = FALSE,
  plot = FALSE, verbose = FALSE)

`n.of.x`	Number of observed summary values
`n.of.y`	Number of simulated summary values
`n2s`	Function to calculate the standard deviation of the test statistic from n.of.y
`s2n`	Function to calculate n.of.y from the standard deviation of the test statistic
`what`	Character string to indicate the type of calibration to be performed
`mx.pw`	Maximum power at the point of equality
`alpha`	Level of the equivalence test
`c.u`	Upper boundary point of the critical region
`tau.u`	Upper boundary point of the equivalence region
`tol`	Required error tolerance in calibrating the actual maximum power to the requested maximum power
`max.it`	Maximum number of optimization steps at each calibration hierarchy
`pow_scale`	Scale for the support of the standardized power. The power is truncated to `pow_scale*[-tau.u,tau.u]` and then standardized
`debug`	Flag to switch off C implementation
`plot`	Flag to plot calibrations
`verbose`	Flag to run in verbose mode
`plot_debug`	Flag to plot at each calibration iteration

vector

(what=ALPHA) This calibration requires the inputs c.u, tau.u with 0<tau.u and c.u>0. The output contains the corresponding ABC false positive rate alpha. This option does not specify any of the free ABC parameters, but may be useful to determine the ABC false positive rate for uncalibrated ABC routines.
(what=CR) This calibration requires the input tau.u, alpha with tau.u>0 and default alpha=0.01. The output contains the corresponding critical region [c.l, c.u], which corresponds to the ABC tolerance region typically denoted by [-epsilon, epsilon]. The resulting critical region may be empty under this test, if stochasticity is too large. This is an intermediate calibration step and may result in unsuitable power properties (see Examples).
(what=MXPW) This calibration requires the inputs alpha, mx.pw, with default values 0.01 and 0.9 respectively. The output contains the corresponding critical region [c.l, c.u] (to be used in ABC, see Notes on (2)), and the corresponding equivalence region [tau.l, tau.u] that gives a suitable ABC accept/reject probability if the simulated summary values are close to the observed summary values. As a check to the numerical calibrations, the actual power at the point of equality is returned (pw.cmx).
(what=KL) This is the default calibration routine for ABC inference. Inputs are n.of.x (always known), alpha, mx.pw, with default values 0.01 and 0.9 respectively. The output consists of the corresponding critical region [c.l, c.u] (to be used in ABC, see Notes on (2)), the equivalence region [tau.l, tau.u], and the number of simulated summary values needed (n.of.y). As a check to the numerical calibrations, the KL divergence is returned (KL). It is desirable to compare the power to the summary likelihood in terms of the KL divergence, see References.

Note that the underlying test statistic only depends on n.of.y, which can be calibrated before ABC is run. It is not necessary to re-calibrate this test during ABC runtime.

The lower boundary point of the critical region c.l is always fixed to -c.u, because this choice implies that the power is maximized at the point of equality rho=0. This is also commonly used in uncalibrated ABC routines.

http://arxiv.org/abs/1305.4283

mutost.calibrate, vartest.calibrate, ratetest.calibrate

# calibrating the Z-test,
# to test the equivalence of autocorrelations of normal summary values in the MA(1) model

n2s		<- function(n){ 1/sqrt(floor(n)-3) }	#need formula to convert n.of.y into s.of.T, depends on application
s2n		<- function(s){ (1/s)^2+3 }				#need formula to convert s.of.T into n.of.y, depends on application
n.of.y	<- 1500		#number of independent pairs of the form (y_t, y_{t+1}) for simulated summary values y_t, t=1, ...

# Example 1: calibrate critical region and power of ABC accept/reject step
# this requires to specify alpha, mx.pw (calibration parameters), and n.of.y (summary parameters)
# note: this is **not** the default ABC calibration because it is for this test always possible to 
# minimize the KL divergence with respect to the summary likelihood, see Example 4

ztest.calibrate(n.of.y=n.of.y, n2s=n2s, s2n=s2n, mx.pw=0.9, alpha=0.01, what='MXPW', plot=TRUE)

# Example 2: calculate ABC false positive rate for given ABC tolerance
# this requires to specify c.u, tau.u (ad-hoc ABC parameters), n.of.y (summary parameters)
# note: can be useful to compute the ABC false positive rate for uncalibrated ABC routines

ztest.calibrate(n.of.y=n.of.y, n2s=n2s, s2n=s2n, c.u=1.5427, tau.u=0.1, what='ALPHA')

# Example 3: calibrate critical region for given ABC false positive rate and equivalence region
# this requires to specify alpha (calibration parameters), tau.u (ad-hoc ABC parameter), n.of.y  (summary parameters)
# note: this is just an intermediate calibration and may result in unsuitable power properties

ztest.calibrate(n.of.y=n.of.y, n2s=n2s, s2n=s2n, tau.u=0.1, alpha=0.01, what='CR', plot=TRUE)

# Example 4: calibrate critical region, power of ABC accept/reject step, and #simulated data points (default)
# this requires to specify alpha, mx.pw (calibration parameters), n.of.x (summary parameters)
# note: this is recommended to calibrate the ABC accept/reject step

n.of.x	<- 1500	
ztest.calibrate(n.of.x=n.of.x, n2s=n2s, s2n=s2n, mx.pw=0.9, alpha=0.01, what='KL', plot=TRUE)