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/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