info.stats.lsd: Compute Monte Carlo statistics from a set of LSD runs

Description

This function reads a 3 or 4-dimensional array produced by read.3d.lsd or read.4d.lsd and produces a list with 2D data frames containing the (Monte Carlo) mean, the standard deviation, the maximum, the minimum, and other optional statistics for each variable, at each time step.

Usage

info.stats.lsd( array, rows = 1, cols = 2, median = FALSE,
                ci = c( "none", "mean", "median", "auto" ),
                ci.conf = 0.95, ci.boot = NULL, boot.R = 999,
                seed = 1, na.rm = TRUE, inf.rm = TRUE )

Value

Returns a list containing four to seven matrices, with the original size and naming of the selected 2 dimensions of the argument.

avg: a matrix with the mean of the MC experiments
sd: a matrix with the standard deviation of the MC experiments
max: a matrix with the maximum value of the MC experiments
min: a matrix with the minimum value of the MC experiments
med: a matrix with the median of the MC experiments (only present if argument median = TRUE)
mad: a matrix with the median absolute deviation of the MC experiments (only present if argument median = TRUE)
ci.hi: a matrix with the maximum value of the MC experiments (only present if argument ci is not set to "none")
ci.lo: a matrix with the minimum value of the MC experiments (only present if argument ci is not set to "none")
n: a matrix with the number of observations available for computation of statistics

Arguments

array: a 3D or 4D array as produced by read.3d.lsd and read.4d.lsd, where in the first dimension (rows) you have the time steps, in the second (columns), the variables and in the third/fourth dimension, the Monte Carlo experiments, and the instances in the third dimension (4D arrays only).
rows: an integer array dimension to be used as the rows for the statistics matrices, default is to use first array dimension.
cols: an integer array dimension to be used as the columns for the statistics matrices, default is to use second array dimension.
median: a logical value indicating if (TRUE) the median and the median absolute deviation should also be computed. The default (FALSE) is not to compute these statistics.
ci: a character string specifying the type of confidence interval to compute, must be one of "none" (default) for no confidence interval computation, "mean", to compute a confidence interval for the mean, "median", for the median, or "auto", to use the option set for the median argument (above). This option can be abbreviated.
ci.conf: confidence level of the confidence interval.
ci.boot: a character string specifying the type of bootstrap confidence interval to compute, must be one of "basic", "perc" (percentile interval), or "bca" (BCa - adjusted percentile interval). If set to NULL or an empty string, a regular asymptotic confidence interval is produced (no bootstrap), assuming normal distribution for the mean or using a non-parametric rank test for the median. Non-bootstrap percentiles are much faster to compute but generally less accurate.
boot.R: number of bootstrap replicates.
seed: a single value, interpreted as an integer to define the pseudo-random number generator state used for the bootstrap process, or NULL, to re-initialize the generator as if no seed had yet been set (a new state is created from the current time and the process ID).
na.rm: a logical value indicating whether NA values should be stripped before the computation proceeds.
inf.rm: a logical value indicating whether non-finite values should be stripped before the computation proceeds.

Author

Marcelo C. Pereira

Examples

Run this code

# get the list of file names of example LSD results
files <- list.files.lsd( system.file( "extdata", package = "LSDinterface" ) )

# read first instance of all variables from MC files (3D array)
inst1Array <- read.3d.lsd( files )

# create statistics data frames for the variables
inst1Stats <- info.stats.lsd( inst1Array )
print( inst1Stats$avg[ 10 : 20, ] )
print( inst1Stats$sd[ 10 : 20, ] )

# organize the stats, including medians, by variable (dim=2) and file (dim=3)
inst1Stats2 <- info.stats.lsd( inst1Array, rows = 2, cols = 3, median = TRUE )
print( inst1Stats2$med[ , 1 : 2 ] )

# the same but for all instance of all variables (from a 4D array)
# and a normal (non-boostrap) confidence intervals for the means
allArray <- read.4d.lsd( files )
allStats <- info.stats.lsd( allArray, ci = "auto" )
print( allStats$ci.lo[ 3, 1 : 7 ] )
print( allStats$avg[ 3, 1 : 7 ] )
print( allStats$ci.hi[ 3, 1 : 7 ] )

# organize the stats by file (dim=4) and variable (dim=2)
# plus boostrat confidence intervals for the median
allStats2 <- info.stats.lsd( allArray, rows = 4, cols = 2, median = TRUE,
                             ci = "auto", ci.boot = "bca" )
print( allStats2$ci.lo[ , 1 : 3 ] )
print( allStats2$med[ , 1 : 3 ] )
print( allStats2$ci.hi[ , 1 : 3 ] )