NNS Python

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, designed for real-world data that violate symmetry, linearity, or distributional assumptions.

NNS is built around partial moments, the lower and upper components of variance, and uses them across nonlinear dependence, correlation, causation, regression, classification, forecasting, stochastic dominance, stochastic superiority, Monte Carlo simulation, and numerical differentiation workflows.

NNS was created by Fred Viole as the companion R package to Viole, F. and Nawrocki, D. (2013), Nonlinear Nonparametric Statistics: Using Partial Moments. Book (2nd Edition): https://ovvo-financial.github.io/NNS/book/

Implementation: For a direct quantitative finance implementation of NNS, see OVVO Labs

Package at a glance

Item	Value
Distribution package	`ovvo-nns`
Import package	`nns`
Current version	`1.0.8`
Python	`>=3.11`
Required runtime dependencies	NumPy, SciPy
R required at runtime	No
Native acceleration	Private, optional `nns._nnscore` kernels where available
Public API status	Stable, parity-focused
License	GPL-3.0-only

The public package is Python-native and does not call R at runtime. Some core kernels can use the private _nnscore extension when it is present, while public functions keep Python implementations and explicit fallback behavior.

Install

pip install ovvo-nns

This includes the matplotlib plotting API (nns.plotting); matplotlib is a regular dependency and is imported lazily, so import nns stays light. See the plot parity policy.

Use the package as nns:

import nns

print(nns.__version__)

Source builds use scikit-build-core and nanobind for the optional native extension. Published wheels should be preferred when available.

Quick start

import numpy as np
from nns import lpm, nns_dep, nns_reg, upm

x = np.array([-2.0, -1.0, 0.5, 3.0], dtype=np.float64)

lower = lpm(degree=2, target=0.0, x=x)
upper = upm(degree=2, target=0.0, x=x)

print("lower partial moment:", lower)
print("upper partial moment:", upper)

Measure nonlinear dependence:

import numpy as np
from nns import nns_cor, nns_dep

grid = np.linspace(-2.0, 2.0, 80, dtype=np.float64)
y = grid**2

print("NNS dependence:", nns_dep(grid, y))
print("NNS correlation:", nns_cor(grid, y))

Fit a nonlinear regression and estimate new points:

import numpy as np
from nns import nns_reg

x = np.linspace(-3.0, 3.0, 80, dtype=np.float64)
y = np.sin(x) + 0.2 * x
points = np.array([-1.5, 0.0, 1.5], dtype=np.float64)

fit = nns_reg(x, y, point_est=points, confidence_interval=None)

print("R2:", fit["R2"])
print(np.column_stack((points, fit["Point.est"])))

Forecast a univariate series:

import numpy as np
from nns import nns_arma, nns_seas

t = np.arange(1, 60, dtype=np.float64)
series = 10.0 + np.sin(t / 3.0) + 0.05 * t

seasonality = nns_seas(series, modulo=[3, 4, 6], mod_only=True)
forecast = nns_arma(series, h=3, seasonal_factor=4, method="lin")

print("best seasonal period:", seasonality["best.period"])
print("forecast:", forecast)

Main API areas

Area	Representative functions
Partial moments	`lpm`, `upm`, `lpm_ratio`, `upm_ratio`, `pm_matrix`
Classical moment helpers	`mean_pm`, `var_pm`, `skew_pm`, `kurt_pm`, `nns_moments`
Dependence, correlation, copula	`nns_dep`, `nns_cor`, `nns_copula`
Causation	`nns_causation`, `causal_matrix`
Regression and classification	`nns_reg`, `nns_m_reg`, `nns_stack`, `nns_boost`
Forecasting	`nns_seas`, `nns_arma`, `nns_arma_optim`, `nns_var`
Distribution tools	`nns_cdf`, `nns_anova`, `nns_norm`
Stochastic dominance	`fsd`, `ssd`, `tsd`, `nns_sd_cluster`, `sd_efficient_set`
Stochastic superiority and simulation	`nns_ss`, `nns_mc`, `nns_meboot`
Differentiation	`nns_diff`, `dy_dx`, `dy_d`
Categorical helpers	`encode_factor_codes`, `factor_2_dummy`, `factor_2_dummy_fr`, `prepare_factor_predictors`

