dannce-density 0.1.0__py3-none-any.whl
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.
- dannce_density/__init__.py +5 -0
- dannce_density/_network.py +39 -0
- dannce_density/_reference.py +40 -0
- dannce_density/estimator.py +305 -0
- dannce_density-0.1.0.dist-info/METADATA +75 -0
- dannce_density-0.1.0.dist-info/RECORD +9 -0
- dannce_density-0.1.0.dist-info/WHEEL +5 -0
- dannce_density-0.1.0.dist-info/licenses/LICENSE +21 -0
- dannce_density-0.1.0.dist-info/top_level.txt +1 -0
|
@@ -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,9 @@
|
|
|
1
|
+
dannce_density/__init__.py,sha256=AZqQoryjUaFAmdYN0_evxT1RJodbuJE68-qFl2SAyM0,118
|
|
2
|
+
dannce_density/_network.py,sha256=XGJKlr_QQEJBHrflnjn92J6KCBVjAt_HLbqG2oGQ8Fo,1544
|
|
3
|
+
dannce_density/_reference.py,sha256=VSrPexMSux2CvGzJmXwSohjt6PneoTdWdlWuwY_sgBg,1575
|
|
4
|
+
dannce_density/estimator.py,sha256=CZqz8c9SwuZEz7e5F_AJlzoeR0cmLX4h_hF74DDJPtA,13566
|
|
5
|
+
dannce_density-0.1.0.dist-info/licenses/LICENSE,sha256=0medSfsR23owXpeEirn2b5irR5w28LtnHEIp1KFZOaM,1068
|
|
6
|
+
dannce_density-0.1.0.dist-info/METADATA,sha256=IP_JH6bZ7pNgPEmTHi4Mgr9Gr2IRukeJsj9BPlHCGVM,4538
|
|
7
|
+
dannce_density-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
|
|
8
|
+
dannce_density-0.1.0.dist-info/top_level.txt,sha256=wb1xrmounHLqDBhB_NOZFO9-oN97Jd6rQ9H-MX_Xo_k,15
|
|
9
|
+
dannce_density-0.1.0.dist-info/RECORD,,
|
|
@@ -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 @@
|
|
|
1
|
+
dannce_density
|