fitle 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.
- fitle/__init__.py +9 -0
- fitle/compiler.py +681 -0
- fitle/cost.py +358 -0
- fitle/fitting.py +402 -0
- fitle/model.py +1372 -0
- fitle/param.py +542 -0
- fitle/pdfs.py +207 -0
- fitle-0.1.0.dist-info/METADATA +628 -0
- fitle-0.1.0.dist-info/RECORD +12 -0
- fitle-0.1.0.dist-info/WHEEL +5 -0
- fitle-0.1.0.dist-info/licenses/LICENSE +21 -0
- fitle-0.1.0.dist-info/top_level.txt +1 -0
fitle/cost.py
ADDED
|
@@ -0,0 +1,358 @@
|
|
|
1
|
+
"""cost.py
|
|
2
|
+
=========
|
|
3
|
+
Cost function factory for model fitting.
|
|
4
|
+
|
|
5
|
+
Provides the ``Cost`` class which generates various cost functions
|
|
6
|
+
(loss functions) that can be combined with Models using the pipe
|
|
7
|
+
operator (``|``).
|
|
8
|
+
|
|
9
|
+
Supported cost functions:
|
|
10
|
+
|
|
11
|
+
- **MSE**: Mean Squared Error for regression
|
|
12
|
+
- **NLL / unbinnedNLL**: Unbinned Negative Log-Likelihood for PDFs
|
|
13
|
+
- **chi2**: Chi-squared for binned histogram fits
|
|
14
|
+
- **binnedNLL**: Binned Negative Log-Likelihood for histograms
|
|
15
|
+
|
|
16
|
+
Example usage::
|
|
17
|
+
|
|
18
|
+
from fitle import Param, Cost
|
|
19
|
+
from fitle.pdfs import gaussian
|
|
20
|
+
|
|
21
|
+
# Create a model
|
|
22
|
+
model = gaussian(Param("mu"), Param.positive("sigma"))
|
|
23
|
+
|
|
24
|
+
# Pipe to a cost function
|
|
25
|
+
cost_model = model | Cost.NLL(data)
|
|
26
|
+
|
|
27
|
+
# Fit
|
|
28
|
+
result = fit(cost_model)
|
|
29
|
+
"""
|
|
30
|
+
from __future__ import annotations
|
|
31
|
+
|
|
32
|
+
import numpy as np
|
|
33
|
+
from numpy.typing import NDArray
|
|
34
|
+
from .model import Model, const
|
|
35
|
+
from .param import INPUT
|
|
36
|
+
|
|
37
|
+
class Cost:
|
|
38
|
+
"""
|
|
39
|
+
A unified class for generating and calculating various cost functions for model fitting.
|
|
40
|
+
|
|
41
|
+
This class acts as a factory, providing class methods to create specific cost function
|
|
42
|
+
instances (e.g., MSE, NLL, Chi-squared, Binned NLL). Once instantiated, a `Cost` object
|
|
43
|
+
can be piped with a `Model` instance using the `|` operator to create a model that represents the cost.
|
|
44
|
+
|
|
45
|
+
Attributes:
|
|
46
|
+
x (const): Constant representation of the independent variable data.
|
|
47
|
+
y (const, optional): Constant representation of the dependent variable data
|
|
48
|
+
(observed counts/values). `None` for some NLL cases.
|
|
49
|
+
bin_widths (const, optional): Constant representation of bin widths for binned data.
|
|
50
|
+
"""
|
|
51
|
+
def __init__(self, x_data, y_data=None, bin_widths=None):
|
|
52
|
+
# Convert lists to numpy arrays for consistency
|
|
53
|
+
if not isinstance(x_data, np.ndarray):
|
|
54
|
+
x_data = np.asarray(x_data)
|
|
55
|
+
if y_data is not None and not isinstance(y_data, np.ndarray):
|
|
56
|
+
y_data = np.asarray(y_data)
|
|
57
|
+
if bin_widths is not None and not isinstance(bin_widths, np.ndarray):
|
|
58
|
+
bin_widths = np.asarray(bin_widths)
|
|
59
|
+
|
|
60
|
+
# Validate array lengths
|
|
61
|
+
if len(x_data) == 0:
|
|
62
|
+
raise ValueError("x cannot be empty.")
|
|
63
|
+
if y_data is not None:
|
|
64
|
+
if len(x_data) != len(y_data):
|
|
65
|
+
raise ValueError(
|
|
66
|
+
f"x and y must have the same length.\n"
|
|
67
|
+
f" Got x: {len(x_data)} elements, y: {len(y_data)} elements."
|
|
68
|
+
)
|
|
69
|
+
if bin_widths is not None:
|
|
70
|
+
if len(bin_widths) != len(x_data):
|
|
71
|
+
raise ValueError(
|
|
72
|
+
f"bin_widths must have the same length as x.\n"
|
|
73
|
+
f" Got x: {len(x_data)} elements, bin_widths: {len(bin_widths)} elements."
|
|
74
|
+
)
|
|
75
|
+
|
|
76
|
+
self.x = const(x_data)
|
|
77
|
+
self.y = const(y_data) if y_data is not None else None
|
|
78
|
+
self.bin_widths = const(bin_widths) if bin_widths is not None else None
|
|
79
|
+
self.fcn = self._base_fcn # Assign the method to the attribute
|
|
80
|
+
|
|
81
|
+
def _base_fcn(self, *args):
|
|
82
|
+
"""
|
|
83
|
+
Placeholder function for base Cost class.
|
|
84
|
+
Specific cost functions will override the __ror__ behavior.
|
|
85
|
+
"""
|
|
86
|
+
raise NotImplementedError("This is a base Cost class. Use specific cost function generators like Cost.MSE, Cost.NLL, etc.")
|
|
87
|
+
|
|
88
|
+
def __ror__(self, model: Model) -> Model:
|
|
89
|
+
"""Combine a Model with this cost function using the pipe operator.
|
|
90
|
+
|
|
91
|
+
When using ``model | cost``, this method is called to create
|
|
92
|
+
a new Model representing the cost function applied to the model.
|
|
93
|
+
|
|
94
|
+
Parameters
|
|
95
|
+
----------
|
|
96
|
+
model : Model
|
|
97
|
+
The model (typically a PDF) to compute cost for.
|
|
98
|
+
|
|
99
|
+
Returns
|
|
100
|
+
-------
|
|
101
|
+
Model
|
|
102
|
+
A new Model that computes the cost when evaluated.
|
|
103
|
+
|
|
104
|
+
Note
|
|
105
|
+
----
|
|
106
|
+
The cost model preserves INPUT in its structure rather than
|
|
107
|
+
substituting data. This enables compilation reuse across different
|
|
108
|
+
datasets. The data is stored in model.memory['_eval_x'] and passed
|
|
109
|
+
at evaluation time.
|
|
110
|
+
"""
|
|
111
|
+
# Ensure model broadcasts with data by adding INPUT dependency if missing
|
|
112
|
+
if INPUT not in model.free:
|
|
113
|
+
model = model + 0 * INPUT
|
|
114
|
+
ret = self.fcn(model)
|
|
115
|
+
ret.memory['base'] = model
|
|
116
|
+
ret.memory['cost'] = self
|
|
117
|
+
# Store raw data for evaluation (not const-wrapped)
|
|
118
|
+
ret.memory['_eval_x'] = self.x() if hasattr(self.x, '__call__') else self.x
|
|
119
|
+
return ret
|
|
120
|
+
|
|
121
|
+
@classmethod
|
|
122
|
+
def MSE(cls, x: NDArray | list, y: NDArray | list) -> Cost:
|
|
123
|
+
"""Create a Mean Squared Error cost function.
|
|
124
|
+
|
|
125
|
+
Computes ``np.sum((y - model(x))^2)``.
|
|
126
|
+
|
|
127
|
+
Parameters
|
|
128
|
+
----------
|
|
129
|
+
x : array_like
|
|
130
|
+
Independent variable data (input values).
|
|
131
|
+
y : array_like
|
|
132
|
+
Dependent variable data (observed values).
|
|
133
|
+
|
|
134
|
+
Returns
|
|
135
|
+
-------
|
|
136
|
+
Cost
|
|
137
|
+
A Cost instance configured for MSE.
|
|
138
|
+
|
|
139
|
+
Note
|
|
140
|
+
----
|
|
141
|
+
The model's INPUT is preserved (not substituted with data).
|
|
142
|
+
Data is passed at evaluation time for compilation reuse.
|
|
143
|
+
"""
|
|
144
|
+
cost_instance = cls(x, y)
|
|
145
|
+
# Keep INPUT in model structure - y is embedded as constant
|
|
146
|
+
cost_instance.fcn = lambda model: np.sum((cost_instance.y - model)**2)
|
|
147
|
+
return cost_instance
|
|
148
|
+
|
|
149
|
+
@classmethod
|
|
150
|
+
def unbinnedNLL(cls, x: NDArray | list) -> Cost:
|
|
151
|
+
"""Create an unbinned Negative Log-Likelihood cost function.
|
|
152
|
+
|
|
153
|
+
Computes ``np.sum(-np.log(model(x)))``, suitable for fitting
|
|
154
|
+
probability density functions to unbinned data.
|
|
155
|
+
|
|
156
|
+
Parameters
|
|
157
|
+
----------
|
|
158
|
+
x : array_like
|
|
159
|
+
Observed data points (unbinned).
|
|
160
|
+
|
|
161
|
+
Returns
|
|
162
|
+
-------
|
|
163
|
+
Cost
|
|
164
|
+
A Cost instance configured for unbinned NLL.
|
|
165
|
+
|
|
166
|
+
Note
|
|
167
|
+
----
|
|
168
|
+
The model's INPUT is preserved (not substituted with data).
|
|
169
|
+
Data is passed at evaluation time for compilation reuse.
|
|
170
|
+
"""
|
|
171
|
+
cost_instance = cls(x)
|
|
172
|
+
# Keep INPUT in model structure - data passed at eval time
|
|
173
|
+
# np.log and np.sum dispatch via __array_ufunc__/__array_function__
|
|
174
|
+
cost_instance.fcn = lambda model: np.sum(-np.log(model))
|
|
175
|
+
return cost_instance
|
|
176
|
+
|
|
177
|
+
NLL = unbinnedNLL # Alias for convenience
|
|
178
|
+
|
|
179
|
+
@classmethod
|
|
180
|
+
def chi2(
|
|
181
|
+
cls,
|
|
182
|
+
data: NDArray | list | None = None,
|
|
183
|
+
bins: int | NDArray | None = None,
|
|
184
|
+
range: tuple[float, float] | None = None,
|
|
185
|
+
x: NDArray | list | None = None,
|
|
186
|
+
y: NDArray | list | None = None,
|
|
187
|
+
bin_widths: NDArray | list | None = None,
|
|
188
|
+
zero_method: str = 'error'
|
|
189
|
+
) -> Cost:
|
|
190
|
+
"""Create a chi-squared cost function for binned data.
|
|
191
|
+
|
|
192
|
+
Computes ``np.sum((y - model(x) * bin_widths)^2 / y)``.
|
|
193
|
+
|
|
194
|
+
Can be initialized either from raw data (which gets binned) or
|
|
195
|
+
from pre-binned histogram data.
|
|
196
|
+
|
|
197
|
+
Parameters
|
|
198
|
+
----------
|
|
199
|
+
data : array_like, optional
|
|
200
|
+
Raw data to bin (use with ``bins``).
|
|
201
|
+
bins : int or array_like, optional
|
|
202
|
+
Number of bins or bin edges (use with ``data``).
|
|
203
|
+
range : tuple[float, float], optional
|
|
204
|
+
Histogram range (use with ``data`` and ``bins``).
|
|
205
|
+
x : array_like, optional
|
|
206
|
+
Bin centers (use with ``y``).
|
|
207
|
+
y : array_like, optional
|
|
208
|
+
Observed counts per bin (use with ``x``).
|
|
209
|
+
bin_widths : array_like, optional
|
|
210
|
+
Width of each bin (required if using ``x`` and ``y``).
|
|
211
|
+
zero_method : str, default 'error'
|
|
212
|
+
How to handle zero counts: 'error' raises, 'absolute' uses
|
|
213
|
+
absolute residuals for zero bins.
|
|
214
|
+
|
|
215
|
+
Returns
|
|
216
|
+
-------
|
|
217
|
+
Cost
|
|
218
|
+
A Cost instance configured for chi-squared.
|
|
219
|
+
"""
|
|
220
|
+
if data is not None and bins is not None:
|
|
221
|
+
if x is not None or y is not None:
|
|
222
|
+
raise ValueError("Cannot provide both 'data' and 'x,y' for binned cost functions.")
|
|
223
|
+
centers, counts, edges = _bin(data, bins, range)
|
|
224
|
+
widths = np.diff(edges)
|
|
225
|
+
cost_instance = cls(centers, counts, widths)
|
|
226
|
+
elif x is not None and y is not None:
|
|
227
|
+
# Calculate bin widths from centers if not provided
|
|
228
|
+
if bin_widths is None:
|
|
229
|
+
import warnings
|
|
230
|
+
x_arr = np.asarray(x)
|
|
231
|
+
# Calculate widths from spacing between centers
|
|
232
|
+
if len(x_arr) > 1:
|
|
233
|
+
center_diffs = np.diff(x_arr)
|
|
234
|
+
# Check if bins are uniformly spaced
|
|
235
|
+
if not np.allclose(center_diffs, center_diffs[0], rtol=1e-5):
|
|
236
|
+
warnings.warn(
|
|
237
|
+
"Inferring bin widths from non-uniform bin centers. "
|
|
238
|
+
"This may be inaccurate. Consider providing bin_widths explicitly.",
|
|
239
|
+
UserWarning,
|
|
240
|
+
stacklevel=2
|
|
241
|
+
)
|
|
242
|
+
# Assume first/last bins have same width as neighbors
|
|
243
|
+
widths = np.empty(len(x_arr))
|
|
244
|
+
widths[0] = center_diffs[0]
|
|
245
|
+
widths[-1] = center_diffs[-1]
|
|
246
|
+
widths[1:-1] = (center_diffs[:-1] + center_diffs[1:]) / 2
|
|
247
|
+
else:
|
|
248
|
+
raise ValueError("Cannot infer bin widths from a single bin center. Please provide bin_widths explicitly.")
|
|
249
|
+
else:
|
|
250
|
+
widths = bin_widths
|
|
251
|
+
cost_instance = cls(x, y, widths)
|
|
252
|
+
else:
|
|
253
|
+
raise ValueError("For chi2, provide either 'data' and 'bins' (and optional 'range') or 'x', 'y', and 'bin_widths'.")
|
|
254
|
+
|
|
255
|
+
y_data = cost_instance.y()
|
|
256
|
+
if np.any(y_data == 0):
|
|
257
|
+
if zero_method == 'absolute':
|
|
258
|
+
y_star = const(np.where(y_data > 0, y_data, 1))
|
|
259
|
+
# Keep INPUT - model evaluated at x passed at runtime
|
|
260
|
+
cost_instance.fcn = lambda model: np.sum(
|
|
261
|
+
((cost_instance.y - model * cost_instance.bin_widths) ** 2) / y_star
|
|
262
|
+
)
|
|
263
|
+
return cost_instance
|
|
264
|
+
raise ValueError("Chi2 calculation requires that all observed counts (y) be non-zero unless zero_method is set to 'absolute'.")
|
|
265
|
+
# Keep INPUT - model evaluated at x passed at runtime
|
|
266
|
+
cost_instance.fcn = lambda model: np.sum(
|
|
267
|
+
((cost_instance.y - model * cost_instance.bin_widths) ** 2) / cost_instance.y
|
|
268
|
+
)
|
|
269
|
+
return cost_instance
|
|
270
|
+
|
|
271
|
+
@classmethod
|
|
272
|
+
def binnedNLL(
|
|
273
|
+
cls,
|
|
274
|
+
data: NDArray | list | None = None,
|
|
275
|
+
bins: int | NDArray | None = None,
|
|
276
|
+
range: tuple[float, float] | None = None,
|
|
277
|
+
x: NDArray | list | None = None,
|
|
278
|
+
y: NDArray | list | None = None,
|
|
279
|
+
bin_widths: NDArray | list | None = None
|
|
280
|
+
) -> Cost:
|
|
281
|
+
"""Create a binned Negative Log-Likelihood cost function.
|
|
282
|
+
|
|
283
|
+
Computes ``2 * np.sum(model(x) * bin_widths - y * np.log(model(x) * bin_widths))``,
|
|
284
|
+
which is the Poisson likelihood for binned data (up to a constant).
|
|
285
|
+
|
|
286
|
+
Can be initialized either from raw data (which gets binned) or
|
|
287
|
+
from pre-binned histogram data.
|
|
288
|
+
|
|
289
|
+
Parameters
|
|
290
|
+
----------
|
|
291
|
+
data : array_like, optional
|
|
292
|
+
Raw data to bin (use with ``bins``).
|
|
293
|
+
bins : int or array_like, optional
|
|
294
|
+
Number of bins or bin edges (use with ``data``).
|
|
295
|
+
range : tuple[float, float], optional
|
|
296
|
+
Histogram range (use with ``data`` and ``bins``).
|
|
297
|
+
x : array_like, optional
|
|
298
|
+
Bin centers (use with ``y``).
|
|
299
|
+
y : array_like, optional
|
|
300
|
+
Observed counts per bin (use with ``x``).
|
|
301
|
+
bin_widths : array_like, optional
|
|
302
|
+
Width of each bin (required if using ``x`` and ``y``).
|
|
303
|
+
|
|
304
|
+
Returns
|
|
305
|
+
-------
|
|
306
|
+
Cost
|
|
307
|
+
A Cost instance configured for binned NLL.
|
|
308
|
+
"""
|
|
309
|
+
if data is not None and bins is not None:
|
|
310
|
+
if x is not None or y is not None:
|
|
311
|
+
raise ValueError("Cannot provide both 'data' and 'x,y' for binned cost functions.")
|
|
312
|
+
centers, counts, edges = _bin(data, bins, range)
|
|
313
|
+
widths = np.diff(edges)
|
|
314
|
+
cost_instance = cls(centers, counts, widths)
|
|
315
|
+
elif x is not None and y is not None:
|
|
316
|
+
if bin_widths is None:
|
|
317
|
+
raise ValueError("When providing x and y directly, you must also provide bin_widths.")
|
|
318
|
+
cost_instance = cls(x, y, bin_widths)
|
|
319
|
+
else:
|
|
320
|
+
raise ValueError("For binned_nll, provide either 'data' and 'bins' (and optional 'range') or 'x', 'y', and 'bin_widths'.")
|
|
321
|
+
|
|
322
|
+
# Keep INPUT - model evaluated at x passed at runtime
|
|
323
|
+
def _binned_nll_cost(model):
|
|
324
|
+
scaled = model * cost_instance.bin_widths
|
|
325
|
+
return 2 * np.sum(scaled - cost_instance.y * np.log(scaled))
|
|
326
|
+
|
|
327
|
+
cost_instance.fcn = _binned_nll_cost
|
|
328
|
+
return cost_instance
|
|
329
|
+
|
|
330
|
+
def _bin(
|
|
331
|
+
data: NDArray | list,
|
|
332
|
+
bins: int | NDArray,
|
|
333
|
+
range: tuple[float, float] | None = None
|
|
334
|
+
) -> tuple[NDArray, NDArray, NDArray]:
|
|
335
|
+
"""Bin data into a histogram.
|
|
336
|
+
|
|
337
|
+
Parameters
|
|
338
|
+
----------
|
|
339
|
+
data : array_like
|
|
340
|
+
The input data to be binned.
|
|
341
|
+
bins : int or array_like
|
|
342
|
+
If int, the number of equal-width bins. If array, the bin edges.
|
|
343
|
+
range : tuple[float, float], optional
|
|
344
|
+
The (min, max) range for binning. Defaults to data range.
|
|
345
|
+
|
|
346
|
+
Returns
|
|
347
|
+
-------
|
|
348
|
+
centers : ndarray
|
|
349
|
+
The center of each bin.
|
|
350
|
+
counts : ndarray
|
|
351
|
+
The number of data points in each bin (as float64).
|
|
352
|
+
edges : ndarray
|
|
353
|
+
The bin edges.
|
|
354
|
+
"""
|
|
355
|
+
counts, edges = np.histogram(data, bins=bins, range=range)
|
|
356
|
+
centers = 0.5 * (edges[1:] + edges[:-1])
|
|
357
|
+
counts = counts.astype(np.float64)
|
|
358
|
+
return centers, counts, edges
|