See API status for implemented, partial, guarded, and known-gap paths.

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, uses explicit Python errors for several unsafe R coercions, and generally ignores plotting side effects.

Important boundaries:

R is used only for parity tests and local cache regeneration, not normal runtime use.
Stochastic exact stream parity is not expected because Python paths use NumPy random generation.
Factor and class ordering should be passed explicitly when ordering matters.
Direct raw-factor nns_m_reg(..., factor_2_dummy=True) is intentionally guarded. Use prepare_factor_predictors(...) before nns_m_reg(...).
Compute functions still return values, not figures; passing plot=True (where R has it) additionally renders a Matplotlib figure as a side effect via the nns.plotting layer, which is color/element-faithful to R but not pixel-diffed. The plot functions can also be called directly on a computed result.

See behavior conventions for detailed compatibility notes.

Examples

Runnable, self-checking example scripts live in examples/vignettes, mirroring the R NNS vignettes. They are exercised in CI by tests/docs/test_vignette_examples.py, so they stay in sync with the package.

Topic	Script
Overview	`overview.py`
Partial moments	`partial_moments.py`
Descriptive and distributional tools	`descriptive_distributional_tools.py`
Dependence and nonlinear association	`dependence_nonlinear_association.py`
Normalization and rescaling	`normalization_rescaling.py`
Hypothesis, ANOVA and stochastic superiority	`hypothesis_anova_stochastic_superiority.py`
Regression, boosting, stacking and causality	`regression_boosting_stacking_causality.py`
Time series forecasting	`time_series_forecasting.py`
Simulation, bootstrap and risk-neutral	`simulation_bootstrap_riskneutral.py`
Portfolio and stochastic dominance	`portfolio_stochastic_dominance.py`

Run one example:

uv run python examples/vignettes/partial_moments.py

Run all of them with a PASS/FAIL summary:

uv run python examples/run_all_vignettes.py

Documentation

The full documentation site is hosted at https://ovvo-financial.github.io/NNS-python/.

Development

uv sync --group dev
uv run pytest
uv run ruff check .
uv run mypy

Run benchmark tests explicitly:

uv run pytest -n0 -m benchmark --benchmark-enable tests/benchmarks/

The default parity suite is cache-backed and does not require Rscript. Rscript and the R NNS package are needed only when regenerating parity caches or running live R comparison scripts.

Benchmarks

Benchmarks compare selected Python paths with installed R NNS 13.0+ baselines. Many core operations are faster in Python, while some large stochastic-dominance workloads remain faster in R because the R package uses compiled kernels for those paths. See benchmarks for current measurements and commands.

Authors and contributors

Fred Viole — author and maintainer
Roberto Spadim — contributor
Rasheed Khoshnaw — contributor

Attribution

Upstream R package and reference implementation: OVVO-Financial/NNS

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

ovvo_nns-1.0.8.tar.gz (8.7 MB view details)

Uploaded Jun 30, 2026 Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

ovvo_nns-1.0.8-cp314-cp314-win_amd64.whl (463.9 kB view details)

Uploaded Jun 30, 2026 CPython 3.14Windows x86-64

ovvo_nns-1.0.8-cp314-cp314-musllinux_1_2_x86_64.whl (775.4 kB view details)

Uploaded Jun 30, 2026 CPython 3.14musllinux: musl 1.2+ x86-64

ovvo_nns-1.0.8-cp314-cp314-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl (313.2 kB view details)

Uploaded Jun 30, 2026 CPython 3.14manylinux: glibc 2.24+ x86-64manylinux: glibc 2.28+ x86-64

