enchase 2.2.0__tar.gz → 2.3.0__tar.gz

{enchase-2.2.0/enchase.egg-info → enchase-2.3.0}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: enchase
-Version: 2.2.0
+Version: 2.3.0
 Summary: enCHASE: calibration and analysis pipeline for CHASE/HIS solar spectroscopy (TUI + SDK + CLI)
 Author: Waleed Ajmal
 License: MIT
-Project-URL: Homepage, https://github.com/Majboor/enchase
-Project-URL: Repository, https://github.com/Majboor/enchase
-Project-URL: Changelog, https://github.com/Majboor/enchase/blob/main/CHANGELOG.md
+Project-URL: Homepage, https://github.com/waleedsworld/enchase
+Project-URL: Repository, https://github.com/waleedsworld/enchase
+Project-URL: Changelog, https://github.com/waleedsworld/enchase/blob/main/CHANGELOG.md
 Keywords: solar,CHASE,HIS,spectroscopy,flare,calibration,astronomy
 Classifier: Programming Language :: Python :: 3
 Classifier: License :: OSI Approved :: MIT License
@@ -45,13 +45,13 @@ Dynamic: license-file
 
 Calibration and flare analysis for CHASE/HIS solar spectroscopy. Install one package, point it at data, get aligned cubes, animations, contrast profiles, and temperature maps.
 
