Package {NNS}

NNS: Nonlinear Nonparametric Statistics

Description

Nonlinear nonparametric statistics using partial moments. Partial moments are the elements of variance and asymptotically approximate the area of f(x). These robust statistics provide the basis for nonlinear analysis while retaining linear equivalences. NNS offers: Numerical integration, Numerical differentiation, Clustering, Correlation, Dependence, Causal analysis, ANOVA, Regression, Classification, Seasonality, Autoregressive modeling, Normalization and Stochastic dominance. All routines based on: Viole, F. and Nawrocki, D. (2013), Nonlinear Nonparametric Statistics: Using Partial Moments (ISBN: 1490523995, 2nd edition: https://ovvo-financial.github.io/NNS/book/).

Author(s)

Maintainer: Fred Viole ovvo.open.source@gmail.com

Other contributors:

• Roberto Spadim [contributor]

• Rasheed Khoshnaw [contributor]

See Also

Useful links:

• https://github.com/OVVO-Financial/NNS

• Report bugs at https://github.com/OVVO-Financial/NNS/issues

Finite-difference weights for a local polynomial stencil

Description

Construct polynomial finite-difference weights on distinct local nodes. Invalid or degenerate stencils return NA coefficients.

Usage

.nns_fd_weights(nodes, at, degree = 1L)

Arguments

Value

Numeric vector of finite-difference weights, or NA coefficients when the stencil is invalid.

Co‑Lower Partial Moment

Description

Computes the co‑lower partial moment (lower‑left quadrant 4) between two equal‑length numeric vectors at any degree and target.

Usage

Co.LPM(degree_lpm, x, y, target_x, target_y, degree_y = NULL)

Arguments

Value

Numeric vector of co‑LPM values.

Author(s)

Fred Viole, OVVO Financial Systems

References

Viole, F. & Nawrocki, D. (2013) *Nonlinear Nonparametric Statistics: Using Partial Moments* (ISBN:1490523995)

Examples

  set.seed(123)
  x <- rnorm(100); y <- rnorm(100)
  Co.LPM(0, x, y, mean(x), mean(y))

Co‑Lower Partial Moment nD

Description

This function generates an n‑dimensional co‑lower partial moment (n >= 2) for any degree or target.

Usage

Co.LPM_nD(data, target, degree = 0, norm = TRUE)

Arguments

Value

Numeric; the n‑dimensional co‑lower partial moment.

Examples

## Not run: 
mat <- matrix(rnorm(200), ncol = 4)
Co.LPM_nD(mat, rep(0, ncol(mat)), degree = 1, norm = FALSE)

## End(Not run)

Batched Co-Lower Partial Moment nD

Description

Internal batched backend for evaluating Co.LPM_nD over many targets.

Usage

Co.LPM_nD.batch(data, targets, degree = 0, norm = TRUE)

Arguments

Value

Numeric vector, one value per row of targets.

Co‑Upper Partial Moment

Description

Computes the co‑upper partial moment (upper‑right quadrant 1) between two equal‑length numeric vectors at any degree and target.

Usage

Co.UPM(degree_upm, x, y, target_x, target_y, degree_y = NULL)

Arguments

Value

Numeric vector of co‑UPM values.

Author(s)

Fred Viole, OVVO Financial Systems

References

Viole, F. & Nawrocki, D. (2013) *Nonlinear Nonparametric Statistics: Using Partial Moments* (ISBN:1490523995)

Examples

  set.seed(123)
  x <- rnorm(100); y <- rnorm(100)
  Co.UPM(0, x, y, mean(x), mean(y))

Co‑Upper Partial Moment nD

Description

This function generates an n‑dimensional co‑upper partial moment (n >= 2) for any degree or target.

Usage

Co.UPM_nD(data, target, degree = 0, norm = TRUE)

Arguments

Value

Numeric; the n‑dimensional co‑upper partial moment.

Examples

## Not run: 
mat <- matrix(rnorm(200), ncol = 4)
Co.UPM_nD(mat, rep(0, ncol(mat)), degree = 1, norm = FALSE)

## End(Not run)

Divergent‑Lower Partial Moment

Description

Computes the divergent lower partial moment (lower‑right quadrant 3) between two equal‑length numeric vectors.

Usage

D.LPM(degree_lpm, degree_upm, x, y, target_x, target_y)

Arguments

Value

Numeric vector of divergent LPM values.

Author(s)

Fred Viole, OVVO Financial Systems

References

Viole, F. & Nawrocki, D. (2013) *Nonlinear Nonparametric Statistics: Using Partial Moments* (ISBN:1490523995)

Examples

  set.seed(123)
  x <- rnorm(100); y <- rnorm(100)
  D.LPM(0, 0, x, y, mean(x), mean(y))

Divergent‑Upper Partial Moment

Description

Computes the divergent upper partial moment (upper‑left quadrant 2) between two equal‑length numeric vectors.

Usage

D.UPM(degree_lpm, degree_upm, x, y, target_x, target_y)

Arguments

Value

Numeric vector of divergent UPM values.

Author(s)

Fred Viole, OVVO Financial Systems

References

Viole, F. & Nawrocki, D. (2013) *Nonlinear Nonparametric Statistics: Using Partial Moments* (ISBN:1490523995)

Examples

  set.seed(123)
  x <- rnorm(100); y <- rnorm(100)
  D.UPM(0, 0, x, y, mean(x), mean(y))

Divergent Partial Moment nD

Description

This function generates the aggregate n‑dimensional divergent partial moment (n >= 2) for any degree or target.

Usage

DPM_nD(data, target, degree = 0, norm = TRUE)

Arguments

Value

Numeric; the n-dimensional divergent partial moment.

Examples

## Not run: 
mat <- matrix(rnorm(200), ncol = 4)
DPM_nD(mat, rep(0, ncol(mat)), degree = 1, norm = FALSE)

## End(Not run)

Lower Partial Moment

Description

This function generates a univariate lower partial moment for any degree or target.

Usage

LPM(degree, target, variable, excess_ret = FALSE)

Arguments

Value

LPM of variable

Author(s)

Fred Viole, OVVO Financial Systems

References

Viole, F. and Nawrocki, D. (2013) "Nonlinear Nonparametric Statistics: Using Partial Moments" (ISBN: 1490523995, 2nd edition: https://ovvo-financial.github.io/NNS/book/)

Examples

set.seed(123)
x <- rnorm(100)
LPM(0, mean(x), x)

LPM VaR

Description

Generates a value at risk (VaR) quantile based on the Lower Partial Moment ratio.

Usage

LPM.VaR(percentile, degree, x)

Arguments

Value

Returns the type-7 empirical quantile (degree = 0), whose strict or inclusive sample tail fraction may differ from percentile because of interpolation or ties, or the threshold with percentile of the directional deviation area below it (degree > 0).

Author(s)

Fred Viole, OVVO Financial Systems

References

Viole, F. and Nawrocki, D. (2013) "Nonlinear Nonparametric Statistics: Using Partial Moments" (ISBN: 1490523995, 2nd edition: https://ovvo-financial.github.io/NNS/book/)

Examples

## Not run: 
set.seed(123)
x <- rnorm(100)

## For 5th percentile, left-tail
LPM.VaR(0.05, 0, x)

## End(Not run)

Lower Partial Moment Ratio

Description

This function generates a standardized univariate lower partial moment of any non‑negative degree for a given target.

Usage

LPM.ratio(degree, target, variable)

Arguments

Value

Numeric vector of standardized lower partial moments. For degree > 0, a target at which every observation equals the target (0/0) returns the degree = 0 ratio.

Author(s)

Fred Viole, OVVO Financial Systems

References

Viole, F. & Nawrocki, D. (2013) *Nonlinear Nonparametric Statistics: Using Partial Moments* (ISBN:1490523995)

Viole, F. (2017) Continuous CDFs and ANOVA with NNS. doi:10.2139/ssrn.3007373

Examples

  set.seed(123)
  x <- rnorm(100)
  LPM.ratio(0, mean(x), x)
## Not run: 
  plot(sort(x), LPM.ratio(0, sort(x), x))
  plot(sort(x), LPM.ratio(1, sort(x), x))

## End(Not run)

NNS ANOVA: Nonparametric Analysis of Variance

Description

Compares control and treatment groups through benchmark-relative partial moments. The chosen mode compares means, medians, or a distribution profile with central and tail benchmarks, without selecting a parametric family.

Usage

NNS.ANOVA(
  control,
  treatment,
  means.only = FALSE,
  medians = FALSE,
  confidence.interval = 0.95,
  tails = "Both",
  pairwise = FALSE,
  plot = TRUE,
  robust = FALSE
)

Arguments

Details

The key output, Certainty, is a descriptive agreement index in [0, 1] for the chosen target:

• means.only = TRUE, medians = FALSE: compares group means using degree-one deviation-area ratios at the pooled mean.

• means.only = TRUE, medians = TRUE: compares medians using the distance of 0.5 from each interval [F(t-), F(t)] at the pooled median t. This interval contains 0.5 exactly when t is a median, including tied and discrete data.

• means.only = FALSE: adds the 12.5% and 25% lower and upper deviation-area benchmarks to the chosen central comparison. This examines distributional shape through a finite profile; agreement at these benchmarks does not prove equality of laws.

At a constant group's only value both deviation areas vanish. For agreement comparisons this satisfies the expectile balance at every level, so its area discrepancy is zero there. Returned CDF values retain the public partial-moment step convention; other benchmarks and nonconstant samples use the ordinary ratio discrepancy.

The raw score is 1 at maximal benchmark agreement. The returned score is multiplied by ((n_1 + n_2 - 2)/(n_1 + n_2))^2, so the finite-sample maximum is below 1. Certainty is not a calibrated probability, a p-value, or statistical power, and has no universal significance cutoff. Equal population means need not produce the same score distribution when sample sizes or spreads differ. robust = TRUE describes sampling variability of the score; it does not generate a null reference distribution.

Random relabelings of the pooled observations provide a reference under identical distributions only when observations are exchangeable. They are not a general unequal-variance equal-means test. Any inferential calibration must match the chosen target and the sampling design; dependent observations require a suitable resampling design.

Effect-size bounds retain the conservative difference of the groups' separate bootstrap endpoints. They are not quantiles of the bootstrap difference and need not have exactly the requested nominal coverage. The independent-group bootstrap assumes independent observations within and between groups.

Value

Returns a list containing:

• Control: Mean/median of control group

• Treatment: Mean/median of treatment group

• Grand_Statistic: Mean/median of all observations pooled

• Control_CDF: CDF value at grand statistic (control)

• Treatment_CDF: CDF value at grand statistic (treatment)

• Certainty: Agreement index for the chosen central or distribution-profile comparison, with the finite-sample adjustment; not a calibrated probability.

• Effect_Size_LB: Lower bound of treatment effect (if confidence.interval requested)

• Effect_Size_UB: Upper bound of treatment effect (if confidence.interval requested)

• Confidence_Level: Confidence level used (if confidence.interval requested)

Author(s)

Fred Viole, OVVO Financial Systems

References

Viole, F. and Nawrocki, D. (2013) "Nonlinear Nonparametric Statistics: Using Partial Moments" (ISBN: 1490523995, 2nd edition: https://ovvo-financial.github.io/NNS/book/)

Viole, F. (2017) "Continuous CDFs and ANOVA with NNS" doi:10.2139/ssrn.3007373

Examples

 ## Not run: 
### Binary analysis and effect size
set.seed(123)
x <- rnorm(100) ; y <- rnorm(100)
NNS.ANOVA(control = x, treatment = y)

### Two variable analysis with no control variable
A <- cbind(x, y)
NNS.ANOVA(A)

### Medians test
NNS.ANOVA(A, means.only = TRUE, medians = TRUE)

### Multiple variable analysis with no control variable
set.seed(123)
x <- rnorm(100) ; y <- rnorm(100) ; z <- rnorm(100)
A <- cbind(x, y, z)
NNS.ANOVA(A)

### Different length vectors used in a list
x <- rnorm(30) ; y <- rnorm(40) ; z <- rnorm(50)
A <- list(x, y, z)
NNS.ANOVA(A)

## End(Not run)

NNS ARMA

Description

Autoregressive model incorporating nonlinear regressions of component series.

Usage

NNS.ARMA(
  variable,
  h = 1,
  training.set = NULL,
  seasonal.factor = TRUE,
  weights = NULL,
  best.periods = 1,
  modulo = NULL,
  mod.only = TRUE,
  negative.values = FALSE,
  method = "nonlin",
  dynamic = FALSE,
  shrink = FALSE,
  plot = TRUE,
  seasonal.plot = TRUE,
  pred.int = NULL
)

Arguments

Value

Returns a vector of forecasts of length (h) if no pred.int specified. Else, returns a data.table with the forecasts as well as the lower and upper forecast-path bands per forecast point (see pred.int).

Note

For monthly data series, increased accuracy may be realized from forcing seasonal factors to multiples of 12. For example, if the best periods reported are: {37, 47, 71, 73} use (seasonal.factor = c(36, 48, 72)).

(seasonal.factor = FALSE) can be a very computationally expensive exercise due to the number of seasonal periods detected.

Author(s)

Fred Viole, OVVO Financial Systems

References

Viole, F. and Nawrocki, D. (2013) "Nonlinear Nonparametric Statistics: Using Partial Moments" (ISBN: 1490523995, 2nd edition: https://ovvo-financial.github.io/NNS/book/)

Viole, F. (2019) "Forecasting Using NNS" doi:10.2139/ssrn.3382300

Examples

## Nonlinear NNS.ARMA using AirPassengers monthly data and 12 period lag
## Not run: 
NNS.ARMA(AirPassengers, h = 45, training.set = 100, seasonal.factor = 12, method = "nonlin")

## Linear NNS.ARMA using AirPassengers monthly data and 12, 24, and 36 period lags
NNS.ARMA(AirPassengers, h = 45, training.set = 120, seasonal.factor = c(12, 24, 36), method = "lin")

## Nonlinear NNS.ARMA using AirPassengers monthly data and 2 best periods lag
NNS.ARMA(AirPassengers, h = 45, training.set = 120, seasonal.factor = FALSE, best.periods = 2)

## End(Not run)

NNS ARMA Optimizer

Description

Wrapper function for optimizing any combination of a given seasonal.factor vector in NNS.ARMA. The objective function obj.fn on a validation window (the last length(variable) - training.set observations) is used to determine the optimum across all NNS.ARMA methods.

Usage

NNS.ARMA.optim(
  variable,
  h = NULL,
  training.set = NULL,
  seasonal.factor,
  lin.only = FALSE,
  negative.values = FALSE,
  obj.fn = expression({
     .denom <- NNS::Co.LPM(1, predicted, actual, target_x =
    mean(predicted), target_y = mean(actual)) + NNS::Co.UPM(1, predicted, actual,
    target_x = mean(predicted), target_y = mean(actual))
     if (.denom == 0) Inf else
    mean((predicted - actual)^2)/.denom
 }),
  objective = "min",
  linear.approximation = TRUE,
  ncores = NULL,
  pred.int = 0.95,
  print.trace = TRUE,
  plot = FALSE,
  bias.correction = c("none", "split")
)

Arguments

Value

Returns a list containing:

• $period a vector of optimal seasonal periods

• $weights the optimal weights of each seasonal period between an equal weight or NULL weighting

• $obj.fn the obj.fn value of the returned model's internal validation forecasts, after $bias.shift.

• $method the method identifying which NNS.ARMA method was used.

• $shrink whether to use the shrink parameter in NNS.ARMA.

• $nns.regress whether to smooth the variable via NNS.reg before forecasting.

• $bias.shift the accepted additive correction (0 when rejected or disabled). Add it to the forecast from NNS.ARMA with the returned model parameters, then apply the nonnegative support clamp if required.

• $bias.validation correction policy, estimated/applied shifts, chronological estimate and acceptance rows, and raw/adjusted acceptance scores.

• $raw.results forecasts before the additive bias correction.

• $validation.forecast the final internal validation forecasts, including correction and support clamp.

• $errors a vector of the returned model's internal validation errors (forecast - actual), before $bias.shift.

• $results a vector of length h.

• $lower.pred.int a vector of lower prediction intervals per forecast point.

• $upper.pred.int a vector of upper prediction intervals per forecast point.

Note

By default no bias shift is added. With bias.correction = "split" the shift is estimated on the first half of the validation window and accepted on the second. Base model selection still uses the internal validation window, so these tuning scores are not an independent evaluation of the whole forecasting procedure. Evaluate the complete procedure at fresh chronological origins.

• Typically, (training.set = 0.8 * length(variable)) is used for optimization. Smaller samples could use (training.set = 0.9 * length(variable)) (or larger) in order to preserve information.

• The number of combinations will grow prohibitively large, they should be kept as small as possible. seasonal.factor containing an element too large will result in an error. Please reduce the maximum seasonal.factor.

• Set (ncores = 1) if routine is used within a parallel architecture.

Author(s)

Fred Viole, OVVO Financial Systems

References

Viole, F. and Nawrocki, D. (2013) "Nonlinear Nonparametric Statistics: Using Partial Moments" (ISBN: 1490523995, 2nd edition: https://ovvo-financial.github.io/NNS/book/)

Examples

## Nonlinear NNS.ARMA period optimization using 2 yearly lags on AirPassengers monthly data
## Not run: 
nns.optims <- NNS.ARMA.optim(AirPassengers[1:132], training.set = 120,
seasonal.factor = seq(12, 24, 6))

## To predict out of sample using best parameters:
NNS.ARMA.optim(AirPassengers[1:132], h = 12, seasonal.factor = seq(12, 24, 6))

## Incorporate any objective function from external packages (such as \code{Metrics::mape})
NNS.ARMA.optim(AirPassengers[1:132], h = 12, seasonal.factor = seq(12, 24, 6),
obj.fn = expression(Metrics::mape(actual, predicted)), objective = "min")

## End(Not run)

NNS CDF

Description

This function generates an empirical CDF using partial moment ratios LPM.ratio, and resulting survival, hazard and cumulative hazard functions.

Usage

NNS.CDF(variable, degree = 0, target = NULL, type = "CDF", plot = TRUE)

Arguments

Value

Returns:

• "Function" a data.frame (class NNS.data.frame) containing the observations and the resulting function of the variable.

• "target.value" value from the target argument.

Author(s)

Fred Viole, OVVO Financial Systems

References

Viole, F. and Nawrocki, D. (2013) "Nonlinear Nonparametric Statistics: Using Partial Moments" (ISBN: 1490523995, 2nd edition: https://ovvo-financial.github.io/NNS/book/)

Viole, F. (2017) "Continuous CDFs and ANOVA with NNS" doi:10.2139/ssrn.3007373

Examples

## Not run: 
set.seed(123)
x <- rnorm(100)
NNS.CDF(x)

## Empirical CDF (degree = 0)
NNS.CDF(x)

## Area-weighted CDF (degree = 1): the share of deviation area below each point
NNS.CDF(x, 1)

## Joint CDF
x <- rnorm(5000) ; y <- rnorm(5000)
A <- cbind(x,y)

NNS.CDF(A, 0)

## Joint CDF with target
NNS.CDF(A, 0, target = rep(0, ncol(A)))

## End(Not run)

NNS FSD Test

Description

Compares empirical first-order stochastic dominance or degree-one area-ratio (Omega/expectile) dominance using partial moments.

Usage

NNS.FSD(x, y, type = "discrete", plot = TRUE)

Arguments

Value

With type = "discrete", returns "X FSD Y", "Y FSD X", or "NO FSD EXISTS". With type = "continuous", returns "X OMEGA Y", "Y OMEGA X", or "NO OMEGA DOMINANCE EXISTS"; the numerical area-order criterion is unchanged.

Note

The curves are compared on the merged sample points and, for TSD and continuous area order, also at their closed-form extrema between those points. Differences smaller than 64 * .Machine$double.eps * S^d (S = largest absolute value in x and y, d = 1 for SSD and the mean condition, 2 for TSD; a ratio analogue for continuous area order) are treated as ties, so that rounding noise does not decide dominance. Discrete FSD compares exact empirical CDF values.

Author(s)

Fred Viole, OVVO Financial Systems

References

Viole, F. and Nawrocki, D. (2016) "LPM Density Functions for the Computation of the SD Efficient Set." Journal of Mathematical Finance, 6, 105-126. doi:10.4236/jmf.2016.61012.

Viole, F. (2017) "A Note on Stochastic Dominance." doi:10.2139/ssrn.3002675.

Examples

## Not run: 
set.seed(123)
x <- rnorm(100) ; y <- rnorm(100)
NNS.FSD(x, y)

## End(Not run)

NNS FSD Test uni-directional

Description

Uni-directional test of first degree stochastic dominance using lower partial moments used in SD Efficient Set routine.

Usage

NNS.FSD.uni(x, y, type = "discrete")

Arguments

Value

Returns (1) if X dominates Y in the selected order (ordinary FSD or Omega/expectile order), else (0).

Note

The curves are compared on the merged sample points and, for TSD and continuous area order, also at their closed-form extrema between those points. Differences smaller than 64 * .Machine$double.eps * S^d (S = largest absolute value in x and y, d = 1 for SSD and the mean condition, 2 for TSD; a ratio analogue for continuous area order) are treated as ties, so that rounding noise does not decide dominance. Discrete FSD compares exact empirical CDF values.

Author(s)

Fred Viole, OVVO Financial Systems

References

Viole, F. and Nawrocki, D. (2016) "LPM Density Functions for the Computation of the SD Efficient Set." Journal of Mathematical Finance, 6, 105-126. doi:10.4236/jmf.2016.61012

Viole, F. (2017) "A Note on Stochastic Dominance." doi:10.2139/ssrn.3002675

Examples

## Not run: 
set.seed(123)
x <- rnorm(100) ; y <- rnorm(100)
NNS.FSD.uni(x, y)

## End(Not run)

NNS Monte Carlo Sampling

Description

Monte Carlo sampling from the maximum entropy bootstrap routine NNS.meboot, ensuring the replicates are sampled across the full [-1,1] range of rho (the target dependence of the detrended residuals, see NNS.meboot).

Usage

NNS.MC(
  x,
  reps = 30,
  lower_rho = -1,
  upper_rho = 1,
  by = 0.01,
  exp = 1,
  type = "spearman",
  drift = TRUE,
  target_drift = NULL,
  target_drift_scale = NULL,
  xmin = NULL,
  xmax = NULL,
  ...
)

Arguments

Value

• ensemble average observation over all replicates as a vector.

• replicates maximum entropy bootstrap replicates as a list for each rho.

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

Examples

## Not run: 
# To generate a set of MC sampled time-series to AirPassengers
MC_samples <- NNS.MC(AirPassengers, reps = 10, lower_rho = -1, upper_rho = 1, by = .5, xmin = 0)

## End(Not run)

NNS SD-based Clustering

Description

Clusters a set of variables by iteratively extracting Stochastic Dominance (SD)-efficient sets, subject to a minimum cluster size.

Usage

NNS.SD.cluster(
  data,
  degree = 1,
  type = "discrete",
  min_cluster = 1,
  dendrogram = FALSE
)

Arguments

Details

The function applies NNS.SD.efficient.set iteratively, peeling off the SD-efficient set at each step (whatever its size) while more than min_cluster variables remain, or until no more subsets can be extracted. Variables in each SD-efficient set form a cluster. The remaining variables form the final cluster, which is merged into the previous cluster if it has fewer than min_cluster members.

Value

A list with the following components:

• Clusters: A named list of cluster memberships where each element is the set of variable names belonging to that cluster.

• Dendrogram (optional): If dendrogram = TRUE, an hclust object is also returned.

Author(s)

Fred Viole, OVVO Financial Systems

References

Viole, F. and Nawrocki, D. (2016) "LPM Density Functions for the Computation of the SD Efficient Set." Journal of Mathematical Finance, 6, 105-126. doi:10.4236/jmf.2016.61012.

Viole, F. (2017) "A Note on Stochastic Dominance." doi:10.2139/ssrn.3002675

Examples

## Not run: 
set.seed(123)
x <- rnorm(100)
y <- rnorm(100)
z <- rnorm(100)
A <- cbind(x, y, z)

# Perform SD-based clustering (degree 1), requiring at least 2 elements per cluster
results <- NNS.SD.cluster(data = A, degree = 1, min_cluster = 2)
print(results$Clusters)

# Produce a dendrogram as well
results_with_dendro <- NNS.SD.cluster(data = A, degree = 1, min_cluster = 2, dendrogram = TRUE)

## End(Not run)

NNS SD Efficient Set

Description

Determines the set of stochastic dominant variables for various degrees.

Usage

NNS.SD.efficient.set(x, degree, type = "discrete", status = TRUE)

Arguments

Value

Returns set of stochastic dominant variable names.

Note

The curves are compared on the merged sample points and, for TSD and continuous area order, also at their closed-form extrema between those points. Differences smaller than 64 * .Machine$double.eps * S^d (S = largest absolute value in x and y, d = 1 for SSD and the mean condition, 2 for TSD; a ratio analogue for continuous area order) are treated as ties, so that rounding noise does not decide dominance. Discrete FSD compares exact empirical CDF values.

Author(s)

Fred Viole, OVVO Financial Systems

References

Viole, F. and Nawrocki, D. (2016) "LPM Density Functions for the Computation of the SD Efficient Set." Journal of Mathematical Finance, 6, 105-126. doi:10.4236/jmf.2016.61012.

Viole, F. (2017) "A Note on Stochastic Dominance." doi:10.2139/ssrn.3002675

Examples

## Not run: 
set.seed(123)
x <- rnorm(100) ; y<-rnorm(100) ; z<-rnorm(100)
A <- cbind(x, y, z)
NNS.SD.efficient.set(A, 1)

## End(Not run)

NNS Stochastic Superiority

Description

Computes stochastic superiority between two numeric vectors as the empirical probability that an observation from x exceeds an observation from y, with optional tie adjustment and optional confidence intervals via maximum entropy bootstrap.

Usage

NNS.SS(
  x,
  y,
  confidence.interval = FALSE,
  reps = 999,
  ci = 0.95,
  rho = 1
)

Arguments

Details

NNS.SS returns:

P(X > Y),

the tie probability

P(X = Y),

and the tie-adjusted stochastic superiority measure

P^* = P(X > Y) + \frac{1}{2} P(X = Y).

When confidence.interval = TRUE, confidence bounds for P^* are computed from NNS.meboot bootstrap replicates using LPM.VaR and UPM.VaR with degree = 0.

Missing values are removed from both x and y using stats::na.omit. The empirical estimates are computed via a fast sorted comparison routine rather than explicit pairwise expansion of all x-y combinations.

For continuous data, p_tie will typically be zero, so p_star and p_gt will be identical up to numerical precision. For discrete data, p_star provides the standard tie-adjusted superiority measure.

When confidence.interval = TRUE, the interval is constructed from the empirical bootstrap distribution of p_star, where \alpha = 1 - ci. The lower bound is obtained from LPM.VaR evaluated at \alpha / 2, and the upper bound is obtained from UPM.VaR evaluated at \alpha / 2, both with degree = 0.

Value

If confidence.interval = FALSE, returns a list containing:

p_gt

empirical probability that x > y.

p_tie

empirical probability that x = y.

p_star

tie-adjusted stochastic superiority probability.

If confidence.interval = TRUE, returns a list containing:

p_gt

empirical probability that x > y.

p_tie

empirical probability that x = y.

p_star

tie-adjusted stochastic superiority probability.

lower

lower confidence bound for p_star.

upper

upper confidence bound for p_star.

ci

confidence level used.

reps

number of bootstrap replicates used.

boot_vals

bootstrap replicate values of p_star.

Note

This function measures stochastic superiority as a pairwise exceedance probability. This is distinct from first-, second-, or third-degree stochastic dominance; see NNS.FSD, NNS.SSD, and NNS.TSD for dominance testing.

Author(s)

Fred Viole, OVVO Financial Systems

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

• Viole, F. and Nawrocki, D. (2013) Nonlinear Nonparametric Statistics: Using Partial Moments. ISBN: 1490523995, 2nd edition: https://ovvo-financial.github.io/NNS/book/.

Examples

## Not run: 
set.seed(123)
x <- rnorm(200, mean = 0.4, sd = 1)
y <- rnorm(200, mean = 0.0, sd = 1)

# Empirical stochastic superiority
NNS.SS(x, y)

# With confidence intervals
NNS.SS(x, y, confidence.interval = TRUE, reps = 999, ci = 0.95)

# Discrete example with ties
x <- sample(1:5, 100, replace = TRUE)
y <- sample(1:5, 100, replace = TRUE)
NNS.SS(x, y)

## End(Not run)

NNS SSD Test

Description

Bi-directional test of second degree stochastic dominance using lower partial moments.

Usage

NNS.SSD(x, y, plot = TRUE)

Arguments

Value

Returns one of the following SSD results: "X SSD Y", "Y SSD X", or "NO SSD EXISTS".

Note

The curves are compared on the merged sample points and, for TSD and continuous FSD, also at their closed-form extrema between those points. Differences smaller than 64 * .Machine$double.eps * S^d (S = largest absolute value in x and y, d = 1 for SSD and the mean condition, 2 for TSD; a ratio analogue for continuous FSD) are treated as ties, so that rounding noise does not decide dominance. Discrete FSD compares exact empirical CDF values.

Author(s)

Fred Viole, OVVO Financial Systems

References

Viole, F. and Nawrocki, D. (2016) "LPM Density Functions for the Computation of the SD Efficient Set." Journal of Mathematical Finance, 6, 105-126. doi:10.4236/jmf.2016.61012.

Examples

## Not run: 
set.seed(123)
x <- rnorm(100) ; y <- rnorm(100)
NNS.SSD(x, y)

## End(Not run)

NNS SSD Test uni-directional

Description

Uni-directional test of second degree stochastic dominance using lower partial moments used in SD Efficient Set routine.

Usage

NNS.SSD.uni(x, y)

Arguments

Value

Returns (1) if "X SSD Y", else (0).

Note

The curves are compared on the merged sample points and, for TSD and continuous area order, also at their closed-form extrema between those points. Differences smaller than 64 * .Machine$double.eps * S^d (S = largest absolute value in x and y, d = 1 for SSD and the mean condition, 2 for TSD; a ratio analogue for continuous area order) are treated as ties, so that rounding noise does not decide dominance. Discrete FSD compares exact empirical CDF values.

Author(s)

Fred Viole, OVVO Financial Systems

References

Viole, F. and Nawrocki, D. (2016) "LPM Density Functions for the Computation of the SD Efficient Set." Journal of Mathematical Finance, 6, 105-126. doi:10.4236/jmf.2016.61012.

Examples

## Not run: 
set.seed(123)
x <- rnorm(100) ; y <- rnorm(100)
NNS.SSD.uni(x, y)

## End(Not run)

NNS TSD Test

Description

Bi-directional test of third degree stochastic dominance using lower partial moments.

Usage

NNS.TSD(x, y, plot = TRUE)

Arguments

Value

Returns one of the following TSD results: "X TSD Y", "Y TSD X", or "NO TSD EXISTS".

Note

The curves are compared on the merged sample points and, for TSD and continuous FSD, also at their closed-form extrema between those points. Differences smaller than 64 * .Machine$double.eps * S^d (S = largest absolute value in x and y, d = 1 for SSD and the mean condition, 2 for TSD; a ratio analogue for continuous FSD) are treated as ties, so that rounding noise does not decide dominance. Discrete FSD compares exact empirical CDF values.

Author(s)

Fred Viole, OVVO Financial Systems

References

Viole, F. and Nawrocki, D. (2016) "LPM Density Functions for the Computation of the SD Efficient Set." Journal of Mathematical Finance, 6, 105-126. doi:10.4236/jmf.2016.61012.

Examples

## Not run: 
set.seed(123)
x <- rnorm(100) ; y <- rnorm(100)
NNS.TSD(x, y)

## End(Not run)

NNS TSD Test uni-directional

Description

Uni-directional test of third degree stochastic dominance using lower partial moments used in SD Efficient Set routine.

Usage

NNS.TSD.uni(x, y)

Arguments

Value

Returns (1) if "X TSD Y", else (0).

Note

The curves are compared on the merged sample points and, for TSD and continuous area order, also at their closed-form extrema between those points. Differences smaller than 64 * .Machine$double.eps * S^d (S = largest absolute value in x and y, d = 1 for SSD and the mean condition, 2 for TSD; a ratio analogue for continuous area order) are treated as ties, so that rounding noise does not decide dominance. Discrete FSD compares exact empirical CDF values.

Author(s)

Fred Viole, OVVO Financial Systems

References

Viole, F. and Nawrocki, D. (2016) "LPM Density Functions for the Computation of the SD Efficient Set." Journal of Mathematical Finance, 6, 105-126. doi:10.4236/jmf.2016.61012.

Examples

## Not run: 
set.seed(123)
x <- rnorm(100) ; y <- rnorm(100)
NNS.TSD.uni(x, y)

## End(Not run)

NNS VAR

Description

Nonparametric vector autoregressive model incorporating NNS.ARMA estimates of variables into NNS.reg for a multi-variate time-series forecast.

Usage

NNS.VAR(
  variables,
  h,
  tau = 1,
  dim.red.method = "cor",
  naive.weights = TRUE,
  obj.fn = expression({
     .denom <- NNS::Co.LPM(1, predicted, actual, target_x =
    mean(predicted), target_y = mean(actual)) + NNS::Co.UPM(1, predicted, actual,
    target_x = mean(predicted), target_y = mean(actual))
     if (.denom == 0) Inf else
    mean((predicted - actual)^2)/.denom
 }),
  objective = "min",
  status = TRUE,
  ncores = NULL,
  nowcast = FALSE,
  validation = c("pipeline", "observed")
)

Arguments

Value

Returns the following matrices of forecasted variables:

• "interpolated_and_extrapolated" Returns a data.frame of the original variables with their NA values replaced. When a variable's latest values are missing, every NA of that variable is estimated from its own observations by the NNS.stack fit on the time index used in NNS 13.0: NNS.reg with one nearest regression point, on the index duplicated into two predictors. The latest observation keeps its own regression point, and values after it (or before the first observation) extend the gradient at that boundary. When only earlier values are missing, they are interpolated linearly with NNS.reg(order = "max") on the index. This is required for working with variables containing different frequencies, e.g. where NA would be reported for intra-quarterly data when indexed with monthly periods.

• "relevant_variables" Returns the relevant variables from the dimension reduction step: the lagged regressors whose dimension reduction coefficient meets the cross-validated threshold. These are the only regressors used in the "multivariate" estimate.

• "univariate" Returns the univariate NNS.ARMA forecasts.

• "multivariate" Returns the multi-variate forecasts: NNS.stack (method = 1, stack = FALSE) on the relevant variables, evaluated on the lag-matrix rows of the forecast period (built from the univariate forecasts).

• "validation" validation mode, origin and horizon used for tuning; pipeline mode excludes future covariates from prefix completion and prediction.

• "ensemble" Returns the ensemble of both "univariate" and "multivariate" forecasts.

Note

• "Error in { : task xx failed -}" should be re-run with NNS.VAR(..., ncores = 1).

• Not recommended for factor variables, even after transformed to numeric. NNS.reg is better suited for factor or binary regressor extrapolation.

Author(s)

Fred Viole, OVVO Financial Systems

References

Viole, F. and Nawrocki, D. (2013) "Nonlinear Nonparametric Statistics: Using Partial Moments" (ISBN: 1490523995, 2nd edition: https://ovvo-financial.github.io/NNS/book/)

Viole, F. (2019) "Multi-variate Time-Series Forecasting: Nonparametric Vector Autoregression Using NNS" doi:10.2139/ssrn.3489550

Viole, F. (2020) "NOWCASTING with NNS" doi:10.2139/ssrn.3589816

Viole, F. (2019) "Forecasting Using NNS" doi:10.2139/ssrn.3382300

Vinod, H. and Viole, F. (2017) "Nonparametric Regression Using Clusters" doi:10.1007/s10614-017-9713-5

Vinod, H. and Viole, F. (2018) "Clustering and Curve Fitting by Line Segments" doi:10.20944/preprints201801.0090.v1

Examples

 ## Not run: 
 ####################################################
 ### Standard Nonparametric Vector Autoregression ###
 ####################################################

 set.seed(123)
 x <- rnorm(100) ; y <- rnorm(100) ; z <- rnorm(100)
 A <- cbind(x = x, y = y, z = z)

 ### Using lags 1:4 for each variable
 NNS.VAR(A, h = 12, tau = 4, status = TRUE)

 ### Using lag 1 for variable 1, lag 3 for variable 2 and lag 3 for variable 3
 NNS.VAR(A, h = 12, tau = c(1,3,3), status = TRUE)

 ### Using lags c(1,2,3) for variables 1 and 3, while using lags c(4,5,6) for variable 2
 NNS.VAR(A, h = 12, tau = list(c(1,2,3), c(4,5,6), c(1,2,3)), status = TRUE)

 ### PREDICTION INTERVALS
 # Store NNS.VAR output
 nns_estimate <- NNS.VAR(A, h = 12, tau = 4, status = TRUE)

 # Create bootstrap replicates using NNS.meboot
 replicates <- NNS.meboot(nns_estimate$ensemble[,1], rho = seq(-1,1,.25))["replicates",]
 replicates <- do.call(cbind, replicates)

 # Apply UPM.VaR and LPM.VaR for a band around the forecast path (2.5 percent per tail).
 # The replicates resample the forecast path itself, so the band shows the path's
 # dispersion, not a calibrated 95 percent prediction interval (see NNS.ARMA's pred.int).
 # Tail percentage used in first argument per {LPM.VaR} and {UPM.VaR} functions
 lower_CIs <- apply(replicates, 1, function(z) LPM.VaR(0.025, 0, z))
 upper_CIs <- apply(replicates, 1, function(z) UPM.VaR(0.025, 0, z))

 # View results
 cbind(nns_estimate$ensemble[,1], lower_CIs, upper_CIs)


 #########################################
 ### NOWCASTING with Mixed Frequencies ###
 #########################################

 library(Quandl)
 econ_variables <- Quandl(c("FRED/GDPC1", "FRED/UNRATE", "FRED/CPIAUCSL"),type = 'ts',
                          order = "asc", collapse = "monthly", start_date = "2000-01-01")

 ### Note the missing values that need to be imputed
 head(econ_variables)
 tail(econ_variables)


 NNS.VAR(econ_variables, h = 12, tau = 12, status = TRUE)
 
## End(Not run)

NNS Boost

Description

Ensemble method for classification using the NNS multivariate regression NNS.reg as the base learner instead of trees.

Usage

NNS.boost(
  IVs.train,
  DV.train,
  IVs.test = NULL,
  type = NULL,
  depth = NULL,
  learner.trials = 100,
  epochs = NULL,
  CV.size = NULL,
  balance = FALSE,
  ts.test = NULL,
  threshold = NULL,
  obj.fn = expression(sum((predicted - actual)^2)),
  objective = "min",
  extreme = FALSE,
  features.only = FALSE,
  feature.importance = TRUE,
  pred.int = NULL,
  status = TRUE,
  seed = 123L,
  dist = NULL,
  folds = 5
)

Arguments

Value

Returns a vector of fitted values for the dependent variable test set $results, prediction intervals $pred.int, the final feature loadings $feature.weights, final feature frequencies $feature.frequency, and (for classification) the class labels $class.levels. Classification results are numeric: a factor or character DV.train yields integer class codes with a base category of 1 (label recoverable as class.levels[results]), and a numeric DV.train yields its original numeric class values.

Note

• Like a logistic regression, the (type = "CLASS") setting is not necessary for target variable of two classes e.g. [0, 1]. The response variable base category should be 1 for classification problems.

• Incorporate any objective function from external packages (such as Metrics::mape) via NNS.boost(..., obj.fn = expression(Metrics::mape(actual, predicted)), objective = "min")

Author(s)

Fred Viole, OVVO Financial Systems

References

Viole, F. (2016) "Classification Using NNS Clustering Analysis" doi:10.2139/ssrn.2864711

Examples

 ## Using 'iris' dataset with a stratified test set of ten rows per species
 ## (rows 141:150 alone are all virginica).
 ## Not run: 
 test.set <- c(41:50, 91:100, 141:150)
 a <- NNS.boost(iris[-test.set, 1:4], iris[-test.set, 5],
 IVs.test = iris[test.set, 1:4],
 epochs = 100, learner.trials = 100,
 type = "CLASS", depth = NULL, balance = TRUE)

 ## Test accuracy
 mean(a$results == as.numeric(iris[test.set, 5]))

 ## Recover the labels
 a$class.levels[a$results]
 
## End(Not run)

NNS Causation

Description

Returns the directional lagged-association diagnostic between two variables from observational data, as an index in [0, 1] for each direction (0.5 = no net direction).

Usage

NNS.caus(
  x,
  y = NULL,
  factor.2.dummy = FALSE,
  tau = 0,
  plot = FALSE,
  p.value = FALSE,
  nperm = 100L,
  permute = c("auto", "y", "x", "both", "shift"),
  seed = NULL,
  conf.int = 0.95
)

Arguments

Details

Following book chapter 14, each direction is evaluated on explicitly lagged pairs mapped to the copula scale with per-column ranks (the degree-0 lower partial moment), so the result is invariant to shifts, rescaling and any increasing transform of either variable (reversing a variable's order changes the copula, and so the index). For x —> y the raw score is

\tilde{C}_{x \to y} = \frac{1}{2}\left[P_{x \to y} + \max(\rho_{x \to y} - \rho_{y \to x}, 0)\right],

where P_{x \to y} is the share of the deviation of y[t] resolved by conditioning on the position of x[t - tau], the deviation being the degree-2 lower plus upper partial moment about the mean with the m/(m-1) factor, used as a finite-sample normalization under the permutation reference, and \rho_{x \to y} is the debiased directional dependence of y[t] on x[t - tau] from NNS.dep's cells (the lagged co-partial moments of the pair), averaged over the levels of the partition on x[t - tau]. NNS.dep reports the strongest level; the average avoids that maximization step. The neutral value is 0.5, but finite-sample behavior depends on the data and the null construction. The index is

C_{x \to y} = \frac{\tilde{C}_{x \to y} + \kappa}{\tilde{C}_{x \to y} + \tilde{C}_{y \to x} + 2\kappa}, \quad C_{y \to x} = 1 - C_{x \to y},

with a neutral pseudo-count \kappa = 1/\sqrt{n - \tau}, a regularization that shrinks weak directional evidence toward 0.5. It does not make the index's spread under independence constant: the spread grows with persistence. For independent pairs with n = 300 and tau = 20, the standard deviation of the index was about 0.08 for iid series, 0.14 for AR(1) series with coefficient 0.9 and 0.17 for random walks, and more than half of the persistent pairs fell more than 0.1 from 0.5. Distance from 0.5 alone is therefore not a significance criterion. An invertible relationship (e.g. y = 2 * x + 1) has no cross-sectional direction and returns 0.5; a lag can produce unequal directional association in that case. The index measures directional lagged association. It does not adjust for the response's own history, confounding variables, common drivers, or interventions. A common driver that reaches y later than x can favor x —> y without a causal effect. Circular-shift inference requires a null model invariant under the allowed shifts; stationarity and preserved autocorrelation alone do not establish this. Restricted offsets and boundary wraparound make this a finite resampling diagnostic, not an exact conditional-causality test. Shuffled-value inference instead requires exchangeability. The reported interval is an interval of the permutation null, not an uncertainty interval for an identified causal parameter.

Value

If p.value = FALSE returns a named vector c("C(x--->y)", "C(y--->x)") of directional association indices in [0, 1] that sum to 1: above 0.5 means the first lagged direction has the larger score, and 0.5 is no net direction under this diagnostic. If p.value = TRUE returns a list with components: * causation: the vector above. * p.value: a list with empirical two-sided and one-sided p-values (x_causes_y, y_causes_x) of the signed statistic C(x--->y) - C(y--->x), its null distribution and observed value, the partial-moment interval of the null, and metadata (permute, nperm). For a matrix x, entry [i, j] is C(column i ---> column j), with a 0 diagonal. If p.value = TRUE for a matrix, the function returns a list with components: * causality: the causation matrix. * lower_CI, upper_CI: matrices with the partial-moment interval of each index under the permutation null. * p.value_matrix: matrix of empirical two-sided p-values of C(i ---> j) - C(j ---> i).

Author(s)

Fred Viole, OVVO Financial Systems

References

Viole, F. and Nawrocki, D. (2013) "Nonlinear Nonparametric Statistics: Using Partial Moments" (ISBN: 1490523995, 2nd edition: https://ovvo-financial.github.io/NNS/book/)

Examples

## Not run: 
## x causes y (y is a function of x, x is not a function of y)
set.seed(123)
x <- rnorm(1000) ; y <- x ^ 2
NNS.caus(x, y, tau = "cs")

## Lagged causation: y follows x by one period
x <- rnorm(500) ; y <- c(0, 0.8 * x[-500]) + 0.3 * rnorm(500)
NNS.caus(x, y, tau = 1)

## Causal matrix: entry [i, j] is C(column i ---> column j)
NNS.caus(iris, tau = 0)

## Causal matrix with per factor causation
NNS.caus(iris, factor.2.dummy = TRUE, tau = 0)

## End(Not run)

NNS Co-Partial Moments Higher Dimension Dependence

Description

Determines higher dimension dependence coefficients based on co-partial moment matrices ratios.

Usage

NNS.copula(
  X,
  target = NULL,
  continuous = TRUE,
  plot = FALSE,
  independence.overlay = FALSE
)

Arguments

Value

Returns a multivariate dependence value [0,1]. Each co-partial moment is compared with its value under independence, the product of the marginal partial moments at target, so independent variables give a value near 0 for any target and marginal distributions. At a target with every variable's observations on one side, the normalized directional-region shares carry no contrast and the neutral value is 0. This target degeneracy is not evidence that the variables are independent. In general, 0 and 1 describe this target-specific summary, not global independence or deterministic dependence.

Author(s)

Fred Viole, OVVO Financial Systems

References

Viole, F. (2016) "Beyond Correlation: Using the Elements of Variance for Conditional Means and Probabilities" doi:10.2139/ssrn.2745308.

Examples

## Not run: 
set.seed(123)
x <- rnorm(1000) ; y <- rnorm(1000) ; z <- rnorm(1000)
A <- data.frame(x, y, z)
NNS.copula(A, target = colMeans(A), plot = TRUE, independence.overlay = TRUE)

### Target 0
NNS.copula(A, target = rep(0, ncol(A)), plot = TRUE, independence.overlay = TRUE)

## End(Not run)

NNS Dependence

Description

Returns the dependence and nonlinear correlation between two variables based on higher order partial moment matrices measured by frequency or area.

Usage

NNS.dep(x, y = NULL, asym = FALSE, p.value = FALSE, print.map = FALSE)

Arguments

Details

Dependence is a finite-resolution summary of the recursive partitions of NNS.part, which split each cell at the gravity of its observations (noise.reduction = "off"), not at its mean. At each cell, degree-0 (frequency) and degree-1 (area) concordance around the cell means are measured relative to a within-cell permutation reference and rescaled. Their cell-size-weighted averages are evaluated across partition levels. The reported Dependence is the strongest level, floored at zero; Correlation is a signed summary at that selected level and is bounded by Dependence in absolute value. With asym = FALSE, partitions on x, on y, and on joint quadrants are considered. With asym = TRUE, only partitions on x are considered, so the direction describes the resolution supplied by the conditioning variable rather than a causal effect.

The split depth, stopping rules, finite occupancy, and maximization across levels affect the score. A zero score does not prove independence, a noiseless nonlinear function need not score one, and finite independent samples can produce positive scores. The permutation calculation repeats the same selection rule, providing a reference for the selected statistic rather than removing every finite-sample effect from the score itself.

The degree-0 cell reference uses the hypergeometric distribution, with a normal approximation for cell sizes above 400. The degree-1 reference enumerates distinct arrangements only when at most 720 are required (all arrangements for up to six distinct values); larger cells use an approximation. These are properties of the cell calibration, separate from the 100 whole-sample permutations used by p.value = TRUE.

Power depends on the alternative. On noisy linear relationships in small samples, rank-based, distance-correlation or Hoeffding tests can reject more often than the p.value permutation test of NNS.dep; on non-monotone or heteroscedastic shapes such as a circle or y = x * e, the NNS.dep test can reject far more often.

Whole-sample shuffling assumes exchangeability of observations under the null. It is not an automatic test for serially dependent or clustered observations. The returned fields named 95% CIs are central intervals of the permutation null, not confidence intervals for a population dependence parameter. Inclusive-tail counts with the plus-one correction avoid zero Monte Carlo p-values; ties make the test conservative.

Value

Returns the bi-variate "Correlation" and "Dependence" or correlation / dependence matrix for matrix input.

Note

For asymmetrical (asym = TRUE) matrices, entry [i, j] is the directional dependence ([row variable i] —> [column variable j]), i.e. NNS.dep(x[, i], x[, j], asym = TRUE), the dependence of column j on row variable i.

Author(s)

Fred Viole, OVVO Financial Systems

References

Viole, F. and Nawrocki, D. (2013) "Nonlinear Nonparametric Statistics: Using Partial Moments" (ISBN: 1490523995, 2nd edition: https://ovvo-financial.github.io/NNS/book/)

Examples

## Not run: 
set.seed(123)
x <- rnorm(100) ; y <- rnorm(100)
NNS.dep(x, y)

## Correlation / Dependence Matrix
x <- rnorm(100) ; y <- rnorm(100) ; z <- rnorm(100)
B <- cbind(x, y, z)
NNS.dep(B)

## End(Not run)

NNS Numerical Differentiation

Description

Determines numerical derivative of a given univariate function using projected secant lines on the y-axis. These projected points infer finite steps h, in the finite step method.

Usage

NNS.diff(
  f,
  point,
  h = abs(point) * 0.1 + 0.01,
  tol = 1e-10,
  max.iter = NULL,
  digits = 12,
  print.trace = FALSE,
  plot = FALSE
)

Arguments

Value

Returns a matrix of values, intercepts, derivatives, inferred step sizes for multiple methods of estimation.

Author(s)

Fred Viole, OVVO Financial Systems

References

Viole, F. and Nawrocki, D. (2013) "Nonlinear Nonparametric Statistics: Using Partial Moments" (ISBN: 1490523995, 2nd edition: https://ovvo-financial.github.io/NNS/book/)

Examples

## Not run: 
f <- function(x) sin(x) / x
NNS.diff(f, 4.1)

## Noisy function with explicit iteration cap
f_noisy <- function(x) sin(x) + rnorm(1, 0, 0.001)
NNS.diff(f_noisy, 1.0, max.iter = 100)

## End(Not run)

NNS Distance

Description

Internal kernel function for NNS multivariate regression NNS.reg parallel instances.

Usage

NNS.distance(rpm, dist.estimate, k = "all", class = NULL)

Arguments

Value

Returns sum of weighted distances.

NNS gravity

Description

Central tendency averaging the median, the mean, the midpoint of the quartiles and a histogram mode; less sensitive to outliers than the mean.

Usage

NNS.gravity(x, discrete = FALSE)

Arguments

Details

(Q_2 + m + \bar{x} + (Q_1 + Q_3)/2) / 4,

with the quartiles Q_1, Q_2, Q_3 of quantile(x, type = 7) and, as the mode m, the mean of the observations in the tallest bin of a histogram with bin width IQR / sqrt(n) and its two neighbouring bins (all observations when several bins are equally tall). Up to three values give the median. The mean term remains unbounded under one-point contamination: a single 1e6 among 99 zeros gives 2500, against 10000 for the mean. The other components can also change, so the one-quarter factor is an example, not a universal sensitivity bound. Its asymptotic replacement breakdown point is zero; it is not a high-breakdown estimator.

Value

Returns a numeric value representing the central tendency of the distribution.

Author(s)

Fred Viole, OVVO Financial Systems

Examples

## Not run: 
set.seed(123)
x <- rnorm(100)
NNS.gravity(x)

## End(Not run)

NNS meboot

Description

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

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

## Not run: 
# 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") 

## End(Not run)

NNS mode

Description

Mode of a distribution, either continuous or discrete.

Usage

NNS.mode(x, discrete = FALSE, multi = TRUE)

Arguments

Details

The continuous mode finds the peaks of a smoothed histogram with bin width IQR / sqrt(n), peaks in the first and last bins included, and centres each peak on the mean of the observations within three bins of it, so a peak on a single value returns that value. When every gap between consecutive distinct values is wider than a bin, the data are treated as discrete-valued: the modes are the values more frequent than their neighbouring values, a run of equally frequent values counting together. discrete = TRUE instead rounds to integers and returns the most frequent integers.

Value

Returns the mode of the distribution: a numeric vector of all modes when multi = TRUE (default), otherwise a single numeric value.

Author(s)

Fred Viole, OVVO Financial Systems

Examples

## Not run: 
set.seed(123)
x <- rnorm(100)
NNS.mode(x)

## End(Not run)

NNS moments

Description

This function returns the first 4 moments of the distribution.

Usage

NNS.moments(x, population = TRUE)

Arguments

Value

Returns:

• "$mean" mean of the distribution.

• "$variance" variance of the distribution.

• "$skewness" skewness of the distribution.

• "$kurtosis" excess kurtosis.

Author(s)

Fred Viole, OVVO Financial Systems

References

Viole, F. and Nawrocki, D. (2013) "Nonlinear Nonparametric Statistics: Using Partial Moments" (ISBN: 1490523995, 2nd edition: https://ovvo-financial.github.io/NNS/book/)

Examples

## Not run: 
set.seed(123)
x <- rnorm(100)
NNS.moments(x)

## End(Not run)

NNS Normalization

Description

Normalizes a matrix of variables based on nonlinear scaling normalization method.

Usage

NNS.norm(X, linear = FALSE, chart.type = NULL, location = "topleft")

Arguments

Value

Returns a data.frame of normalized values.

Note

Unequal vectors provided in a list will only generate linear=TRUE normalized values.

Author(s)

Fred Viole, OVVO Financial Systems

References

Viole, F. and Nawrocki, D. (2013) "Nonlinear Nonparametric Statistics: Using Partial Moments" (ISBN: 1490523995, 2nd edition: https://ovvo-financial.github.io/NNS/book/)

Examples

## Not run: 
set.seed(123)
x <- rnorm(100) ; y <- rnorm(100)
A <- cbind(x, y)
NNS.norm(A)

### Normalize list of unequal vector lengths

vec1 <- c(1, 2, 3, 4, 5, 6, 7)
vec2 <- c(10, 20, 30, 40, 50, 60)
vec3 <- c(0.5, 0.6, 0.7, 0.8, 0.9, 1.0, 1.1, 1.2, 1.3)

vec_list <- list(vec1, vec2, vec3)
NNS.norm(vec_list)

## End(Not run)

NNS Partition Map

Description

Creates partitions based on partial-moment quadrant centroids. Numeric orders use the compiled recursive partitioner. 'order = "max"' returns the maximum observable partition representation without passing an invalid integer to C++.

Usage

NNS.part(
  x,
  y,
  Voronoi = FALSE,
  type = NULL,
  order = NULL,
  obs.req = 8,
  min.obs.stop = TRUE,
  noise.reduction = "off"
)

Arguments

Details

For a numeric order, each cell is split at a centre per coordinate, set by noise.reduction: "mean" and "median" use the mean and median, "mode" uses the continuous NNS.mode(multi = FALSE), "mode_class" uses NNS.gravity for x and NNS.mode(discrete = TRUE) for y, and "off" uses NNS.gravity. Regression points are the same centres of each prior.quadrant. order = "max" makes no splits: every observation is its own regression point, or with type = "XONLY" each distinct x gets the y centre of its observations. Quadrant labels append one digit per order. With split centres cx and cy, the digit for the default joint partition (type = NULL) is 1 + (x <= cx) + 2 * (y <= cy): 1 = upper-right, 2 = upper-left, 3 = lower-right, 4 = lower-left. For type = "XONLY" the digit is 1 for x <= cx and 2 for x > cx.

Value

A list containing 'order', 'dt', and 'regression.points'.

• order: the order actually completed. It can be smaller than the requested order when obs.req / min.obs.stop stop the recursion (e.g. order = 3 returns 2 for n = 200 with the default obs.req = 8).

• dt: the observations with their final quadrant and prior.quadrant labels.

• regression.points: for a numeric order, one (x, y) centroid per prior.quadrant, i.e. per cell of the previous order: order = 1 gives 4 final quadrants but a single regression point ("q"), order = 2 gives up to 16 quadrants and 4 points.

NNS Regression

Description

Generates a nonlinear regression based on partial moment quadrant means.

Usage

NNS.reg(
  x,
  y,
  factor.2.dummy = TRUE,
  order = NULL,
  dim.red.method = NULL,
  tau = NULL,
  type = NULL,
  point.est = NULL,
  location = "top",
  return.values = TRUE,
  plot = TRUE,
  plot.regions = FALSE,
  residual.plot = TRUE,
  confidence.interval = NULL,
  threshold = 0,
  n.best = NULL,
  smooth = FALSE,
  noise.reduction = "off",
  dist = NULL,
  ncores = NULL,
  point.only = FALSE,
  multivariate.call = FALSE
)

Arguments

Details

For regression, R2 measures association between fitted and observed responses: it is cor(y, \hat y)^2, with the package's finite constant-vector convention. It is not 1-SSE/SST; a biased or incorrectly scaled prediction can have R2 = 1. Evaluate held-out prediction errors for predictive accuracy.

The default partition order combines a finite-partition dependence score with the average of the duplicated-predictor copula score under both response orientations. This complexity heuristic is invariant to reflecting the response; the underlying directional dependence and copula definitions are unchanged. A supplied order bypasses this heuristic.

Univariate regression linearly interpolates the selected regression points and extends the first or last segment beyond their range (unless a smoothing spline is requested). Endpoint slopes can be unstable with sparse or noisy boundary points. Multivariate distance weighting is a weighted average of regression-point responses, so it does not automatically continue a trend outside the training support. Neither construction supplies a general extrapolation guarantee. With the default n.best = NULL, purely categorical predictors use exact observed joint cells, and an unobserved joint combination uses its nearest cells. An explicit n.best weights that many nearest cells, as for numeric predictors. A declared factor level with no training rows is accepted in point.est and is placed by the same distance rule. A coordinate with exactly two observed values retains both terminal cells, including a dummy column in a mixed design. Other finite-order numeric coordinates retain interval cells; order = "max" uses exact joint support.

Classification forms an indicator for each observed class, retains the empirical class frequencies in each predictor cell, and interpolates or distance-weights those probability vectors. Class labels never enter numeric interpolation. Point.probabilities, Fitted.probabilities, and RPM.probabilities expose the corresponding vectors. Tied class decisions follow first appearance in the training response. Factor and character responses retain numeric output codes with class.levels; numeric responses retain their supplied values. For dimension reduction, one signed NNS index is fitted per class indicator, and the resulting probabilities are normalized across classes; equation is then a list indexed by class. confidence.interval returns Prediction.set, the smallest leading set of classes attaining the requested estimated probability mass. These are descriptive probability sets, not calibrated coverage guarantees; nominal classes have no numeric prediction interval.

Value

UNIVARIATE REGRESSION RETURNS THE FOLLOWING VALUES:

• "R2" is squared Pearson correlation between fitted and observed responses (Racine–Hastie goodness of fit), or fitted classification accuracy;

• "SE" returns the overall standard error of the estimate between y and y.hat;

• "Prediction.Accuracy" returns the proportion of fitted class decisions equal to the observed class;

• "derivative" for the coefficient of the x and its applicable range;

• "Point.est" for the predicted value generated;

• "pred.int" lower and upper prediction intervals for the "Point.est" returned using the "confidence.interval" provided;

• "regression.points" provides the points used in the regression equation for the given order of partitions;

• "Fitted.xy" returns a data.frame of x, y, y.hat, resid, NNS.ID, gradient;

MULTIVARIATE REGRESSION RETURNS THE FOLLOWING VALUES:

• "R2" is squared Pearson correlation between fitted and observed responses (Racine–Hastie goodness of fit), or fitted classification accuracy;

• "equation" returns the numerator of the synthetic X* dimension reduction equation as a data.frame consisting of regressor and its coefficient. Denominator is the number of non-zero coefficients (abs(coefficient) > 0), returned in last row of equation data.frame.

• "x.star" returns the synthetic X* as a vector;

• "rhs.partitions" returns the partition points for each regressor x;

• "RPM" provides the Regression Point Matrix, the points for each x used in the regression equation for the given order of partitions;

• "Point.est" returns the predicted value generated;

• "pred.int" lower and upper prediction intervals for the "Point.est" returned using the "confidence.interval" provided;

• "Fitted.xy" returns a data.frame of the regressors, y, y.hat, NNS.ID and residuals for full multivariate regression, or of the synthetic x, y, y.hat, NNS.ID, gradient and residuals for dimension reduction regression. confidence.interval adds conf.int.neg and conf.int.pos.

Note

• Please ensure point.est is of compatible dimensions to x, error message will ensue if not compatible.

• Like a logistic regression, the (type = "CLASS") setting is not necessary for target variable of two classes e.g. [0, 1]. For other numeric responses set type = "CLASS"; class values can be any distinct numbers.

• For low signal:noise instances, increasing the dimension may yield better results using NNS.stack(cbind(x,x), y, method = 1, ...).

Author(s)

Fred Viole, OVVO Financial Systems

References

Viole, F. and Nawrocki, D. (2013) "Nonlinear Nonparametric Statistics: Using Partial Moments" (ISBN: 1490523995, 2nd edition: https://ovvo-financial.github.io/NNS/book/)

Vinod, H. and Viole, F. (2017) "Nonparametric Regression Using Clusters" doi:10.1007/s10614-017-9713-5

Vinod, H. and Viole, F. (2018) "Clustering and Curve Fitting by Line Segments" doi:10.20944/preprints201801.0090.v1

Viole, F. (2020) "Partitional Estimation Using Partial Moments" doi:10.2139/ssrn.3592491

Dana, J., and Dawes, R. M. (2004). The Superiority of Simple Alternatives to Regression for Social Science Predictions. Journal of Educational and Behavioral Statistics, 29(3), 317–331.

Examples

## Not run: 
set.seed(123)
x <- rnorm(100) ; y <- rnorm(100)
NNS.reg(x, y)

## Manual {order} selection
NNS.reg(x, y, order = 2)

## Maximum {order} selection
NNS.reg(x, y, order = "max")


## For Multiple Regression:
x <- cbind(rnorm(100), rnorm(100), rnorm(100)) ; y <- rnorm(100)
NNS.reg(x, y, point.est = c(.25, .5, .75))

## For Multiple Regression based on Synthetic X* (Dimension Reduction):
x <- cbind(rnorm(100), rnorm(100), rnorm(100)) ; y <- rnorm(100)
NNS.reg(x, y, point.est = c(.25, .5, .75), dim.red.method = "cor", ncores = 1)

## IRIS dataset examples:
# Dimension Reduction:
NNS.reg(iris[,1:4], iris[,5], dim.red.method = "cor", order = 5, ncores = 1)

# Dimension Reduction using causal weights:
NNS.reg(iris[,1:4], iris[,5], dim.red.method = "NNS.caus", order = 5, ncores = 1)

# Multiple Regression:
NNS.reg(iris[,1:4], iris[,5], order = 2, noise.reduction = "off")

# Classification:
NNS.reg(iris[,1:4], iris[,5], point.est = iris[1:10, 1:4], type = "CLASS")$Point.est

## To call fitted values:
x <- rnorm(100) ; y <- rnorm(100)
NNS.reg(x, y)$Fitted

## To call partial derivative (univariate regression only):
NNS.reg(x, y)$derivative

## End(Not run)

NNS rescale

Description

Rescale a vector using either min-max scaling or risk-neutral adjustment.

Usage

NNS.rescale(x, a, b, method = "minmax", T = NULL, type = "Terminal")

Arguments

Value

Returns a rescaled distribution: - For "minmax": values scaled linearly to the range [a, b]. - For "riskneutral": values scaled multiplicatively to a risk-neutral mean (\( S_0 e^(rT) \) if type = "Terminal", or \( S_0 \) if type = "Discounted").

Author(s)

Fred Viole, OVVO Financial Systems

Examples

## Not run: 
set.seed(123)
# Min-max scaling: a = lower limit, b = upper limit
x <- rnorm(100)
NNS.rescale(x, a = 5, b = 10, method = "minmax")  # Scales to [5, 10]

# Risk-neutral scaling (Terminal): a = S_0, b = r  # Mean approx 105.13
prices <- 100 * exp(cumsum(rnorm(100, 0.001, 0.02)))
NNS.rescale(prices, a = 100, b = 0.05, method = "riskneutral", T = 1, type = "Terminal")

# Risk-neutral scaling (Discounted): a = S_0, b = r  # Mean approx 100
NNS.rescale(prices, a = 100, b = 0.05, method = "riskneutral", T = 1, type = "Discounted")

## End(Not run)

NNS Seasonality Test

Description

Seasonality test based on the coefficient of variation for the variable and lagged component series. A linear trend is removed first (detrend = TRUE), keeping the mean of the variable, so that a trend does not mask the period. For each lag m, the variable is split into its m component series variable[seq(j, n, m)], j = 1, ..., m, and lag m is reported when the length-weighted mean of the component coefficients of variation is below the coefficient of variation of the variable. Dispersion is the Gini mean difference, the degree-1 lower plus upper partial moment about each observation in turn, which is unbiased for any distribution at any component length. The coefficient of variation is used when the (detrended) variable stays on one side of zero; otherwise dispersions are compared directly. Lags are scanned up to max.period, by default n / 5, so every component series has at least 5 observations. Periods added through modulo are kept up to n / 2. On a series without seasonality about half of the lags pass by chance, so treat the result as candidate periods and validate them, for example with NNS.ARMA.optim, or set p.value = TRUE. A result of 1 signifies no seasonality present. A multiple of the true period scores as well in expectation, and its shorter components make its score noisier, so the lowest score often falls on a multiple. best.period is therefore the fundamental period: the smallest period that divides the lowest-scoring lag, or nearly divides it for a non-integer period, and whose score exceeds the lowest by at most two jackknife standard errors of their difference, from paired delete-one scores. It is listed first in all.periods and periods, followed by the other periods in order of score.

Usage

NNS.seas(
  variable,
  modulo = NULL,
  mod.only = TRUE,
  plot = TRUE,
  detrend = TRUE,
  max.period = NULL,
  p.value = FALSE,
  nperm = 100L,
  dispersion = c("auto", "absolute")
)

Arguments

Value

Returns a matrix of all periods exhibiting less coefficient of variation than the variable with "all.periods"; and the fundamental period with "best.period" (see Description); as well as a vector of "periods" for easy call into NNS.ARMA.optim. If no seasonality is detected, all.periods holds a single row with Period = 1 and a coefficient of variation equal to the variable's (Period = 0 for fewer than 5 observations). The coefficients of variation are those of the detrended variable when detrend = TRUE.

Note

The historical column names Coefficient.of.Variation and Variable.Coefficient.of.Variation are retained in absolute mode; their values then contain absolute Gini dispersions.

best.period need not be the lowest-scoring lag: with(all.periods, Period[which.min(Coefficient.of.Variation)]) returns that lag. The jackknife behind the two-standard-error rule treats observations as exchangeable and does not adjust for serial dependence. The minimum five observations per component is a reliability default; modulo can supply longer domain-informed candidates. Shuffling removes serial dependence as well as seasonality, so the optional permutation comparison is not calibrated against every dependent nonseasonal process.

Author(s)

Fred Viole, OVVO Financial Systems

References

Viole, F. and Nawrocki, D. (2013) "Nonlinear Nonparametric Statistics: Using Partial Moments" (ISBN: 1490523995, 2nd edition: https://ovvo-financial.github.io/NNS/book/)

Examples

## Not run: 
set.seed(123)
x <- rnorm(100)

## To call strongest period based on coefficient of variation:
NNS.seas(x, plot = FALSE)$best.period

## Using modulos for logical seasonal inference:
NNS.seas(x, modulo = c(2,3,5,7), plot = FALSE)

## Keep only periods that beat shuffled copies of the series:
NNS.seas(x, plot = FALSE, p.value = TRUE)$best.period

## End(Not run)

NNS Stack

Description

Prediction model using the predictions of the NNS base models NNS.reg as features (i.e. meta-features) for the stacked model.

Usage

NNS.stack(
  IVs.train,
  DV.train,
  IVs.test = NULL,
  type = NULL,
  obj.fn = expression(sum((predicted - actual)^2)),
  objective = "min",
  optimize.threshold = TRUE,
  dist = NULL,
  CV.size = NULL,
  balance = FALSE,
  ts.test = NULL,
  folds = 5,
  order = NULL,
  method = c(1, 2),
  stack = TRUE,
  dim.red.method = "cor",
  pred.int = NULL,
  status = TRUE,
  ncores = NULL,
  seed = 123L,
  .validation = NULL
)

Arguments

Details

Classification tunes and combines class-probability vectors from the NNS predictor cells, preserving nominal label identity. probabilities, reg.probabilities, and dim.red.probabilities return the final probability matrices. Class balancing resamples the training rows of each fold. The neighbour count and the dimension count are chosen by optimizing obj.fn on the pooled out-of-fold predictions; the default classification objective is accuracy. As in NNS 13.0, the two models' probability vectors are then blended with weights proportional to their squared objective scores (inverse squares when objective = "min"), so models with nearly equal scores are blended nearly equally, and the binary probability threshold is tuned on the out-of-fold predictions of that blend. OBJfn.reg and OBJfn.dim.red are the best scores of that search on the same predictions, so they are selection-optimized and overstate held-out performance; assess the final model on an independent test set. Custom objectives receive original numeric or logical response values, and factor/character codes as identified by class.levels. Relabelling is invariant for label-invariant objectives such as accuracy; a custom loss assigning different costs to classes can deliberately change the result.

Named numeric dimension-reduction coefficients are matched to encoded predictor names in both regression and classification. Factor columns use predictor__level names; unnamed vectors follow encoded column order. Classification dimension reduction uses one signed index per class indicator. Its reported coefficients are a list of class-specific equations. The tuned dimension count is returned as NNS.dim.red.count, and NNS.dim.red.threshold gives the coefficient cutoff that keeps that count in every class index: one number when the class indices share it, as two-class indices always do, and otherwise one cutoff per class. The field NNS.dim.red.variables is the union of their active encoded columns. These equations describe the synthetic indices, not a complete saved prediction model: reconstruction also requires training-fitted scaling, the predictor cells, their class frequencies, and the selected smoothing controls. With stack = TRUE, the multivariate classification component retains the selected number of actual encoded coordinates ranked by maximum class-indicator dependence. Prediction.set contains classes attaining the requested estimated probability mass. Binary interval fields contain the range of this set for compatibility; multiclass interval fields are NULL. The sets do not assert calibrated coverage.

For regression, all dimension-reduction coefficients, normalizations, and candidate predictions used in validation are fitted to the corresponding training fold. The final coefficients and regressions are refitted to the full supplied training data. Method 1 retains the selected predictor coordinates, while method 2 evaluates their signed synthetic index; the components can therefore represent different regression geometry.

Value

Returns a vector of fitted values for the dependent variable test set for all models.

• "NNS.reg.n.best" returns the optimum "n.best" parameter for the NNS.reg multivariate regression; when all regression points (for classification, all cells) are selected, their number in the final fit. NA for a single predictor in regression, whose univariate NNS.reg fit has no n.best to tune (use cbind(x, x) to search one), and when method does not include 1. "SSE.reg" returns the SSE for the NNS.reg multivariate regression.

• "OBJfn.reg" returns the best obj.fn value of the NNS.reg regression's tuning on the out-of-fold predictions; it is selection-optimized, not an estimate of out-of-sample performance.

• "NNS.dim.red.threshold" returns the coefficient cutoff at which NNS.reg on (IVs.train, DV.train) with the same dim.red.method keeps the tuned number of predictors: the smallest kept coefficient magnitude, or 0 when every predictor is kept. Ties at the cutoff keep every tied predictor. For classification it is one number when every class index shares the cutoff, as two-class indices always do, and otherwise one cutoff per class, which NNS.reg accepts as threshold. NA when method does not include 2.

• "NNS.dim.red.variables" returns the names of the predictors carried by the final dimension reduction regression, ranked by absolute coefficient. With (stack = TRUE) these are also the only predictors used by the NNS.reg multivariate regression, so they are exactly the variables behind "stack". NULL when method does not include 2.

• "NNS.dim.red.coefficients" returns the named final dimension reduction coefficients for every encoded predictor column (zero for predictors not selected). NULL when method does not include 2.

• "OBJfn.dim.red" returns the best obj.fn value of the NNS.reg dimension reduction regression's tuning on the out-of-fold predictions; it is selection-optimized, not an estimate of out-of-sample performance.

• "probability.threshold" returns the optimum probability threshold for classification, else 0.5 when set to FALSE.

• "reg" returns NNS.reg output.

• "reg.pred.int" returns the prediction intervals for the regression output.

• "dim.red" returns NNS.reg dimension reduction regression output.

• "dim.red.pred.int" returns the prediction intervals for the dimension reduction regression output.

• "stack" returns the output of the stacked model.

• "pred.int" returns the prediction intervals for the stacked model.

• "weights" returns the weights of "reg" and "dim.red" in "stack". For classification they are proportional to the squared "OBJfn.reg" and "OBJfn.dim.red" (inverse squares when objective = "min"); for regression the weight is selected by obj.fn on the out-of-fold predictions of the blend.

Note

• Incorporate any objective function from external packages (such as Metrics::mape) via NNS.stack(..., obj.fn = expression(Metrics::mape(actual, predicted)), objective = "min")

• Like a logistic regression, the (type = "CLASS") setting is not necessary for target variable of two classes e.g. [0, 1]. Numeric class values are returned on their original scale; factor and character responses use codes with the returned class.levels mapping.

• Missing data should be handled prior as well using na.omit or complete.cases on the full dataset.

Author(s)

Fred Viole, OVVO Financial Systems

References

Viole, F. (2016) "Classification Using NNS Clustering Analysis" doi:10.2139/ssrn.2864711

Examples

 ## Using 'iris' dataset with a stratified test set of ten rows per species
 ## (rows 141:150 alone are all virginica).
 ## Not run: 
 test.set <- c(41:50, 91:100, 141:150)
 NNS.stack(iris[-test.set, 1:4], iris[-test.set, 5], IVs.test = iris[test.set, 1:4],
 type = "CLASS", balance = TRUE)

 ## Using 'iris' dataset to determine [n.best] and [threshold] with no test set.
 NNS.stack(iris[ , 1:4], iris[ , 5], type = "CLASS")
 
## End(Not run)

Partial Moment Matrix

Description

Builds a list containing CUPM, DUPM, DLPM, CLPM and the overall covariance matrix.

Usage

PM.matrix(LPM_degree, UPM_degree, target, variable, pop_adj, norm = FALSE)

Arguments

Details

Partial Moment Matrix

Value

A list: $cupm, $dupm, $dlpm, $clpm, $cov.matrix.

Note

When norm = TRUE, each cell (i,j) of the four quadrant matrices is normalized so that their sum equals 1. In this case, $cov.matrix is computed as $cupm + $clpm - $dupm - $dlpm, yielding a dimensionless, signed dependence measure bounded between -1 and 1. This representation discards magnitude information and is therefore a lossy nonlinear correlation matrix. A higher fidelity nonlinear correlation matrix is available via the NNS.dep function.

Examples

set.seed(123)
A <- cbind(rnorm(100), rnorm(100), rnorm(100))

# Uses norm = FALSE by default
PM.matrix(1, 1, target = NULL, variable = A, pop_adj = TRUE)

# Enable normalization
PM.matrix(1, 1, target = NULL, variable = A, pop_adj = TRUE, norm = TRUE)

# Use 0's for targets
PM.matrix(1, 1, target = rep(0, ncol(A)), variable = A, pop_adj = TRUE)        

# Use variable medians as targets
PM.matrix(1, 1, target = apply(A, 2, "median"), variable = A, pop_adj = TRUE)  

Upper Partial Moment

Description

This function generates a univariate upper partial moment for any degree or target.

Usage

UPM(degree, target, variable, excess_ret = FALSE)

Arguments

Value

UPM of variable

Author(s)

Fred Viole, OVVO Financial Systems

References

Viole, F. and Nawrocki, D. (2013) "Nonlinear Nonparametric Statistics: Using Partial Moments" (ISBN: 1490523995, 2nd edition: https://ovvo-financial.github.io/NNS/book/)

Examples

set.seed(123)
x <- rnorm(100)
UPM(0, mean(x), x)

UPM VaR

Description

Generates an upside value at risk (VaR) quantile based on the Upper Partial Moment ratio.

Usage

UPM.VaR(percentile, degree, x)

Arguments

Value

Returns the type-7 empirical quantile (degree = 0), whose strict or inclusive sample tail fraction may differ from percentile because of interpolation or ties, or the threshold with percentile of the directional deviation area above it (degree > 0).

Author(s)

Fred Viole, OVVO Financial Systems

References

Viole, F. and Nawrocki, D. (2013) "Nonlinear Nonparametric Statistics: Using Partial Moments" (ISBN: 1490523995, 2nd edition: https://ovvo-financial.github.io/NNS/book/)

Examples

set.seed(123)
x <- rnorm(100)

## For 5th percentile, right-tail
UPM.VaR(0.05, 0, x)

Upper Partial Moment Ratio

Description

This function generates a standardized univariate upper partial moment of any non‑negative degree for a given target.

Usage

UPM.ratio(degree, target, variable)

Arguments

Value

Numeric vector of standardized upper partial moments. For degree > 0, a target at which every observation equals the target (0/0) returns the degree = 0 ratio.

Author(s)

Fred Viole, OVVO Financial Systems

References

Viole, F. & Nawrocki, D. (2013) *Nonlinear Nonparametric Statistics: Using Partial Moments* (ISBN:1490523995)

Examples

  set.seed(123)
  x <- rnorm(100)
  UPM.ratio(0, mean(x), x)
## Not run: 
  plot(sort(x), UPM.ratio(0, sort(x), x))

## End(Not run)

Partial Derivative dy/d_[wrt]

Description

Returns the numerical partial derivative of y with respect to [wrt] any regressor for a point of interest. Finite difference method is used with NNS.reg estimates as f(x + h) and f(x - h) values.

Usage

dy.d_(x, y, wrt, eval.points = "obs", mixed = FALSE, messages = TRUE)

Arguments

Details

Derivatives are finite-difference summaries of the fitted NNS.reg surface, averaged over four local probability windows derived from degree-1 partial-moment quantiles. Window sizes depend on the number of observations; they are capped before constructing a local coordinate half-width. All evaluation points and perturbed coordinates must stay inside the observed coordinate ranges. Interior unequal spacings use polynomial finite-difference weights; support endpoints use one-sided three-point formulas. This avoids averaging artificial full-support extrapolation bands into a local derivative.

The coordinate-range check does not establish that every perturbed tuple lies in a densely observed part of the joint support. Sparse cells, neighbour changes, fitted-surface bias, and correlated predictors can affect the result, including at the boundary. These are numerical derivatives of an estimated surface, with no universal recovery or coverage guarantee. A two-valued coordinate returns its finite contrast divided by the coordinate difference and an undefined (NA) second derivative. Constant coordinates return NA. Mixed derivatives require two predictors and explicit matrix evaluation points.

Value

Returns column-wise matrix of wrt regressors:

• dy.d_(...)[, wrt]$First the 1st derivative

• dy.d_(...)[, wrt]$Second the 2nd derivative

• dy.d_(...)[, wrt]$Mixed the mixed derivative (for two independent variables only).

Note

Binary regressors provide a finite contrast, not an identified continuous derivative between the two levels.

Author(s)

Fred Viole, OVVO Financial Systems

References

Viole, F. and Nawrocki, D. (2013) "Nonlinear Nonparametric Statistics: Using Partial Moments" (ISBN: 1490523995, 2nd edition: https://ovvo-financial.github.io/NNS/book/)

Vinod, H. and Viole, F. (2020) "Comparing Old and New Partial Derivative Estimates from Nonlinear Nonparametric Regressions" doi:10.2139/ssrn.3681104

Examples

## Not run: 
set.seed(123) ; x_1 <- runif(1000) ; x_2 <- runif(1000) ; y <- x_1 ^ 2 * x_2 ^ 2
B <- cbind(x_1, x_2)

## To find derivatives of y wrt 1st regressor for specific points of both regressors
dy.d_(B, y, wrt = 1, eval.points = t(c(.5, median(x_2))))

## To find average partial derivative of y wrt 1st regressor,
## only supply 1 value in [eval.points], or a vector of [eval.points]:
dy.d_(B, y, wrt = 1, eval.points = .5)

dy.d_(B, y, wrt = 1, eval.points = fivenum(B[,1]))


## To find average partial derivative of y wrt 1st regressor,
## for every observation of 1st regressor:
apd <- dy.d_(B, y, wrt = 1, eval.points = "apd")
plot(B[,1], apd[,1]$First)

## Central 95% range across estimated partial derivatives (descriptive)
### Lower CI
LPM.VaR(.025, 0, apd[,1]$First)

### Upper CI
UPM.VaR(.025, 0, apd[,1]$First)

## End(Not run)

Partial Derivative dy/dx

Description

Returns the numerical partial derivative of y wrt x for a point of interest.

Usage

dy.dx(x, y, eval.point = NULL)

Arguments

Details

eval.point = "overall" returns the mean of the gradient column of NNS.reg(x, y)$Fitted.xy. Each observation receives the slope of the unsmoothed regression segment that contains it, so the result is an observation-weighted average of segment slopes, not an average of smoothed derivatives. Very short segments between nearly coincident regression points can have extreme slopes; mean(dy.dx(x, y, eval.point = x)$first.derivative) averages the smoothed pointwise estimates instead.

Numeric evaluation points use central differences of smoothed NNS.reg estimates over five steps from 2 to floor(sqrt(n)) typical spacings of x, clipped to the observed range. second.derivative is a second difference of those estimates, and second differences amplify noise: for y = x^2 plus noise with an R-squared near 0.99 and n = 400, estimates of the true value 2 at three interior points had a root mean squared error of about 5, and about one in five had the wrong sign. Treat it as a descriptive diagnostic on noisy data.

Value

Returns a data.frame of eval.point along with both 1st and 2nd derivative.

Author(s)

Fred Viole, OVVO Financial Systems

References

Viole, F. and Nawrocki, D. (2013) "Nonlinear Nonparametric Statistics: Using Partial Moments" (ISBN: 1490523995, 2nd edition: https://ovvo-financial.github.io/NNS/book/)

Vinod, H. and Viole, F. (2017) "Nonparametric Regression Using Clusters" doi:10.1007/s10614-017-9713-5

Examples

## Not run: 
x <- seq(0, 2 * pi, pi / 100) ; y <- sin(x)
dy.dx(x, y, eval.point = 1.75)

# First derivative
dy.dx(x, y, eval.point = 1.75)$first.derivative

# Second derivative
dy.dx(x, y, eval.point = 1.75)$second.derivative

# Vector of derivatives
dy.dx(x, y, eval.point = c(1.75, 2.5))

## End(Not run)