ovvo_nns-1.0.8-cp314-cp314-macosx_11_0_arm64.whl (280.2 kB view details)

Uploaded Jun 30, 2026 CPython 3.14macOS 11.0+ ARM64

ovvo_nns-1.0.8-cp314-cp314-macosx_10_15_x86_64.whl (305.5 kB view details)

Uploaded Jun 30, 2026 CPython 3.14macOS 10.15+ x86-64

ovvo_nns-1.0.8-cp313-cp313-win_amd64.whl (452.7 kB view details)

Uploaded Jun 30, 2026 CPython 3.13Windows x86-64

ovvo_nns-1.0.8-cp313-cp313-musllinux_1_2_x86_64.whl (775.3 kB view details)

Uploaded Jun 30, 2026 CPython 3.13musllinux: musl 1.2+ x86-64

ovvo_nns-1.0.8-cp313-cp313-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl (313.1 kB view details)

Uploaded Jun 30, 2026 CPython 3.13manylinux: glibc 2.24+ x86-64manylinux: glibc 2.28+ x86-64

ovvo_nns-1.0.8-cp313-cp313-macosx_11_0_arm64.whl (280.2 kB view details)

Uploaded Jun 30, 2026 CPython 3.13macOS 11.0+ ARM64

ovvo_nns-1.0.8-cp313-cp313-macosx_10_14_x86_64.whl (305.4 kB view details)

Uploaded Jun 30, 2026 CPython 3.13macOS 10.14+ x86-64

ovvo_nns-1.0.8-cp312-cp312-win_amd64.whl (452.8 kB view details)

Uploaded Jun 30, 2026 CPython 3.12Windows x86-64

ovvo_nns-1.0.8-cp312-cp312-musllinux_1_2_x86_64.whl (775.3 kB view details)

Uploaded Jun 30, 2026 CPython 3.12musllinux: musl 1.2+ x86-64

ovvo_nns-1.0.8-cp312-cp312-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl (313.1 kB view details)

Uploaded Jun 30, 2026 CPython 3.12manylinux: glibc 2.24+ x86-64manylinux: glibc 2.28+ x86-64

ovvo_nns-1.0.8-cp312-cp312-macosx_11_0_arm64.whl (280.2 kB view details)

Uploaded Jun 30, 2026 CPython 3.12macOS 11.0+ ARM64

ovvo_nns-1.0.8-cp312-cp312-macosx_10_14_x86_64.whl (305.4 kB view details)

Uploaded Jun 30, 2026 CPython 3.12macOS 10.14+ x86-64

ovvo_nns-1.0.8-cp311-cp311-win_amd64.whl (453.7 kB view details)

Uploaded Jun 30, 2026 CPython 3.11Windows x86-64

ovvo_nns-1.0.8-cp311-cp311-musllinux_1_2_x86_64.whl (776.3 kB view details)

Uploaded Jun 30, 2026 CPython 3.11musllinux: musl 1.2+ x86-64

ovvo_nns-1.0.8-cp311-cp311-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl (314.3 kB view details)

Uploaded Jun 30, 2026 CPython 3.11manylinux: glibc 2.24+ x86-64manylinux: glibc 2.28+ x86-64

ovvo_nns-1.0.8-cp311-cp311-macosx_11_0_arm64.whl (281.2 kB view details)

Uploaded Jun 30, 2026 CPython 3.11macOS 11.0+ ARM64

ovvo_nns-1.0.8-cp311-cp311-macosx_10_14_x86_64.whl (306.4 kB view details)

Uploaded Jun 30, 2026 CPython 3.11macOS 10.14+ x86-64

File details

Details for the file ovvo_nns-1.0.8.tar.gz.

File metadata

Download URL: ovvo_nns-1.0.8.tar.gz
Upload date: Jun 30, 2026
Size: 8.7 MB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for ovvo_nns-1.0.8.tar.gz
Algorithm	Hash digest
SHA256	`3a834ab90d5703f100b6032c52403f5a8421e1e3a5048791d93e04ae3677bfba`
MD5	`f4969cd667155732b00160e9928d229d`
BLAKE2b-256	`34c35d131c64f39fbea09e55c80d0db26c08fd259efd0d580dbfeed7addb936e`

