Skip to contents

Adapted maximum entropy bootstrap routine from meboot https://cran.r-project.org/package=meboot.

Usage

NNS.meboot(
  x,
  reps = 999,
  rho = NULL,
  type = "spearman",
  drift = TRUE,
  target_drift = NULL,
  target_drift_scale = NULL,
  trim = 0.1,
  xmin = NULL,
  xmax = NULL,
  reachbnd = TRUE,
  expand.sd = TRUE,
  force.clt = TRUE,
  scl.adjustment = FALSE,
  sym = FALSE,
  elaps = FALSE,
  digits = 6,
  colsubj,
  coldata,
  coltimes,
  ...,
  expand.residual.sd = TRUE
)

Arguments

x

vector of data.

reps

numeric; number of replicates to generate.

rho

numeric [-1,1] (vectorized); A rho must be provided, otherwise a blank list will be returned. The dependence target is applied to each individual replicate (every replicate is mixed to the requested dependence with the original series); it is not applied to the ensemble. See Note.

type

options("spearman", "pearson", "NNScor", "NNSdep"); type = "spearman"(default) dependence metric desired.

drift

logical; drift = TRUE (default) preserves the drift of the original series. drift = FALSE removes it: replicates are a flat baseline at mean(x) plus the resampled residuals.

target_drift

numerical; target_drift = NULL (default) Specifies the desired drift when drift = TRUE, i.e. a risk-free rate of return. A drift other than the original is centred so the replicates keep mean(x).

target_drift_scale

numerical; instead of calculating a target_drift, provide a scalar to the existing drift when drift = TRUE.

trim

numeric [0,1]; The mean trimming proportion, defaults to trim = 0.1.

xmin

numeric; the lower limit for the left tail.

xmax

numeric; the upper limit for the right tail.

reachbnd

logical; If TRUE potentially reached bounds (xmin = smallest value - trimmed mean and xmax = largest value + trimmed mean) are given when the random draw happens to be equal to 0 and 1, respectively.

expand.sd

logical; If TRUE the standard deviation in the ensemble is expanded. See expand.sd in meboot::meboot. The expansion toward sd(x) is skipped when drift = FALSE, target_drift or target_drift_scale replaces the original drift, since sd(x) includes that drift. A target equal to the original drift up to rounding (relative tolerance sqrt(.Machine$double.eps), plus an allowance for rounding in the slope fit that grows with max(abs(x))) keeps the original reconstruction.

force.clt

logical; If TRUE the replicate means are assigned an iid normal-reference scale: the replicate means are spread as a normal sample centred on mean(x) with standard deviation sd(x) / sqrt(n), the standard error of the mean of the n observations, whatever the number of reps. See force.clt in meboot::meboot, whose code divides by the number of replicates instead (its comment says n). When drift = FALSE, target_drift or target_drift_scale replaces the original drift, the replicate means are centred and spread using the new baseline plus the original residuals instead of x.

scl.adjustment

logical; If TRUE scale adjustment is performed to ensure that the population variance of the resampled residuals equals the variance of the detrended data.

sym

logical; If TRUE an adjustment is performed to ensure that the ME density is symmetric.

elaps

logical; If TRUE elapsed time during computations is displayed.

digits

integer; 6 (default) number of digits to round output to.

colsubj

numeric; the column in x that contains the individual index. It is ignored if the input data x is not a pdata.frame object.

coldata

numeric; the column in x that contains the data of the variable to create the ensemble. It is ignored if the input data x is not a pdata.frame object.

coltimes

numeric; an optional argument indicating the column that contains the times at which the observations for each individual are observed. It is ignored if the input data x is not a pdata.frame object.

...

possible argument fiv to be passed to expand.sd.

expand.residual.sd

logical; TRUE (default) retains the residual-space SD expansion before trend reconstruction. Set to FALSE to leave the generated residual scales unexpanded; this is separate from the later level-space expand.sd switch.

Value

Returns the following row names in a matrix:

  • x original data provided as input.

  • replicates maximum entropy bootstrap replicates.

  • ensemble average observation over all replicates. Being a per-observation mean it is a central summary, not a single series carrying the target dependence; a rank or linear correlation taken directly on the ensemble tends to read higher than rho (averaging amplifies the shared order), so assess rho on the replicates.

  • xx sorted order stats (xx[1] is minimum value).

  • z class intervals limits.

  • dv deviations of consecutive data values.

  • dvtrim trimmed mean of dv.

  • xmin data minimum for ensemble=xx[1]-dvtrim.

  • xmax data x maximum for ensemble=xx[n]+dvtrim.

  • desintxb desired interval means.

  • ordxx ordered x values.

  • kappa scale adjustment to the variance of ME density.

  • elaps elapsed time.