-[![tests](https://github.com/Majboor/enchase/actions/workflows/test.yml/badge.svg)](https://github.com/Majboor/enchase/actions/workflows/test.yml)
+[![tests](https://github.com/waleedsworld/enchase/actions/workflows/test.yml/badge.svg)](https://github.com/waleedsworld/enchase/actions/workflows/test.yml)
 [![PyPI](https://img.shields.io/pypi/v/enchase)](https://pypi.org/project/enchase/)
 ![python](https://img.shields.io/badge/python-3.9%2B-blue)
 ![license](https://img.shields.io/badge/license-MIT-green)
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/Majboor/enchase/main/assets/flare.gif" width="760" alt="Stabilised 2-panel animation of the 2023-03-29 X1.2 flare"><br>
+  <img src="https://raw.githubusercontent.com/waleedsworld/enchase/main/assets/flare.gif" width="760" alt="Stabilised 2-panel animation of the 2023-03-29 X1.2 flare"><br>
   <em>The 2023-03-29 X1.2 flare, stabilised by this pipeline. Photosphere left, chromosphere right.</em>
 </p>
 
@@ -239,7 +239,16 @@ psf_stray_light(full_disc_image, p)["s_dc_range"]              # scattered fract
 throughput_trend(dates, ifact_per_date)["throughput_pct_per_yr"]
 ```
 
-The pipeline does not correct stray light. For CHASE it is about 6–10 % of the disc-centre intensity, which makes small dark features (umbrae, filaments) look brighter than they are. The atlas factor changes by about 12 % per year, so fit it for each observation (the pipeline does this by default) rather than reusing one from another date. For Hα-only data use `wing_continuum_frac=0.75`: no Hα channel passes the 0.85 default, and `atlas_calibrate` warns about this.
+Stray light is an optional step that `run_pipeline` does not call. `fit_instrumental_profile` fits one profile to both windows at disk centre (a 0.100 Å Gaussian core plus a 1.8 Å broad term with 14.5 % of the light), and `remove_stray_light` takes that stray light from the disk-centre profile and removes the same amount from every pixel. Do not apply it off the limb, and light scattered from a pixel's immediate surroundings is not treated. Details in [docs/CALIBRATION.md](docs/CALIBRATION.md) §8, example in `examples/stray_light.py`:
+
+```python
+from chase import fit_instrumental_profile, remove_stray_light
+fit = fit_instrumental_profile([wav_ha, wav_fe], [dc_spec_ha, dc_spec_fe])   # both windows, one profile
+fe = fit["windows"][1]                                                        # profile = I/Ic at disk centre
+fe_corr = remove_stray_light(fe_cube_ic, wav_fe, fe["profile"], fit["frac"], fit["broad_fwhm"])
+```
+
+The atlas factor changes by about 12 % per year, so fit it for each observation (the pipeline does this by default) rather than reusing one from another date. For Hα-only data use `wing_continuum_frac=0.75`: no Hα channel passes the 0.85 default, and `atlas_calibrate` warns about this.
 
 ## Prefer clicking to typing?
 
@@ -248,7 +257,7 @@ chase-tui
 ```
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/Majboor/enchase/main/assets/tui_e2e_walkthrough.gif" width="800" alt="End-to-end chase-tui walkthrough">
+  <img src="https://raw.githubusercontent.com/waleedsworld/enchase/main/assets/tui_e2e_walkthrough.gif" width="800" alt="End-to-end chase-tui walkthrough">
 </p>
 
 Every checkbox is one of the switches above. There is also a one-file config workflow: `chase --config my.toml`, keys mirror the flags ([examples/config.toml](examples/config.toml)).
@@ -265,13 +274,14 @@ CHASE (the Chinese Hα Solar Explorer) scans the full solar disk in Hα (118 wav
 | `chase.calib.spatial` / `.align` | shift-then-crop tracking, optical-flow stabilisation | <img src="assets/diag_optical_flow.png" width="220"> |
 | `chase.calib.wavelength` | per-frame resampling onto a common grid, spectral-drift xcorr | <img src="assets/diag_qs_spectrum.png" width="220"> |
 | `chase.calib.intensity` | quiet-Sun norm, integral scaling, FTS-atlas absolute calibration | <img src="assets/atlas_calibration.png" width="220"> |
+| `chase.calib.straylight` | one instrumental profile for both windows, disk-centre stray-light removal | |
 | `chase.analysis.contrast` | wavelength-vs-time flare contrast | <img src="assets/contrast_profile.png" width="220"> |
 | `chase.analysis.temperature` | Hα width to T (Molnar), Fe I to T (Planck / EB / Voigt) | <img src="assets/double_temp_map_peak.png" width="220"> |
 | `chase.analysis.validation` | residual pointing (arcsec), wavelength scatter (mÅ, km/s), frame-to-frame RMS (%, cgs) | |
 | `chase.analysis.systematics` | stray light from the off-limb profile, throughput trend of the atlas factor | |
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/Majboor/enchase/main/assets/temperature.gif" width="720" alt="Double temperature map animation"><br>
+  <img src="https://raw.githubusercontent.com/waleedsworld/enchase/main/assets/temperature.gif" width="720" alt="Double temperature map animation"><br>
   <em>Double temperature map: chromosphere from Hα width (~10⁴ K), photosphere from Fe I Planck inversion (~5100 K).</em>
 </p>
 
@@ -287,7 +297,7 @@ CHASE (the Chinese Hα Solar Explorer) scans the full solar disk in Hα (118 wav
 ## Development
 
 ```bash
-git clone https://github.com/Majboor/enchase.git
+git clone https://github.com/waleedsworld/enchase.git
 cd enchase
 pip install -e '.[all]'
 pytest -q            # 27 tests, synthetic FITS fixtures, no big data needed

{enchase-2.2.0 → enchase-2.3.0}/README.md

@@ -2,13 +2,13 @@
 
 Calibration and flare analysis for CHASE/HIS solar spectroscopy. Install one package, point it at data, get aligned cubes, animations, contrast profiles, and temperature maps.
 
-[![tests](https://github.com/Majboor/enchase/actions/workflows/test.yml/badge.svg)](https://github.com/Majboor/enchase/actions/workflows/test.yml)
+[![tests](https://github.com/waleedsworld/enchase/actions/workflows/test.yml/badge.svg)](https://github.com/waleedsworld/enchase/actions/workflows/test.yml)
 [![PyPI](https://img.shields.io/pypi/v/enchase)](https://pypi.org/project/enchase/)
 ![python](https://img.shields.io/badge/python-3.9%2B-blue)
 ![license](https://img.shields.io/badge/license-MIT-green)
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/Majboor/enchase/main/assets/flare.gif" width="760" alt="Stabilised 2-panel animation of the 2023-03-29 X1.2 flare"><br>
+  <img src="https://raw.githubusercontent.com/waleedsworld/enchase/main/assets/flare.gif" width="760" alt="Stabilised 2-panel animation of the 2023-03-29 X1.2 flare"><br>
   <em>The 2023-03-29 X1.2 flare, stabilised by this pipeline. Photosphere left, chromosphere right.</em>
 </p>
 
@@ -196,7 +196,16 @@ psf_stray_light(full_disc_image, p)["s_dc_range"]              # scattered fract
 throughput_trend(dates, ifact_per_date)["throughput_pct_per_yr"]
 ```
 
-The pipeline does not correct stray light. For CHASE it is about 6–10 % of the disc-centre intensity, which makes small dark features (umbrae, filaments) look brighter than they are. The atlas factor changes by about 12 % per year, so fit it for each observation (the pipeline does this by default) rather than reusing one from another date. For Hα-only data use `wing_continuum_frac=0.75`: no Hα channel passes the 0.85 default, and `atlas_calibrate` warns about this.
+Stray light is an optional step that `run_pipeline` does not call. `fit_instrumental_profile` fits one profile to both windows at disk centre (a 0.100 Å Gaussian core plus a 1.8 Å broad term with 14.5 % of the light), and `remove_stray_light` takes that stray light from the disk-centre profile and removes the same amount from every pixel. Do not apply it off the limb, and light scattered from a pixel's immediate surroundings is not treated. Details in [docs/CALIBRATION.md](docs/CALIBRATION.md) §8, example in `examples/stray_light.py`:
+
+```python
+from chase import fit_instrumental_profile, remove_stray_light
+fit = fit_instrumental_profile([wav_ha, wav_fe], [dc_spec_ha, dc_spec_fe])   # both windows, one profile
+fe = fit["windows"][1]                                                        # profile = I/Ic at disk centre
+fe_corr = remove_stray_light(fe_cube_ic, wav_fe, fe["profile"], fit["frac"], fit["broad_fwhm"])
+```
+
+The atlas factor changes by about 12 % per year, so fit it for each observation (the pipeline does this by default) rather than reusing one from another date. For Hα-only data use `wing_continuum_frac=0.75`: no Hα channel passes the 0.85 default, and `atlas_calibrate` warns about this.
 
 ## Prefer clicking to typing?
 
@@ -205,7 +214,7 @@ chase-tui
 ```
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/Majboor/enchase/main/assets/tui_e2e_walkthrough.gif" width="800" alt="End-to-end chase-tui walkthrough">
+  <img src="https://raw.githubusercontent.com/waleedsworld/enchase/main/assets/tui_e2e_walkthrough.gif" width="800" alt="End-to-end chase-tui walkthrough">
 </p>
 
 Every checkbox is one of the switches above. There is also a one-file config workflow: `chase --config my.toml`, keys mirror the flags ([examples/config.toml](examples/config.toml)).
@@ -222,13 +231,14 @@ CHASE (the Chinese Hα Solar Explorer) scans the full solar disk in Hα (118 wav
 | `chase.calib.spatial` / `.align` | shift-then-crop tracking, optical-flow stabilisation | <img src="assets/diag_optical_flow.png" width="220"> |
 | `chase.calib.wavelength` | per-frame resampling onto a common grid, spectral-drift xcorr | <img src="assets/diag_qs_spectrum.png" width="220"> |
 | `chase.calib.intensity` | quiet-Sun norm, integral scaling, FTS-atlas absolute calibration | <img src="assets/atlas_calibration.png" width="220"> |
+| `chase.calib.straylight` | one instrumental profile for both windows, disk-centre stray-light removal | |
 | `chase.analysis.contrast` | wavelength-vs-time flare contrast | <img src="assets/contrast_profile.png" width="220"> |
 | `chase.analysis.temperature` | Hα width to T (Molnar), Fe I to T (Planck / EB / Voigt) | <img src="assets/double_temp_map_peak.png" width="220"> |
 | `chase.analysis.validation` | residual pointing (arcsec), wavelength scatter (mÅ, km/s), frame-to-frame RMS (%, cgs) | |
 | `chase.analysis.systematics` | stray light from the off-limb profile, throughput trend of the atlas factor | |
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/Majboor/enchase/main/assets/temperature.gif" width="720" alt="Double temperature map animation"><br>
+  <img src="https://raw.githubusercontent.com/waleedsworld/enchase/main/assets/temperature.gif" width="720" alt="Double temperature map animation"><br>
   <em>Double temperature map: chromosphere from Hα width (~10⁴ K), photosphere from Fe I Planck inversion (~5100 K).</em>
 </p>
 
@@ -244,7 +254,7 @@ CHASE (the Chinese Hα Solar Explorer) scans the full solar disk in Hα (118 wav
 ## Development
 
 ```bash
-git clone https://github.com/Majboor/enchase.git
+git clone https://github.com/waleedsworld/enchase.git
 cd enchase
 pip install -e '.[all]'
 pytest -q            # 27 tests, synthetic FITS fixtures, no big data needed

{enchase-2.2.0 → enchase-2.3.0}/chase/__init__.py

@@ -24,7 +24,7 @@ from __future__ import annotations
 
 from . import _compat  # noqa: F401  (lzma stub + headless matplotlib)
 
-__version__ = "2.2.0"
+__version__ = "2.3.0"
 
 # --- I/O -------------------------------------------------------------------
 from .io import (
@@ -82,6 +82,11 @@ from .calib import (
     rotation_shift,
     track_shifts,
     tie_to_header,
+    fit_instrumental_profile,
+    instrumental_profile_model,
+    load_fts_atlas,
+    remove_stray_light,
+    stray_light_veil,
 )
 
 # --- Analysis --------------------------------------------------------------
@@ -135,6 +140,8 @@ __all__ = [
     "activity_mask", "wing_channels", "atlas_sensitivity", "atlas_factor_series",
     "planck_inversion", "limb_darkening", "clv_factor", "clv_reference",
     "download_clv_table", "load_clv_table", "mu_map",
+    "fit_instrumental_profile", "instrumental_profile_model", "load_fts_atlas",
+    "remove_stray_light", "stray_light_veil",
     # analysis
     "contrast_profile", "halpha_width_map", "halpha_width_temperature",
     "width_to_temperature", "fe_planck_temperature", "fe_eb_temperature",

{enchase-2.2.0 → enchase-2.3.0}/chase/calib/__init__.py

@@ -1,4 +1,4 @@
-"""Calibration stages: spatial, alignment, wavelength, intensity.
+"""Calibration stages: spatial, alignment, wavelength, intensity, stray light.
 
 Every function here is usable on its own — nothing forces a full pipeline.
 """
@@ -58,6 +58,13 @@ from .intensity import (
     quiet_sun_mask,
     wing_channels,
 )
+from .straylight import (
+    fit_instrumental_profile,
+    instrumental_profile_model,
+    load_fts_atlas,
+    remove_stray_light,
+    stray_light_veil,
+)
 
 __all__ = [
     "derotate",
@@ -110,4 +117,10 @@ __all__ = [
     "integral_scaling",
     "normalize_intensity",
     "planck_inversion",
+    # stray light
+    "fit_instrumental_profile",
+    "instrumental_profile_model",
+    "load_fts_atlas",
+    "remove_stray_light",
+    "stray_light_veil",
 ]

enchase-2.3.0/chase/calib/straylight.py

@@ -0,0 +1,271 @@
+"""Instrumental profile and stray light of CHASE/HIS.
+
+The disk-center profile is compared with the FTS atlas seen through one
+instrumental profile for both spectral windows, a narrow Gaussian core plus a
+broad Gaussian that carries a fraction ``frac`` of the light,
+
+    T(lambda) * DN  =  (1 - frac) * atlas (x) G(fwhm)  +  frac * atlas (x) G(broad_fwhm)
+
+where (x) is a convolution and T a low-order polynomial for the prefilter
+slope. This is the model of Hou et al. (2020, RAA 20, 045, Eq. 1), used for
+CHASE by Hong et al. (2022, A&A 668, A9), with their constant stray-light
+level replaced by the broad term. With ``broad_fwhm=None`` it is their model
+exactly. A constant level needs different values in the two windows (about
+10 percent in Fe I and 5 percent in H-alpha), which cannot be right for two
+windows recorded in the same exposure on the same detector. The broad term
+fits both with one set of numbers.
+
+The stray light is then assumed to be the same over the field of view (Hong
+et al. 2022), so it is taken from the disk-center profile and removed from
+every pixel,
+
+    I  =  (I_obs - frac * I_dc (x) G(broad_fwhm)) / (1 - frac).
+
+This removes the broad wings of the profile. The narrow core is left in.
+
+Limits. The level is set at disk center, so the correction takes away too
+much close to and beyond the limb and must not be used on off-limb features.
+Light scattered from the immediate surroundings of a pixel is not treated.
+
+Functions
+---------
+load_fts_atlas      FTS disk-center atlas, I/Ic (ISPy or an idlsave file)
+instrumental_profile_model       right-hand side of the first equation above
+fit_instrumental_profile         fit of the profile at disk center, one or several windows
+stray_light_veil    frac * I_dc (x) G(broad_fwhm)
+remove_stray_light  the correction
+"""
+from __future__ import annotations
+
+from typing import Optional, Sequence, Tuple, Union
+
+import numpy as np
+from scipy.ndimage import gaussian_filter1d, uniform_filter1d
+
+__all__ = ["load_fts_atlas", "instrumental_profile_model", "fit_instrumental_profile",
+           "stray_light_veil", "remove_stray_light",
+           "DEFAULT_FWHM", "DEFAULT_BROAD_FWHM", "DEFAULT_FRAC", "CAL_MASK"]
+
+DEFAULT_FWHM = 0.100        # A, Gaussian core (before the detector pixel)
+DEFAULT_BROAD_FWHM = 1.8    # A, broad term
+DEFAULT_FRAC = 0.145        # fraction of the light in the broad term
+
+# Wavelengths left out of the fit (center, half width, in A). Telluric lines
+# and weak blends that differ between the ground-based atlas and CHASE.
+CAL_MASK = [(6559.56, 0.14), (6560.22, 0.12), (6561.10, 0.13), (6564.04, 0.12),
+            (6564.18, 0.14), (6565.51, 0.12), (6565.88, 0.12), (6568.71, 0.10),
+            (6568.83, 0.10)]
+
+_FWHM_TO_SIGMA = 1.0 / (2.0 * np.sqrt(2.0 * np.log(2.0)))
+
+
+def load_fts_atlas(w0: float, w1: float, atlas_file: Optional[str] = None
+                   ) -> Tuple[np.ndarray, np.ndarray]:
+    """FTS disk-center atlas between w0 and w1 (A), as (wavelength, I/Ic).
+
+    Wavelengths are in the observer frame (no gravitational redshift taken
+    out). Without ``atlas_file`` the atlas shipped with ISPy is used
+    (https://github.com/ISP-SST/ISPy). ``atlas_file`` can point at an
+    ``fts_disk_center*.idlsave`` file instead.
+    """
+    if atlas_file is None:
+        try:
+            from ISPy.spec import atlas as isp_atlas
+        except ImportError as e:
+            raise ImportError(
+                "load_fts_atlas needs ISPy (pip install "
+                "git+https://github.com/ISP-SST/ISPy) or atlas_file=...") from e
+        fts = isp_atlas.atlas()
+        wav, spec, cont = fts.wave, fts.spec, fts.cont
+    else:
+        from scipy.io import readsav
+        sav = {k.lower(): v for k, v in readsav(atlas_file).items()}
+        wav = sav["ftswav"]
+        spec = sav.get("ftsint_si", sav.get("ftsint"))
+        cont = sav.get("ftscnt_si", sav.get("ftscnt"))
+    keep = (wav >= w0) & (wav <= w1)
+    return (np.asarray(wav[keep], float),
+            np.asarray(spec[keep], float) / np.asarray(cont[keep], float))
+
+
+def _smeared_atlas(atlas_wav, atlas_int, fwhm, pixel):
+    """Atlas convolved with a Gaussian of this FWHM and one detector pixel."""
+    step = float(np.median(np.diff(atlas_wav)))
+    out = gaussian_filter1d(atlas_int, fwhm * _FWHM_TO_SIGMA / step,
+                            mode="reflect", truncate=4.0)
+    npix = max(1, int(round(pixel / step)))
+    return uniform_filter1d(out, npix, mode="reflect")
+
+
+def instrumental_profile_model(wav, atlas_wav, atlas_int, fwhm: float = DEFAULT_FWHM,
+                  frac: float = DEFAULT_FRAC,
+                  broad_fwhm: Optional[float] = DEFAULT_BROAD_FWHM,
+                  shift: float = 0.0, pixel: Optional[float] = None) -> np.ndarray:
+    """Atlas seen through the instrumental profile, I/Ic on ``wav``.
+
+    ``(1 - frac) * atlas (x) G(fwhm) + frac * atlas (x) G(broad_fwhm)``,
+    evaluated at ``wav + shift``. ``broad_fwhm=None`` gives the constant
+    stray-light level of Hou et al. (2020), ``(1 - frac) * ... + frac``.
+    ``pixel`` is the detector pixel in A (default, the step of ``wav``).
+    """
+    wav = np.asarray(wav, float)
+    pixel = float(np.median(np.diff(wav))) if pixel is None else float(pixel)
+    core = np.interp(wav + shift, atlas_wav,
+                     _smeared_atlas(atlas_wav, atlas_int, fwhm, pixel))
+    if broad_fwhm is None:
+        return (1.0 - frac) * core + frac
+    broad = np.interp(wav + shift, atlas_wav,
+                      _smeared_atlas(atlas_wav, atlas_int, broad_fwhm, pixel))
+    return (1.0 - frac) * core + frac * broad
+
+
+def _grid(value):
+    return np.atleast_1d(np.asarray([np.nan] if value is None else value, float))
+
+
+def fit_instrumental_profile(wav, spectrum, atlas: Optional[Tuple[np.ndarray, np.ndarray]] = None,
+                fwhm: Union[float, Sequence[float]] = DEFAULT_FWHM,
+                frac: Union[float, Sequence[float]] = DEFAULT_FRAC,
+                broad_fwhm: Union[None, float, Sequence[float]] = DEFAULT_BROAD_FWHM,
+                poly_deg: Optional[int] = None,
+                mask: Sequence[Tuple[float, float]] = CAL_MASK,
+                shifts: Optional[Sequence[float]] = None,
+                atlas_file: Optional[str] = None, verbose: bool = False) -> dict:
+    """Fit the instrumental profile to a disk-center spectrum.
+
+    Parameters
+    ----------
+    wav, spectrum : array (nwav,), or lists of such arrays
+        Mean disk-center spectrum of one window, in any units (DN is fine).
+        Pass lists, e.g. ``[wav_ha, wav_fe], [spec_ha, spec_fe]``, to fit
+        several windows with ONE profile. Each window then gets its own
+        wavelength offset and polynomial, and the windows have equal weight.
+    atlas : (wavelength, I/Ic), optional
+        Reference atlas. Default, :func:`load_fts_atlas` over the windows.
+    fwhm, frac, broad_fwhm : float or sequence of float
+        Core FWHM (A), fraction of the light in the broad term, and FWHM of
+        the broad term (A). A single number holds that parameter fixed, a
+        sequence is searched as a grid. ``broad_fwhm=None`` is the constant
+        level of Hou et al. (2020), where ``frac`` is their alpha.
+    poly_deg : int, optional
+        Degree of the transmission polynomial. Default 3 for windows wider
+        than 4 A (H-alpha) and 2 otherwise (Fe I).
+    mask : sequence of (center, half width)
+        Wavelengths left out of the fit.
+    shifts : sequence of float, optional
+        Wavelength offsets to try (A). Default -0.2 to 0.2 in steps of 0.002.
+    verbose : bool
+        Print one line per core width while a grid is searched.
+
+    Returns
+    -------
+    dict with the best ``fwhm``, ``frac``, ``broad_fwhm``, the summed
+    ``chi2`` (mean squared residual, added over windows) and ``windows``, a
+    list with one dict per window holding ``shift``, ``poly`` and ``wmean``
+    (transmission = polyval(poly, wav - wmean)), ``transmission``,
+    ``profile`` (= transmission * spectrum, the observed I/Ic), ``model``,
+    ``rms`` (of profile - model over the fitted points) and ``keep``. For a
+    single window these entries are also at the top level.
+    """
+    single = np.ndim(wav[0]) == 0
+    wavs = [np.asarray(wav, float)] if single else [np.asarray(w, float) for w in wav]
+    specs = [np.asarray(spectrum, float)] if single else [np.asarray(s, float) for s in spectrum]
+    shifts = np.arange(-0.200, 0.2001, 0.002) if shifts is None else np.asarray(shifts, float)
+    fwhms, fracs, broads = _grid(fwhm), _grid(frac), _grid(broad_fwhm)
+    flat = broad_fwhm is None
+
+    if atlas is None:
+        margin = 2.0 + (0.0 if flat else 2.5 * float(np.nanmax(broads)))
+        atlas = load_fts_atlas(min(w[0] for w in wavs) - margin,
+                               max(w[-1] for w in wavs) + margin, atlas_file)
+    awav, aint = np.asarray(atlas[0], float), np.asarray(atlas[1], float)
+
+    setup = []
+    for w in wavs:
+        keep = np.ones(w.size, bool)
+        for lam, half in mask:
+            keep &= np.abs(w - lam) > half
+        deg = poly_deg if poly_deg is not None else (3 if w[-1] - w[0] > 4.0 else 2)
+        setup.append((keep, deg, w - w.mean(), float(np.median(np.diff(w)))))
+
+    best = None
+    for i, fw in enumerate(fwhms):
+        cores = [_smeared_atlas(awav, aint, fw, s[3]) for s in setup]
+        for bw in broads:
+            wings = [None if flat else _smeared_atlas(awav, aint, bw, s[3]) for s in setup]
+            for fr in fracs:
+                total, found = 0.0, []
+                for w, sp, (keep, deg, x, _), core, wing in zip(wavs, specs, setup, cores, wings):
+                    win = None
+                    for sh in shifts:
+                        mod = (1.0 - fr) * np.interp(w + sh, awav, core)
+                        mod = mod + (fr if flat else fr * np.interp(w + sh, awav, wing))
+                        poly = np.polyfit(x[keep], (mod / sp)[keep], deg)
+                        ms = float(np.mean((sp * np.polyval(poly, x) - mod)[keep] ** 2))
+                        if win is None or ms < win[0]:
+                            win = (ms, sh, poly, mod)
+                    total += win[0]
+                    found.append(win)
+                if best is None or total < best[0]:
+                    best = (total, fw, fr, bw, found)
+        if verbose and fwhms.size > 1:
+            print("fit_instrumental_profile: core %.3f A (%d/%d), best so far %.3f A"
+                  % (fw, i + 1, fwhms.size, best[1]), flush=True)
+
+    total, fw, fr, bw, found = best
+    out = dict(fwhm=float(fw), frac=float(fr),
+               broad_fwhm=None if flat else float(bw), chi2=float(total), windows=[])
+    for w, sp, (keep, deg, x, _), (ms, sh, poly, mod) in zip(wavs, specs, setup, found):
+        trans = np.polyval(poly, x)
+        out["windows"].append(dict(shift=float(sh), poly=poly, wmean=float(w.mean()),
+                                   transmission=trans, profile=sp * trans, model=mod,
+                                   rms=float(np.sqrt(ms)), keep=keep))
+    if single:
+        out.update(out["windows"][0])
+    return out
+
+
+def stray_light_veil(wav, dc_profile, frac: float = DEFAULT_FRAC,
+                     broad_fwhm: Optional[float] = DEFAULT_BROAD_FWHM) -> np.ndarray:
+    """The stray light, ``frac * dc_profile (x) G(broad_fwhm)``.
+
+    ``dc_profile`` is the observed disk-center profile of one window on the
+    regular grid ``wav``. The result has its units. The window is padded with
+    its edge values for the convolution. ``broad_fwhm=None`` gives the
+    constant level ``frac`` (for a profile normalized to the continuum).
+    """
+    dc_profile = np.asarray(dc_profile, float)
+    if broad_fwhm is None:
+        return np.full(dc_profile.shape, float(frac))
+    step = float(np.median(np.diff(np.asarray(wav, float))))
+    return frac * gaussian_filter1d(dc_profile, broad_fwhm * _FWHM_TO_SIGMA / step,
+                                    mode="nearest", truncate=4.0)
+
+
+def remove_stray_light(cube, wav, dc_profile, frac: float = DEFAULT_FRAC,
+                       broad_fwhm: Optional[float] = DEFAULT_BROAD_FWHM) -> np.ndarray:
+    """Remove the stray light from a cube, the same amount in every pixel.
+
+    ``(cube - frac * dc_profile (x) G(broad_fwhm)) / (1 - frac)``
+
+    Parameters
+    ----------
+    cube : array (nwav, ...)
+        Observed intensities of one window, wavelength first.
+    wav : array (nwav,)
+        Its wavelengths (regular grid, A).
+    dc_profile : array (nwav,)
+        Observed mean profile at disk center, same wavelengths and SAME UNITS
+        as ``cube`` (both multiplied by the transmission of
+        :func:`fit_instrumental_profile`, or both calibrated with the same factor).
+    frac, broad_fwhm : float
+        As fitted or adopted in :func:`fit_instrumental_profile`.
+
+    Notes
+    -----
+    At disk center this turns the observed profile into the one the fit
+    describes with the narrow core alone. Do not use it on off-limb pixels.
+    """
+    cube = np.asarray(cube, float)
+    veil = stray_light_veil(wav, dc_profile, frac, broad_fwhm)
+    return (cube - veil.reshape((-1,) + (1,) * (cube.ndim - 1))) / (1.0 - frac)

{enchase-2.2.0 → enchase-2.3.0/enchase.egg-info}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: enchase
-Version: 2.2.0
+Version: 2.3.0
 Summary: enCHASE: calibration and analysis pipeline for CHASE/HIS solar spectroscopy (TUI + SDK + CLI)
 Author: Waleed Ajmal
 License: MIT
-Project-URL: Homepage, https://github.com/Majboor/enchase
-Project-URL: Repository, https://github.com/Majboor/enchase
-Project-URL: Changelog, https://github.com/Majboor/enchase/blob/main/CHANGELOG.md
+Project-URL: Homepage, https://github.com/waleedsworld/enchase
+Project-URL: Repository, https://github.com/waleedsworld/enchase
+Project-URL: Changelog, https://github.com/waleedsworld/enchase/blob/main/CHANGELOG.md
 Keywords: solar,CHASE,HIS,spectroscopy,flare,calibration,astronomy
 Classifier: Programming Language :: Python :: 3
 Classifier: License :: OSI Approved :: MIT License
@@ -45,13 +45,13 @@ Dynamic: license-file
 
 Calibration and flare analysis for CHASE/HIS solar spectroscopy. Install one package, point it at data, get aligned cubes, animations, contrast profiles, and temperature maps.
 
-[![tests](https://github.com/Majboor/enchase/actions/workflows/test.yml/badge.svg)](https://github.com/Majboor/enchase/actions/workflows/test.yml)
+[![tests](https://github.com/waleedsworld/enchase/actions/workflows/test.yml/badge.svg)](https://github.com/waleedsworld/enchase/actions/workflows/test.yml)
 [![PyPI](https://img.shields.io/pypi/v/enchase)](https://pypi.org/project/enchase/)
 ![python](https://img.shields.io/badge/python-3.9%2B-blue)
 ![license](https://img.shields.io/badge/license-MIT-green)
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/Majboor/enchase/main/assets/flare.gif" width="760" alt="Stabilised 2-panel animation of the 2023-03-29 X1.2 flare"><br>
+  <img src="https://raw.githubusercontent.com/waleedsworld/enchase/main/assets/flare.gif" width="760" alt="Stabilised 2-panel animation of the 2023-03-29 X1.2 flare"><br>
   <em>The 2023-03-29 X1.2 flare, stabilised by this pipeline. Photosphere left, chromosphere right.</em>
 </p>
 
@@ -239,7 +239,16 @@ psf_stray_light(full_disc_image, p)["s_dc_range"]              # scattered fract
 throughput_trend(dates, ifact_per_date)["throughput_pct_per_yr"]
 ```
 
-The pipeline does not correct stray light. For CHASE it is about 6–10 % of the disc-centre intensity, which makes small dark features (umbrae, filaments) look brighter than they are. The atlas factor changes by about 12 % per year, so fit it for each observation (the pipeline does this by default) rather than reusing one from another date. For Hα-only data use `wing_continuum_frac=0.75`: no Hα channel passes the 0.85 default, and `atlas_calibrate` warns about this.
+Stray light is an optional step that `run_pipeline` does not call. `fit_instrumental_profile` fits one profile to both windows at disk centre (a 0.100 Å Gaussian core plus a 1.8 Å broad term with 14.5 % of the light), and `remove_stray_light` takes that stray light from the disk-centre profile and removes the same amount from every pixel. Do not apply it off the limb, and light scattered from a pixel's immediate surroundings is not treated. Details in [docs/CALIBRATION.md](docs/CALIBRATION.md) §8, example in `examples/stray_light.py`:
+
+```python
+from chase import fit_instrumental_profile, remove_stray_light
+fit = fit_instrumental_profile([wav_ha, wav_fe], [dc_spec_ha, dc_spec_fe])   # both windows, one profile
+fe = fit["windows"][1]                                                        # profile = I/Ic at disk centre
+fe_corr = remove_stray_light(fe_cube_ic, wav_fe, fe["profile"], fit["frac"], fit["broad_fwhm"])
+```
+
+The atlas factor changes by about 12 % per year, so fit it for each observation (the pipeline does this by default) rather than reusing one from another date. For Hα-only data use `wing_continuum_frac=0.75`: no Hα channel passes the 0.85 default, and `atlas_calibrate` warns about this.
 
 ## Prefer clicking to typing?
 
@@ -248,7 +257,7 @@ chase-tui
 ```
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/Majboor/enchase/main/assets/tui_e2e_walkthrough.gif" width="800" alt="End-to-end chase-tui walkthrough">
+  <img src="https://raw.githubusercontent.com/waleedsworld/enchase/main/assets/tui_e2e_walkthrough.gif" width="800" alt="End-to-end chase-tui walkthrough">
 </p>
 
 Every checkbox is one of the switches above. There is also a one-file config workflow: `chase --config my.toml`, keys mirror the flags ([examples/config.toml](examples/config.toml)).
@@ -265,13 +274,14 @@ CHASE (the Chinese Hα Solar Explorer) scans the full solar disk in Hα (118 wav
 | `chase.calib.spatial` / `.align` | shift-then-crop tracking, optical-flow stabilisation | <img src="assets/diag_optical_flow.png" width="220"> |
 | `chase.calib.wavelength` | per-frame resampling onto a common grid, spectral-drift xcorr | <img src="assets/diag_qs_spectrum.png" width="220"> |
 | `chase.calib.intensity` | quiet-Sun norm, integral scaling, FTS-atlas absolute calibration | <img src="assets/atlas_calibration.png" width="220"> |
+| `chase.calib.straylight` | one instrumental profile for both windows, disk-centre stray-light removal | |
 | `chase.analysis.contrast` | wavelength-vs-time flare contrast | <img src="assets/contrast_profile.png" width="220"> |
 | `chase.analysis.temperature` | Hα width to T (Molnar), Fe I to T (Planck / EB / Voigt) | <img src="assets/double_temp_map_peak.png" width="220"> |
 | `chase.analysis.validation` | residual pointing (arcsec), wavelength scatter (mÅ, km/s), frame-to-frame RMS (%, cgs) | |
 | `chase.analysis.systematics` | stray light from the off-limb profile, throughput trend of the atlas factor | |
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/Majboor/enchase/main/assets/temperature.gif" width="720" alt="Double temperature map animation"><br>
+  <img src="https://raw.githubusercontent.com/waleedsworld/enchase/main/assets/temperature.gif" width="720" alt="Double temperature map animation"><br>
   <em>Double temperature map: chromosphere from Hα width (~10⁴ K), photosphere from Fe I Planck inversion (~5100 K).</em>
 </p>
 
@@ -287,7 +297,7 @@ CHASE (the Chinese Hα Solar Explorer) scans the full solar disk in Hα (118 wav
 ## Development
 
 ```bash
-git clone https://github.com/Majboor/enchase.git
+git clone https://github.com/waleedsworld/enchase.git
 cd enchase
 pip install -e '.[all]'
 pytest -q            # 27 tests, synthetic FITS fixtures, no big data needed

{enchase-2.2.0 → enchase-2.3.0}/enchase.egg-info/SOURCES.txt

@@ -21,6 +21,7 @@ chase/calib/align.py
 chase/calib/intensity.py
 chase/calib/pointing.py
 chase/calib/spatial.py
+chase/calib/straylight.py
 chase/calib/wavelength.py
 chase/io/__init__.py
 chase/io/download.py
@@ -42,5 +43,6 @@ tests/test_io.py
 tests/test_limb_clv.py
 tests/test_pipeline.py
 tests/test_pointing.py
+tests/test_straylight.py
 tests/test_systematics.py
 tests/test_validation.py

{enchase-2.2.0 → enchase-2.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "enchase"
-version = "2.2.0"
+version = "2.3.0"
 description = "enCHASE: calibration and analysis pipeline for CHASE/HIS solar spectroscopy (TUI + SDK + CLI)"
 readme = "README.md"
 license = { text = "MIT" }
@@ -43,9 +43,9 @@ chase-tui = "chase.tui:main"
 chase-portal = "chase.portal:main"
 
 [project.urls]
-Homepage = "https://github.com/Majboor/enchase"
-Repository = "https://github.com/Majboor/enchase"
-Changelog = "https://github.com/Majboor/enchase/blob/main/CHANGELOG.md"
+Homepage = "https://github.com/waleedsworld/enchase"
+Repository = "https://github.com/waleedsworld/enchase"
+Changelog = "https://github.com/waleedsworld/enchase/blob/main/CHANGELOG.md"
 
 [tool.setuptools.packages.find]
 include = ["chase*", "enchase*"]

enchase-2.3.0/tests/test_straylight.py

@@ -0,0 +1,120 @@
+"""Instrumental profile and stray light (chase.calib.straylight).
+
+Everything runs on a synthetic atlas, so neither ISPy nor real data is needed.
+The synthetic "observation" is built with the same forward model the fit uses,
+multiplied by a known transmission polynomial, so the fit must give back the
+numbers that went in.
+"""
+
+import numpy as np
+import pytest
+
+from chase.calib import (
+    fit_instrumental_profile,
+    instrumental_profile_model,
+    remove_stray_light,
+    stray_light_veil,
+)
+
+
+def _atlas():
+    """Continuum normalized atlas on a 0.0078 A grid: H-alpha-like and Fe I-like lines."""
+    wav = np.arange(6550.0, 6580.0, 0.0078125)
+    spec = np.ones_like(wav)
+    for core, depth, width in ((6562.8, 0.84, 0.45), (6569.21, 0.65, 0.06),
+                               (6560.58, 0.20, 0.05), (6564.20, 0.05, 0.03)):
+        spec *= 1.0 - depth * np.exp(-0.5 * ((wav - core) / width) ** 2)
+    return wav, spec
+
+
+def _window(w0, w1, n):
+    return np.linspace(w0, w1, n)
+
+
+WAV_HA = _window(6559.4, 6565.1, 118)
+WAV_FE = _window(6567.5, 6569.7, 46)
+
+
+def _observe(wav, atlas, fwhm, frac, broad, shift, poly):
+    """DN spectrum whose transmission-corrected profile is the model."""
+    model = instrumental_profile_model(wav, *atlas, fwhm=fwhm, frac=frac,
+                                       broad_fwhm=broad, shift=shift)
+    trans = np.polyval(poly, wav - wav.mean())
+    return model / trans
+
+
+def test_constant_level_is_hou_model():
+    """broad_fwhm=None is Hou et al. 2020 Eq. 1: (1 - a) atlas (x) G + a."""
+    atlas = _atlas()
+    core = instrumental_profile_model(WAV_FE, *atlas, fwhm=0.1, frac=0.0)
+    flat = instrumental_profile_model(WAV_FE, *atlas, fwhm=0.1, frac=0.1, broad_fwhm=None)
+    assert np.allclose(flat, 0.9 * core + 0.1)
+
+
+def test_fit_recovers_one_profile_for_both_windows():
+    atlas = _atlas()
+    truth = dict(fwhm=0.105, frac=0.12, broad=2.4)
+    dn_ha = _observe(WAV_HA, atlas, truth["fwhm"], truth["frac"], truth["broad"],
+                     -0.004, [2e-6, -1e-5, 1e-3])
+    dn_fe = _observe(WAV_FE, atlas, truth["fwhm"], truth["frac"], truth["broad"],
+                     0.006, [5e-5, 2e-3])
+    r = fit_instrumental_profile([WAV_HA, WAV_FE], [dn_ha, dn_fe], atlas=atlas, mask=[],
+                                 fwhm=np.arange(0.09, 0.1201, 0.005),
+                                 broad_fwhm=np.arange(2.0, 2.81, 0.2),
+                                 frac=np.arange(0.10, 0.1401, 0.01),
+                                 shifts=np.arange(-0.01, 0.0101, 0.002))
+    assert r["fwhm"] == pytest.approx(truth["fwhm"], abs=1e-6)
+    assert r["broad_fwhm"] == pytest.approx(truth["broad"], abs=1e-6)
+    assert r["frac"] == pytest.approx(truth["frac"], abs=1e-6)
+    assert [w["shift"] for w in r["windows"]] == pytest.approx([-0.004, 0.006], abs=1e-9)
+    assert max(w["rms"] for w in r["windows"]) < 1e-4
+    # the returned transmission puts the window back on the model
+    for w in r["windows"]:
+        assert np.allclose(w["profile"], w["model"], atol=1e-4)
+
+
+def test_single_window_returns_flat_dict():
+    atlas = _atlas()
+    dn = _observe(WAV_FE, atlas, 0.1, 0.1, None, 0.0, [1e-3])
+    r = fit_instrumental_profile(WAV_FE, dn, atlas=atlas, broad_fwhm=None, mask=[],
+                                 fwhm=np.arange(0.08, 0.1201, 0.01),
+                                 frac=np.arange(0.06, 0.1401, 0.02),
+                                 shifts=[0.0])
+    assert r["broad_fwhm"] is None
+    assert r["fwhm"] == pytest.approx(0.1) and r["frac"] == pytest.approx(0.1)
+    assert "rms" in r and len(r["windows"]) == 1
+
+
+def test_correction_leaves_only_the_core_at_disk_center():
+    """At disk center the corrected profile is the atlas seen through the core alone."""
+    atlas = _atlas()
+    dc = instrumental_profile_model(WAV_HA, *atlas, fwhm=0.1, frac=0.145, broad_fwhm=1.8)
+    core = instrumental_profile_model(WAV_HA, *atlas, fwhm=0.1, frac=0.0)
+    corrected = remove_stray_light(dc[:, None, None], WAV_HA, dc)[:, 0, 0]
+    # the veil is built from the observed dc profile, not the atlas, so the match
+    # holds to second order in frac
+    assert np.max(np.abs(corrected - core)) < 0.01
+    assert np.max(np.abs(corrected - core)) < 0.2 * np.max(np.abs(dc - core))
+
+
+def test_same_veil_in_every_pixel():
+    """Pixels that differ by a constant offset stay apart by offset / (1 - frac)."""
+    atlas = _atlas()
+    dc = instrumental_profile_model(WAV_FE, *atlas)
+    cube = np.stack([dc, dc - 0.3, dc + 0.1], axis=1)
+    out = remove_stray_light(cube, WAV_FE, dc, frac=0.145)
+    assert np.allclose(out[:, 0] - out[:, 1], 0.3 / 0.855)
+    assert np.allclose(out[:, 2] - out[:, 0], 0.1 / 0.855)
+
+
+def test_veil_shapes_and_flat_option():
+    atlas = _atlas()
+    dc = instrumental_profile_model(WAV_HA, *atlas)
+    veil = stray_light_veil(WAV_HA, dc, 0.145, 1.8)
+    assert veil.shape == dc.shape
+    # a smoothed spectrum: shallower than the profile, same mean to a few percent
+    assert veil.min() / 0.145 > dc.min()
+    assert abs(veil.mean() / 0.145 - dc.mean()) < 0.03
+    assert np.allclose(stray_light_veil(WAV_HA, dc, 0.05, None), 0.05)
+    cube4 = np.ones((WAV_HA.size, 2, 3, 4))
+    assert remove_stray_light(cube4, WAV_HA, dc).shape == cube4.shape