Algorithm	Hash digest
SHA256	`11826f2451ae9fad4f677bc5787bb8abc3344f131446324d628ac15424445c1c`
MD5	`d04cd7a69396a5a935736d98d4999031`
BLAKE2b-256	`56367dbcd3fa4cbecf70730d4d3d5008b41a55a3e99fcfad0878d319cac8bdfe`

Algorithm	Hash digest
SHA256	`c88d47035f357da820f2b0a4913e95f3b089c9e479e60d4391ba5778923ec60a`
MD5	`223efef7adf61bc117e5958098481919`
BLAKE2b-256	`ef55e03543374986f4785526084d2e66241fc7332602748e2e1f384faf40a8ca`

Algorithm	Hash digest
SHA256	`09763c5b7edd0652139ecb00086c12c2b15d2c84eea7d38df5042f1b5d874cf0`
MD5	`7209357d5bd1b710ae61a2a03a78000c`
BLAKE2b-256	`45c921577664901033c1822b38707bb3eac7c3bb6b874cc56116a6d35978dd51`

Algorithm	Hash digest
SHA256	`6745a142e7fb7249c2c65548a6b1cd871d754d4b081df609c9a672f86cef016d`
MD5	`7e2812e3419d5ac1eb32f8d12d7a914c`
BLAKE2b-256	`9f58e4981503f92d9d98394da26bcad73e6ae1441f9da27b4961bfee5a32e607`

Algorithm	Hash digest
SHA256	`9f37f5776fc4c9e5355695e2bcb8ac2aaa65fea7f4b255ffce8f379507a096a2`
MD5	`434e1e0ccf7c76c8771dafe8777b47f7`
BLAKE2b-256	`e66ec23801f52c2d304c098e1770f9d43ea6552659f5d0f0611a4b059c260e03`

Algorithm	Hash digest
SHA256	`c75c853191e92e33bcf8145f330639f28e0c38d4c34c2480c002e8d3ba7c3cfd`
MD5	`6aa1d608713d4d95b9f6146cefe734d1`
BLAKE2b-256	`ffb7d148306a39f7ad39290e4e42ba5e5d1c3dfa9bb7e783f993f78a75b71e49`

Algorithm	Hash digest
SHA256	`617ffbc17c371c87724d4616ad09a4b3d5233c2b9d9e39d275171c4a8c07036f`
MD5	`681c78af7abf6204752ff90447a23c6c`
BLAKE2b-256	`41fc0be472695dca499d5e54f46b12479f30c1293bfe01b7af7062da7ac8bbcd`

Algorithm	Hash digest
SHA256	`cfad852cca622015c0bae611b37091646949dfb691d79b3b5966f1fe4695596f`
MD5	`6a87b2a6d6d9ec1724c985692f822a83`
BLAKE2b-256	`463a170cf2877be8b13758ab9f801329d89e8de00b11d232bb812c4c2aa95985`

Algorithm	Hash digest
SHA256	`8eaabb2f5f08254105701475e7b44e6cb1ee38683e43d47670af28509502cd15`
MD5	`18670f25957f4533d8390ae8cf012d21`
BLAKE2b-256	`14e9641688a83f40966bb18df918d28b0d7f917d7538096b078839c9a9025e46`

Algorithm	Hash digest
SHA256	`7b78ddb817c8fba6767c21dc007fbbf5be295d65faa4db8aad5225733851c065`
MD5	`85b132eb387a89076e8d2201fd9671ce`
BLAKE2b-256	`0e45c12577d51b9605eed89aa60c8548f56a6f18cacbe34519fe52ae4c603a26`

