Global Package Options for np

Global options controlling selected computational and display behavior for the np package.

Details

Documentation guide: see np.kernels for kernels and plot for plotting options.

The following options are recognized by np.

Output and Plot Progress

np.messages (logical): controls console/progress output. Default is TRUE.
np.plot.progress (logical): controls bounded plot/bootstrap progress heartbeats. Default is TRUE.
np.plot.progress.start.grace.sec (numeric): delay before the first plot/bootstrap progress line is shown. Default is 0.75.
np.plot.progress.interval.sec (numeric): minimum elapsed time between plot/bootstrap heartbeat lines once progress reporting has started. Default is 0.5.
np.plot.progress.max.intermediate (integer): maximum number of mid-run plot/bootstrap heartbeat lines emitted between the initial start notice and final completion line. Default is 3.

Kernel Routing and Acceleration

np.tree (logical or "auto"): controls kd-tree acceleration for continuous variables. TRUE forces eligible tree routes on, FALSE disables them, and "auto" enables trees only when active continuous kernels are bounded support ("epanechnikov" or "uniform"). Default is "auto".
np.categorical.compress (logical): enables exact unique-profile compression for eligible all-categorical routes. This is distinct from np.tree: no continuous kd-tree is requested merely because categorical compression is enabled. The default is TRUE. Set options(np.categorical.compress = FALSE, np.tree = FALSE) to force the historical dense categorical route for debugging or timing comparisons.
np.macMseries.accelerate (logical or "auto"): controls macOS arm64 Accelerate/vDSP/vForce fast paths for eligible Gaussian-kernel and weighted-reduction computations. "auto" enables these paths only when they were compiled for macOS arm64 with Accelerate support; TRUE requests them when available; and FALSE disables them exactly. Default is "auto". On non-macOS, non-arm64, or non-Accelerate builds, this option falls back to the ordinary portable code path.

Search and Objective Caching

np.objective.cache (logical): enables package-side objective caching for repeated Powell bandwidth-search candidates. For all Powell routes using the shared C optimizer wrapper, exact repeated raw candidate vectors within one bandwidth solve reuse the previous objective value, including repeated candidates reached by later Powell restarts. For eligible continuous-only generalized/adaptive nearest-neighbor routes, this also enables the existing integer nearest-neighbor objective cache. Mixed continuous/categorical rows use only the exact full-candidate cache, so categorical smoothing parameters remain part of the cache key. Default is TRUE. Set options(np.objective.cache = FALSE) to force repeated Powell candidates through the objective evaluator for diagnostic timing comparisons. MADS/NOMAD solver caching is separate and is not controlled by this option, and the saturated extended-NN distance cache is governed by np.extendednn. Bandwidth summaries keep Number of Function Evaluations as the established cumulative optimizer evaluation count and report NOMAD, Powell, nearest-neighbor, degree-search, guarded-evaluation, and other fast-CV diagnostics on separate lines when the corresponding counters are available. These diagnostics describe their own optimizer/cache layer and are not intended to decompose the function-evaluation count arithmetically.
np.nomad.degree.start.policy (character): controls automatic polynomial-degree starting values for NOMAD local-polynomial searches when degree.start is not supplied. The default, "low_first_full_random", uses degree.min for the first start and draws later starts over the full user-specified degree.min/degree.max range. Other accepted values are "mid_first_full_random", "anchor_then_random", "spread_then_random", and "random_full_only". Explicit degree.start values remain the first start.

Bandwidth Shortcuts

np.largeh (logical): enables continuous large-\(h\) shortcut evaluations. Default is TRUE. Set options(np.largeh = FALSE) to keep tree/dense routing unchanged while forcing continuous large-bandwidth objective rows through the ordinary kernel-summation machinery for diagnostic timing comparisons.
np.extendednn (logical): enables extended nearest-neighbor bandwidth search and manually supplied nearest-neighbor bandwidths above the ordinary \(n-1\) neighbor-count limit for eligible generalized/adaptive nearest-neighbor routes. When TRUE, a nearest-neighbor search parameter above \(n-1\) scales the saturated nearest-neighbor bandwidth. Default is TRUE.
np.largeh.rel.tol (numeric): relative tolerance used by the continuous large-\(h\) shortcut. When all standardized distances for a continuous predictor are sufficiently close to zero, the corresponding kernel factor is approximated by \(K(0)\) to reduce repeated kernel evaluations. Default is 1e-3. Valid range is (0, 0.1).
np.largelambda (logical): enables discrete near-upper bandwidth shortcut evaluations. Default is TRUE. Set options(np.largelambda = FALSE) to keep categorical routing unchanged while forcing near-upper discrete bandwidth rows through the ordinary category-comparison machinery for diagnostic timing comparisons.
np.disc.upper.rel.tol (numeric): relative tolerance used by the discrete upper-bound shortcut for bandwidths near their feasible upper bounds. The near-upper check is applied relative to each kernel's own feasible upper bound (e.g., Aitchison-Aitken depends on category cardinality), with a tiny machine-precision floor for numerical robustness. When same/different-category kernel values are numerically close, the corresponding discrete kernel factor is treated as constant to reduce repeated category comparisons. Default is 1e-2. Valid range is (0, 0.5).

Plot Layout

plot.par.mfrow (logical): used by plot to determine whether plotting layout is automatically managed via par(mfrow=...). If NULL (default behavior), np uses its internal plotting defaults.

Option values can be set globally via options and restored with on.exit in scripts/functions for reproducibility.

Author

Jeffrey S. Racine racinej@mcmaster.ca

Examples

if (FALSE) { # \dontrun{
old <- options(
  np.tree = "auto",
  np.categorical.compress = TRUE,
  np.macMseries.accelerate = "auto",
  np.objective.cache = TRUE,
  np.largeh = TRUE,
  np.extendednn = TRUE,
  np.largelambda = TRUE,
  np.messages = FALSE,
  np.largeh.rel.tol = 1e-3,
  np.disc.upper.rel.tol = 1e-2
)
on.exit(options(old), add = TRUE)

## ... run bandwidth selection / estimation ...
} # }