File Exchange

image thumbnail

ibootci

version 2.3.7.0 (38.4 KB) by Andrew Penn
Bootstrap confidence interval

17 Downloads

Updated 15 Sep 2019

GitHub view license on GitHub

Function File: ibootci

Bootstrap confidence interval

ci = ibootci(nboot,bootfun,...) computes the 95% iterated (double) bootstrap confidence interval of the statistic computed by bootfun. nboot is a scalar, or vector of upto two positive integers indicating the number of replicate samples for the first and second bootstraps. bootfun is a function handle specified with @, or a string indicating the function name. The third and later input arguments are data (column vectors), that are used to create inputs to bootfun. ibootci creates each first level bootstrap by sampling from the rows of the column vector data arguments (which must be the same size) [1]. Nominal central coverage of two-sided intervals is calibrated to achieve second order accurate coverage by bootstrap iteration and interpolation [2]. Linear interpolation of the empirical cumulative distribution function of bootstat is then used to construct two-sided confidence intervals [3]. The resampling method used throughout is balanced resampling [4]. Default values for the number of first and second bootstrap replicate sample sets in nboot are 5000 and 200 respectively.

ci = ibootci(nboot,{bootfun,...},...,'alpha',alpha) computes the iterated bootstrap confidence interval of the statistic defined by the function bootfun with coverage 100*(1-alpha)%, where alpha is a scalar value between 0 and 1. bootfun and the data that ibootci passes to it are contained in a single cell array. The default value of alpha is 0.05 corresponding to intervals with a coverage of 95% confidence.

ci = ibootci(nboot,{bootfun,...},...,'type',type) computes the bootstrap confidence interval of the statistic defined by the function bootfun. type is the confidence interval type, chosen from among the following:
'per' or 'percentile' - Percentile method.
'bca' - Bias corrected and accelerated percentile method. (Default)
'stud' or 'student' - Studentized (bootstrap-t) confidence interval.

ci = ibootci(nboot,{bootfun,...},...,'Weights',weights) specifies observation weights. weights must be a vector of non-negative numbers. The dimensions of weights must be equal to that of the non-scalar input arguments to bootfun. The weights are used as bootstrap sampling probabilities. Note that weights are not implemented for bootstrap iteration. To improve on standard percentile intervals from a single bootstrap when using weights, we suggest calibrating the nominal alpha level using iterated bootstrap without weights, then using the calibrated alpha in a weighted bootstrap without iteration.

ci = ibootci(nboot,{bootfun,...},...,'Strata',strata) specifies a vector containing numeric identifiers of strata. The dimensions of strata must be equal to that of the non-scalar input arguments to bootfun. Bootstrap resampling is stratified so that every stratum is represented in each bootstrap test statistic [5]. If weights are also provided then they are within-stratum weights; the weighting of individual strata depends on their respective sample size.

ci = ibootci(nboot,{bootfun,...},...,'Clusters',clusters) specifies a vector containing numeric identifiers for clusters. Whereas strata are fixed, clusters are resampled. This is achieved by two-stage bootstrap resampling of residuals with shrinkage correction [5,7,8]. Note that the strata and clusters options are mutually exclusive.

ci = ibootci(nboot,{bootfun,...},...,'bootidx',bootidx) performs bootstrap computations using the indices from bootidx for the first bootstrap.

ci = ibootci(bootstat, S) produces calibrated confidence intervals for the bootstrap replicate sample set statistics provided in bootstat. This usage also requires a complete settings structure (see below).

[ci,bootstat] = ibootci(...) also returns the bootstrapped statistic computed for each of the bootstrap replicate samples sets. If only a single bootstrap is requested, bootstat will return a vector: each column of bootstat contains the result of applying bootfun to one replicate sample from the first bootstrap. If bootstrap iteration is requested, bootstat will return a cell array containing the statistics computed by bootfun in the first and second bootstrap. For the second boostrap, each column of bootstat contains the results of applying bootfun to each replicate sample from the second bootstrap for one replicate sample from the first bootstrap.

[ci,bootstat,S] = ibootci(...) also returns a structure containing the settings used in the bootstrap and the resulting statistics including the (double) bootstrap bias and standard error. Field descriptions are provided in the function help.

[ci,bootstat,S,calcurve] = ibootci(...) also returns calcurve, a vector of calibration values the same size as the first bootstrap replicate set.

[ci,bootstat,S,calcurve,bootidx] = ibootci(...) also returns bootidx, a matrix of indices from the first bootstrap.

ibootci has very similar usage to the function bootci. Please see function help for examples of function usage.

