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.progress.interval.sec (numeric): package-wide minimum elapsed time between visible progress heartbeats. The default is 2.0 seconds. When set, this canonical option takes precedence over the older surface-specific interval options.
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 when np.progress.interval.sec is unset. Default is 2.0.
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". Conditional-distribution generalized-neighbor bandwidth selection admits explicit TRUE for second-order Epanechnikov and uniform kernels without boundary normalization. The same explicit selection is available for local-constant and linear/polynomial conditional density/distribution fitting from generalized-neighbor CVLS bandwidth objects. Linear/polynomial adaptive-neighbor fitting reuses bounded evaluation-tree batches. Automatic-selection policies are unchanged. The same explicit compact-kernel selection is available for linear and polynomial regression generalized- and adaptive-neighbor cv.ls/cv.aic bandwidth selection, and for generalized-neighbor linear/polynomial regression fitting and its hat/apply operators. Adaptive-neighbor linear/polynomial regression fitting also supports this explicit selection, using donor-radius evaluation-tree batches. GNN fitting may use dense accumulation when an exact support certificate proves that tree traversal cannot prune any donor; kernel weights remain varying, and no occupancy or conditioning threshold is used. Fixed-bandwidth regression fitting and regression automatic-selection policies are unchanged. Tree and dense accumulation can differ numerically on nearly singular local-polynomial designs; enabling trees does not change the basis, ridge or rank policies.
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. Accelerated and portable paths may use different math-library kernels or summation orders, so platform or option comparisons should use numerical tolerances; reserve exact equality for controlled runs using the same acceleration setting.

Search and Objective Caching

np.objective.cache (logical): enables package-side evaluation caching for eligible repeated 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. Eligible continuous npscoefbw and npindexbw routes also use package-side caches around their family-native R optim evaluations. Set options(np.objective.cache = FALSE) to force repeated eligible candidates through the evaluator for diagnostic timing comparisons. Each native Powell-side cache has an independent 64 MiB peak workspace ceiling, including replacement storage during growth. If the ceiling or an allocation prevents growth, existing entries remain available and the selected search continues without inserting new entries; bandwidth cache diagnostics report this through allocation.failed. 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, R-optim, 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 ...
} # }