Note

These are dependence-targeted synthetic scenarios. Zero Spearman or Pearson correlation does not imply independence; interior-rho mixtures can retain nonlinear dependence and change the residual marginal distribution. Matching ranks or path moments does not by itself calibrate sampling confidence intervals. The force.clt scale sd(x)/sqrt(n) is an iid finite-variance reference, not a long-run standard error under serial dependence, and does not calibrate uncertainty of other statistics.

Vectorized rho and drift parameters will not vectorize both simultaneously. Also, do not specify target_drift = NULL.

The rho dependence alignment is calibrated on each individual replicate: every replicate's detrended residuals are mixed so that their dependence on the original series' detrended residuals matches rho, in the metric implied by type; the trend is added back afterwards. If the detrended residuals are all exactly zero (a constant or exactly linear series) there is nothing to align and rho has no effect. For a trending series the replicate levels therefore stay strongly correlated with the original even at rho = -1 (e.g. AirPassengers: mean Spearman 0.81 at rho = -1). Assess a result in that same metric – a "NNSdep" target with NNS.dep$Dependence (unsigned) and a "spearman"/"pearson" target with rank/linear correlation – because a signed correlation taken on an unsigned "NNSdep" target is not comparable to rho (it can even read negative while the dependence target is met). Separately, the ensemble is the per-observation mean of the replicates – a central summary, not a single series carrying the target dependence – so a rank or linear correlation computed directly on the ensemble tends to read higher than the per-replicate rho (averaging amplifies the shared order). Verify rho on the replicates, in the metric implied by type, rather than on the ensemble.

References

  • Vinod, H.D. and Viole, F. (2020) Arbitrary Spearman's Rank Correlations in Maximum Entropy Bootstrap and Improved Monte Carlo Simulations. doi:10.2139/ssrn.3621614

  • Vinod, H.D. (2013), Maximum Entropy Bootstrap Algorithm Enhancements. doi:10.2139/ssrn.2285041

  • Vinod, H.D. (2006), Maximum Entropy Ensembles for Time Series Inference in Economics, Journal of Asian Economics, 17(6), pp. 955-978.

  • Vinod, H.D. (2004), Ranking mutual funds using unconventional utility theory and stochastic dominance, Journal of Empirical Finance, 11(3), pp. 353-377.

Examples

if (FALSE) { # \dontrun{
# Target zero Spearman correlation of each replicate's detrended residuals
boots <- NNS.meboot(AirPassengers, reps = 100, rho = 0, drift = FALSE,
  expand.sd = FALSE, force.clt = FALSE)

# Inspect individual residual correlations, not the ensemble's level correlation
detrend <- function(z) residuals(lm(as.numeric(z) ~ seq_along(z)))
apply(boots["replicates",]$replicates, 2, function(z)
  cor(z, detrend(AirPassengers), method = "spearman"))

# Plot all replicates
matplot(boots["replicates",]$replicates , type = 'l')

# Plot ensemble
lines(boots["ensemble",]$ensemble, lwd = 3)

# Plot original
lines(1:length(AirPassengers), AirPassengers, lwd = 3, col = "red")

### Vectorized drift with a single rho
boots <- NNS.meboot(AirPassengers, reps = 10, rho = 0, xmin = 0, target_drift = c(1,7))
matplot(do.call(cbind, boots["replicates", ]), type = "l")
lines(1:length(AirPassengers), AirPassengers, lwd = 3, col = "red")

### Vectorized rho with a single target drift
boots <- NNS.meboot(AirPassengers, reps = 10, rho = c(0, .5, 1), xmin = 0, target_drift = 3)
matplot(do.call(cbind, boots["replicates", ]), type = "l")
lines(1:length(AirPassengers), AirPassengers, lwd = 3, col = "red")

### Vectorized rho with a single target drift scale
boots <- NNS.meboot(AirPassengers, reps = 10, rho = c(0, .5, 1), xmin = 0, target_drift_scale = 0.5)
matplot(do.call(cbind, boots["replicates", ]), type = "l")
lines(1:length(AirPassengers), AirPassengers, lwd = 3, col = "red") 
} # }