Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 5 additions & 3 deletions CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -13,16 +13,18 @@ set(NNSCORE_BUILD_TESTS OFF CACHE BOOL "Build NNS-core tests" FORCE)
set(NNSCORE_BUILD_PYTHON OFF CACHE BOOL "Build NNS-core Python bindings" FORCE)
add_subdirectory(extern/NNS-core)

# Preserve the accepted NNS-core vendor tree; explicitly overlay the two
# R14 central-tendency kernels that its R13.3 snapshot does not yet supply.
# Preserve the accepted NNS-core vendor tree; explicitly overlay the R14
# central-tendency kernels that its R13.3 snapshot does not yet supply, and the
# multivariate prediction kernel with R's own nmath densities.
get_target_property(NNS_CORE_SOURCES nnscore SOURCES)
set(NNS_R14_CORE_SOURCES "")
foreach(source IN LISTS NNS_CORE_SOURCES)
if(NOT source STREQUAL "src/central_tendencies.cpp")
if(NOT source STREQUAL "src/central_tendencies.cpp" AND NOT source STREQUAL "src/mreg_predict.cpp")
list(APPEND NNS_R14_CORE_SOURCES "${CMAKE_CURRENT_SOURCE_DIR}/extern/NNS-core/${source}")
endif()
endforeach()
list(APPEND NNS_R14_CORE_SOURCES "${CMAKE_CURRENT_SOURCE_DIR}/src/nns/_r14_central_tendencies.cpp")
list(APPEND NNS_R14_CORE_SOURCES "${CMAKE_CURRENT_SOURCE_DIR}/src/nns/_r14_mreg_predict.cpp")
set_property(TARGET nnscore PROPERTY SOURCES "${NNS_R14_CORE_SOURCES}")

