eclipse 0.13.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.
Files changed (50) hide show
  1. eclipse/__init__.py +95 -0
  2. eclipse/analysis.py +853 -0
  3. eclipse/atmosphere.py +859 -0
  4. eclipse/band.py +477 -0
  5. eclipse/cli.py +138 -0
  6. eclipse/config.py +1710 -0
  7. eclipse/continuum.py +413 -0
  8. eclipse/data/eis_response/EIS_EffArea_A.004 +61 -0
  9. eclipse/data/eis_response/EIS_EffArea_B.004 +60 -0
  10. eclipse/data/eis_response/EIS_EffArea_B.005 +64 -0
  11. eclipse/data/eis_response/README_dz2025 +50 -0
  12. eclipse/data/eis_response/fit_eis_ea_2023-05-04_smooth.sav +0 -0
  13. eclipse/data/eis_response/source.txt +33 -0
  14. eclipse/data/science_cases.yaml +365 -0
  15. eclipse/data/throughput/grating_reflection_efficiency.dat +25 -0
  16. eclipse/data/throughput/primary_mirror_coating_reflectance.dat +25 -0
  17. eclipse/data/throughput/source.txt +6 -0
  18. eclipse/data/throughput/throughput_aluminium_1000_angstrom.dat +503 -0
  19. eclipse/data/throughput/throughput_aluminium_oxide_1000_angstrom.dat +503 -0
  20. eclipse/data/throughput/throughput_carbon_1000_angstrom.dat +503 -0
  21. eclipse/data_processing.py +904 -0
  22. eclipse/deprecated.py +161 -0
  23. eclipse/eis_calibration.py +573 -0
  24. eclipse/extern/__init__.py +0 -0
  25. eclipse/extern/mpfit.py +2388 -0
  26. eclipse/fitting.py +1734 -0
  27. eclipse/frame.py +594 -0
  28. eclipse/full_frame.py +944 -0
  29. eclipse/main.py +1646 -0
  30. eclipse/monte_carlo.py +660 -0
  31. eclipse/pinhole_diffraction.py +409 -0
  32. eclipse/psf.py +6 -0
  33. eclipse/radiometric.py +1328 -0
  34. eclipse/raster.py +869 -0
  35. eclipse/readout.py +1002 -0
  36. eclipse/resolution_budget.py +108 -0
  37. eclipse/results_file.py +1226 -0
  38. eclipse/sampling.py +351 -0
  39. eclipse/science_cases.py +364 -0
  40. eclipse/synthesis.py +2492 -0
  41. eclipse/synthesis_cli.py +12 -0
  42. eclipse/synthesis_file.py +882 -0
  43. eclipse/utils.py +1145 -0
  44. eclipse-0.13.0.dist-info/METADATA +70 -0
  45. eclipse-0.13.0.dist-info/RECORD +50 -0
  46. eclipse-0.13.0.dist-info/WHEEL +5 -0
  47. eclipse-0.13.0.dist-info/entry_points.txt +7 -0
  48. eclipse-0.13.0.dist-info/licenses/LICENSE +3 -0
  49. eclipse-0.13.0.dist-info/top_level.txt +2 -0
  50. euvst_response/__init__.py +129 -0