Algorithm	Hash digest
SHA256	`d9d7f0f89122603c75da3e045ee8869bf26d5baf9707edd979cc1784e2c446b2`
MD5	`f18ef9c52586bc345783933fededdbfb`
BLAKE2b-256	`3dc5402122125c206c92a07dde21b437a0386ca3022cd4159003d996f1959a50`

Algorithm	Hash digest
SHA256	`6c263b30e6aa8fae6737741e9208e01f13d4ea82f176e74867c5d5872ce2b781`
MD5	`7e59e4bf870976c7bab36afbb81d9d12`
BLAKE2b-256	`eb53ef2f550eca06637fa76f2caf4e76b7bdc9a0eb6ccc854dc4aea80282c6d9`

Algorithm	Hash digest
SHA256	`0219924a9b078bcb701204ff70f3a623b4ee726f1b000e009cae8c7b4725824c`
MD5	`3fd9be87babadf51e34a41366fb0cf4f`
BLAKE2b-256	`9c2c3cf301b5bfb8168d21a505ccfcde35d79513525ded00d74f80aa0de69ef4`

Algorithm	Hash digest
SHA256	`eff5635d313f56f0bc79f39887de9b6560feb96cfcf196d850aad0a39887362c`
MD5	`b1f29b15567285456692f3ab22467011`
BLAKE2b-256	`9b18c84d4582863a6d0a572dc13a73a9601017bfab4da8633f42847103ac6adf`

Algorithm	Hash digest
SHA256	`ec179ee426a220b77edba703c642a63a0d7963226e7a27bb212a091c200c9d29`
MD5	`47b2315977d2cf45889141fdec1f4900`
BLAKE2b-256	`55c0b98f3a8f07dcbce4a380d52949cc17a5ce7c95ac5727683b657902107a86`

Algorithm	Hash digest
SHA256	`809e03c70fecbb63b6795619b8807e9fb3f708972199ba4b1fcae817ca18749c`
MD5	`29a2771222d9c004a2693a851d4cb0dc`
BLAKE2b-256	`4670c7f3e200e79551e812f18e5e9721a7ef462a2e47279911ef17f4166890f2`

Algorithm	Hash digest
SHA256	`19c5f9e796b485593fc7332bd39dd5afc93b939a83fcf8f519929a5279f111d4`
MD5	`d1ffd0a635119f20c7f2f6b971696ece`
BLAKE2b-256	`992ca035b5c39403987c03163ab73dc00bdaa6b6e246f946a0ce574153ba4f7d`

Algorithm	Hash digest
SHA256	`fce5cfcf23ebde9b46ac5cf1e13b6ffd346ad640c3115554705bca937b4929da`
MD5	`334268c31506519ea9e3adec2efb37ae`
BLAKE2b-256	`4072c9b88d50ef89f51ad05278ae19800182ad89002de1d5cb959ce8e21a05e0`

Algorithm	Hash digest
SHA256	`6c7bc7a1b9f8407bb5101ca46438cdf1f5a7d3c8b1657476d70770e94959998e`
MD5	`45c62ca45e0b55bbf7a11374cb5ec232`
BLAKE2b-256	`2a76a470386d682bae375d17e2f0ed36ddb3d28566b273d11c3e6599ca4ec143`

Algorithm	Hash digest
SHA256	`cb4955e2ab108e53349e1eff8dff7fa0becdfe68d683f6fe05c81d86680fd84d`
MD5	`ffbc9c83e767ca9bb957aa71c2d05607`
BLAKE2b-256	`62ef061e5a81b07e5ce8976fecc0a9d756748cf25f716be56b3eda2a722ee930`

ovvo-nns 1.0.8

NNS Python

Package at a glance

Install

Quick start

Main API areas

Design boundaries

Examples

Documentation

Development

Benchmarks

Authors and contributors

Attribution

Project links

Key dates

1 maintainer

Credits

GitHub Statistics

License expression

Requires

Tags

Classifiers

Download files

Source Distribution

Built Distributions

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes