Skip to content
Closed
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
1 change: 1 addition & 0 deletions CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@ 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")
list(APPEND NNS_R14_CORE_SOURCES "${CMAKE_CURRENT_SOURCE_DIR}/src/nns/_r14_seas.cpp")
list(APPEND NNS_R14_CORE_SOURCES "${CMAKE_CURRENT_SOURCE_DIR}/src/nns/_r14_partial_moments.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
20 changes: 10 additions & 10 deletions docs/conventions.md
Original file line number Diff line number Diff line change
Expand Up @@ -69,12 +69,11 @@ check the same rules.

## PM Matrix Target Defaults

R `PM.matrix` uses column means when `target` is `NULL` or any non-numeric value.
NNS Python accepts `None` and `"mean"` for this behavior, with Rcpp's `colMeans`
arithmetic (a row-by-row double sum divided by the row count). NNS Python also broadcasts a
scalar numeric target across all variables; R requires callers to pass an
explicit vector such as `rep(0, ncol(variable))`. Target vectors whose length
does not match the number of variables raise `ValueError`.
Use `None`, `"mean"` or `"means"` for column means. Python and R sum each column
row by row in double precision and divide by the row count. Numeric vectors and
matrices supply one target per variable column. R reads matrix targets in column
order, and Python does the same. Python also broadcasts a numeric scalar across
columns. In R, pass an explicit vector such as `rep(0, ncol(variable))`.

## Mode Default Divergence From R

Expand All @@ -94,6 +93,8 @@ multiplication, fractional degrees by libm `pow`, double sums accumulated
observation by observation and scaled by `1 / n`. `pm_matrix` fills the upper
triangle and mirrors it (CUPM, CLPM and the covariance plainly, DUPM and DLPM
crossed), normalising each cell by `CUPM + DUPM + DLPM + CLPM` in that order.
A normalised n-dimensional moment or matrix cell with an exactly zero total takes
its degree-zero value. In a joint survival calculation, ties are excluded.
`nns_moments` is R 14's `NNS.moments`: deviations from R's `mean()`,
`mean(z^3)` and `mean(z^4)` with R's `^`, and the variance raised by `^1.5`.

Expand Down Expand Up @@ -139,10 +140,9 @@ unrecognised `type` warns (and `fsd` then runs its continuous branch, while
returns the column names), and a vector is one column, as with R's `as.matrix`.
Inputs are checked in R's order and with R's messages: missing values raise
"You have some missing values, please address.", empty samples "Each sample
needs at least one observation.". Like R, the `.uni` tests, `sd_efficient_set`
and `nns_sd_cluster` accept infinite values and compare them as R's C++ test
does, while `fsd`, `ssd` and `tsd` reject them (R first evaluates the plotted
partial-moment curves, which check `x` and then the threshold grid).
needs at least one observation.". Only discrete first-order comparisons accept infinite values in
the `.uni` tests, efficient sets and clustering. The top-level `fsd`, `ssd` and
`tsd` check the partial-moment curves first and reject infinite values.
`nns_sd_cluster` validates its data in the first efficient-set search, as R
does, so a matrix with no more than `min_cluster` columns comes back as one
cluster unchecked, and `min_cluster` is compared as a real number (`1.5` merges
Expand Down
21 changes: 21 additions & 0 deletions src/nns/_helpers.py
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,27 @@
from nns._native import external_stacklevel, native_fn


def _is_factor(value: object) -> bool:
return getattr(getattr(value, "dtype", None), "name", None) == "category"


def _has_factor_column(value: object) -> bool:
return hasattr(value, "columns") and any(
dtype == "category" for dtype in getattr(value, "dtypes", ())
)


def _numeric_matrix(data: object) -> NDArray[np.float64]:
if _has_factor_column(data):
raise ValueError("Not compatible with requested type: [type=character; target=double].")
return np.asarray(data, dtype=np.float64)


def _reject_factor(value: object, name: str) -> None:
if _is_factor(value):
raise ValueError(f"{name} must be numeric, not a factor.")


def _warn_unsupported(**was_set: bool) -> None:
"""Warn about R-compatibility parameters that have no effect in NNS Python.

Expand Down
1 change: 1 addition & 0 deletions src/nns/_nnscore.pyi
Original file line number Diff line number Diff line change
Expand Up @@ -167,6 +167,7 @@ def clpm_nd_batch(
n_targets: int,
degree: float,
norm: bool,
strict: bool = False,
) -> Sequence[float]: ...
def pm_matrix(
degree_lpm: float,
Expand Down
22 changes: 14 additions & 8 deletions src/nns/_nnscore_bindings.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@

#include "nns/nns.hpp"
#include "_r14_dependence.hpp"
#include "_r14_partial_moments.hpp"
#include "_r14_seas.hpp"

namespace nb = nanobind;
Expand Down Expand Up @@ -180,7 +181,7 @@ nb::dict pm_matrix_dict(double degree_lpm,
nns::PMMatrixResult result;
{
nb::gil_scoped_release release;
result = nns::pm_matrix(degree_lpm, degree_upm, target.data(), variable.data(), n, d, pop_adj,
result = nns_r14::pm_matrix(degree_lpm, degree_upm, target.data(), variable.data(), n, d, pop_adj,
norm, call_threads());
}
nb::dict out;
Expand Down Expand Up @@ -623,34 +624,39 @@ NB_MODULE(_nnscore, m) {
checked_flat_matrix_size(data, n, d, "data");
if (target.shape(0) != d) throw std::invalid_argument("target length must equal d.");
nb::gil_scoped_release release;
return nns::clpm_nd(data.data(), n, d, target.data(), degree, norm, call_threads());
return nns_r14::nd_moment(nns::clpm_nd, data.data(), n, d, target.data(), degree, norm,
call_threads());
});
m.def("cupm_nd", [](const Vector& data, std::size_t n, std::size_t d, const Vector& target,
double degree, bool norm) {
checked_flat_matrix_size(data, n, d, "data");
if (target.shape(0) != d) throw std::invalid_argument("target length must equal d.");
nb::gil_scoped_release release;
return nns::cupm_nd(data.data(), n, d, target.data(), degree, norm, call_threads());
return nns_r14::nd_moment(nns::cupm_nd, data.data(), n, d, target.data(), degree, norm,
call_threads());
});
m.def("dpm_nd", [](const Vector& data, std::size_t n, std::size_t d, const Vector& target,
double degree, bool norm) {
checked_flat_matrix_size(data, n, d, "data");
if (target.shape(0) != d) throw std::invalid_argument("target length must equal d.");
nb::gil_scoped_release release;
return nns::dpm_nd(data.data(), n, d, target.data(), degree, norm, call_threads());
return nns_r14::nd_moment(nns::dpm_nd, data.data(), n, d, target.data(), degree, norm,
call_threads());
});
m.def("clpm_nd_batch", [](const Vector& data, std::size_t n, std::size_t d,
const Vector& targets, std::size_t n_targets, double degree, bool norm) {
const Vector& targets, std::size_t n_targets, double degree, bool norm,
bool strict) {
checked_flat_matrix_size(data, n, d, "data");
if (targets.shape(0) != n_targets * d) {
throw std::invalid_argument("targets length must equal n_targets * d.");
}
std::vector<double> out(n_targets, 0.0);
nb::gil_scoped_release release;
nns::clpm_nd_batch(data.data(), n, d, targets.data(), n_targets, degree, norm, out.data(),
call_threads());
nns_r14::clpm_nd_batch(data.data(), n, d, targets.data(), n_targets, degree, norm, strict,
out.data(), call_threads());
return out;
});
}, nb::arg("data"), nb::arg("n"), nb::arg("d"), nb::arg("targets"), nb::arg("n_targets"),
nb::arg("degree"), nb::arg("norm"), nb::arg("strict") = false);
m.def("pm_matrix", &pm_matrix_dict);

m.def(
Expand Down
117 changes: 117 additions & 0 deletions src/nns/_r14_partial_moments.cpp
Original file line number Diff line number Diff line change
@@ -0,0 +1,117 @@
// SPDX-License-Identifier: GPL-3.0-only
#include "_r14_partial_moments.hpp"

#include <climits>
#include <cmath>
#include <stdexcept>

#include "nns/parallel.hpp"

namespace nns_r14 {

double nd_moment(NDMethod moment, const double* data, std::size_t n, std::size_t d,
const double* target, double degree, bool norm, int threads) {
if (!norm || degree == 0.0) return moment(data, n, d, target, degree, false, threads);
const double lower = nns::clpm_nd(data, n, d, target, degree, false, threads);
const double upper = nns::cupm_nd(data, n, d, target, degree, false, threads);
const double div = nns::dpm_nd(data, n, d, target, degree, false, threads);
const double total = lower + upper + div;
if (total == 0.0) return moment(data, n, d, target, 0.0, false, threads);
const double raw = moment == nns::clpm_nd ? lower : (moment == nns::cupm_nd ? upper : div);
return total > 0.0 ? raw / total : 0.0;
}

static double power(double value, double degree) {
if (std::trunc(degree) != degree || degree > INT_MAX) return std::pow(value, degree);
double term = 1.0;
for (int k = 0; k < static_cast<int>(degree); ++k) term *= value;
return term;
}

void clpm_nd_batch(const double* data, std::size_t n, std::size_t d, const double* targets,
std::size_t m, double degree, bool norm, bool strict, double* out, int threads) {
if (!(degree >= 0.0)) throw std::invalid_argument("`degree` must be a non-negative number");
if (n == 0) throw std::invalid_argument("`data` must have at least one row");
const double inv_n = 1.0 / static_cast<double>(n);
nns::parallel_for(0, m, [&](std::size_t begin, std::size_t end) {
for (std::size_t r = begin; r < end; ++r) {
auto lower_share = [&] {
std::size_t count = 0;
for (std::size_t i = 0; i < n; ++i) {
std::size_t j = 0;
for (; j < d; ++j) {
const double x = data[j * n + i], t = targets[j * m + r];
if (strict ? x >= t : x > t) break;
}
if (j == d) ++count;
}
return static_cast<double>(count) / static_cast<double>(n);
};
if (degree == 0.0) {
out[r] = lower_share();
continue;
}
double lower = 0.0, upper = 0.0, div = 0.0;
for (std::size_t i = 0; i < n; ++i) {
double lo = 1.0, hi = 1.0, abs_prod = 1.0;
bool below = true, above = true;
for (std::size_t j = 0; j < d; ++j) {
const double diff = data[j * n + i] - targets[j * m + r];
const double term = power(std::abs(diff), degree);
lo *= diff > 0.0 ? 0.0 : term;
hi *= diff < 0.0 ? 0.0 : term;
abs_prod *= term;
if (diff >= 0.0) below = false;
if (diff <= 0.0) above = false;
}
lower += lo;
upper += hi;
if (!below && !above) div += abs_prod;
}
lower *= inv_n;
if (!norm) {
out[r] = lower;
continue;
}
const double total = lower + upper * inv_n + div * inv_n;
if (total == 0.0) out[r] = lower_share();
else out[r] = total > 0.0 ? lower / total : 0.0;
}
}, threads, n * d);
}

nns::PMMatrixResult pm_matrix(double lower, double upper, const double* target, const double* data,
std::size_t n, std::size_t d, bool pop_adj, bool norm, int threads) {
auto result = nns::pm_matrix(lower, upper, target, data, n, d, pop_adj, false, threads);
if (!norm) return result;
nns::PMMatrixResult pm0;
for (std::size_t i = 0; i < result.dim; ++i) {
for (std::size_t j = i; j < result.dim; ++j) {
const auto k = j * d + i, mirror = i * d + j;
double cu = result.cupm[k], du = result.dupm[k], dl = result.dlpm[k], cl = result.clpm[k];
const double total = cu + du + dl + cl;
if (total > 0.0) {
cu /= total;
du /= total;
dl /= total;
cl /= total;
} else if (total == 0.0) {
if (pm0.clpm.empty()) pm0 = nns::pm_matrix(0, 0, target, data, n, d, false, true, threads);
cu = pm0.cupm[k];
du = pm0.dupm[k];
dl = pm0.dlpm[k];
cl = pm0.clpm[k];
} else {
cu = du = dl = cl = 0.0;
}
result.cupm[k] = result.cupm[mirror] = cu;
result.clpm[k] = result.clpm[mirror] = cl;
result.dupm[k] = result.dlpm[mirror] = du;
result.dlpm[k] = result.dupm[mirror] = dl;
result.cov[k] = result.cov[mirror] = cu + cl - du - dl;
}
}
return result;
}

} // namespace nns_r14
16 changes: 16 additions & 0 deletions src/nns/_r14_partial_moments.hpp
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
// SPDX-License-Identifier: GPL-3.0-only
#pragma once

#include "nns/partial_moments.hpp"

namespace nns_r14 {

using NDMethod = decltype(&nns::clpm_nd);
double nd_moment(NDMethod moment, const double* data, std::size_t n, std::size_t d,
const double* target, double degree, bool norm, int threads);
void clpm_nd_batch(const double* data, std::size_t n, std::size_t d, const double* targets,
std::size_t m, double degree, bool norm, bool strict, double* out, int threads);
nns::PMMatrixResult pm_matrix(double lower, double upper, const double* target, const double* data,
std::size_t n, std::size_t d, bool pop_adj, bool norm, int threads);

} // namespace nns_r14
Loading
Loading