eclipse/fitting.py ADDED
@@ -0,0 +1,1734 @@
1
+ """
2
+ Spectral fitting functions for Gaussian line profile analysis.
3
+ """
4
+
5
+ from __future__ import annotations
6
+ import warnings
7
+ from dataclasses import dataclass, field
8
+ from typing import List, Literal, Optional, overload
9
+ import numpy as np
10
+ import astropy.units as u
11
+ import astropy.constants as const
12
+ from ndcube import NDCube
13
+ from scipy.optimize import curve_fit, least_squares, OptimizeWarning
14
+ from joblib import Parallel, delayed
15
+ from tqdm import tqdm
16
+ from .utils import _fwhm_to_sigma, gaussian, multi_gaussian, pixel_mean_gaussians, tqdm_joblib
17
+ from .extern.mpfit import mpfit
18
+
19
+
20
+ def _line_profile(x, *params, n_components=1, pixel=None):
21
+ """
22
+ Fitted model: the Gaussians at wavelengths `x`, or with `pixel`, their
23
+ mean over pixels that wide centred on `x`, as a detector records them.
24
+ """
25
+ if pixel is None:
26
+ return multi_gaussian(x, *params, n_components=n_components)
27
+ return pixel_mean_gaussians(x, *params, n_components=n_components, pixel=pixel)
28
+
29
+
30
+ def _poisson_residuals(counts: np.ndarray, model: np.ndarray) -> np.ndarray:
31
+ """
32
+ Residuals whose sum of squares is the Poisson deviance of counts about a model.
33
+
34
+ For counts d and model m, each residual is
35
+ sign(d - m) sqrt(2 (m - d + d ln(d / m))). Their sum of squares is minus
36
+ twice the Poisson log-likelihood plus a constant, so a least-squares fit
37
+ to them is the maximum-likelihood fit. The residual is zero at d = m and
38
+ close to (d - m) / sqrt(d) near it, the residual weighted by the noise.
39
+
40
+ A zero model has zero likelihood for counts above zero, so it is raised
41
+ to the smallest positive float to keep the arithmetic finite; the fit
42
+ then moves away from it.
43
+ """
44
+ d = np.asarray(counts, dtype=float)
45
+ m = np.maximum(np.asarray(model, dtype=float), np.finfo(float).tiny)
46
+ positive = d > 0
47
+ log_ratio = np.log(np.where(positive, d, 1.0) / m)
48
+ deviance = 2.0 * (m - d + np.where(positive, d * log_ratio, 0.0))
49
+ return np.sign(d - m) * np.sqrt(np.maximum(deviance, 0.0))
50
+
51
+
52
+ # ---------------------------------------------------------------------------
53
+ # Fit configuration
54
+ # ---------------------------------------------------------------------------
55
+
56
+ @dataclass
57
+ class FitComponent:
58
+ """
59
+ One line of a blend, fitted as one Gaussian.
60
+
61
+ Parameters
62
+ ----------
63
+ wavelength : u.Quantity
64
+ Rest wavelength of the line.
65
+ tie_center : int, optional
66
+ Index of a component whose velocity this line shares.
67
+ tie_width : int, optional
68
+ Index of a component whose width this line shares.
69
+ amplitude_greater_than : int, optional
70
+ Index of a component this line's amplitude is kept above.
71
+ name : str, optional
72
+ Name in the results. Default the rest wavelength, e.g.
73
+ `"195.1190 Angstrom"`.
74
+ """
75
+ wavelength: u.Quantity
76
+ tie_center: Optional[int] = None # index of component whose centre this is tied to
77
+ tie_width: Optional[int] = None # index of component whose width this is tied to
78
+ amplitude_greater_than: Optional[int] = None # index of component this must be brighter than
79
+ # Label for this component in the results. Defaults to its rest
80
+ # wavelength, e.g. "195.1190 Angstrom".
81
+ name: Optional[str] = None
82
+
83
+ def __post_init__(self):
84
+ # Catch a wavelength with no unit here rather than in the fit.
85
+ if not (isinstance(self.wavelength, u.Quantity)
86
+ and self.wavelength.unit.physical_type == "length"
87
+ and np.isfinite(self.wavelength.value) and self.wavelength.value > 0):
88
+ raise ValueError(f"A fitting component's wavelength must be the wavelength of a "
89
+ f"line, such as '195.119 AA'; got {self.wavelength!r}.")
90
+
91
+
92
+ def default_component_name(wavelength: u.Quantity) -> str:
93
+ """Name of a component in the results when it is not given one."""
94
+ return f"{wavelength.to_value(u.AA):.4f} Angstrom"
95
+
96
+
97
+ @dataclass
98
+ class FitConfig:
99
+ """
100
+ Fit settings: one Gaussian, or several for a blend.
101
+
102
+ Parameters
103
+ ----------
104
+ components : list of FitComponent
105
+ Lines of a blend, two or more. Default empty, for one Gaussian.
106
+ primary_component : int
107
+ Index of the blend component whose velocity and width are reported.
108
+ Default 0.
109
+ constrain_positive_intensity : bool
110
+ Keep every blend component's amplitude at zero or above. Default
111
+ False.
112
+ backend : str, optional
113
+ Optimiser, `"scipy"` or `"mpfit"`. Default None, for scipy.
114
+ max_iter : int
115
+ Maximum optimiser iterations per spectrum. Default 1000.
116
+ bessel_correction : bool
117
+ Use n - 1 rather than n in the standard deviations over Monte Carlo
118
+ iterations (Bessel's correction). Default False.
119
+ save_iterations : bool
120
+ Keep every iteration's fit in the results as well as the statistics.
121
+ Default False.
122
+ weighted : bool
123
+ Weight each pixel of the DN spectra by one over its uncertainty
124
+ squared, estimated from its own signal as eispac does, and fit the
125
+ photon spectra by their Poisson likelihood. Default True.
126
+ """
127
+ components: List[FitComponent] = field(default_factory=list)
128
+ primary_component: int = 0
129
+ constrain_positive_intensity: bool = False
130
+ backend: str | None = None # None = auto (scipy)
131
+ # Iterations the optimiser may take before it gives up. Counted in
132
+ # iterations, not function evaluations, so it means the same for both
133
+ # backends and does not shrink as components are added. EISPAC uses 2000;
134
+ # fits here converge in tens.
135
+ max_iter: int = 1000
136
+ # Use n - 1 rather than n in the standard deviation over Monte Carlo
137
+ # iterations (Bessel's correction). Off by default, to keep results
138
+ # comparable with earlier runs.
139
+ bessel_correction: bool = False
140
+ # Keep every iteration's fitted parameters in the results, not only their
141
+ # statistics. The results grow by about n_iter times the fit arrays.
142
+ save_iterations: bool = False
143
+ # Weight the DN fits by each pixel's uncertainty and fit the photons by
144
+ # their Poisson likelihood. Unweighted, the velocity scatter of a Gaussian
145
+ # line is 1.24 times the photon-noise limit, because the wings that fix
146
+ # its position count no more than its noisier peak. Results files from
147
+ # before this setting are unweighted.
148
+ weighted: bool = True
149
+
150
+ def __post_init__(self):
151
+ if len(self.components) == 1:
152
+ raise ValueError(
153
+ "fitting.components has one entry. Multi-component fitting "
154
+ "needs at least two; for a single Gaussian leave components "
155
+ "out, and the other fitting settings still apply."
156
+ )
157
+ if self.backend not in (None, "scipy", "mpfit"):
158
+ raise ValueError(
159
+ f"Unknown fitting backend '{self.backend}'. "
160
+ f"Supported values: 'scipy', 'mpfit', or omit for auto."
161
+ )
162
+ if (isinstance(self.max_iter, bool)
163
+ or not isinstance(self.max_iter, (int, np.integer))
164
+ or self.max_iter < 1):
165
+ raise ValueError(
166
+ f"fitting.max_iter must be a positive integer, got "
167
+ f"{self.max_iter!r}."
168
+ )
169
+ for key in ("bessel_correction", "save_iterations", "constrain_positive_intensity",
170
+ "weighted"):
171
+ if not isinstance(getattr(self, key), bool):
172
+ raise ValueError(
173
+ f"fitting.{key} must be true or false, got "
174
+ f"{getattr(self, key)!r}."
175
+ )
176
+ if self.components:
177
+ n = len(self.components)
178
+ if (isinstance(self.primary_component, bool)
179
+ or not isinstance(self.primary_component, (int, np.integer))
180
+ or not 0 <= self.primary_component < n):
181
+ raise ValueError(
182
+ f"fitting.primary_component is {self.primary_component}, "
183
+ f"but there are {n} components, numbered from 0."
184
+ )
185
+ for idx, comp in enumerate(self.components):
186
+ for key in ("tie_center", "tie_width", "amplitude_greater_than"):
187
+ other = getattr(comp, key)
188
+ if other is not None and (
189
+ isinstance(other, bool)
190
+ or not isinstance(other, (int, np.integer))
191
+ or not 0 <= other < n or other == idx):
192
+ raise ValueError(
193
+ f"fitting.components[{idx}].{key} is {other!r}. It "
194
+ f"has to be the index of another component, from "
195
+ f"0 to {n - 1}."
196
+ )
197
+ if comp.name is not None and (
198
+ not isinstance(comp.name, str) or not comp.name.strip()):
199
+ raise ValueError(
200
+ f"fitting.components[{idx}].name must be a non-empty "
201
+ f"string, got {comp.name!r}."
202
+ )
203
+ for key in ("tie_center", "tie_width", "amplitude_greater_than"):
204
+ for start in range(n):
205
+ index, chain = start, [start]
206
+ while getattr(self.components[index], key) is not None:
207
+ index = getattr(self.components[index], key)
208
+ if index in chain:
209
+ raise ValueError(
210
+ f"fitting.components {chain + [index]} make a loop of "
211
+ f"{key}, which no fit can meet. One component in a chain "
212
+ f"has to be left free.")
213
+ chain.append(index)
214
+ fainter = [comp.amplitude_greater_than for comp in self.components
215
+ if comp.amplitude_greater_than is not None]
216
+ shared = sorted({index for index in fainter if fainter.count(index) > 1})
217
+ if shared:
218
+ raise ValueError(
219
+ f"fitting.components {shared} are each held fainter than more than one "
220
+ f"component by amplitude_greater_than. A component can be held fainter "
221
+ f"than one other; chain them to hold it below several.")
222
+ names = [default_component_name(c.wavelength) if c.name is None
223
+ else c.name for c in self.components]
224
+ repeated = sorted({name for name in names if names.count(name) > 1})
225
+ if repeated:
226
+ raise ValueError(
227
+ f"Fitted components need distinct names, because the "
228
+ f"results are stored by name. Repeated: {repeated}. Give "
229
+ f"the components a 'name'."
230
+ )
231
+ else:
232
+ # Both settings need components; without them they would
233
+ # silently do nothing.
234
+ if self.primary_component != 0:
235
+ raise ValueError(
236
+ "fitting.primary_component picks one of the components, "
237
+ "and there are none."
238
+ )
239
+ if self.constrain_positive_intensity:
240
+ raise ValueError(
241
+ "fitting.constrain_positive_intensity is only applied to "
242
+ "multi-component fits, and there are no components."
243
+ )
244
+
245
+ @property
246
+ def n_components(self) -> int:
247
+ return max(len(self.components), 1)
248
+
249
+ @property
250
+ def is_single(self) -> bool:
251
+ return len(self.components) <= 1
252
+
253
+ @property
254
+ def n_full_params(self) -> int:
255
+ """Total stored parameters: 3 per component + 1 background."""
256
+ return 3 * self.n_components + 1
257
+
258
+ # Indices into the full parameter vector for the primary component
259
+ @property
260
+ def idx_peak(self) -> int:
261
+ return 3 * self.primary_component
262
+
263
+ @property
264
+ def idx_center(self) -> int:
265
+ return 3 * self.primary_component + 1
266
+
267
+ @property
268
+ def idx_sigma(self) -> int:
269
+ return 3 * self.primary_component + 2
270
+
271
+
272
+ def _tie_root(fit_config: FitConfig, key: str, index: int) -> int:
273
+ """
274
+ Free component at the end of the chain of `key` ties from component `index`.
275
+
276
+ Tying to a tied component is the same as tying to the one it is tied to:
277
+ for centres the rest-wavelength ratios multiply out to the ratio with the
278
+ last, and tied widths are all equal. FitConfig refuses loops, so the
279
+ chain ends.
280
+ """
281
+ while getattr(fit_config.components[index], key) is not None:
282
+ index = getattr(fit_config.components[index], key)
283
+ return index
284
+
285
+
286
+ # Fraction of the primary's amplitude that every other component starts at.
287
+ _GUESS_FRACTION = 0.15
288
+
289
+
290
+ def _start_ratio(wv: np.ndarray, prof: np.ndarray, guess: np.ndarray,
291
+ child: int, parent: int) -> float:
292
+ """
293
+ Starting amplitude ratio of a component held fainter than its parent.
294
+
295
+ The ratio is read from the spectrum above the guessed background, at the
296
+ two guessed centres, interpolated between the finite pixels. The guess
297
+ itself starts every component but the primary at the same fraction of
298
+ the primary, so two components held one below the other would start
299
+ equal, at the bound, and a primary held below another would start above
300
+ it. If the spectrum makes the child the brighter, `_GUESS_FRACTION` is
301
+ used, strictly inside the bounds. `child` and `parent` index the
302
+ amplitudes in the full `guess`. A centre in NaN or infinite pixels at an
303
+ end of the window has zero height, as background.
304
+ """
305
+ wv, prof = np.asarray(wv), np.asarray(prof)
306
+ finite = np.isfinite(prof)
307
+ if not finite.any():
308
+ return _GUESS_FRACTION
309
+ if len(wv) > 1 and wv[0] > wv[-1]:
310
+ wv, prof, finite = wv[::-1], prof[::-1], finite[::-1]
311
+ left = None if finite[0] else 0.0
312
+ right = None if finite[-1] else 0.0
313
+ wv, prof = _finite_pixels(wv, prof, finite)
314
+ height = prof - guess[-1]
315
+
316
+ def level(index):
317
+ return float(np.interp(guess[index + 1], wv, height, left=left, right=right))
318
+
319
+ child_level, parent_level = level(child), level(parent)
320
+ if parent_level > 0 and 0 < child_level / parent_level < 1:
321
+ return child_level / parent_level
322
+ return _GUESS_FRACTION
323
+
324
+
325
+ def _finite_pixels(wv: np.ndarray, prof: np.ndarray, finite: np.ndarray) -> tuple:
326
+ """Wavelengths and values where `finite` is True, the arrays themselves if it is everywhere."""
327
+ if finite.all():
328
+ return wv, prof
329
+ return wv[finite], prof[finite]
330
+
331
+
332
+ def _fit_finite(fit, wv: np.ndarray, prof: np.ndarray, sigma: np.ndarray | None,
333
+ kept: np.ndarray, min_pixels: int, start) -> tuple[np.ndarray, bool]:
334
+ """
335
+ Fit only the pixels of a spectrum marked in `kept`.
336
+
337
+ `fit(wv, prof, sigma)` fits a spectrum and returns the parameters and
338
+ whether it succeeded. `sigma` is None, or one uncertainty per pixel,
339
+ kept or left out with its pixel. A spectrum with every pixel kept is
340
+ fitted as it is. With fewer than `min_pixels` kept, the fit is not
341
+ tried, and `start` of the whole window, with the pixels left out set to
342
+ NaN, is returned as a failed fit.
343
+ """
344
+ if kept.all():
345
+ return fit(wv, prof, sigma)
346
+ if np.count_nonzero(kept) < min_pixels:
347
+ return np.asarray(start(wv, np.where(kept, prof, np.nan)), dtype=float), False
348
+ return fit(wv[kept], prof[kept], None if sigma is None else sigma[kept])
349
+
350
+
351
+ def _in_dependency_order(fainter_than: dict) -> list:
352
+ """
353
+ `(child, parent)` items of `fainter_than`, each parent before its children.
354
+
355
+ A child's amplitude is fitted as a fraction of its parent's, so the
356
+ parent's must be known first. This matters when a parent is itself the
357
+ child of a component listed after it.
358
+ """
359
+ def depth(child):
360
+ steps = 0
361
+ while child in fainter_than:
362
+ child = fainter_than[child]
363
+ steps += 1
364
+ return steps
365
+
366
+ return sorted(fainter_than.items(), key=lambda item: depth(item[0]))
367
+
368
+
369
+ # ---------------------------------------------------------------------------
370
+ # Single-component helpers
371
+ # ---------------------------------------------------------------------------
372
+
373
+ def _guess_params(wv: np.ndarray, prof: np.ndarray) -> list:
374
+ """
375
+ Starting peak, centre, width and background for a Gaussian fit.
376
+
377
+ The guesses are made robust to noise. The background is the median, as
378
+ most of a window is off the line; the minimum would sit below it by the
379
+ largest noise excursion. The line is found in the spectrum smoothed over
380
+ three pixels, so one noisy pixel cannot take it. Its width is that of
381
+ the run of pixels around it above half its height; the first and last
382
+ pixels above half maximum anywhere in the window would include noise far
383
+ from the line and start the width several times too wide. With those
384
+ cruder guesses, at a peak of two or three times the noise per pixel, the
385
+ fits ending hundreds of km/s away and the scatter of the fitted
386
+ velocities were both twice those from a good start.
387
+
388
+ Only the finite pixels are used. A spectrum with no finite pixel starts
389
+ at zero peak and background, at the first wavelength.
390
+ """
391
+ wv = np.asarray(wv)
392
+ prof = np.asarray(prof, dtype=float)
393
+ finite = np.isfinite(prof)
394
+ if not finite.any():
395
+ return [0.0, wv[0], (wv.max() - wv.min()) / 10, 0.0]
396
+ wv, prof = _finite_pixels(wv, prof, finite)
397
+ back = float(np.median(prof))
398
+ height = prof - back
399
+ smooth = np.convolve(height, np.ones(3) / 3, mode="same") if prof.size >= 3 else height
400
+ peak_idx = int(np.nanargmax(smooth))
401
+ peak = max(float(height[peak_idx]), float(smooth[peak_idx]), 0.0)
402
+ centre = wv[peak_idx]
403
+ if smooth[peak_idx] <= 0:
404
+ sigma = (wv.max() - wv.min()) / 10
405
+ else:
406
+ above = smooth >= 0.5 * smooth[peak_idx]
407
+ lo = hi = peak_idx
408
+ while lo > 0 and above[lo - 1]:
409
+ lo -= 1
410
+ while hi < len(above) - 1 and above[hi + 1]:
411
+ hi += 1
412
+ # Every pixel of the run is a pixel wide, ends included, so add one step.
413
+ step = abs(float(np.median(np.diff(wv)))) if len(wv) > 1 else 0.0
414
+ fwhm = abs(float(wv[hi] - wv[lo])) + step
415
+ sigma = (_fwhm_to_sigma(fwhm) if fwhm > 0
416
+ else (wv.max() - wv.min()) / 10)
417
+ return [peak, centre, sigma, back]
418
+
419
+
420
+ def _single_fit_scales(wv: np.ndarray, prof: np.ndarray) -> tuple[float, float, float]:
421
+ """
422
+ Wavelength offset, wavelength step and signal scale for a single-Gaussian fit.
423
+
424
+ In the cgs units of the spectra, a line's peak can be 1e13 and its centre
425
+ 2e-6 cm, thousands of widths from zero. The optimiser's convergence tests
426
+ are then set by the largest numbers, and a change in the last bits of the
427
+ data could move a fitted velocity by half a km/s. So the fit uses
428
+ wavelengths in pixels from the middle of the window and the signal
429
+ divided by its largest value, and the result is converted back. The
430
+ model is the same, so the fit is the same, in better-conditioned numbers.
431
+ """
432
+ offset = 0.5 * (float(np.min(wv)) + float(np.max(wv)))
433
+ step = float(np.median(np.abs(np.diff(wv)))) if len(wv) > 1 else 0.0
434
+ if not (np.isfinite(step) and step > 0):
435
+ step = 1.0
436
+ peak = float(np.max(np.abs(prof)))
437
+ scale = peak if np.isfinite(peak) and peak > 0 else 1.0
438
+ return offset, step, scale
439
+
440
+
441
+ def _single_fit_back(params, offset: float, step: float, scale: float) -> np.ndarray:
442
+ """Parameters in the units of :func:`_single_fit_scales`, converted to the spectrum's."""
443
+ params = np.asarray(params, dtype=float)
444
+ return np.array([params[0] * scale, params[1] * step + offset,
445
+ params[2] * step, params[3] * scale])
446
+
447
+
448
+ def _fit_one_mpfit(wv: np.ndarray, prof: np.ndarray,
449
+ max_iter: int = FitConfig.max_iter,
450
+ pixel: float | None = None,
451
+ sigma: np.ndarray | None = None,
452
+ poisson: bool = False) -> tuple[np.ndarray, bool]:
453
+ """Fit one spectrum with a Gaussian using mpfit.
454
+
455
+ Same model, initial guess and fallback as :func:`_fit_one`, with the
456
+ width held positive as on the multi-component mpfit path. `max_iter` is
457
+ passed to mpfit, which counts iterations directly. `sigma` is each
458
+ pixel's uncertainty; the residuals are divided by it. With `poisson`, the
459
+ spectrum is counts, fitted by their Poisson likelihood
460
+ (:func:`_poisson_residuals`), with the peak and background held at zero
461
+ or above so the model is too.
462
+
463
+ Returns the parameters and whether the fit succeeded; see
464
+ :func:`_mpfit_succeeded`.
465
+ """
466
+ offset, step, scale = _single_fit_scales(wv, prof)
467
+ if poisson:
468
+ # Leave counts unscaled, as their likelihood depends on their values.
469
+ scale = 1.0
470
+ x = (np.asarray(wv, dtype=float) - offset) / step
471
+ y = np.asarray(prof, dtype=float) / scale
472
+ p0 = np.asarray(_guess_params(x, y), dtype=float)
473
+ parinfo = [
474
+ {"value": p0[0]},
475
+ {"value": p0[1]},
476
+ {"value": p0[2], "limited": [1, 0], "limits": [1e-30, 0.0]},
477
+ {"value": p0[3]},
478
+ ]
479
+ if poisson:
480
+ for index in (0, 3):
481
+ p0[index] = max(p0[index], 0.0)
482
+ parinfo[index] = {"value": p0[index], "limited": [1, 0], "limits": [0.0, 0.0]}
483
+ functkw = {"x": x, "y": y, "n_components": 1,
484
+ "pixel": None if pixel is None else pixel / step,
485
+ "err": None if sigma is None else np.asarray(sigma, dtype=float) / scale,
486
+ "poisson": poisson}
487
+ try:
488
+ result = mpfit(_mpfit_residuals, p0, parinfo=parinfo,
489
+ functkw=functkw, quiet=True, maxiter=max_iter)
490
+ if result.status > 0:
491
+ params = _single_fit_back(result.params, offset, step, scale)
492
+ return params, _mpfit_succeeded(result.status, params)
493
+ except Exception:
494
+ pass
495
+ return _single_fit_back(p0, offset, step, scale), False
496
+
497
+
498
+ def _mpfit_succeeded(status: int, params: np.ndarray) -> bool:
499
+ """Whether an mpfit result counts as a successful fit.
500
+
501
+ Status 5 means mpfit ran out of iterations. scipy raises in that case
502
+ and the fit falls back to its initial guess, so it counts as failed here
503
+ too, even though mpfit returns its last parameters.
504
+ """
505
+ return status > 0 and status != 5 and bool(np.all(np.isfinite(params)))
506
+
507
+
508
+ def _fit_one_poisson(x: np.ndarray, counts: np.ndarray, p0, max_iter: int,
509
+ width: float | None, offset: float, step: float) -> tuple[np.ndarray, bool]:
510
+ """
511
+ Maximum Poisson likelihood fit of a single Gaussian; see :func:`_fit_one`.
512
+
513
+ `x` is in the pixel units of :func:`_single_fit_scales`, with pixels
514
+ `width` wide, and the counts are unscaled.
515
+ """
516
+ start = np.array(p0, dtype=float)
517
+ start[[0, 3]] = np.maximum(start[[0, 3]], 0.0)
518
+ lower = np.array([0.0, -np.inf, -np.inf, 0.0])
519
+
520
+ def residuals(params):
521
+ return _poisson_residuals(counts, _line_profile(x, *params, pixel=width))
522
+
523
+ try:
524
+ result = least_squares(residuals, start, bounds=(lower, np.inf), method="trf",
525
+ x_scale="jac", max_nfev=max_iter)
526
+ except Exception:
527
+ return _single_fit_back(start, offset, step, 1.0), False
528
+ succeeded = result.status > 0 and bool(np.all(np.isfinite(result.x)))
529
+ return _single_fit_back(result.x if succeeded else start, offset, step, 1.0), succeeded
530
+
531
+
532
+ def _fit_one(wv: np.ndarray, prof: np.ndarray,
533
+ max_iter: int = FitConfig.max_iter,
534
+ pixel: float | None = None,
535
+ sigma: np.ndarray | None = None,
536
+ poisson: bool = False) -> tuple[np.ndarray, bool]:
537
+ """Fit one spectrum with a Gaussian.
538
+
539
+ `max_iter` is an iteration count. curve_fit uses lm here, as there are no
540
+ bounds. lm counts every residual call against maxfev, including one per
541
+ parameter for each finite-difference Jacobian, so an iteration costs
542
+ len(p0) + 1 evaluations. With `pixel`, the Gaussian is averaged over
543
+ pixels that wide (:func:`_line_profile`). `sigma` is each pixel's
544
+ uncertainty; each pixel is weighted by one over its square.
545
+
546
+ With `poisson`, the spectrum is counts, fitted by their Poisson
547
+ likelihood (:func:`_poisson_residuals`). The peak and background are
548
+ held at zero or above so the model is too, which needs least_squares'
549
+ trf method. That counts only its own residual calls, so `max_iter` is
550
+ the cap as it is. Wavelengths are in pixels from the middle of the
551
+ window, as in the other fits, but the counts are not divided by their
552
+ largest value, as the likelihood depends on the counts themselves.
553
+
554
+ Returns the parameters and whether the fit succeeded. A failed fit,
555
+ including one that runs out of iterations, returns the initial guess.
556
+ """
557
+ offset, step, scale = _single_fit_scales(wv, prof)
558
+ if poisson:
559
+ # Leave counts unscaled, as their likelihood depends on their values.
560
+ scale = 1.0
561
+ x = (np.asarray(wv, dtype=float) - offset) / step
562
+ y = np.asarray(prof, dtype=float) / scale
563
+ p0 = _guess_params(x, y)
564
+ if poisson:
565
+ return _fit_one_poisson(x, y, p0, max_iter, None if pixel is None else pixel / step,
566
+ offset, step)
567
+ model = gaussian if pixel is None else (
568
+ lambda x, *params: pixel_mean_gaussians(x, *params, n_components=1,
569
+ pixel=pixel / step))
570
+ with warnings.catch_warnings():
571
+ warnings.simplefilter("ignore", OptimizeWarning)
572
+ try:
573
+ popt, _ = curve_fit(model, x, y, p0=p0,
574
+ sigma=None if sigma is None else np.asarray(sigma) / scale,
575
+ maxfev=max_iter * (len(p0) + 1))
576
+ params = _single_fit_back(popt, offset, step, scale)
577
+ return params, bool(np.all(np.isfinite(params)))
578
+ except:
579
+ return _single_fit_back(p0, offset, step, scale), False
580
+
581
+
582
+ # ---------------------------------------------------------------------------
583
+ # Multi-component helpers (scipy back-end -- fast, default)
584
+ # ---------------------------------------------------------------------------
585
+
586
+ def _build_scipy_multi(fit_config: FitConfig, pixel_angstrom: float | None = None):
587
+ """Build a tied multi-Gaussian model for `curve_fit`.
588
+
589
+ With `pixel_angstrom`, the Gaussians are averaged over pixels that wide
590
+ (:func:`_line_profile`).
591
+
592
+ The model takes centres and sigmas in Angstrom, so all free parameters
593
+ are within a few orders of magnitude of each other. In cgs the fit is
594
+ severely ill-conditioned.
595
+
596
+ Without bounds, the Levenberg-Marquardt (`lm`) method is used (fast, no
597
+ bounds). When any component sets `amplitude_greater_than`, the
598
+ constrained component's amplitude is fitted as a ratio in [0, 1] of its
599
+ parent's. That, or `constrain_positive_intensity`, sets bounds, and
600
+ `curve_fit` then uses the Trust Region Reflective (`trf`) method.
601
+
602
+ Returns
603
+ -------
604
+ model_func : callable
605
+ `model_func(x_angstrom, *free_params_angstrom) -> y`
606
+ free_to_full_A : callable
607
+ `free_to_full_A(free_params_A) -> full_params_A` (length 3*N+1)
608
+ n_free : int
609
+ free_indices : list[int]
610
+ ratio_spec : dict
611
+ `{free_position: parent_full_amplitude_index}` for ratio params.
612
+ bounds : tuple
613
+ Bounds for `curve_fit(..., bounds=...)`.
614
+ """
615
+ nc = fit_config.n_components
616
+ n_full = fit_config.n_full_params # 3*nc + 1
617
+
618
+ # Components whose amplitude is held below another's.
619
+ # amp_ratio_child[j] = i means amp_j = amp_i * ratio (ratio in [0,1]).
620
+ amp_ratio_child: dict[int, int] = {}
621
+ for i, comp in enumerate(fit_config.components):
622
+ if comp.amplitude_greater_than is not None:
623
+ j = comp.amplitude_greater_than
624
+ amp_ratio_child[j] = i
625
+
626
+ free_indices: list[int] = []
627
+ # tie_spec[full_idx] = (source_full_idx, factor), applied multiplicatively
628
+ tie_spec: dict[int, tuple[int, float]] = {}
629
+ # ratio_spec[free_position] = parent_full_amplitude_index
630
+ ratio_spec: dict[int, int] = {}
631
+
632
+ for i, comp in enumerate(fit_config.components):
633
+ base = 3 * i
634
+ # peak - always free; mark as ratio if constrained
635
+ if i in amp_ratio_child:
636
+ ratio_spec[len(free_indices)] = 3 * amp_ratio_child[i]
637
+ free_indices.append(base)
638
+
639
+ # centre
640
+ if comp.tie_center is not None:
641
+ src = _tie_root(fit_config, "tie_center", i)
642
+ # Tied centres share one velocity, and a velocity shifts a line in
643
+ # proportion to its wavelength, so the tie is the ratio of the rest
644
+ # wavelengths, not their separation. A fixed separation would give
645
+ # each component a different velocity: across an 8 Angstrom window
646
+ # near 195 Angstrom the end components would differ by (8 / 195) v,
647
+ # some 12 km/s at 300 km/s. The ratio is dimensionless, so it is the
648
+ # same in Angstrom or cm.
649
+ factor = float(comp.wavelength.to(u.cm).value
650
+ / fit_config.components[src].wavelength.to(u.cm).value)
651
+ tie_spec[base + 1] = (3 * src + 1, factor)
652
+ else:
653
+ free_indices.append(base + 1)
654
+
655
+ # sigma
656
+ if comp.tie_width is not None:
657
+ src = _tie_root(fit_config, "tie_width", i)
658
+ # Tied widths are equal. Thermal broadening scales with wavelength,
659
+ # but the instrumental width that dominates these windows does not.
660
+ tie_spec[base + 2] = (3 * src + 2, 1.0)
661
+ else:
662
+ free_indices.append(base + 2)
663
+
664
+ # background -- always free
665
+ free_indices.append(n_full - 1)
666
+
667
+ n_free = len(free_indices)
668
+
669
+ # Build per-parameter bounds (default: unbounded -> LM method).
670
+ # Any non-default bound triggers TRF method.
671
+ lower = np.full(n_free, -np.inf)
672
+ upper = np.full(n_free, np.inf)
673
+ for fp in ratio_spec:
674
+ lower[fp] = 0.0
675
+ upper[fp] = 1.0
676
+ # Enforce positive amplitudes during fitting (not post-hoc clipping)
677
+ if fit_config.constrain_positive_intensity:
678
+ for pos, fi in enumerate(free_indices):
679
+ if fi % 3 == 0 and fi < 3 * nc and pos not in ratio_spec:
680
+ lower[pos] = 0.0
681
+ has_bounds = ratio_spec or fit_config.constrain_positive_intensity
682
+ bounds = (lower, upper) if has_bounds else (-np.inf, np.inf)
683
+
684
+ # Order the ratios so parents come before their children.
685
+ by_child = {free_indices[fp]: fp for fp in ratio_spec}
686
+ ratio_order = [(by_child[child], parent) for child, parent in
687
+ _in_dependency_order({free_indices[fp]: parent
688
+ for fp, parent in ratio_spec.items()})]
689
+
690
+ def free_to_full_A(free_params):
691
+ full = np.empty(n_full)
692
+ for pos, fi in enumerate(free_indices):
693
+ full[fi] = free_params[pos]
694
+ # Convert ratio params -> absolute amplitudes
695
+ for fp, parent_idx in ratio_order:
696
+ child_idx = free_indices[fp]
697
+ full[child_idx] = full[parent_idx] * free_params[fp]
698
+ for fi, (src_fi, factor) in tie_spec.items():
699
+ full[fi] = full[src_fi] * factor
700
+ return full
701
+
702
+ def model_func(x, *free_params):
703
+ full = free_to_full_A(free_params)
704
+ return _line_profile(x, *full, n_components=nc, pixel=pixel_angstrom)
705
+
706
+ return model_func, free_to_full_A, n_free, free_indices, ratio_spec, bounds, has_bounds
707
+
708
+
709
+ def _n_free_params(fit_config: FitConfig | None) -> int:
710
+ """Number of parameters a fit adjusts: those not tied to another, and the background."""
711
+ if fit_config is None or fit_config.is_single:
712
+ return 4
713
+ return _build_scipy_multi(fit_config)[2]
714
+
715
+
716
+ def _fit_one_scipy_multi(wv_cm: np.ndarray, prof: np.ndarray,
717
+ fit_config: FitConfig,
718
+ model_func, free_to_full_A,
719
+ free_indices: list[int],
720
+ ratio_spec: dict, bounds,
721
+ has_bounds: bool,
722
+ sigma: np.ndarray | None = None,
723
+ poisson: bool = False) -> tuple[np.ndarray, bool]:
724
+ """Fit one spectrum with several Gaussians using scipy's curve_fit.
725
+
726
+ `wv_cm` is the wavelength axis in cm. The fit works in Angstrom and the
727
+ result is converted back to cm. `sigma` is each pixel's uncertainty;
728
+ each pixel is weighted by one over its square. With `poisson`, the
729
+ spectrum is counts, fitted by their Poisson likelihood
730
+ (:func:`_poisson_residuals`) with least_squares' trf method.
731
+
732
+ Returns the parameters and whether the fit succeeded. A failed fit
733
+ returns the initial guess.
734
+ """
735
+ CM_TO_A = 1e8
736
+
737
+ # Initial guess in cm (from shared helper)
738
+ p0_full_cm = _guess_multi_params(wv_cm, prof, fit_config)
739
+
740
+ # Convert centres & sigmas to A
741
+ p0_full_A = p0_full_cm.copy()
742
+ for i in range(fit_config.n_components):
743
+ p0_full_A[3 * i + 1] *= CM_TO_A # centre
744
+ p0_full_A[3 * i + 2] *= CM_TO_A # sigma
745
+
746
+ p0_free_A = p0_full_A[free_indices]
747
+
748
+ # Start constrained amplitudes as ratios read from the spectrum.
749
+ for free_pos, parent_idx in ratio_spec.items():
750
+ p0_free_A[free_pos] = _start_ratio(wv_cm, prof, p0_full_cm,
751
+ free_indices[free_pos], parent_idx)
752
+
753
+ wv_A = wv_cm * CM_TO_A
754
+
755
+ # Keep scipy's default tolerances. At 1e-4, lm stopped with a blend's
756
+ # centres still over a km/s from convergence: the centres are some 195
757
+ # Angstrom from zero, so a relative step of 1e-4 is 30 km/s. Cap function
758
+ # evaluations as a safety net. Use 'trf' when bounds are active and 'lm'
759
+ # otherwise; each takes a different keyword for the cap.
760
+ #
761
+ # fit_config.max_iter is an iteration count, so convert it to what each
762
+ # method counts. MINPACK's lm counts every residual call against maxfev,
763
+ # including the n_free calls for each forward-difference Jacobian, so an
764
+ # iteration costs n_free + 1 and the cap must scale with the problem or
765
+ # it shrinks as components are added. least_squares' trf counts only its
766
+ # own residual calls (Jacobian work goes in njev), so its cap is already
767
+ # an iteration count.
768
+ n_free = len(free_indices)
769
+ max_iter = fit_config.max_iter
770
+ if has_bounds:
771
+ fit_kwargs: dict = {
772
+ "method": "trf", "max_nfev": max_iter,
773
+ # Amplitudes reach ~1e11 while sigmas are ~0.03 Angstrom, some
774
+ # thirteen orders of magnitude apart, so step in variables scaled
775
+ # by the Jacobian. lm scales the same way internally, so only trf
776
+ # needs telling. On the blends tested this changed neither the
777
+ # fitted velocity nor the evaluation count; it guards against
778
+ # worse-conditioned windows rather than fixing an observed failure.
779
+ "x_scale": "jac",
780
+ }
781
+ else:
782
+ fit_kwargs: dict = {
783
+ "method": "lm", "maxfev": max_iter * (n_free + 1),
784
+ }
785
+
786
+ if poisson:
787
+ # Hold the background and every amplitude not fitted as a ratio at
788
+ # zero or above, so the model is too.
789
+ lower = np.array(bounds[0], dtype=float) * np.ones(n_free)
790
+ upper = np.array(bounds[1], dtype=float) * np.ones(n_free)
791
+ n_full = fit_config.n_full_params
792
+ for pos, index in enumerate(free_indices):
793
+ if (index % 3 == 0 and pos not in ratio_spec) or index == n_full - 1:
794
+ lower[pos] = max(lower[pos], 0.0)
795
+ start = np.clip(p0_free_A, lower, upper)
796
+ try:
797
+ result = least_squares(lambda p: _poisson_residuals(prof, model_func(wv_A, *p)),
798
+ start, bounds=(lower, upper), method="trf",
799
+ x_scale="jac", max_nfev=max_iter)
800
+ succeeded = result.status > 0 and bool(np.all(np.isfinite(result.x)))
801
+ popt_free_A = result.x if succeeded else start
802
+ except Exception:
803
+ popt_free_A = start
804
+ succeeded = False
805
+ else:
806
+ with warnings.catch_warnings():
807
+ warnings.simplefilter("ignore", OptimizeWarning)
808
+ try:
809
+ popt_free_A, _ = curve_fit(model_func, wv_A, prof, p0=p0_free_A,
810
+ sigma=sigma, bounds=bounds, **fit_kwargs)
811
+ succeeded = bool(np.all(np.isfinite(popt_free_A)))
812
+ except Exception:
813
+ popt_free_A = p0_free_A
814
+ succeeded = False
815
+
816
+ # Reconstruct full A vector, then convert centres & sigmas back to cm
817
+ full_A = free_to_full_A(popt_free_A)
818
+ full_cm = full_A.copy()
819
+ for i in range(fit_config.n_components):
820
+ full_cm[3 * i + 1] /= CM_TO_A # centre
821
+ full_cm[3 * i + 2] /= CM_TO_A # sigma
822
+
823
+ return full_cm, succeeded
824
+
825
+
826
+ # ---------------------------------------------------------------------------
827
+ # Multi-component helpers (mpfit back-end)
828
+ # ---------------------------------------------------------------------------
829
+
830
+ def _build_parinfo(fit_config: FitConfig, p0: np.ndarray,
831
+ ratio_params: dict | None = None) -> list[dict]:
832
+ """Build the mpfit `parinfo` list from a FitConfig and initial guess.
833
+
834
+ The full parameter vector is
835
+ `[peak0, centre0, sigma0, peak1, centre1, sigma1, ..., background]`.
836
+
837
+ Parameters
838
+ ----------
839
+ fit_config : FitConfig
840
+ Multi-component configuration, with ties and constraints.
841
+ p0 : np.ndarray
842
+ Initial guess, length `3*N + 1`.
843
+ ratio_params : dict, optional
844
+ `{child_full_amp_idx: parent_full_amp_idx}` for amplitudes fitted as
845
+ a ratio in [0, 1] of their parent's.
846
+
847
+ Returns
848
+ -------
849
+ parinfo : list[dict]
850
+ One dict per parameter, for `mpfit(..., parinfo=...)`.
851
+ """
852
+ nc = fit_config.n_components
853
+ if ratio_params is None:
854
+ ratio_params = {}
855
+ parinfo: list[dict] = []
856
+
857
+ for i, comp in enumerate(fit_config.components):
858
+ base = 3 * i
859
+
860
+ # --- peak (intensity) ---
861
+ if base in ratio_params:
862
+ # _fit_one_multi sets this for each spectrum; any value inside
863
+ # the bounds will do here.
864
+ ratio = _GUESS_FRACTION
865
+ peak_info: dict = {"value": ratio,
866
+ "limited": [1, 1], "limits": [0.0, 1.0]}
867
+ else:
868
+ peak_info = {"value": p0[base]}
869
+ if fit_config.constrain_positive_intensity:
870
+ peak_info["limited"] = [1, 0]
871
+ peak_info["limits"] = [0.0, 0.0]
872
+ parinfo.append(peak_info)
873
+
874
+ # --- centre ---
875
+ centre_info: dict = {"value": p0[base + 1]}
876
+ if comp.tie_center is not None:
877
+ src = _tie_root(fit_config, "tie_center", i)
878
+ # Ratio of rest wavelengths, so every tied component has the same
879
+ # velocity; see _build_scipy_multi.
880
+ factor = float(comp.wavelength.to(u.cm).value
881
+ / fit_config.components[src].wavelength.to(u.cm).value)
882
+ # mpfit tie expression references the parameter array p
883
+ centre_info["tied"] = f"p[{3 * src + 1}] * {factor!r}"
884
+ parinfo.append(centre_info)
885
+
886
+ # --- sigma (width) ---
887
+ sigma_info: dict = {"value": p0[base + 2]}
888
+ # Width must be strictly positive (avoid divide-by-zero in Gaussian)
889
+ sigma_info["limited"] = [1, 0]
890
+ sigma_info["limits"] = [1e-30, 0.0]
891
+ if comp.tie_width is not None:
892
+ src = _tie_root(fit_config, "tie_width", i)
893
+ sigma_info["tied"] = f"p[{3 * src + 2}]"
894
+ parinfo.append(sigma_info)
895
+
896
+ # --- background ---
897
+ bg_info: dict = {"value": p0[-1]}
898
+ parinfo.append(bg_info)
899
+
900
+ return parinfo
901
+
902
+
903
+ def _guess_multi_params(wv: np.ndarray, prof: np.ndarray,
904
+ fit_config: FitConfig) -> np.ndarray:
905
+ """
906
+ Initial guess for the full parameter vector.
907
+
908
+ Only the finite pixels are used. A spectrum with no finite pixel starts
909
+ at zero peak and background.
910
+ """
911
+ wv, prof = np.asarray(wv), np.asarray(prof)
912
+ if len(wv) > 1 and wv[0] > wv[-1]:
913
+ # The width and comb search below need increasing wavelengths.
914
+ wv, prof = wv[::-1], prof[::-1]
915
+ finite = np.isfinite(prof)
916
+ if finite.any():
917
+ wv, prof = _finite_pixels(wv, prof, finite)
918
+ back = float(prof.min())
919
+ prof_c = prof - back
920
+ else:
921
+ back = 0.0
922
+ prof_c = np.zeros(len(wv))
923
+ prof_c[prof_c < 0] = 0
924
+
925
+ peak = float(prof_c.max())
926
+ if peak == 0:
927
+ sigma = (wv.max() - wv.min()) / 10
928
+ else:
929
+ # Width of the feature containing the peak, not of everything above
930
+ # half maximum.
931
+ #
932
+ # In a blend, the first and last pixels above half maximum span the
933
+ # whole blend, not one line. Every component then starts several
934
+ # pixels wide, and the fit can settle there: on a seven-component EIS
935
+ # window the widths came out at 89 mA and 16 mA either side of a 28 mA
936
+ # instrumental floor, with a residual 45 percent of the peak and the
937
+ # requested line fitted at effectively zero. Walking out from the peak
938
+ # to half maximum measures the peak feature alone, and for a single
939
+ # line it matches the first and last pixels.
940
+ half_max = 0.5 * peak
941
+ above = prof_c >= half_max
942
+ peak_idx = int(np.nanargmax(prof_c))
943
+ lo = hi = peak_idx
944
+ while lo > 0 and above[lo - 1]:
945
+ lo -= 1
946
+ while hi < len(above) - 1 and above[hi + 1]:
947
+ hi += 1
948
+ if hi > lo:
949
+ sigma = _fwhm_to_sigma(wv[hi] - wv[lo])
950
+ else:
951
+ # Unresolved: the feature is one pixel wide, so take that as an
952
+ # upper bound on the width rather than a tenth of the window.
953
+ sigma = float(np.median(np.diff(wv))) if len(wv) > 1 else \
954
+ (wv.max() - wv.min()) / 10
955
+
956
+ # Estimate one shift of the primary centre, and start every other centre
957
+ # at its rest wavelength scaled by the same factor, as the tie enforces.
958
+ #
959
+ # The peak pixel belongs to whichever component dominates the window,
960
+ # which need not be the primary. Starting the primary there displaces it
961
+ # by the gap between the two, and as every tied centre is a fixed multiple
962
+ # of the primary's, the whole comb starts displaced by that gap. The
963
+ # optimiser does not reliably recover: a noiseless 7-component EIS window
964
+ # whose primary sat 0.14 Angstrom from the dominant line gave a 239 km/s
965
+ # centroid for lines at rest by construction, and moving the primary to a
966
+ # different component gave 451 km/s, each time very nearly the offset
967
+ # between that component and the brightest one.
968
+ #
969
+ # So match the whole comb against the profile. Assigning the peak pixel
970
+ # to the nearest rest wavelength only works while the shift is below half
971
+ # the spacing to the neighbouring component, a small velocity for a close
972
+ # blend: Fe XII 195.119 and 195.179 are 0.060 Angstrom apart, so beyond
973
+ # about 46 km/s it picks the wrong component and displaces the comb by a
974
+ # whole spacing, while the synthesis default allows +/- 300 km/s.
975
+ #
976
+ # Each trial shift is scored by the total profile height under the
977
+ # shifted comb, which uses the spacing pattern that one pixel lacks. The
978
+ # trial shifts cover the range that keeps the comb inside the observed
979
+ # window, on the wavelength grid itself, so no resolution is invented.
980
+ # With a single component the score is the profile at each grid point, so
981
+ # the best shift puts the centre on the brightest pixel.
982
+ rest_wl = np.array([c.wavelength.to(u.cm).value
983
+ for c in fit_config.components])
984
+ ref_wl = float(rest_wl[fit_config.primary_component])
985
+ if peak > 0:
986
+ # A trial shift moves the primary centre to ref_wl + shift and every
987
+ # other component to its rest wavelength times the same factor. The
988
+ # range keeps the whole comb inside the observed window; with all
989
+ # components at one wavelength it reduces to shifting the comb bodily.
990
+ lo = float(wv.min()) * ref_wl / float(rest_wl.min()) - ref_wl
991
+ hi = float(wv.max()) * ref_wl / float(rest_wl.max()) - ref_wl
992
+ step = float(np.median(np.diff(wv))) if len(wv) > 1 else 0.0
993
+ if hi > lo and step > 0:
994
+ trial = np.arange(lo, hi + 0.5 * step, step)
995
+ score = np.zeros(trial.size)
996
+ for r in rest_wl:
997
+ score += np.interp(r * (ref_wl + trial) / ref_wl, wv, prof_c,
998
+ left=0.0, right=0.0)
999
+ # Known limit: if the primary carries no flux, every alias that
1000
+ # puts some component on the one visible line scores the same, and
1001
+ # the data cannot say which component produced it. With amplitudes
1002
+ # free, all the flux in one component at one alias fits exactly as
1003
+ # well as all of it in another at the next, so no scoring rule
1004
+ # resolves it and the comb can start a spacing away. The velocity
1005
+ # asked for is then that of a line that is not there, so there is
1006
+ # nothing to recover.
1007
+ shift = float(trial[int(np.argmax(score))])
1008
+ else:
1009
+ # The comb is wider than the window, so no shift keeps all of it
1010
+ # inside. Fall back to the brightest pixel and the component
1011
+ # nearest to it, read as a Doppler factor.
1012
+ peak_wl = float(wv[np.nanargmax(prof_c)])
1013
+ nearest = float(rest_wl[np.argmin(np.abs(rest_wl - peak_wl))])
1014
+ shift = ref_wl * (peak_wl / nearest - 1.0)
1015
+ else:
1016
+ shift = 0.0
1017
+
1018
+ doppler = (ref_wl + shift) / ref_wl
1019
+ full_guess = np.zeros(fit_config.n_full_params)
1020
+ for i, comp in enumerate(fit_config.components):
1021
+ base = 3 * i
1022
+ full_guess[base] = peak if i == fit_config.primary_component else peak * 0.15
1023
+ full_guess[base + 1] = rest_wl[i] * doppler
1024
+ full_guess[base + 2] = sigma
1025
+ full_guess[-1] = back
1026
+ return full_guess
1027
+
1028
+
1029
+ def _mpfit_residuals(p, fjac=None, x=None, y=None, n_components=1,
1030
+ ratio_params=None, pixel=None, err=None, poisson=False):
1031
+ """Residual function in the form mpfit expects.
1032
+
1033
+ Must return `[status, residuals]`, with `status` 0 for success. `err` is
1034
+ each pixel's uncertainty; the residuals are divided by it. With
1035
+ `poisson`, `y` is counts and the residuals are those whose squares sum
1036
+ to the Poisson deviance (:func:`_poisson_residuals`).
1037
+ """
1038
+ p_eval = np.array(p, dtype=float)
1039
+ if ratio_params:
1040
+ for child_idx, parent_idx in _in_dependency_order(ratio_params):
1041
+ p_eval[child_idx] = p_eval[parent_idx] * p[child_idx]
1042
+ model = _line_profile(x, *p_eval, n_components=n_components, pixel=pixel)
1043
+ if poisson:
1044
+ return [0, _poisson_residuals(y, model)]
1045
+ residuals = y - model
1046
+ return [0, residuals if err is None else residuals / err]
1047
+
1048
+
1049
+ def _fit_one_multi(wv: np.ndarray, prof: np.ndarray,
1050
+ fit_config: FitConfig,
1051
+ parinfo_template: list[dict],
1052
+ ratio_params: dict | None = None,
1053
+ pixel: float | None = None,
1054
+ sigma: np.ndarray | None = None,
1055
+ poisson: bool = False) -> tuple[np.ndarray, bool]:
1056
+ """Fit one spectrum with several Gaussians using mpfit.
1057
+
1058
+ With `pixel`, the Gaussians are averaged over pixels that wide
1059
+ (:func:`_line_profile`). `sigma` is each pixel's uncertainty; the
1060
+ residuals are divided by it. With `poisson`, the spectrum is counts,
1061
+ fitted by their Poisson likelihood (:func:`_poisson_residuals`), with
1062
+ every amplitude and the background held at zero or above so the model is
1063
+ too.
1064
+
1065
+ Returns the full parameter vector (length `3*N + 1`), with ratio
1066
+ parameters converted back to absolute amplitudes, and whether the fit
1067
+ succeeded; see :func:`_mpfit_succeeded`.
1068
+ """
1069
+ p0 = _guess_multi_params(wv, prof, fit_config)
1070
+ p0_orig = p0.copy()
1071
+
1072
+ # Stamp current initial guesses into the parinfo dicts
1073
+ parinfo = []
1074
+ for i, pi in enumerate(parinfo_template):
1075
+ d = dict(pi)
1076
+ d["value"] = p0[i]
1077
+ parinfo.append(d)
1078
+
1079
+ # Convert absolute amplitudes to ratios for constrained params. Use the
1080
+ # original guesses, as a parent may already have been converted.
1081
+ if ratio_params:
1082
+ for child_idx, parent_idx in ratio_params.items():
1083
+ ratio = _start_ratio(wv, prof, p0_orig, child_idx, parent_idx)
1084
+ parinfo[child_idx]["value"] = ratio
1085
+ p0[child_idx] = ratio
1086
+
1087
+ if poisson:
1088
+ nc = fit_config.n_components
1089
+ held = [3 * i for i in range(nc) if 3 * i not in (ratio_params or {})] + [3 * nc]
1090
+ for index in held:
1091
+ p0[index] = max(p0[index], 0.0)
1092
+ parinfo[index].update({"value": p0[index], "limited": [1, 0], "limits": [0.0, 0.0]})
1093
+
1094
+ functkw = {"x": wv, "y": prof, "n_components": fit_config.n_components,
1095
+ "ratio_params": ratio_params, "pixel": pixel, "err": sigma,
1096
+ "poisson": poisson}
1097
+
1098
+ try:
1099
+ result = mpfit(_mpfit_residuals, p0, parinfo=parinfo,
1100
+ functkw=functkw, quiet=True,
1101
+ maxiter=fit_config.max_iter)
1102
+ if result.status > 0:
1103
+ out = np.asarray(result.params, dtype=float)
1104
+ # Convert ratios back to absolute amplitudes
1105
+ if ratio_params:
1106
+ for child_idx, parent_idx in _in_dependency_order(ratio_params):
1107
+ out[child_idx] = out[parent_idx] * result.params[child_idx]
1108
+ return out, _mpfit_succeeded(result.status, out)
1109
+ except Exception:
1110
+ pass
1111
+
1112
+ return p0_orig, False # fall back to initial guess (absolute amplitudes)
1113
+
1114
+
1115
+ # ---------------------------------------------------------------------------
1116
+ # Public fitting entry point
1117
+ # ---------------------------------------------------------------------------
1118
+ def _unmeasurable(params: np.ndarray, spectra: np.ndarray, wavelength: np.ndarray,
1119
+ n_components: int, kept: np.ndarray | None = None) -> np.ndarray:
1120
+ """
1121
+ Fits that cannot have measured a line, to be counted as failed.
1122
+
1123
+ Also makes the widths positive in place. A Gaussian does not depend on
1124
+ the sign of its width, so a fit with a negative width is kept with the
1125
+ sign flipped, which also flips the sign of the intensity computed from
1126
+ it. Only the pixels each fit kept are considered: those marked in
1127
+ `kept`, by default the finite ones. A flat spectrum, such as one with no
1128
+ photons, holds no line to fit, and a component wider than the window of
1129
+ kept pixels is background, not a line. A spectrum with no kept pixel
1130
+ counts as flat. Where the pixels at an end of the window were left out,
1131
+ a centre, tied or not, beyond the edge of the last kept pixel on that
1132
+ side was fitted with no data there.
1133
+ """
1134
+ widths = np.abs(params[..., 2:3 * n_components:3])
1135
+ params[..., 2:3 * n_components:3] = widths
1136
+ spectra = np.asarray(spectra)
1137
+ finite = np.isfinite(spectra) if kept is None else kept
1138
+ if not np.issubdtype(spectra.dtype, np.floating):
1139
+ if finite.all():
1140
+ return (np.all(spectra == spectra[..., :1], axis=-1)
1141
+ | np.any(widths > np.ptp(wavelength), axis=-1))
1142
+ spectra = spectra.astype(float)
1143
+ wavelength = np.asarray(wavelength)
1144
+ first, last = np.min(wavelength), np.max(wavelength)
1145
+ half_pixel = 0.5 * np.median(np.abs(np.diff(wavelength))) if wavelength.size > 1 else 0.0
1146
+ wavelength = np.broadcast_to(wavelength, spectra.shape)
1147
+
1148
+ def extent(values):
1149
+ return (np.max(values, axis=-1, where=finite, initial=-np.inf),
1150
+ np.min(values, axis=-1, where=finite, initial=np.inf))
1151
+
1152
+ highest, lowest = extent(spectra)
1153
+ flat = highest <= lowest
1154
+ longest, shortest = extent(wavelength)
1155
+ too_wide = np.any(widths > (longest - shortest)[..., np.newaxis], axis=-1)
1156
+ centres = params[..., 1:3 * n_components:3]
1157
+ below = ((shortest > first)[..., np.newaxis]
1158
+ & (centres < (shortest - half_pixel)[..., np.newaxis]))
1159
+ above = ((longest < last)[..., np.newaxis]
1160
+ & (centres > (longest + half_pixel)[..., np.newaxis]))
1161
+ return flat | too_wide | np.any(below | above, axis=-1)
1162
+
1163
+
1164
+ @overload
1165
+ def fit_cube_gauss(signal_cube: NDCube, n_jobs: int = -1,
1166
+ fit_config: FitConfig | None = None, *,
1167
+ return_failed: Literal[False] = False, pixel_mean: bool = False,
1168
+ uncertainty: np.ndarray | None = None, poisson: bool = False
1169
+ ) -> tuple[np.ndarray, list[u.Unit]]: ...
1170
+
1171
+
1172
+ @overload
1173
+ def fit_cube_gauss(signal_cube: NDCube, n_jobs: int = -1,
1174
+ fit_config: FitConfig | None = None, *,
1175
+ return_failed: Literal[True], pixel_mean: bool = False,
1176
+ uncertainty: np.ndarray | None = None, poisson: bool = False
1177
+ ) -> tuple[np.ndarray, list[u.Unit], np.ndarray]: ...
1178
+
1179
+
1180
+ def fit_cube_gauss(signal_cube: NDCube, n_jobs: int = -1,
1181
+ fit_config: FitConfig | None = None, *,
1182
+ return_failed: bool = False, pixel_mean: bool = False,
1183
+ uncertainty: np.ndarray | None = None, poisson: bool = False):
1184
+ """
1185
+ Fit a Gaussian, or several for a blend, on a flat background to every spectrum.
1186
+
1187
+ By default each Gaussian is evaluated at the centre of each wavelength
1188
+ pixel, as observers fit spectra. With `pixel_mean`, it is averaged over
1189
+ each pixel instead, which is what the pixel records. The two differ for
1190
+ a line not much wider than a pixel.
1191
+
1192
+ By default every pixel of a spectrum has the same weight. With
1193
+ `uncertainty`, each is weighted by one over its uncertainty squared, as
1194
+ eispac weights its fits. Only the ratios of the uncertainties within a
1195
+ spectrum matter, not their scale. With `poisson`, the spectra are counts,
1196
+ such as photons, and each is fitted by maximum Poisson likelihood
1197
+ instead. This needs no uncertainty, even for a pixel with none.
1198
+
1199
+ Parameters
1200
+ ----------
1201
+ signal_cube : NDCube
1202
+ Spectra, shaped (along the slit, slit positions, wavelength).
1203
+ n_jobs : int, optional
1204
+ Number of processes; -1 for one per CPU. Default -1.
1205
+ fit_config : FitConfig, optional
1206
+ Fit configuration. Default None, for one Gaussian.
1207
+ return_failed : bool, optional
1208
+ Also return which fits failed. Keyword only. Default False.
1209
+ pixel_mean : bool, optional
1210
+ Fit the Gaussians' mean over each pixel. Keyword only. Default False.
1211
+ uncertainty : np.ndarray, optional
1212
+ Uncertainty of every value in the cube, same shape as its data or
1213
+ broadcastable to it. A pixel whose uncertainty is NaN or positive
1214
+ infinity is left out. Where the value is finite, an uncertainty at or
1215
+ below zero, negative infinity included, is refused. If there are
1216
+ finite values but none has a finite uncertainty, the uncertainty is
1217
+ refused. Keyword only. Default None, for an unweighted fit.
1218
+ poisson : bool, optional
1219
+ Fit the spectra as counts by their Poisson likelihood, with every
1220
+ amplitude and the background held at zero or above. Each finite
1221
+ count must be zero or more. Not with `uncertainty`. Keyword only.
1222
+ Default False.
1223
+
1224
+ Returns
1225
+ -------
1226
+ data_array : np.ndarray
1227
+ Fitted values, shaped (along the slit, slit positions, parameters).
1228
+ The parameters are `[peak, centre, sigma, background]` for one
1229
+ Gaussian and `[peak0, centre0, sigma0, peak1, ..., background]` for
1230
+ several.
1231
+ units_list : list of Unit
1232
+ Unit of each parameter.
1233
+ failed : np.ndarray of bool
1234
+ True where the fit failed, shaped (along the slit, slit positions).
1235
+ This includes where the optimiser used up `max_iter`, and spectra
1236
+ with pixels left out, as given in the Notes. Only with
1237
+ `return_failed`.
1238
+
1239
+ Notes
1240
+ -----
1241
+ A pixel whose value is NaN or infinite is left out, and each spectrum is
1242
+ fitted to the pixels kept. With `uncertainty`, so is a pixel whose
1243
+ uncertainty is NaN or positive infinity.
1244
+ Such a spectrum is a failed fit if fewer pixels are kept than free
1245
+ parameters, or if the pixels at an end of the window were left out and
1246
+ a fitted centre lies more than half a pixel beyond the outermost kept
1247
+ pixel on that side. As for every spectrum, it is also a failed fit if
1248
+ its kept pixels are flat or a fitted width is more than their span.
1249
+ """
1250
+ n_slit, n_scan, _ = signal_cube.shape
1251
+ wv = signal_cube.axis_world_coords_values(2)[0].cgs # wavelength axis
1252
+
1253
+ # A component outside the window has no line to fit, and would come back
1254
+ # at its guess with no spread, like a perfect measurement.
1255
+ if fit_config is not None and not fit_config.is_single:
1256
+ for idx, component in enumerate(fit_config.components):
1257
+ if not wv.min() <= component.wavelength.to(wv.unit) <= wv.max():
1258
+ raise ValueError(
1259
+ f"fitting.components[{idx}] is at {component.wavelength}, outside the "
1260
+ f"observed window, {wv.min().to(u.AA):.3f} to {wv.max().to(u.AA):.3f}, "
1261
+ f"so there is no line of it to fit. Check its wavelength.")
1262
+
1263
+ # The iteration limit applies to every path. Without a fitting block
1264
+ # there is no FitConfig, so use its default.
1265
+ max_iter = FitConfig.max_iter if fit_config is None else fit_config.max_iter
1266
+ # Pixel width in cm, the unit the fits use for wavelength.
1267
+ pixel = spectral_pixel_width(signal_cube).to_value(wv.unit) if pixel_mean else None
1268
+
1269
+ if poisson and uncertainty is not None:
1270
+ raise ValueError("A Poisson fit needs no uncertainty: give poisson or uncertainty, "
1271
+ "not both.")
1272
+ # Pixels the fits keep: those with a finite value and, if given, a finite uncertainty.
1273
+ kept = np.isfinite(signal_cube.data)
1274
+ if poisson and np.any(kept & (signal_cube.data < 0)):
1275
+ raise ValueError("A Poisson fit is of counts, which are zero or more.")
1276
+ if uncertainty is not None:
1277
+ try:
1278
+ uncertainty = np.broadcast_to(np.asarray(uncertainty, dtype=float),
1279
+ signal_cube.data.shape)
1280
+ except ValueError:
1281
+ raise ValueError(
1282
+ f"The uncertainty, shaped {np.shape(uncertainty)}, does not match the "
1283
+ f"spectra, shaped {signal_cube.data.shape}.") from None
1284
+ if np.any(kept & (uncertainty <= 0)):
1285
+ raise ValueError("The uncertainty of a finite value must be above zero, or NaN "
1286
+ "to leave that pixel out, as each pixel is weighted by one over "
1287
+ "its square.")
1288
+ finite_uncertainty = np.isfinite(uncertainty)
1289
+ if kept.any() and not np.any(kept & finite_uncertainty):
1290
+ raise ValueError("No finite value has a finite uncertainty, so there is nothing "
1291
+ "to weight the fits by.")
1292
+ kept &= finite_uncertainty
1293
+
1294
+ min_pixels = _n_free_params(fit_config)
1295
+
1296
+ def _rows():
1297
+ """Each row along the slit, with its uncertainties and the pixels kept."""
1298
+ for i in range(n_slit):
1299
+ yield (signal_cube.data[i], None if uncertainty is None else uncertainty[i],
1300
+ kept[i])
1301
+
1302
+ if fit_config is None or fit_config.is_single:
1303
+ # One Gaussian on a background, with its own fast fit.
1304
+ use_mpfit = fit_config is not None and fit_config.backend == "mpfit"
1305
+ fit_one = _fit_one_mpfit if use_mpfit else _fit_one
1306
+
1307
+ def _fit(wave, prof, sigma):
1308
+ return fit_one(wave, prof, max_iter, pixel, sigma, poisson)
1309
+
1310
+ _start = _guess_params
1311
+ n_components, n_params = 1, 4
1312
+ description = "Fit chunks"
1313
+ else:
1314
+ n_components, n_params = fit_config.n_components, fit_config.n_full_params
1315
+ description = "Fit chunks (multi)"
1316
+ if fit_config.backend != "mpfit":
1317
+ # scipy (default, fast) supports all constraints, positive
1318
+ # intensity and amplitude ratio, through TRF bounds: LM when
1319
+ # unconstrained, TRF when bounds are active.
1320
+ (model_func, free_to_full, n_free,
1321
+ free_indices, ratio_spec, bounds, has_bounds) = _build_scipy_multi(
1322
+ fit_config, None if pixel is None else pixel * 1e8)
1323
+
1324
+ def _fit(wave, prof, sigma):
1325
+ return _fit_one_scipy_multi(wave, prof, fit_config, model_func, free_to_full,
1326
+ free_indices, ratio_spec, bounds, has_bounds,
1327
+ sigma, poisson)
1328
+
1329
+ else:
1330
+ # mpfit with full parinfo (slower, supports hard bounds)
1331
+ # Build ratio_params for amplitude ordering constraint
1332
+ ratio_params: dict[int, int] = {}
1333
+ for i, comp in enumerate(fit_config.components):
1334
+ if comp.amplitude_greater_than is not None:
1335
+ j = comp.amplitude_greater_than
1336
+ ratio_params[3 * j] = 3 * i
1337
+ ratio_params = ratio_params or None
1338
+
1339
+ p0_template = _guess_multi_params(wv.value, signal_cube.data[0, 0], fit_config)
1340
+ parinfo_template = _build_parinfo(fit_config, p0_template, ratio_params)
1341
+
1342
+ def _fit(wave, prof, sigma):
1343
+ return _fit_one_multi(wave, prof, fit_config, parinfo_template, ratio_params,
1344
+ pixel, sigma, poisson)
1345
+
1346
+ def _start(wave, prof):
1347
+ return _guess_multi_params(wave, prof, fit_config)
1348
+
1349
+ def _fit_block(spec_block, unc_block, kept_block):
1350
+ results = np.empty((spec_block.shape[0], n_params))
1351
+ succeeded = np.empty(spec_block.shape[0], dtype=bool)
1352
+ for i in range(spec_block.shape[0]):
1353
+ results[i], succeeded[i] = _fit_finite(
1354
+ _fit, wv.value, spec_block[i],
1355
+ None if unc_block is None else unc_block[i], kept_block[i], min_pixels,
1356
+ _start)
1357
+ return results, succeeded
1358
+
1359
+ with tqdm_joblib(tqdm(total=n_slit, desc=description, leave=False)):
1360
+ results = Parallel(n_jobs=n_jobs)(
1361
+ delayed(_fit_block)(*row) for row in _rows()
1362
+ )
1363
+
1364
+ data_array = np.stack([r[0] for r in results], axis=0)
1365
+ failed = ~np.stack([r[1] for r in results], axis=0)
1366
+ failed |= _unmeasurable(data_array, signal_cube.data, wv.value, n_components, kept)
1367
+
1368
+ # Amplitude, centre and width of each component, then the background.
1369
+ units_list = [signal_cube.unit, wv.unit, wv.unit] * n_components + [signal_cube.unit]
1370
+
1371
+ if return_failed:
1372
+ return data_array, units_list, failed
1373
+ return data_array, units_list
1374
+
1375
+
1376
+ # ---------------------------------------------------------------------------
1377
+ # Results by component
1378
+ # ---------------------------------------------------------------------------
1379
+
1380
+ def component_names(fit_config: FitConfig | None,
1381
+ rest_wavelength: u.Quantity) -> list[str]:
1382
+ """
1383
+ Names of the fitted components, in fit order.
1384
+
1385
+ Parameters
1386
+ ----------
1387
+ fit_config : FitConfig or None
1388
+ Fit configuration. A single-Gaussian fit has one component.
1389
+ rest_wavelength : u.Quantity
1390
+ Rest wavelength of the line, used to name a single-Gaussian fit.
1391
+
1392
+ Returns
1393
+ -------
1394
+ list of str
1395
+ """
1396
+ if fit_config is None or fit_config.is_single:
1397
+ return [default_component_name(rest_wavelength)]
1398
+ return [default_component_name(c.wavelength) if c.name is None else c.name
1399
+ for c in fit_config.components]
1400
+
1401
+
1402
+ def spectral_pixel_width(cube: NDCube) -> u.Quantity:
1403
+ """Width of one spectral pixel, above zero, of a cube with wavelength on its last axis."""
1404
+ wavelength = u.Quantity(cube.axis_world_coords_values(2)[0]).to(u.cm)
1405
+ return abs(wavelength[1] - wavelength[0])
1406
+
1407
+
1408
+ def fit_quantities(fit_data: np.ndarray, units: list,
1409
+ wavelength_step: u.Quantity, rest_wavelength: u.Quantity,
1410
+ fit_config: FitConfig | None = None) -> dict:
1411
+ """
1412
+ Intensity, velocity and width of every fitted component, by name.
1413
+
1414
+ Parameters
1415
+ ----------
1416
+ fit_data : np.ndarray
1417
+ Fitted parameters with the parameter axis last, as from
1418
+ :func:`fit_cube_gauss`.
1419
+ units : list of Unit
1420
+ One unit per parameter, as from :func:`fit_cube_gauss`.
1421
+ wavelength_step : u.Quantity
1422
+ Width of one spectral pixel; its sign is ignored.
1423
+ rest_wavelength : u.Quantity
1424
+ Rest wavelength of a single-Gaussian fit. With components, each uses
1425
+ its own.
1426
+ fit_config : FitConfig, optional
1427
+ Fit configuration; None for a single Gaussian.
1428
+
1429
+ Returns
1430
+ -------
1431
+ dict
1432
+ `components` maps each component name to `intensity`, `velocity` and
1433
+ `width`, and `background` holds the fitted background. Each is a
1434
+ Quantity shaped like `fit_data` without its last axis. `intensity` is
1435
+ the fitted Gaussian summed over spectral pixels, so it is in counts,
1436
+ like the total signal maps. `velocity` is relative to the component's
1437
+ rest wavelength, and `width` is the Gaussian sigma.
1438
+ """
1439
+ names = component_names(fit_config, rest_wavelength)
1440
+ if fit_config is None or fit_config.is_single:
1441
+ rest = [rest_wavelength]
1442
+ else:
1443
+ rest = [c.wavelength for c in fit_config.components]
1444
+
1445
+ components = {}
1446
+ for i, (name, lam0) in enumerate(zip(names, rest)):
1447
+ peak = fit_data[..., 3 * i] * units[3 * i]
1448
+ centre = fit_data[..., 3 * i + 1] * units[3 * i + 1]
1449
+ sigma = fit_data[..., 3 * i + 2] * units[3 * i + 2]
1450
+ pixels = (sigma / abs(wavelength_step)).to(u.dimensionless_unscaled)
1451
+ components[name] = {
1452
+ "intensity": np.sqrt(2 * np.pi) * peak * pixels * u.pix,
1453
+ "velocity": ((centre - lam0) / lam0 * const.c).to(u.km / u.s),
1454
+ "width": sigma.to(u.AA),
1455
+ }
1456
+ return {"components": components,
1457
+ "background": fit_data[..., -1] * units[-1]}
1458
+
1459
+
1460
+ def summarise_fits(fit_data: np.ndarray, failed: np.ndarray, units: list,
1461
+ wavelength_step: u.Quantity, rest_wavelength: u.Quantity,
1462
+ fit_config: FitConfig | None = None) -> dict:
1463
+ """
1464
+ Statistics of the Monte Carlo fits, per parameter and per component.
1465
+
1466
+ Failed fits are left out of every mean and standard deviation. A pixel
1467
+ whose fits all failed has NaN statistics. The intensity statistics are
1468
+ taken over each iteration's intensity, so they account for the peak and
1469
+ width moving together, which the per-parameter statistics cannot.
1470
+
1471
+ Parameters
1472
+ ----------
1473
+ fit_data : np.ndarray
1474
+ Shape `(n_iter, n_slit, n_scan, n_params)`.
1475
+ failed : np.ndarray of bool
1476
+ Shape `(n_iter, n_slit, n_scan)`, True where a fit failed.
1477
+ units, wavelength_step, rest_wavelength, fit_config
1478
+ As for :func:`fit_quantities`. `fit_config.bessel_correction` makes
1479
+ the standard deviations divide by n - 1 rather than n, and
1480
+ `fit_config.save_iterations` keeps `fit_data` and `failed`.
1481
+
1482
+ Returns
1483
+ -------
1484
+ dict
1485
+ `first_fit_data` (the first iteration, failed or not), `mean_data`,
1486
+ `std_data` and `units`, per parameter, and:
1487
+
1488
+ - `components`: for each component name, its `rest_wavelength`,
1489
+ `tied` (names of the components its `velocity` and `width` are
1490
+ tied to, or None), and `intensity`, `velocity` and `width`, each
1491
+ with `first`, `mean` and `std` maps. `first` is NaN where the
1492
+ first fit failed.
1493
+ - `background`: `first`, `mean` and `std` maps.
1494
+ - `primary_component`: name of the primary component.
1495
+ - `failed_fits`: number of failed fits in each pixel.
1496
+ - `n_iterations`: number of fits in each pixel.
1497
+ - `bessel_correction`: whether the standard deviations divide by
1498
+ n - 1.
1499
+ - `iterations`: `fit_data` and `failed`, only when
1500
+ `fit_config.save_iterations` is set.
1501
+ """
1502
+ bessel = fit_config is not None and fit_config.bessel_correction
1503
+ ddof = 1 if bessel else 0
1504
+
1505
+ def _stats(values, leave_out):
1506
+ kept = np.where(leave_out, np.nan, values)
1507
+ with warnings.catch_warnings():
1508
+ # A pixel with no successful fit, or only one under Bessel's
1509
+ # correction, has no statistic, and NaN is the right answer.
1510
+ warnings.simplefilter("ignore", RuntimeWarning)
1511
+ return (kept[0], np.nanmean(kept, axis=0),
1512
+ np.nanstd(kept, axis=0, ddof=ddof))
1513
+
1514
+ _, mean_data, std_data = _stats(fit_data, failed[..., np.newaxis])
1515
+
1516
+ quantities = fit_quantities(fit_data, units, wavelength_step,
1517
+ rest_wavelength, fit_config)
1518
+ names = list(quantities["components"])
1519
+ configured = ([None] if fit_config is None or fit_config.is_single
1520
+ else fit_config.components)
1521
+
1522
+ def _summary(q):
1523
+ first, mean, std = _stats(q.value, failed)
1524
+ return {"first": first * q.unit, "mean": mean * q.unit,
1525
+ "std": std * q.unit}
1526
+
1527
+ components = {}
1528
+ for name, comp, values in zip(names, configured,
1529
+ quantities["components"].values()):
1530
+ components[name] = {
1531
+ "rest_wavelength": rest_wavelength if comp is None else comp.wavelength,
1532
+ "tied": {
1533
+ "velocity": (None if comp is None or comp.tie_center is None
1534
+ else names[comp.tie_center]),
1535
+ "width": (None if comp is None or comp.tie_width is None
1536
+ else names[comp.tie_width]),
1537
+ },
1538
+ **{key: _summary(values[key])
1539
+ for key in ("intensity", "velocity", "width")},
1540
+ }
1541
+
1542
+ summary = {
1543
+ "first_fit_data": fit_data[0],
1544
+ "mean_data": mean_data,
1545
+ "std_data": std_data,
1546
+ "units": units,
1547
+ "components": components,
1548
+ "background": _summary(quantities["background"]),
1549
+ "primary_component": names[0 if fit_config is None or fit_config.is_single
1550
+ else fit_config.primary_component],
1551
+ "failed_fits": np.count_nonzero(failed, axis=0),
1552
+ "n_iterations": fit_data.shape[0],
1553
+ "bessel_correction": bessel,
1554
+ }
1555
+ if fit_config is not None and fit_config.save_iterations:
1556
+ summary["iterations"] = {"fit_data": fit_data, "failed": failed}
1557
+ return summary
1558
+
1559
+
1560
+ def ground_truth_summary(cube: NDCube, fit_config: FitConfig | None = None,
1561
+ n_jobs: int = -1, *,
1562
+ uncertainty: np.ndarray | None = None) -> dict:
1563
+ """
1564
+ Fit the noiseless cube and return each component's velocity and width.
1565
+
1566
+ Parameters
1567
+ ----------
1568
+ cube : NDCube
1569
+ Cube before the instrument, with `rest_wav` in its metadata.
1570
+ fit_config : FitConfig, optional
1571
+ Fit configuration; None for a single Gaussian.
1572
+ n_jobs : int
1573
+ Joblib parallelism.
1574
+ uncertainty : np.ndarray, optional
1575
+ Each pixel's uncertainty, to weight the fit like the measured
1576
+ spectra, as for :func:`fit_cube_gauss`. Keyword only. Default None,
1577
+ for an unweighted fit.
1578
+
1579
+ Returns
1580
+ -------
1581
+ dict
1582
+ `fit_truth_data` and `fit_truth_units` as from
1583
+ :func:`fit_cube_gauss`, `failed` (True where the fit failed), and
1584
+ `components`: for each component name, `velocity` and `width` maps,
1585
+ NaN where the fit failed. There is no intensity, because the cube is
1586
+ in the units of the synthesis rather than in counts.
1587
+ """
1588
+ # The cube holds the spectrum averaged over each pixel, so the truth is
1589
+ # fitted with pixel-averaged Gaussians. Fitted at the pixel centres, as
1590
+ # the noisy spectra are, a line not much wider than a pixel comes out
1591
+ # pulled toward the middle of its pixel and too wide, and the truth would
1592
+ # hide the same error in the noisy fits.
1593
+ data, units, failed = fit_cube_gauss(cube, n_jobs=n_jobs,
1594
+ fit_config=fit_config,
1595
+ return_failed=True, pixel_mean=True,
1596
+ uncertainty=uncertainty)
1597
+ quantities = fit_quantities(data, units, spectral_pixel_width(cube),
1598
+ cube.meta["rest_wav"], fit_config)
1599
+ components = {
1600
+ name: {key: np.where(failed, np.nan, values[key].value) * values[key].unit
1601
+ for key in ("velocity", "width")}
1602
+ for name, values in quantities["components"].items()
1603
+ }
1604
+ return {"fit_truth_data": data, "fit_truth_units": units,
1605
+ "failed": failed, "components": components}
1606
+
1607
+
1608
+ def velocity_from_fit(fit_arr: u.Quantity | np.ndarray, wl0: u.Quantity,
1609
+ n_jobs: int = -1, fit_config: FitConfig | None = None) -> u.Quantity:
1610
+ """
1611
+ Line-of-sight velocity of each fitted line from its centre.
1612
+
1613
+ A positive velocity is a redshift, away from the observer.
1614
+
1615
+ Parameters
1616
+ ----------
1617
+ fit_arr : np.ndarray or u.Quantity
1618
+ Fitted values from `fit_cube_gauss`, with the parameters on the last
1619
+ axis.
1620
+ wl0 : u.Quantity
1621
+ Rest wavelength the velocity is measured from.
1622
+ n_jobs : int, optional
1623
+ Number of processes; -1 for one per CPU. Default -1.
1624
+ fit_config : FitConfig, optional
1625
+ Fit configuration of a blend, which gives the parameter holding the
1626
+ primary component's centre.
1627
+
1628
+ Returns
1629
+ -------
1630
+ u.Quantity
1631
+ Velocity in each pixel, in cm/s.
1632
+ """
1633
+ idx = 1 if (fit_config is None or fit_config.is_single) else fit_config.idx_center
1634
+ centres_raw = fit_arr[..., idx] # (n_slit, n_scan)
1635
+ # Ensure we have a pure Quantity array
1636
+ if isinstance(centres_raw, u.Quantity):
1637
+ centres = centres_raw.to(wl0.unit)
1638
+ elif np.asarray(centres_raw).dtype != object:
1639
+ # fit_cube_gauss fits in the cube's wavelengths in cgs.
1640
+ centres = u.Quantity(centres_raw, u.cm).to(wl0.unit)
1641
+ else: # object array of Quantity scalars
1642
+ get_val = np.vectorize(lambda q: q.to_value(wl0.unit))
1643
+ centres = u.Quantity(get_val(centres_raw), wl0.unit)
1644
+
1645
+ n_rows = centres.shape[0]
1646
+
1647
+ def _one_row(i):
1648
+ return ((centres[i] - wl0) / wl0 * const.c).to(u.cm / u.s).value
1649
+
1650
+ with tqdm_joblib(tqdm(total=n_rows, desc="Velocity calc", leave=False)):
1651
+ v_val = np.array(
1652
+ Parallel(n_jobs=n_jobs)(
1653
+ delayed(_one_row)(i) for i in range(n_rows)
1654
+ )
1655
+ )
1656
+
1657
+ v = v_val * (u.cm / u.s)
1658
+ return v
1659
+
1660
+
1661
+ def width_from_fit(fit_arr: u.Quantity | np.ndarray, n_jobs: int = -1,
1662
+ fit_config: FitConfig | None = None) -> u.Quantity:
1663
+ """
1664
+ Width of each fitted line: its Gaussian sigma, in wavelength.
1665
+
1666
+ Parameters
1667
+ ----------
1668
+ fit_arr : np.ndarray or u.Quantity
1669
+ Fitted values from `fit_cube_gauss`, with the parameters on the last
1670
+ axis.
1671
+ n_jobs : int, optional
1672
+ Not used; kept so existing calls still work.
1673
+ fit_config : FitConfig, optional
1674
+ Fit configuration of a blend, which gives the parameter holding the
1675
+ primary component's width.
1676
+
1677
+ Returns
1678
+ -------
1679
+ u.Quantity
1680
+ Width in each pixel: in cm for a plain array, as `fit_cube_gauss`
1681
+ returns, or in the unit of `fit_arr` for quantities.
1682
+ """
1683
+ idx = 2 if (fit_config is None or fit_config.is_single) else fit_config.idx_sigma
1684
+ widths_raw = fit_arr[..., idx] # (n_slit, n_scan)
1685
+ # Ensure we have a pure Quantity array
1686
+ if isinstance(widths_raw, u.Quantity):
1687
+ widths = widths_raw
1688
+ elif np.asarray(widths_raw).dtype != object:
1689
+ widths = u.Quantity(widths_raw, u.cm)
1690
+ else: # object array of Quantity scalars
1691
+ get_val = np.vectorize(lambda q: q.value)
1692
+ get_unit = widths_raw.flat[0].unit # Get unit from first element
1693
+ widths = u.Quantity(get_val(widths_raw), get_unit)
1694
+
1695
+ return widths
1696
+
1697
+
1698
+ def analyse(fits_all: u.Quantity | np.ndarray, v_true: u.Quantity, wl0: u.Quantity,
1699
+ fit_config: FitConfig | None = None) -> dict:
1700
+ """
1701
+ Mean and scatter of the velocity and width over Monte Carlo iterations.
1702
+
1703
+ Parameters
1704
+ ----------
1705
+ fits_all : np.ndarray or u.Quantity
1706
+ Fits of every iteration, with the iterations on the first axis and
1707
+ the parameters on the last.
1708
+ v_true : u.Quantity
1709
+ True velocity, for comparison.
1710
+ wl0 : u.Quantity
1711
+ Rest wavelength the velocity is measured from.
1712
+ fit_config : FitConfig, optional
1713
+ Fit configuration of a blend.
1714
+
1715
+ Returns
1716
+ -------
1717
+ dict
1718
+ `v_mean`, `v_std`, `w_mean` and `w_std`: mean and standard deviation
1719
+ of the velocity and width over the iterations. `v_err`: true
1720
+ velocity minus the mean. `v_samples` and `w_samples`: every
1721
+ iteration's values. `v_true`: the true velocity.
1722
+ """
1723
+ v_all = velocity_from_fit(fits_all, wl0, fit_config=fit_config)
1724
+ w_all = width_from_fit(fits_all, fit_config=fit_config)
1725
+ return {
1726
+ "v_mean": v_all.mean(axis=0),
1727
+ "v_std": v_all.std(axis=0),
1728
+ "v_err": v_true - v_all.mean(axis=0),
1729
+ "v_samples": v_all,
1730
+ "v_true": v_true,
1731
+ "w_mean": w_all.mean(axis=0),
1732
+ "w_std": w_all.std(axis=0),
1733
+ "w_samples": w_all,
1734
+ }