dannce-density 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,24 @@
1
+ cff-version: "1.2.0"
2
+ message: "If you use DANNCE, please cite the paper below."
3
+ title: "dannce-density"
4
+ type: software
5
+ version: "0.1.0"
6
+ license: MIT
7
+ authors:
8
+ - family-names: Li
9
+ given-names: Chenghao
10
+ preferred-citation:
11
+ type: article
12
+ title: "A Data-Augmented Contrastive Learning Approach to Nonparametric Density Estimation"
13
+ authors:
14
+ - family-names: Li
15
+ given-names: Chenghao
16
+ - family-names: Lin
17
+ given-names: Yuanyuan
18
+ journal: "Journal of Machine Learning Research"
19
+ year: 2026
20
+ volume: 27
21
+ issue: 10
22
+ start: 1
23
+ end: 47
24
+ url: "https://www.jmlr.org/papers/v27/25-0376.html"
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Li-Chenqhao
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,3 @@
1
+ include CITATION.cff
2
+ include examples/basic_usage.py
3
+ include tests/test_estimator.py
@@ -0,0 +1,75 @@
1
+ Metadata-Version: 2.4
2
+ Name: dannce-density
3
+ Version: 0.1.0
4
+ Summary: Data-augmented nonparametric noise contrastive density estimation
5
+ Author: Chenghao Li
6
+ License-Expression: MIT
7
+ Project-URL: Paper, https://www.jmlr.org/papers/v27/25-0376.html
8
+ Project-URL: Research Code, https://github.com/Li-Chenqhao/DANNCE
9
+ Keywords: density estimation,noise contrastive estimation,DANNCE
10
+ Classifier: Programming Language :: Python :: 3
11
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
12
+ Classifier: Topic :: Scientific/Engineering :: Mathematics
13
+ Requires-Python: >=3.11
14
+ Description-Content-Type: text/markdown
15
+ License-File: LICENSE
16
+ Requires-Dist: numpy>=1.26
17
+ Requires-Dist: torch>=2.7.1
18
+ Dynamic: license-file
19
+
20
+ # DANNCE density estimation
21
+
22
+ `dannce-density` fits the data-augmented nonparametric noise contrastive estimator of Li and Lin (2026) to continuous data and evaluates the estimated density at new points. See the [JMLR paper](https://www.jmlr.org/papers/v27/25-0376.html) and [research code](https://github.com/Li-Chenqhao/DANNCE).
23
+
24
+ ## Installation
25
+
26
+ Use Python 3.11 or later with a compatible PyTorch build.
27
+
28
+ ```sh
29
+ python -m pip install dannce-density
30
+ ```
31
+
32
+ For a specific CPU or CUDA build, install [PyTorch](https://pytorch.org/get-started/locally/) first. `device="auto"` selects CUDA when available and CPU otherwise.
33
+
34
+ ## Usage
35
+
36
+ ```python
37
+ import numpy as np
38
+ from dannce_density import DANNCE
39
+
40
+ rng = np.random.default_rng(42)
41
+ centers = rng.choice([-1.5, 1.5], size=2000)
42
+ X = rng.normal(loc=centers, scale=0.4)
43
+
44
+ model = DANNCE(random_state=42).fit(X)
45
+ X_new = [-1.5, 0.0, 1.5]
46
+ print(model.pdf(X_new))
47
+ print(model.log_pdf(X_new))
48
+ ```
49
+
50
+ Use an array of shape `(n_samples, n_features)` to fit multivariate data, with one observation per row. For univariate data, a one-dimensional array also works. For a single multivariate query, pass a vector of length `n_features`. `pdf` and `log_pdf` return a NumPy array with one entry for each query.
51
+
52
+ `pdf` sets negative estimates to zero and `log_pdf` returns `-inf` at those zeros. `log_pdf` evaluates in log space and can retain very small estimates that underflow in `pdf`. Use `pdf(X_new, clip=False)` for the signed estimate in equation (4), for example to rank anomalies from lowest to highest. Finite-sample estimates may fail to integrate to one, and tail estimates can be unreliable.
53
+
54
+ ## Parameters
55
+
56
+ | Parameter | Default | Meaning |
57
+ | --- | --- | --- |
58
+ | `rho` | `0.3` | Ratio of augmentation draws to the number of observations. `rho=0` runs noise contrastive estimation without augmentation. |
59
+ | `nu` | `5` | Number of contrastive noise draws per augmented observation. |
60
+ | `reference_std` | Largest sample standard deviation across columns | Common standard deviation of the isotropic Gaussian reference, in the original units. The Gaussian is centered at the sample mean. |
61
+ | `output_scale` | Eight times the peak reference density | Upper bound of the scaled sigmoid that models the mixture density, in the original units. |
62
+ | `depth`, `hidden_width` | `4`, `32` | Number of hidden layers and units per layer in the LeakyReLU network. |
63
+ | `learning_rate` | `0.0002` | Adam learning rate. |
64
+ | `batch_size` | `128` | Maximum number of augmented observations per update. Each batch uses `nu` times as many contrastive draws. |
65
+ | `max_iter` | `2500` | Number of optimizer updates. |
66
+ | `device` | `"auto"` | `"auto"`, `"cpu"`, `"cuda"`, or a CUDA index such as `"cuda:1"`. |
67
+ | `random_state` | `None` | Supply a nonnegative integer to seed the reference draws, minibatch sampling, and network initialization. |
68
+
69
+ The fit draws `floor(rho * n_samples)` augmentation points. The density correction uses the actual ratio, available as `model.rho_`. The fitted reference standard deviation is available as `model.reference_std_`. If all observations are identical, supply a positive `reference_std` to fit. The default settings are starting points. Feature scale, reference spread, mixture-density bounds, and training length can all affect the fit. See Sections 2 and 5 of the [paper](https://www.jmlr.org/papers/v27/25-0376.html).
70
+
71
+ ## Citation and license
72
+
73
+ Chenghao Li and Yuanyuan Lin (2026). A Data-Augmented Contrastive Learning Approach to Nonparametric Density Estimation. *Journal of Machine Learning Research*, 27(10), 1–47. [BibTeX](https://www.jmlr.org/papers/v27/25-0376.bib)
74
+
75
+ The package adapts the LeakyReLU network and contrastive training from the [MIT-licensed research code](https://github.com/Li-Chenqhao/DANNCE/tree/8bce06524e1f56725dbeb4b4f29c0821fe0691ee).
@@ -0,0 +1,56 @@
1
+ # DANNCE density estimation
2
+
3
+ `dannce-density` fits the data-augmented nonparametric noise contrastive estimator of Li and Lin (2026) to continuous data and evaluates the estimated density at new points. See the [JMLR paper](https://www.jmlr.org/papers/v27/25-0376.html) and [research code](https://github.com/Li-Chenqhao/DANNCE).
4
+
5
+ ## Installation
6
+
7
+ Use Python 3.11 or later with a compatible PyTorch build.
8
+
9
+ ```sh
10
+ python -m pip install dannce-density
11
+ ```
12
+
13
+ For a specific CPU or CUDA build, install [PyTorch](https://pytorch.org/get-started/locally/) first. `device="auto"` selects CUDA when available and CPU otherwise.
14
+
15
+ ## Usage
16
+
17
+ ```python
18
+ import numpy as np
19
+ from dannce_density import DANNCE
20
+
21
+ rng = np.random.default_rng(42)
22
+ centers = rng.choice([-1.5, 1.5], size=2000)
23
+ X = rng.normal(loc=centers, scale=0.4)
24
+
25
+ model = DANNCE(random_state=42).fit(X)
26
+ X_new = [-1.5, 0.0, 1.5]
27
+ print(model.pdf(X_new))
28
+ print(model.log_pdf(X_new))
29
+ ```
30
+
31
+ Use an array of shape `(n_samples, n_features)` to fit multivariate data, with one observation per row. For univariate data, a one-dimensional array also works. For a single multivariate query, pass a vector of length `n_features`. `pdf` and `log_pdf` return a NumPy array with one entry for each query.
32
+
33
+ `pdf` sets negative estimates to zero and `log_pdf` returns `-inf` at those zeros. `log_pdf` evaluates in log space and can retain very small estimates that underflow in `pdf`. Use `pdf(X_new, clip=False)` for the signed estimate in equation (4), for example to rank anomalies from lowest to highest. Finite-sample estimates may fail to integrate to one, and tail estimates can be unreliable.
34
+
35
+ ## Parameters
36
+
37
+ | Parameter | Default | Meaning |
38
+ | --- | --- | --- |
39
+ | `rho` | `0.3` | Ratio of augmentation draws to the number of observations. `rho=0` runs noise contrastive estimation without augmentation. |
40
+ | `nu` | `5` | Number of contrastive noise draws per augmented observation. |
41
+ | `reference_std` | Largest sample standard deviation across columns | Common standard deviation of the isotropic Gaussian reference, in the original units. The Gaussian is centered at the sample mean. |
42
+ | `output_scale` | Eight times the peak reference density | Upper bound of the scaled sigmoid that models the mixture density, in the original units. |
43
+ | `depth`, `hidden_width` | `4`, `32` | Number of hidden layers and units per layer in the LeakyReLU network. |
44
+ | `learning_rate` | `0.0002` | Adam learning rate. |
45
+ | `batch_size` | `128` | Maximum number of augmented observations per update. Each batch uses `nu` times as many contrastive draws. |
46
+ | `max_iter` | `2500` | Number of optimizer updates. |
47
+ | `device` | `"auto"` | `"auto"`, `"cpu"`, `"cuda"`, or a CUDA index such as `"cuda:1"`. |
48
+ | `random_state` | `None` | Supply a nonnegative integer to seed the reference draws, minibatch sampling, and network initialization. |
49
+
50
+ The fit draws `floor(rho * n_samples)` augmentation points. The density correction uses the actual ratio, available as `model.rho_`. The fitted reference standard deviation is available as `model.reference_std_`. If all observations are identical, supply a positive `reference_std` to fit. The default settings are starting points. Feature scale, reference spread, mixture-density bounds, and training length can all affect the fit. See Sections 2 and 5 of the [paper](https://www.jmlr.org/papers/v27/25-0376.html).
51
+
52
+ ## Citation and license
53
+
54
+ Chenghao Li and Yuanyuan Lin (2026). A Data-Augmented Contrastive Learning Approach to Nonparametric Density Estimation. *Journal of Machine Learning Research*, 27(10), 1–47. [BibTeX](https://www.jmlr.org/papers/v27/25-0376.bib)
55
+
56
+ The package adapts the LeakyReLU network and contrastive training from the [MIT-licensed research code](https://github.com/Li-Chenqhao/DANNCE/tree/8bce06524e1f56725dbeb4b4f29c0821fe0691ee).
@@ -0,0 +1,20 @@
1
+ """Fit DANNCE to a univariate sample and estimate density at three points."""
2
+
3
+ import numpy as np
4
+
5
+ from dannce_density import DANNCE
6
+
7
+
8
+ def main() -> None:
9
+ rng = np.random.default_rng(42)
10
+ centers = rng.choice([-1.5, 1.5], size=2000)
11
+ observations = rng.normal(loc=centers, scale=0.4)
12
+ model = DANNCE(random_state=42).fit(observations)
13
+
14
+ query = [-1.5, 0.0, 1.5]
15
+ for point, density in zip(query, model.pdf(query)):
16
+ print(f"x = {point:4.1f} estimated density = {density:.4f}")
17
+
18
+
19
+ if __name__ == "__main__":
20
+ main()
@@ -0,0 +1,28 @@
1
+ [build-system]
2
+ requires = ["setuptools>=77"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "dannce-density"
7
+ version = "0.1.0"
8
+ description = "Data-augmented nonparametric noise contrastive density estimation"
9
+ readme = "README.md"
10
+ requires-python = ">=3.11"
11
+ license = "MIT"
12
+ license-files = ["LICENSE"]
13
+ authors = [{name = "Chenghao Li"}]
14
+ keywords = ["density estimation", "noise contrastive estimation", "DANNCE"]
15
+ classifiers = [
16
+ "Programming Language :: Python :: 3",
17
+ "Topic :: Scientific/Engineering :: Artificial Intelligence",
18
+ "Topic :: Scientific/Engineering :: Mathematics",
19
+ ]
20
+ dependencies = ["numpy>=1.26", "torch>=2.7.1"]
21
+
22
+ [project.urls]
23
+ Paper = "https://www.jmlr.org/papers/v27/25-0376.html"
24
+ "Research Code" = "https://github.com/Li-Chenqhao/DANNCE"
25
+
26
+ [tool.setuptools.packages.find]
27
+ where = ["src"]
28
+ namespaces = false
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,5 @@
1
+ """Data-augmented nonparametric noise contrastive estimation."""
2
+
3
+ from .estimator import DANNCE
4
+
5
+ __all__ = ["DANNCE"]
@@ -0,0 +1,39 @@
1
+ """Network and weighted noise contrastive loss from the research code."""
2
+
3
+ import math
4
+
5
+ import torch
6
+ from torch import nn
7
+ from torch.nn import functional as F
8
+
9
+
10
+ def make_network(n_features: int, depth: int, width: int, seed: int) -> nn.Sequential:
11
+ generator = torch.Generator(device="cpu").manual_seed(seed)
12
+ layers = []
13
+ sizes = [n_features, *([width] * depth), 1]
14
+ for index, (in_features, out_features) in enumerate(zip(sizes, sizes[1:])):
15
+ # Initialize with PyTorch's default Linear bounds and a fit-local RNG.
16
+ layer = nn.Linear(in_features, out_features, device="meta", dtype=torch.float32)
17
+ layer.to_empty(device="cpu")
18
+ bound = 1.0 / math.sqrt(in_features)
19
+ nn.init.uniform_(layer.weight, -bound, bound, generator=generator)
20
+ nn.init.uniform_(layer.bias, -bound, bound, generator=generator)
21
+ layers.append(layer)
22
+ if index < depth:
23
+ layers.append(nn.LeakyReLU(negative_slope=0.1))
24
+ return nn.Sequential(*layers)
25
+
26
+
27
+ def contrastive_loss(
28
+ scores: torch.Tensor,
29
+ log_noise: torch.Tensor,
30
+ log_output_scale: float,
31
+ n_positive: int,
32
+ nu: int,
33
+ ) -> torch.Tensor:
34
+ # log(sigmoid(scores)) = -softplus(-scores). The log odds are
35
+ # log(f_M) - log(nu * f_R), with both densities relative to the same peak.
36
+ log_odds = log_output_scale - F.softplus(-scores) - log_noise
37
+ positive_loss = F.softplus(-log_odds[:n_positive]).mean()
38
+ negative_loss = F.softplus(log_odds[n_positive:]).mean()
39
+ return positive_loss + nu * negative_loss
@@ -0,0 +1,40 @@
1
+ """Isotropic Gaussian reference used for augmentation and contrastive noise."""
2
+
3
+ import math
4
+ from dataclasses import dataclass
5
+
6
+ import numpy as np
7
+
8
+
9
+ @dataclass(frozen=True)
10
+ class GaussianReference:
11
+ mean: np.ndarray
12
+ std: float
13
+
14
+ @classmethod
15
+ def from_data(cls, points: np.ndarray, std: float | None) -> "GaussianReference":
16
+ # Scale first when computing moments so that a change of units does
17
+ # not cause overflow or underflow in the sample variance.
18
+ magnitude = float(max(abs(points.min()), abs(points.max())))
19
+ scaled = points / (magnitude or 1.0)
20
+ mean = scaled.mean(axis=0) * magnitude
21
+ if std is None:
22
+ std = float(scaled.std(axis=0, ddof=1).max()) * magnitude
23
+ if std == 0.0:
24
+ raise ValueError("X has zero sample spread. Specify a positive reference_std.")
25
+ if not math.isfinite(std):
26
+ raise ValueError("The sample spread is too large. Rescale X or set reference_std.")
27
+ return cls(mean=mean, std=std)
28
+
29
+ @property
30
+ def log_peak(self) -> float:
31
+ return -self.mean.size * (math.log(self.std) + 0.5 * math.log(2.0 * math.pi))
32
+
33
+ def standardize(self, points: np.ndarray) -> np.ndarray:
34
+ with np.errstate(over="ignore", invalid="ignore"):
35
+ return (points - self.mean) / self.std
36
+
37
+
38
+ def log_gaussian_kernel(standardized: np.ndarray) -> np.ndarray:
39
+ """Log reference density relative to its peak, in reference coordinates."""
40
+ return -0.5 * np.einsum("ij,ij->i", standardized, standardized, dtype=np.float64)
@@ -0,0 +1,305 @@
1
+ """Fit and evaluate a DANNCE density estimate on user-supplied data."""
2
+
3
+ import math
4
+ from dataclasses import dataclass
5
+ from numbers import Integral, Real
6
+
7
+ import numpy as np
8
+ import torch
9
+ from numpy.typing import ArrayLike
10
+
11
+ from ._network import contrastive_loss, make_network
12
+ from ._reference import GaussianReference, log_gaussian_kernel
13
+
14
+
15
+ @dataclass(frozen=True)
16
+ class _FittedModel:
17
+ reference: GaussianReference
18
+ network: torch.nn.Sequential
19
+ device: torch.device
20
+ rho: float
21
+ log_output_scale: float
22
+
23
+
24
+ class DANNCE:
25
+ """Data-augmented nonparametric noise contrastive density estimator.
26
+
27
+ Parameters
28
+ ----------
29
+ rho : float, default=0.3
30
+ Nominal ratio of augmentation draws to observations. Set to zero
31
+ for noise contrastive estimation without augmentation.
32
+ nu : int, default=5
33
+ Number of contrastive noise draws per augmented observation.
34
+ reference_std : float or None, default=None
35
+ Common standard deviation of the isotropic Gaussian reference in
36
+ the original units. The default is the largest sample standard
37
+ deviation across the features. The reference is centered at the
38
+ sample mean.
39
+ depth : int, default=4
40
+ Number of hidden layers in the LeakyReLU network.
41
+ hidden_width : int, default=32
42
+ Number of units per hidden layer.
43
+ output_scale : float or None, default=None
44
+ Upper bound on the network's mixture density in the original units.
45
+ The default is eight times the peak of the fitted reference density.
46
+ learning_rate : float, default=0.0002
47
+ Learning rate for Adam.
48
+ batch_size : int, default=128
49
+ Maximum number of augmented observations per update. Each batch
50
+ also contains `nu` times as many contrastive noise draws.
51
+ max_iter : int, default=2500
52
+ Number of Adam updates.
53
+ device : str or torch.device, default="auto"
54
+ Use "cpu", "cuda", a CUDA device such as "cuda:1", or "auto" to
55
+ prefer CUDA when available.
56
+ random_state : int or None, default=None
57
+ Nonnegative seed for this fit's network initialization and sampling.
58
+ """
59
+
60
+ def __init__(
61
+ self,
62
+ *,
63
+ rho: float = 0.3,
64
+ nu: int = 5,
65
+ reference_std: float | None = None,
66
+ depth: int = 4,
67
+ hidden_width: int = 32,
68
+ output_scale: float | None = None,
69
+ learning_rate: float = 2e-4,
70
+ batch_size: int = 128,
71
+ max_iter: int = 2500,
72
+ device: str | torch.device = "auto",
73
+ random_state: int | None = None,
74
+ ) -> None:
75
+ self.rho = rho
76
+ self.nu = nu
77
+ self.reference_std = reference_std
78
+ self.depth = depth
79
+ self.hidden_width = hidden_width
80
+ self.output_scale = output_scale
81
+ self.learning_rate = learning_rate
82
+ self.batch_size = batch_size
83
+ self.max_iter = max_iter
84
+ self.device = device
85
+ self.random_state = random_state
86
+ self._fitted: _FittedModel | None = None
87
+
88
+ @property
89
+ def rho_(self) -> float:
90
+ """Actual ratio of augmentation draws to observations in the last fit."""
91
+ return self._require_fit().rho
92
+
93
+ @property
94
+ def n_features_in_(self) -> int:
95
+ """Number of features in the last fit."""
96
+ return self._require_fit().reference.mean.size
97
+
98
+ @property
99
+ def reference_std_(self) -> float:
100
+ """Gaussian reference standard deviation used in the last fit."""
101
+ return self._require_fit().reference.std
102
+
103
+ def fit(self, X: ArrayLike) -> "DANNCE":
104
+ """Fit to at least two observations and return this estimator.
105
+
106
+ Supply an array of shape (n_samples, n_features) or a one-dimensional
107
+ array of univariate observations. All entries must be finite and real.
108
+ """
109
+ rho = _real_parameter("rho", self.rho, allow_zero=True)
110
+ nu = _integer_parameter("nu", self.nu)
111
+ depth = _integer_parameter("depth", self.depth)
112
+ width = _integer_parameter("hidden_width", self.hidden_width)
113
+ batch_size = _integer_parameter("batch_size", self.batch_size)
114
+ max_iter = _integer_parameter("max_iter", self.max_iter)
115
+ learning_rate = _real_parameter("learning_rate", self.learning_rate)
116
+ reference_std = _optional_positive("reference_std", self.reference_std)
117
+ output_scale = _optional_positive("output_scale", self.output_scale)
118
+ seed = self.random_state
119
+ if seed is not None:
120
+ seed = _integer_parameter("random_state", seed, minimum=0)
121
+ device = _resolve_device(self.device)
122
+
123
+ X = _points(X)
124
+ n_observations, n_features = X.shape
125
+ if n_observations < 2 or n_features == 0:
126
+ raise ValueError("X must contain at least two observations and one feature.")
127
+ reference = GaussianReference.from_data(X, reference_std)
128
+ log_output_scale = math.log(8.0)
129
+ if output_scale is not None:
130
+ log_output_scale = math.log(output_scale) - reference.log_peak
131
+
132
+ augmentation_size = rho * n_observations
133
+ if not math.isfinite(augmentation_size):
134
+ raise ValueError("rho is too large for the number of observations in X.")
135
+ n_augmentation = math.floor(augmentation_size)
136
+ n_positive = n_observations + n_augmentation
137
+ n_noise = nu * n_positive
138
+ rng = np.random.default_rng(seed)
139
+ network_seed = int(rng.integers(0, 2**63))
140
+
141
+ # In reference coordinates, the reference is standard normal. Keep
142
+ # one fixed positive pool and one independent contrastive noise pool.
143
+ points = np.empty((n_positive + n_noise, n_features), dtype=np.float32)
144
+ points[:n_observations] = _network_input(reference.standardize(X))
145
+ noise = points[n_observations:]
146
+ rng.standard_normal(size=noise.shape, dtype=noise.dtype, out=noise)
147
+ with np.errstate(over="ignore"):
148
+ log_noise = (math.log(nu) + log_gaussian_kernel(points)).astype(np.float32)
149
+ if not np.isfinite(log_noise).all():
150
+ raise ValueError("X is too large relative to reference_std. Increase reference_std.")
151
+
152
+ network = make_network(n_features, depth, width, network_seed).to(device)
153
+ optimizer = torch.optim.Adam(network.parameters(), lr=learning_rate)
154
+ batch_size = min(batch_size, n_positive)
155
+ for _ in range(max_iter):
156
+ # Draw without replacement within each pool, as in the research code.
157
+ indices = slice(None)
158
+ if batch_size < n_positive:
159
+ positive = rng.choice(n_positive, batch_size, replace=False)
160
+ negative = rng.choice(n_noise, nu * batch_size, replace=False) + n_positive
161
+ indices = np.concatenate((positive, negative))
162
+ batch = torch.from_numpy(points[indices]).to(device)
163
+ reference_batch = torch.from_numpy(log_noise[indices]).to(device)
164
+ optimizer.zero_grad(set_to_none=True)
165
+ scores = network(batch).squeeze(-1)
166
+ loss = contrastive_loss(scores, reference_batch, log_output_scale, batch_size, nu)
167
+ loss.backward()
168
+ optimizer.step()
169
+
170
+ if not torch.isfinite(loss).item() or any(
171
+ not torch.isfinite(parameter).all().item() for parameter in network.parameters()
172
+ ):
173
+ raise FloatingPointError("DANNCE training diverged. Try a smaller learning_rate.")
174
+ network.zero_grad(set_to_none=True)
175
+ self._fitted = _FittedModel(
176
+ reference, network.eval(), device, n_augmentation / n_observations, log_output_scale
177
+ )
178
+ return self
179
+
180
+ def pdf(self, X: ArrayLike, *, clip: bool = True) -> np.ndarray:
181
+ """Return one density estimate per observation, in the original units.
182
+
183
+ By default, negative estimates are set to zero. Pass `clip=False`
184
+ for the signed estimate in equation (4) of Li and Lin (2026).
185
+ """
186
+ signs, log_magnitudes = self._signed_log_density(X)
187
+ if clip:
188
+ log_magnitudes[signs <= 0] = -np.inf
189
+ with np.errstate(over="ignore", under="ignore"):
190
+ density = np.exp(log_magnitudes)
191
+ return density if clip else signs * density
192
+
193
+ def log_pdf(self, X: ArrayLike) -> np.ndarray:
194
+ """Return the natural log of the clipped density, with -inf at zero."""
195
+ signs, log_magnitudes = self._signed_log_density(X)
196
+ log_magnitudes[signs <= 0] = -np.inf
197
+ return log_magnitudes
198
+
199
+ def _require_fit(self) -> _FittedModel:
200
+ if self._fitted is None:
201
+ raise RuntimeError("Call fit(X) before using the fitted estimator.")
202
+ return self._fitted
203
+
204
+ def _signed_log_density(self, X: ArrayLike) -> tuple[np.ndarray, np.ndarray]:
205
+ fitted = self._require_fit()
206
+ points = _points(X, n_features=fitted.reference.mean.size)
207
+ signs = np.ones(points.shape[0], dtype=np.float64)
208
+ log_magnitudes = np.empty_like(signs)
209
+ log_peak = fitted.reference.log_peak
210
+
211
+ with torch.inference_mode():
212
+ for start in range(0, len(points), 4096):
213
+ rows = slice(start, start + 4096)
214
+ standardized = fitted.reference.standardize(points[rows])
215
+ batch = torch.from_numpy(_network_input(standardized)).to(fitted.device)
216
+ scores = fitted.network(batch).squeeze(-1).cpu().numpy().astype(np.float64)
217
+ if not np.isfinite(scores).all():
218
+ raise FloatingPointError("The network returned nonfinite scores for X.")
219
+ log_mixture = fitted.log_output_scale - np.logaddexp(0.0, -scores)
220
+ if fitted.rho == 0.0:
221
+ log_magnitudes[rows] = log_mixture + log_peak
222
+ continue
223
+
224
+ positive = math.log1p(fitted.rho) + log_mixture
225
+ negative = math.log(fitted.rho) + log_gaussian_kernel(standardized)
226
+ gap = positive - negative
227
+ signs[rows] = np.sign(gap)
228
+ # Recover the magnitude of a difference without exponentiating
229
+ # either density and losing small values to underflow.
230
+ with np.errstate(divide="ignore", under="ignore"):
231
+ log_fraction = np.log(-np.expm1(-np.abs(gap)))
232
+ log_magnitudes[rows] = log_peak + (np.maximum(positive, negative) + log_fraction)
233
+ return signs, log_magnitudes
234
+
235
+
236
+ def _points(values: ArrayLike, n_features: int | None = None) -> np.ndarray:
237
+ try:
238
+ points = np.asarray(values)
239
+ if np.iscomplexobj(points):
240
+ raise ValueError("X must be real.")
241
+ points = np.asarray(points, dtype=np.float64)
242
+ except (TypeError, ValueError, OverflowError) as error:
243
+ raise ValueError("X must be an array of finite real numbers.") from error
244
+ if points.ndim == 1:
245
+ if n_features is not None and n_features > 1:
246
+ points = points[None, :]
247
+ else:
248
+ points = points[:, None]
249
+ if points.ndim != 2:
250
+ raise ValueError("X must be one- or two-dimensional.")
251
+ if n_features is not None and points.shape[1] != n_features:
252
+ raise ValueError(f"X must have {n_features} features, got {points.shape[1]}.")
253
+ if not np.isfinite(points).all():
254
+ raise ValueError("X must contain only finite values.")
255
+ return points
256
+
257
+
258
+ def _network_input(standardized: np.ndarray) -> np.ndarray:
259
+ with np.errstate(over="ignore"):
260
+ points = np.ascontiguousarray(standardized, dtype=np.float32)
261
+ if not np.isfinite(points).all():
262
+ raise ValueError("X is too large relative to reference_std. Rescale the data or refit.")
263
+ return points
264
+
265
+
266
+ def _integer_parameter(name: str, value: int, minimum: int = 1) -> int:
267
+ if isinstance(value, bool) or not isinstance(value, Integral) or value < minimum:
268
+ raise ValueError(f"{name} must be an integer greater than or equal to {minimum}.")
269
+ return int(value)
270
+
271
+
272
+ def _real_parameter(name: str, value: float, *, allow_zero: bool = False) -> float:
273
+ if isinstance(value, bool) or not isinstance(value, Real):
274
+ raise ValueError(f"{name} must be a finite real number.")
275
+ try:
276
+ value = float(value)
277
+ except OverflowError as error:
278
+ raise ValueError(f"{name} must be a finite real number.") from error
279
+ if not math.isfinite(value) or value < 0.0 or (value == 0.0 and not allow_zero):
280
+ requirement = "nonnegative" if allow_zero else "positive"
281
+ raise ValueError(f"{name} must be finite and {requirement}.")
282
+ return value
283
+
284
+
285
+ def _optional_positive(name: str, value: float | None) -> float | None:
286
+ return None if value is None else _real_parameter(name, value)
287
+
288
+
289
+ def _resolve_device(device: str | torch.device) -> torch.device:
290
+ if device == "auto":
291
+ device = "cuda" if torch.cuda.is_available() else "cpu"
292
+ try:
293
+ resolved = torch.device(device)
294
+ except (TypeError, RuntimeError) as error:
295
+ raise ValueError("device must be 'auto', 'cpu', 'cuda', or 'cuda:N'.") from error
296
+ if resolved.type not in {"cpu", "cuda"}:
297
+ raise ValueError("device must be 'auto', 'cpu', 'cuda', or 'cuda:N'.")
298
+ if resolved.type == "cuda":
299
+ if not torch.cuda.is_available():
300
+ raise ValueError("CUDA is unavailable. Use device='cpu' or device='auto'.")
301
+ index = torch.cuda.current_device() if resolved.index is None else resolved.index
302
+ if index >= torch.cuda.device_count():
303
+ raise ValueError(f"CUDA device {index} is unavailable.")
304
+ return torch.device("cuda", index)
305
+ return torch.device("cpu")
@@ -0,0 +1,75 @@
1
+ Metadata-Version: 2.4
2
+ Name: dannce-density
3
+ Version: 0.1.0
4
+ Summary: Data-augmented nonparametric noise contrastive density estimation
5
+ Author: Chenghao Li
6
+ License-Expression: MIT
7
+ Project-URL: Paper, https://www.jmlr.org/papers/v27/25-0376.html
8
+ Project-URL: Research Code, https://github.com/Li-Chenqhao/DANNCE
9
+ Keywords: density estimation,noise contrastive estimation,DANNCE
10
+ Classifier: Programming Language :: Python :: 3
11
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
12
+ Classifier: Topic :: Scientific/Engineering :: Mathematics
13
+ Requires-Python: >=3.11
14
+ Description-Content-Type: text/markdown
15
+ License-File: LICENSE
16
+ Requires-Dist: numpy>=1.26
17
+ Requires-Dist: torch>=2.7.1
18
+ Dynamic: license-file
19
+
20
+ # DANNCE density estimation
21
+
22
+ `dannce-density` fits the data-augmented nonparametric noise contrastive estimator of Li and Lin (2026) to continuous data and evaluates the estimated density at new points. See the [JMLR paper](https://www.jmlr.org/papers/v27/25-0376.html) and [research code](https://github.com/Li-Chenqhao/DANNCE).
23
+
24
+ ## Installation
25
+
26
+ Use Python 3.11 or later with a compatible PyTorch build.
27
+
28
+ ```sh
29
+ python -m pip install dannce-density
30
+ ```
31
+
32
+ For a specific CPU or CUDA build, install [PyTorch](https://pytorch.org/get-started/locally/) first. `device="auto"` selects CUDA when available and CPU otherwise.
33
+
34
+ ## Usage
35
+
36
+ ```python
37
+ import numpy as np
38
+ from dannce_density import DANNCE
39
+
40
+ rng = np.random.default_rng(42)
41
+ centers = rng.choice([-1.5, 1.5], size=2000)
42
+ X = rng.normal(loc=centers, scale=0.4)
43
+
44
+ model = DANNCE(random_state=42).fit(X)
45
+ X_new = [-1.5, 0.0, 1.5]
46
+ print(model.pdf(X_new))
47
+ print(model.log_pdf(X_new))
48
+ ```
49
+
50
+ Use an array of shape `(n_samples, n_features)` to fit multivariate data, with one observation per row. For univariate data, a one-dimensional array also works. For a single multivariate query, pass a vector of length `n_features`. `pdf` and `log_pdf` return a NumPy array with one entry for each query.
51
+
52
+ `pdf` sets negative estimates to zero and `log_pdf` returns `-inf` at those zeros. `log_pdf` evaluates in log space and can retain very small estimates that underflow in `pdf`. Use `pdf(X_new, clip=False)` for the signed estimate in equation (4), for example to rank anomalies from lowest to highest. Finite-sample estimates may fail to integrate to one, and tail estimates can be unreliable.
53
+
54
+ ## Parameters
55
+
56
+ | Parameter | Default | Meaning |
57
+ | --- | --- | --- |
58
+ | `rho` | `0.3` | Ratio of augmentation draws to the number of observations. `rho=0` runs noise contrastive estimation without augmentation. |
59
+ | `nu` | `5` | Number of contrastive noise draws per augmented observation. |
60
+ | `reference_std` | Largest sample standard deviation across columns | Common standard deviation of the isotropic Gaussian reference, in the original units. The Gaussian is centered at the sample mean. |
61
+ | `output_scale` | Eight times the peak reference density | Upper bound of the scaled sigmoid that models the mixture density, in the original units. |
62
+ | `depth`, `hidden_width` | `4`, `32` | Number of hidden layers and units per layer in the LeakyReLU network. |
63
+ | `learning_rate` | `0.0002` | Adam learning rate. |
64
+ | `batch_size` | `128` | Maximum number of augmented observations per update. Each batch uses `nu` times as many contrastive draws. |
65
+ | `max_iter` | `2500` | Number of optimizer updates. |
66
+ | `device` | `"auto"` | `"auto"`, `"cpu"`, `"cuda"`, or a CUDA index such as `"cuda:1"`. |
67
+ | `random_state` | `None` | Supply a nonnegative integer to seed the reference draws, minibatch sampling, and network initialization. |
68
+
69
+ The fit draws `floor(rho * n_samples)` augmentation points. The density correction uses the actual ratio, available as `model.rho_`. The fitted reference standard deviation is available as `model.reference_std_`. If all observations are identical, supply a positive `reference_std` to fit. The default settings are starting points. Feature scale, reference spread, mixture-density bounds, and training length can all affect the fit. See Sections 2 and 5 of the [paper](https://www.jmlr.org/papers/v27/25-0376.html).
70
+
71
+ ## Citation and license
72
+
73
+ Chenghao Li and Yuanyuan Lin (2026). A Data-Augmented Contrastive Learning Approach to Nonparametric Density Estimation. *Journal of Machine Learning Research*, 27(10), 1–47. [BibTeX](https://www.jmlr.org/papers/v27/25-0376.bib)
74
+
75
+ The package adapts the LeakyReLU network and contrastive training from the [MIT-licensed research code](https://github.com/Li-Chenqhao/DANNCE/tree/8bce06524e1f56725dbeb4b4f29c0821fe0691ee).
@@ -0,0 +1,16 @@
1
+ CITATION.cff
2
+ LICENSE
3
+ MANIFEST.in
4
+ README.md
5
+ pyproject.toml
6
+ examples/basic_usage.py
7
+ src/dannce_density/__init__.py
8
+ src/dannce_density/_network.py
9
+ src/dannce_density/_reference.py
10
+ src/dannce_density/estimator.py
11
+ src/dannce_density.egg-info/PKG-INFO
12
+ src/dannce_density.egg-info/SOURCES.txt
13
+ src/dannce_density.egg-info/dependency_links.txt
14
+ src/dannce_density.egg-info/requires.txt
15
+ src/dannce_density.egg-info/top_level.txt
16
+ tests/test_estimator.py
@@ -0,0 +1,2 @@
1
+ numpy>=1.26
2
+ torch>=2.7.1
@@ -0,0 +1 @@
1
+ dannce_density
@@ -0,0 +1,125 @@
1
+ import math
2
+ import unittest
3
+
4
+ import numpy as np
5
+ import torch
6
+ from torch.nn import functional as F
7
+
8
+ from dannce_density import DANNCE
9
+ from dannce_density._network import contrastive_loss
10
+
11
+
12
+ class ContrastiveLossTests(unittest.TestCase):
13
+ def test_matches_weighted_classifier_loss_and_gradient(self):
14
+ scores = torch.tensor([-1.2, 1.0, -0.8, 0.4, 0.3, -1.0], dtype=torch.float64)
15
+ scores.requires_grad_()
16
+ reference = torch.tensor([0.8, 0.3, 0.4, 0.9, 0.6, 0.2], dtype=torch.float64)
17
+ scale, n_positive, nu = 2.5, 2, 2
18
+
19
+ mixture = scale * scores.sigmoid()
20
+ probability = mixture / (mixture + nu * reference)
21
+ positive, negative = probability[:n_positive], probability[n_positive:]
22
+ expected = F.binary_cross_entropy(positive, torch.ones_like(positive))
23
+ expected += nu * F.binary_cross_entropy(negative, torch.zeros_like(negative))
24
+ actual = contrastive_loss(scores, (nu * reference).log(), math.log(scale), n_positive, nu)
25
+
26
+ torch.testing.assert_close(actual, expected)
27
+ torch.testing.assert_close(
28
+ torch.autograd.grad(actual, scores)[0], torch.autograd.grad(expected, scores)[0]
29
+ )
30
+
31
+ def test_finite_loss_when_both_densities_underflow(self):
32
+ scores = torch.tensor([-1200.0, -1300.0], requires_grad=True)
33
+ loss = contrastive_loss(scores, torch.tensor([-1400.0, -1300.0]), 0.0, 1, 1)
34
+ loss.backward()
35
+ self.assertTrue(torch.isfinite(loss).item())
36
+ self.assertTrue(torch.isfinite(scores.grad).all().item())
37
+
38
+
39
+ class EstimatorTests(unittest.TestCase):
40
+ def test_density_correction_and_clipping(self):
41
+ model = DANNCE(
42
+ rho=0.6, nu=2, reference_std=1.0, output_scale=0.06,
43
+ max_iter=1, random_state=7, device="cpu",
44
+ ).fit([-1.0, 0.0, 1.0])
45
+ self.assertEqual(model.rho_, 1 / 3)
46
+ self.assertEqual(model.reference_std_, 1.0)
47
+
48
+ # A network with all-zero weights produces a known mixture density.
49
+ with torch.no_grad():
50
+ for parameter in model._fitted.network.parameters():
51
+ parameter.zero_()
52
+ query = np.array([0.0, 1.0, 2.0])
53
+ reference = np.exp(-0.5 * query**2) / math.sqrt(2 * math.pi)
54
+ expected = (1 + model.rho_) * 0.03 - model.rho_ * reference
55
+
56
+ np.testing.assert_allclose(model.pdf(query, clip=False), expected)
57
+ np.testing.assert_allclose(model.pdf(query), expected.clip(min=0))
58
+ log_density = model.log_pdf(query)
59
+ self.assertTrue(np.isneginf(log_density[:2]).all())
60
+ self.assertAlmostEqual(log_density[2], math.log(expected[2]))
61
+
62
+ def test_univariate_units_and_zero_augmentation(self):
63
+ data = np.array([-2.0, -1.0, 0.0, 1.0, 2.0])
64
+ settings = dict(rho=0.1, max_iter=4, random_state=7, device="cpu")
65
+ model = DANNCE(**settings).fit(data)
66
+ rescaled = DANNCE(**settings).fit(10.0 + 3.0 * data[:, None])
67
+ self.assertEqual(model.rho_, 0.0)
68
+ self.assertAlmostEqual(model.reference_std_, np.std(data, ddof=1))
69
+ np.testing.assert_allclose(model.pdf(data, clip=False), model.pdf(data))
70
+ np.testing.assert_allclose(
71
+ model.pdf(data) / 3.0, rescaled.pdf(10.0 + 3.0 * data), rtol=1e-6
72
+ )
73
+
74
+ def test_multivariate_shapes_and_reproducible_seed(self):
75
+ data = np.arange(20).reshape(10, 2)
76
+ settings = dict(max_iter=5, batch_size=4, random_state=2, device="cpu")
77
+ global_rng = torch.random.get_rng_state()
78
+ first = DANNCE(**settings).fit(data)
79
+ second = DANNCE(**settings).fit(data)
80
+ self.assertTrue(torch.equal(global_rng, torch.random.get_rng_state()))
81
+ self.assertEqual(first.n_features_in_, 2)
82
+ self.assertEqual(first.pdf(data[0]).shape, (1,))
83
+ self.assertEqual(first.pdf(np.empty((0, 2))).shape, (0,))
84
+ np.testing.assert_array_equal(first.pdf(data), second.pdf(data))
85
+ many_queries = np.tile(data, (500, 1))
86
+ np.testing.assert_allclose(first.pdf(many_queries), np.tile(first.pdf(data), 500))
87
+
88
+ def test_log_pdf_preserves_small_positive_values(self):
89
+ data = np.stack([-np.ones(800), np.ones(800)])
90
+ model = DANNCE(rho=0, hidden_width=4, max_iter=1, random_state=1, device="cpu").fit(data)
91
+ self.assertEqual(model.pdf(data[0])[0], 0.0)
92
+ self.assertTrue(np.isfinite(model.log_pdf(data[0])[0]))
93
+
94
+ def test_rejects_invalid_inputs_and_preserves_fit_on_error(self):
95
+ model = DANNCE(max_iter=2, random_state=1, device="cpu")
96
+ with self.assertRaisesRegex(RuntimeError, "fit"):
97
+ model.pdf([0.0])
98
+ model.fit([-1.0, 0.0, 1.0])
99
+ expected = model.pdf([0.0])
100
+
101
+ for data in ([1.0], [1.0, float("nan")], [1.0, 2j], [[1.0], [1.0]], np.ones((2, 3, 1))):
102
+ with self.subTest(data=data), self.assertRaises(ValueError):
103
+ model.fit(data)
104
+ with self.assertRaisesRegex(ValueError, "features"):
105
+ model.pdf([[1.0, 2.0]])
106
+ with self.assertRaisesRegex(ValueError, "nu"):
107
+ DANNCE(nu=0, max_iter=1).fit([-1.0, 1.0])
108
+ np.testing.assert_array_equal(model.pdf([0.0]), expected)
109
+ self.assertIs(model.fit([[1.0, 0.0], [2.0, 1.0]]), model)
110
+ self.assertEqual(model.n_features_in_, 2)
111
+
112
+ def test_learns_two_high_density_regions(self):
113
+ rng = np.random.default_rng(42)
114
+ centers = rng.choice([-1.5, 1.5], size=2000)
115
+ data = rng.normal(loc=centers, scale=0.4)
116
+ model = DANNCE(
117
+ batch_size=64, max_iter=800, learning_rate=0.001, random_state=42, device="cpu"
118
+ ).fit(data)
119
+ left_peak, valley, right_peak = model.pdf([-1.5, 0.0, 1.5])
120
+ self.assertGreater(left_peak, max(0.15, 2 * valley))
121
+ self.assertGreater(right_peak, max(0.15, 2 * valley))
122
+
123
+
124
+ if __name__ == "__main__":
125
+ unittest.main()