Cite As

Andrew Penn (2019). ibootci (https://www.github.com/acp29/iboot), GitHub. Retrieved .

Comments and Ratings (5)

jwswylie

Andrew Penn

Hi Robert. The usage is very similar to bootci in the Matlab Statistics Toolbox. I have now added some example uses in the function help.

Robert

Looks great - could you please provide a simple example to illustrate correct use?

Updates

2.3.7.0

Improved the coverage of cluster bootstrap for unbalanced cluster sizes.

2.3.4.0

Trimmed output structure down to providing only necessary information

2.3.2.0

Corrected calculation of ICC for output structure S

2.3.0.0

Now includes capability to perform two-stage nonparametric bootstrap sampling with shrinkage correction for clustered data

2.2.2.0

Made calculation of SSE components of stratified data (provided as descriptive statistics in output structure S) compatible with multivariate data. Now also returns the degrees of freedom.

2.2.0.0

Changed default interval type to BCa to be consistent with bootci. Corrected some comments and function help.

2.1.0.1

Added extra tags to the webpage

2.1.0.0

Now supports calculation confidence intervals using the bootstrap-t method. Standard errors of the bootstrap samples are determined by double bootstrap.

2.0.0.0

This new version can also perform stratified bootstrap resampling.

1.9.0.0

If bootstrap iteration is requested, bootstat returns: boostat statistics from both 1st and 2nd bootstrap; the double bootstrap bias and bias-corrected statistic in S; and, the double boostrap corrected standard error of the statistic in S.

1.8.4.0

Added a check for successful calculation of the acceleration constant for the BCa intervals

1.8.3.0

Corrected the check for when bootstrap confidence intervals hit the ends of the bootstrap distribution

1.8.2.0

Updated title and summary

1.8.1.0

Linked to Github

1.8.0.0

Moved to Github. Calibration and interval construction carried out by interpolating from the empirical distribution function. Minor performance improvement by avoiding a sort in the second bootstrap. Coverage confirmed with simulations.

1.7.1.0

Performance enhancement for the second bootstrap through alternative execution of randperm

1.7.0.0

Included error message when second bootstrap replicate size is insufficient for the desired alpha. Minor improvement to the calibration included. Changed output arguments: Now includes output structure (of settings and results) and calibration curve.

1.6.3.0

Added back a warning for when the resulting intervals hit the end(s) of the bootstrap distribution

1.6.2.6

Corrected typos (missing % signs) in the comments of the examples in the description

1.6.2.5

Updated image icon

1.6.2.4

Adjusted icon image dimensions

1.6.2.3

Adjusted icon image dimensions

1.6.2.2

Adjusted icon image size

1.6.2.1

Minor update to function description. Added image icon.

1.6.2

Swapped the order of output arguments to match Matlabs bootci

1.6.1

Set default bootstrap type to percentile.

1.6

Added the ability to use different types of intervals: percentile or BCa. The BCa type interval is the default.

1.5.4.2

Made minor changes to the description and to the function help

1.5.4.1

Corrected description

1.5.4.0

Added the capability to use bootidx input when calculating bootstrap confidence for multivariate data. Modified default values for nboot

1.5.3.3

Clarified some of the help/comments and included another example of it's usage for calculating confidence intervals for the median

1.5.3.2

Updated some comments

1.5.3.1

Modified default values for the number of bootstrap samples

1.5.3.0

Modified the implementation with weights based on simulation results

1.5.2.1

Updated the help comments

1.5.2.0

Fixed a bug preventing some function usage. Added back the ability to use functions (in the bootfun input argument) that do not output a row vector for matrix input argument(s) (e.g. 'corr' function).

1.5.1.1

Removed depreciated lines of code

1.5.1.0

Implemented appropriated weight allocation for the second bootstrap

1.5.0.0

Added interpolation also to the first bootstrap. Performance improvements made to the resampling algorithm. Added feature to provide weights to modify sampling probabilities.

1.4.1.0

Corrected a mistake presented in example 3 (in comment only).

1.4.0.0

1.4.0.0 - Implementation modified for less memory footprint. Algorithm now uses balanced resampling. Coverage is calibrated using the interpolation method instead of the approximate Monte Carlo method. Also returns bias of the bootstrap.

1.3.0.0

Simplified title

1.3.0.0

Included example usage in the function help

1.2.0.0

Now less stringent data requirements. Data can be row vectors or column vectors

1.1.0.0

Now checks the dimensions of the data

MATLAB Release Compatibility
Created with R2019a
Compatible with any release
Platform Compatibility
Windows macOS Linux