# The Python extension is a shared object. The vendored NNS-core target builds
Expand Down
12 changes: 6 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
[![License](https://img.shields.io/badge/license-GPL--3.0--only-blue)](https://github.com/OVVO-Financial/NNS-python/blob/main/LICENSE)

`ovvo-nns` brings Nonlinear Nonparametric Statistics to Python as the `nns`
import package. It is a parity-focused port of the R `NNS` 13.0+ package,
import package. It is a parity-focused port of the R `NNS` 14.0 package,
designed for real-world data that violate symmetry, linearity, or
distributional assumptions.

Expand Down Expand Up @@ -125,13 +125,13 @@ uv run python examples/run_all_vignettes.py

## Design boundaries

NNS Python prioritizes stable public behavior from installed R NNS 13.0+, not
private helper parity. The package returns NumPy arrays and plain dictionaries
rather than R `data.table` objects and uses explicit Python errors for unsafe R
coercions.
NNS Python prioritizes stable public behavior from R NNS 14.0, matched to the
last bit where verified (see the parity page), not private helper parity. The
package returns NumPy arrays and plain dictionaries rather than R `data.table`
objects and uses explicit Python errors for unsafe R coercions.

- R is used for parity tests and local cache regeneration, not normal runtime.
- Exact stochastic stream parity is not expected for every randomized path.
- Seeded randomized paths reproduce R's stream: `random_seed = s` matches `set.seed(s)`.
- Factor and class ordering should be supplied explicitly when it matters.
- Classification codes follow the R contract and start at 1.
- Compute functions return values; `plot=True` adds Matplotlib rendering as a
Expand Down
2 changes: 1 addition & 1 deletion docs/api_reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -287,7 +287,7 @@ Detects seasonality and supported modulo structures in a univariate series.

Closest R API: `NNS.ARMA`.

Univariate ARMA-style forecasting surface. Stochastic interval streams use NumPy RNG and are structural or statistical parity targets rather than exact stream parity.
Univariate ARMA-style forecasting surface. Prediction intervals resample the forecast path with `nns_mc`; with `random_seed = s` they are R's after `set.seed(s)`, bit for bit.

#### `nns_arma_optim`

Expand Down
25 changes: 14 additions & 11 deletions docs/api_status.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,19 +43,19 @@ invariant, and property coverage.
| VaR helpers: `lpm_var`, `upm_var` | implemented | high | Used by deterministic confidence and prediction interval paths. |
| Central tendencies: `nns_gravity`, `nns_mode`, `nns_rescale` | implemented | high | Public helper behavior is covered through direct and dependent tests. |
| Dependence and correlation: `nns_dep`, `nns_cor` | implemented | high | Follows installed R bivariate public path; dependence can be below signed correlation magnitude in known R-compatible cases. |
| Copula: `nns_copula` | implemented | high | Bivariate scalar public form is implemented. |
| Causation: `nns_causation`, `causal_matrix` | implemented | medium | Numeric lag paths and `tau="ts"` behavior are covered; some internal asymmetry granularity can differ in regression dimension reduction. |
| Distribution functions: `nns_cdf` | implemented | high | Deterministic non-plotting paths are implemented; plotting is ignored. |
| Distance helpers: `nns_distance`, `nns_distance_bulk` | implemented | high | Numeric and classification conventions follow installed R behavior. |
| Copula: `nns_copula` | implemented | high | Bivariate and any-column matrix forms; R 14's arithmetic to the last bit (long-double `sum`/`prod`/`mean`, `^(1/2)` as `pow`). |
| Causation: `nns_causation`, `causal_matrix` | implemented | high | Pairs, matrices, numeric lags, `tau="ts"`/`"cs"` and the permutation p-values (R's `set.seed` stream via `seed`) match R to the last bit on the live sweeps. |
| Distribution functions: `nns_cdf` | implemented | high | Univariate and multivariate types match R to the last bit (libm `log`, long-double `rowSums`, R's batch kernel, the prefix LPM backend beyond 32 targets); plotting is ignored. |
| Distance helpers: `nns_distance`, `nns_distance_bulk` | implemented | high | R 14's C++ kernels to the last bit, including where tied distances fall and the classification vote. |
| Partitioning: `nns_part` | implemented | high | Returns plain dictionaries/arrays instead of R `data.table` objects. |
| Regression: `nns_reg` | implemented | high | Numeric, class-code, confidence interval, smoothing, dimension-reduction, and factor paths are covered; `point_est` columns are matched by name, categorical/declared levels are honoured. |
| Multivariate regression: `nns_m_reg` | implemented | high | Numeric, class, and raw factor/character predictor paths (`factor_2_dummy=True` by default, as R 13.3) are covered; column names are kept. |
| Regression: `nns_reg` | implemented | high | Numeric, class-code, confidence interval, smoothing (an exact port of R's `smooth.spline`), dimension-reduction, and factor paths match R to the last bit on the live sweeps; `point_est` columns are matched by name, categorical/declared levels are honoured. |
| Multivariate regression: `nns_m_reg` | implemented | high | Numeric, class, and raw factor/character predictor paths (`factor_2_dummy=True` by default, as in R) match R to the last bit; column names are kept. |
| Stack: `nns_stack` | implemented | medium-high | Numeric/class paths, intervals, factor predictors, `ts_test`, and R's seeded CV/balance draws (bit-for-bit) are covered; test columns are matched by name and selection outputs carry predictor names. |
| Boost: `nns_boost` | implemented | medium | Learner trials, epochs, and the final stack match R's seeded stream; feature weights/frequencies are named by column. |
| Seasonality: `nns_seas` | implemented | high | Non-plotting installed-R path is implemented and cached defensively. |
| ARMA and VAR: `nns_arma`, `nns_arma_optim`, `nns_var` | partial | medium | Numeric forecasting and every VAR dimension-reduction path (`cor`, `NNS.dep`, `NNS.caus`, `all`) match R NNS 13.3 exactly on driven multi-variable fixtures, including own-lag weights, `objective="max"`, vector and list `tau`, and interior/trailing missing values. VAR's `relevant_variables` are the regressors the cross-validated dimension reduction threshold keeps, and `multivariate` is `nns_stack(method=1)` (`nns_reg`) on exactly those regressors. Stochastic interval streams are structural/statistical parity only. |
| Bootstrap/Monte Carlo: `nns_meboot`, `nns_mc` | implemented | medium | Deterministic diagnostics are parity-tested; exact stochastic replicate parity with R is not expected. |
| Stochastic dominance/superiority: `fsd`, `ssd`, `tsd`, `.uni` wrappers, `nns_ss`, `nns_sd_cluster`, `sd_efficient_set` | implemented | medium | Public structures and deterministic paths are covered. SD uses exact pure-NumPy prefix-pair kernels plus a degree-1 discrete order-statistic matrix path; R's C++ core remains faster on full finance fixtures. Stochastic intervals use NNS Python RNG. |
| ARMA and VAR: `nns_arma`, `nns_arma_optim`, `nns_var` | implemented | high | Forecasts, `nns_arma_optim` (including its smoothed `nns_reg` paths) and every VAR dimension-reduction path (`cor`, `NNS.dep`, `NNS.caus`, `all`) match R NNS 14.0 to the last bit on the live sweeps, including own-lag weights, `objective="max"`, vector and list `tau`, and interior/trailing missing values. ARMA prediction intervals reproduce R's `set.seed` stream through `random_seed`. VAR's `relevant_variables` are the regressors the cross-validated dimension reduction threshold keeps, and `multivariate` is `nns_stack(method=1)` (`nns_reg`) on exactly those regressors. |
| Bootstrap/Monte Carlo: `nns_meboot`, `nns_mc` | implemented | high | With `random_seed = s` the replicates and summaries are R's after `set.seed(s)`, to the last bit. |
| Stochastic dominance/superiority: `fsd`, `ssd`, `tsd`, `.uni` wrappers, `nns_ss`, `nns_sd_cluster`, `sd_efficient_set` | implemented | high | Contracts, the efficient-set order and the clustering match R 14 to the last bit; `nns_ss` intervals reproduce R's `set.seed` stream through `random_seed`. SD uses exact pure-NumPy prefix-pair kernels plus a degree-1 discrete order-statistic matrix path; R's C++ core remains faster on full finance fixtures. |
| ANOVA: `nns_anova` | implemented | high | Binary, multi-group, pairwise, and degenerate `NaN` conventions are covered. |
| Normalization: `nns_norm` | implemented | high | Numeric matrix path and R's list-of-vectors path are implemented; unequal-length vectors force linear scaling as in R. |
| Categorical helpers: `encode_factor_codes`, `factor_2_dummy`, `factor_2_dummy_fr`, `prepare_factor_predictors` | implemented | high | Explicit `levels=` reproduces R factor ordering. `prepare_factor_predictors(...)` builds a full-rank dummy design; the regression functions encode raw factors themselves and do not need it. |
Expand All @@ -76,8 +76,11 @@ invariant, and property coverage.
- NNS Python uses explicit Python errors for some cases where R silently truncates,
coerces, warns, or returns unusable values. Important divergences are recorded
in `docs/conventions.md`.
- Stochastic exact stream parity is not expected. Stochastic paths use NumPy RNG
and are tested structurally/statistically.
- Seeded stochastic paths reproduce R's random stream: `random_seed = s` gives
R's results after `set.seed(s)` for `nns_meboot`, `nns_mc`, the `nns_ss`
bootstrap bounds, `nns_arma` prediction intervals, the robust and effect-size
`nns_anova` paths, `nns_stack` and `nns_boost`. Without a seed the stream is
seeded from fresh entropy.
- Plotting side effects from R APIs are generally ignored; NNS Python returns data.
- Stochastic-dominance performance work stays pure NumPy for now. The current
implementation mirrors R's sorted-column/prefix-sum algorithm and adds
Expand Down
Loading
Loading