lated 0.1.0__py3-none-any.whl

lated/__init__.py

@@ -0,0 +1,35 @@
+"""lated: photometric emission-line recovery.
+
+Fit a transparent continuum + emission-line model through real filter
+transmission curves to recover line fluxes, rest EWs and line ratios
+(with upper limits) from broad/medium-band photometry.
+
+>>> from lated import FitConfig, fit
+>>> cfg = FitConfig.three_band(z=3.05)          # paper 3-band mode
+>>> res = fit({"F200W": (0.0136, 0.0019),
+...            "F277W": (0.0249, 0.0016),
+...            "F356W": (0.0040, 0.0014)}, cfg)
+>>> res.ratios[0].name, res.ratios[0].is_limit
+('R3', ...)
+"""
+
+from .config import (ContinuumConfig, DustConfig, FitConfig, LineConfig,
+                     MCConfig, RatioConfig, default_lines)
+from .engine import FitResult, LineResult, RatioResult, fit, model_spectrum
+from .filters import Filter, FilterSet, default_filters, filter_group
+from .lines import (BALMER_CASES, BALMER_TABLE, CASE_A_TEMPERATURES,
+                    CASE_B_DENSITIES, CASE_B_TEMPERATURES, LINE_WAVELENGTHS,
+                    balmer_ratios, case_b_ratios)
+from .presets import WINDOW_PRESETS, WindowPreset
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "ContinuumConfig", "DustConfig", "FitConfig", "LineConfig", "MCConfig",
+    "RatioConfig", "default_lines", "FitResult", "LineResult", "RatioResult",
+    "fit", "model_spectrum", "Filter", "FilterSet", "default_filters",
+    "filter_group", "LINE_WAVELENGTHS", "WINDOW_PRESETS", "WindowPreset",
+    "BALMER_CASES", "BALMER_TABLE", "CASE_A_TEMPERATURES",
+    "CASE_B_DENSITIES", "CASE_B_TEMPERATURES", "balmer_ratios",
+    "case_b_ratios", "__version__",
+]

lated/cli.py

@@ -0,0 +1,72 @@
+"""Command-line interface: serve the web app, or fit from a JSON file.
+
+  lated serve [--host H] [--port P]
+  lated fit input.json          # {"photometry": {...}, "config": {...}}
+  lated bands                   # list bundled filters
+  lated lines                   # show the default line registry
+"""
+
+import argparse
+import json
+import sys
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(
+        prog="lated",
+        description=(__doc__ or "LATED line recovery").splitlines()[0])
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    ap_serve = sub.add_parser("serve", help="run the web application")
+    ap_serve.add_argument("--host", default="127.0.0.1")
+    ap_serve.add_argument("--port", type=int, default=8321)
+
+    ap_fit = sub.add_parser("fit", help="fit photometry from a JSON file")
+    ap_fit.add_argument("input", help="JSON with 'photometry' and 'config'")
+
+    sub.add_parser("bands", help="list available filters")
+    sub.add_parser("lines", help="show the default line registry")
+
+    args = ap.parse_args(argv)
+
+    if args.cmd == "serve":
+        import uvicorn
+        from .server.app import create_app
+        uvicorn.run(create_app(), host=args.host, port=args.port)
+    elif args.cmd == "fit":
+        from pydantic import ValidationError
+
+        from .config import FitConfig
+        from .engine import fit
+        try:
+            with open(args.input) as fh:
+                payload = json.load(fh)
+            phot_in = payload["photometry"]
+            cfg = FitConfig.model_validate(payload["config"])
+            phot = {b: (float(v[0]), float(v[1]))
+                    for b, v in phot_in.items()}
+            res = fit(phot, cfg)
+        except KeyError as exc:
+            sys.exit(f"error: input JSON needs 'photometry' (band -> "
+                     f"[flux_uJy, err_uJy]) and 'config' (missing {exc})")
+        except (ValidationError, ValueError, TypeError, OSError,
+                json.JSONDecodeError) as exc:
+            sys.exit(f"error: {exc}")
+        json.dump(res.model_dump(), sys.stdout, indent=2, allow_nan=False)
+        print()
+    elif args.cmd == "bands":
+        from .filters import default_filters, filter_group
+        fs = default_filters()
+        for name in fs.names():
+            f = fs[name]
+            print(f"{name:12s} {filter_group(name):22s} "
+                  f"pivot {f.pivot:9.1f} AA")
+    elif args.cmd == "lines":
+        from .config import default_lines
+        for l in default_lines():
+            tie = (f" = {l.ratio:.4f} x {l.tied_to}" if l.role == "tied" else "")
+            print(f"{l.name:12s} {l.rest_wave:9.2f} AA  {l.role:5s}{tie}")
+
+
+if __name__ == "__main__":
+    main()

lated/config.py

@@ -0,0 +1,258 @@
+"""Fit configuration: every model parameter with an explicit role.
+
+The spectral model is
+
+    f_lambda(lam) = C (lam/lam0)^beta + sum_l F_l delta(lam - lam_l (1+z))
+
+and every parameter is declared here as *free*, *fixed* or *tied*:
+
+===============================  =========================================
+parameter                        role
+===============================  =========================================
+C   (continuum amplitude)        always free (>= 0)
+beta (continuum slope)           free (grid-searched) or fixed (with an
+                                 optional Gaussian sigma folded into the
+                                 Monte-Carlo error budget)
+z                                always fixed (the Lya-slice redshift);
+                                 z_sigma > 0 propagates its uncertainty
+A_V, dust law                    fixed; enters only as a differential on
+                                 tied line ratios
+F_l (one per line)               free (>= 0), tied (ratio x another line),
+                                 or off (excluded from the model)
+===============================  =========================================
+
+Unknown keys are rejected (``extra='forbid'``), so a misspelled option is an
+error instead of a silent no-op.
+"""
+
+from __future__ import annotations
+
+from typing import List, Literal, Optional
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from .lines import (DEFAULT_REGISTRY, LINE_WAVELENGTHS, balmer_ratios,
+                    contaminant_ties)
+
+
+class ContinuumConfig(BaseModel):
+    """The power-law continuum C (lam/lam0)^beta.
+
+    The amplitude C is always free (non-negative).  The slope beta is either
+    ``free`` (grid-searched over [grid_min, grid_max]) or ``fixed`` at
+    ``beta`` — required when only the three selection bands are given, where
+    the slope is degenerate with the amplitudes.  When fixed, ``beta_sigma``
+    (default 0.3) marginalises the assumed slope in the Monte-Carlo so the
+    systematic enters the error budget."""
+    model_config = ConfigDict(extra="forbid")
+
+    beta_mode: Literal["free", "fixed"] = "free"
+    beta: float = -2.0
+    beta_sigma: Optional[float] = Field(
+        None, ge=0, description="None -> 0.3 if fixed, 0.0 if free")
+    grid_min: float = -3.5
+    grid_max: float = 1.0
+    grid_n: int = Field(61, ge=2, le=1001)
+    pivot_wavelength: float = Field(20000.0, gt=0,
+                                    description="lam0 [AA, observed]")
+
+    @property
+    def beta_sigma_effective(self) -> float:
+        if self.beta_sigma is not None:
+            return self.beta_sigma
+        return 0.3 if self.beta_mode == "fixed" else 0.0
+
+    @model_validator(mode="after")
+    def _check_grid(self) -> "ContinuumConfig":
+        if self.beta_mode == "free" and self.grid_min >= self.grid_max:
+            raise ValueError("continuum grid_min must be < grid_max")
+        if self.beta_mode == "free" and self.beta_sigma:
+            raise ValueError(
+                "beta_sigma is only meaningful with beta_mode='fixed' (it is "
+                "the Gaussian prior on the assumed slope); with beta_mode="
+                "'free' the slope is profiled over the grid instead")
+        return self
+
+
+class LineConfig(BaseModel):
+    """One emission line in the model.
+
+    role='free':  amplitude F >= 0 is a fit parameter.
+    role='tied':  F = ratio x F(tied_to) x dust differential; tie chains
+                  (e.g. Hgamma -> Hbeta -> Halpha) resolve to a free root.
+    role='off':   excluded from the model entirely.
+    """
+    model_config = ConfigDict(extra="forbid")
+
+    name: str
+    rest_wave: float = Field(..., gt=0, description="rest wavelength [AA]")
+    role: Literal["free", "tied", "off"] = "free"
+    tied_to: Optional[str] = None
+    ratio: Optional[float] = Field(None, gt=0,
+                                   description="F_this / F_tied_to, intrinsic")
+
+    @model_validator(mode="after")
+    def _check_tie(self) -> "LineConfig":
+        if self.role == "tied":
+            if not self.tied_to or self.ratio is None:
+                raise ValueError(
+                    f"line {self.name!r}: role='tied' requires tied_to and ratio")
+        return self
+
+
+class DustConfig(BaseModel):
+    """Attenuation applied differentially to tied line ratios.
+
+    Like the fixed continuum slope, A_V carries a Gaussian uncertainty
+    ``av_sigma`` (default 0 +/- 0.01) that is propagated through the
+    Monte-Carlo error budget (draws are truncated at A_V >= 0)."""
+    model_config = ConfigDict(extra="forbid")
+
+    av: float = Field(0.0, ge=0)
+    av_sigma: float = Field(0.01, ge=0)
+    law: Literal["calzetti", "smc"] = "calzetti"
+
+
+class MCConfig(BaseModel):
+    """Monte-Carlo error budget.
+
+    method='bootstrap' (paper default): resample the photometry ``n`` times
+    and refit; read percentiles of the refits.  Near the non-negativity
+    boundary these can collapse to zero (an undetected line whose band
+    fluctuated low returns an upper limit of exactly 0), so for honest
+    limits prefer method='posterior': sample the truncated-Gaussian
+    posterior of the amplitudes (flat prior on F >= 0) with the slope
+    drawn from its profile weight (free) or Gaussian prior (fixed).
+
+    ``fast`` (bootstrap only) pins the slope at the best fit instead of
+    re-searching the grid per resample.  ``seed`` fixes the random stream;
+    vary it across a catalogue if you stack results (a shared seed
+    correlates the noise realisations)."""
+    model_config = ConfigDict(extra="forbid")
+
+    n: int = Field(300, ge=10, le=10000)
+    seed: int = 9496
+    fast: bool = False
+    method: Literal["bootstrap", "posterior"] = "bootstrap"
+    keep_draws: bool = Field(
+        False, description="return the (thinned) MC draws of the free "
+        "parameters in FitResult.posterior_draws, e.g. for corner plots")
+
+
+class RatioConfig(BaseModel):
+    """A derived line ratio to report, with upper-limit handling."""
+    model_config = ConfigDict(extra="forbid")
+
+    name: str = "R3"
+    numerator: str = "OIII5007"
+    denominator: str = "Hbeta"
+
+
+def default_lines() -> List[LineConfig]:
+    """The paper's default registry (see :mod:`lated.lines`)."""
+    return [LineConfig(name=n, rest_wave=LINE_WAVELENGTHS[n], role=role,
+                       tied_to=tied_to, ratio=ratio)
+            for n, role, tied_to, ratio in DEFAULT_REGISTRY]
+
+
+class FitConfig(BaseModel):
+    """Complete, explicit specification of one fit."""
+    model_config = ConfigDict(extra="forbid")
+
+    z: float = Field(..., gt=0, description="Lya-slice redshift (fixed)")
+    z_sigma: float = Field(0.0, ge=0)
+    continuum: ContinuumConfig = Field(default_factory=ContinuumConfig)
+    lines: List[LineConfig] = Field(default_factory=default_lines)
+    dust: DustConfig = Field(default_factory=DustConfig)
+    mc: MCConfig = Field(default_factory=MCConfig)
+    ratios: List[RatioConfig] = Field(default_factory=lambda: [RatioConfig()])
+
+    @model_validator(mode="after")
+    def _check_lines(self) -> "FitConfig":
+        names = [l.name for l in self.lines]
+        if len(set(names)) != len(names):
+            dupes = sorted({n for n in names if names.count(n) > 1})
+            raise ValueError(f"duplicate line names: {dupes}")
+        enabled = {l.name: l for l in self.lines if l.role != "off"}
+        if not any(l.role == "free" for l in enabled.values()):
+            raise ValueError("at least one line must have role='free'")
+        for l in enabled.values():
+            if l.role != "tied":
+                continue
+            seen, cur = {l.name}, l
+            while cur.role == "tied":
+                target = enabled.get(cur.tied_to)
+                if target is None:
+                    raise ValueError(
+                        f"line {cur.name!r} is tied to {cur.tied_to!r}, which "
+                        "is off or undefined")
+                if target.name in seen:
+                    raise ValueError(f"tie cycle involving {target.name!r}")
+                seen.add(target.name)
+                cur = target
+        for r in self.ratios:
+            for side in (r.numerator, r.denominator):
+                if side not in enabled:
+                    raise ValueError(
+                        f"ratio {r.name!r} references {side!r}, which is not "
+                        "an enabled line")
+        return self
+
+    # ---- convenience constructors matching the paper's two modes ----------
+    @classmethod
+    def paper_default(cls, z: float, **kwargs) -> "FitConfig":
+        """Multi-band mode: slope fitted, Halpha + [O III] free, Case B ties."""
+        return cls(z=z, **kwargs)
+
+    @classmethod
+    def three_band(cls, z: float, beta: float = -2.0, **kwargs) -> "FitConfig":
+        """Selection-band mode: slope fixed (default beta = -2, the metal-poor
+        expectation) with the 0.3 slope prior in the error budget."""
+        return cls(z=z, continuum=ContinuumConfig(beta_mode="fixed", beta=beta),
+                   **kwargs)
+
+    def with_line_role(self, name: str, role: str,
+                       tied_to: Optional[str] = None,
+                       ratio: Optional[float] = None) -> "FitConfig":
+        """Copy of this config with one line's role changed.  The copy is
+        fully re-validated, so e.g. switching off a line that others are
+        tied to raises immediately rather than failing inside fit()."""
+        if name not in {l.name for l in self.lines}:
+            raise KeyError(f"no line named {name!r}")
+        data = self.model_dump()
+        for l in data["lines"]:
+            if l["name"] == name:
+                l["role"] = role
+                l["tied_to"] = tied_to if role == "tied" else None
+                l["ratio"] = ratio if role == "tied" else None
+        return FitConfig.model_validate(data)
+
+    def with_contaminant_mode(self, frac: float = 0.35) -> "FitConfig":
+        """Tie [N II]+[S II] to Halpha (metal-rich contaminant mode)."""
+        cfg = self
+        for name, ratio in contaminant_ties(frac).items():
+            cfg = cfg.with_line_role(name, "tied", tied_to="Halpha", ratio=ratio)
+        return cfg
+
+    def with_balmer(self, case: str = "B", te: float = 10000.0,
+                    ne: float = 100.0) -> "FitConfig":
+        """Copy with the Balmer tie ratios set for the given recombination
+        case at (T_e, n_e) (see :func:`lated.lines.balmer_ratios`).
+        Only lines that are currently tied to their default parent
+        (Hbeta -> Halpha, higher orders -> Hbeta) are rewritten; free/off
+        lines and custom ties are left alone.  Case B at
+        (1e4 K, 1e2 cm^-3) reproduces the paper defaults."""
+        ratios = balmer_ratios(case, te, ne)
+        parent = {"Hbeta": "Halpha"}
+        data = self.model_dump()
+        for l in data["lines"]:
+            r = ratios.get(l["name"])
+            if (r is not None and l["role"] == "tied"
+                    and l["tied_to"] == parent.get(l["name"], "Hbeta")):
+                l["ratio"] = r
+        return FitConfig.model_validate(data)
+
+    def with_case_b(self, te: float = 10000.0,
+                    ne: float = 100.0) -> "FitConfig":
+        """Backwards-compatible alias for :meth:`with_balmer` (case='B')."""
+        return self.with_balmer("B", te, ne)

lated/data/filters/F070W.dat

@@ -0,0 +1,201 @@
+6031.5 0.000309961
+6041.5 0.00123754
+6051.5 0.00409764
+6061.5 0.010342
+6071.5 0.0207281
+6081.5 0.0345091
+6091.5 0.0494549
+6101.5 0.0632327
+6111.5 0.0743233
+6121.5 0.0825961
+6131.5 0.0884712
+6141.5 0.0931323
+6151.5 0.097091
+6161.5 0.101308
+6171.5 0.105977
+6181.5 0.110771
+6191.5 0.115565
+6201.5 0.119845
+6211.5 0.123279
+6221.5 0.126114
+6231.5 0.128232
+6241.5 0.130247
+6251.5 0.13192
+6261.5 0.133178
+6271.5 0.134178
+6281.5 0.134887
+6291.5 0.135268
+6301.5 0.135521
+6311.5 0.135661
+6321.5 0.135902
+6331.5 0.137156
+6341.5 0.139277
+6351.5 0.14183
+6361.5 0.144646
+6371.5 0.14706
+6381.5 0.149009
+6391.5 0.150766
+6401.5 0.152204
+6411.5 0.153924
+6421.5 0.155673
+6431.5 0.157162
+6441.5 0.158391
+6451.5 0.159284
+6461.5 0.159984
+6471.5 0.160807
+6481.5 0.161983
+6491.5 0.16336
+6501.5 0.165113
+6511.5 0.166385
+6521.5 0.167236
+6531.5 0.167801
+6541.5 0.168033
+6551.5 0.167927
+6561.5 0.167929
+6571.5 0.167631
+6581.5 0.167511
+6591.5 0.167843
+6601.5 0.168728
+6611.5 0.169699
+6621.5 0.1713
+6631.5 0.173464
+6641.5 0.176055
+6651.5 0.178398
+6661.5 0.180203
+6671.5 0.18098
+6681.5 0.181266
+6691.5 0.181391
+6701.5 0.181189
+6711.5 0.180787
+6721.5 0.180361
+6731.5 0.180272
+6741.5 0.180103
+6751.5 0.179942
+6761.5 0.180319
+6771.5 0.181147
+6781.5 0.182099
+6791.5 0.183778
+6801.5 0.18605
+6811.5 0.188199
+6821.5 0.189765
+6831.5 0.190714
+6841.5 0.191931
+6851.5 0.192864
+6861.5 0.194002
+6871.5 0.194906
+6881.5 0.196068
+6891.5 0.197647
+6901.5 0.198913
+6911.5 0.199266
+6921.5 0.198333
+6931.5 0.196206
+6941.5 0.193351
+6951.5 0.190192
+6961.5 0.187901
+6971.5 0.187081
+6981.5 0.187895
+6991.5 0.190337
+7001.5 0.193836
+7011.5 0.197938
+7021.5 0.200988
+7031.5 0.203635
+7041.5 0.205375
+7051.5 0.206029
+7061.5 0.206845
+7071.5 0.207391
+7081.5 0.20855
+7091.5 0.209964
+7101.5 0.210253
+7111.5 0.209846
+7121.5 0.208012
+7131.5 0.205859
+7141.5 0.204222
+7151.5 0.203804
+7161.5 0.204045
+7171.5 0.204292
+7181.5 0.203746
+7191.5 0.202009
+7201.5 0.19976
+7211.5 0.19814
+7221.5 0.198677
+7231.5 0.20182
+7241.5 0.206824
+7251.5 0.212809
+7261.5 0.218645
+7271.5 0.223363
+7281.5 0.226589
+7291.5 0.228757
+7301.5 0.229885
+7311.5 0.229396
+7321.5 0.228432
+7331.5 0.22666
+7341.5 0.224067
+7351.5 0.221453
+7361.5 0.219258
+7371.5 0.217786
+7381.5 0.217562
+7391.5 0.218243
+7401.5 0.219014
+7411.5 0.219954
+7421.5 0.220665
+7431.5 0.222086
+7441.5 0.224779
+7451.5 0.228542
+7461.5 0.232279
+7471.5 0.236426
+7481.5 0.239395
+7491.5 0.241841
+7501.5 0.243029
+7511.5 0.243551
+7521.5 0.24347
+7531.5 0.241723
+7541.5 0.239053
+7551.5 0.234895
+7561.5 0.230498
+7571.5 0.226996
+7581.5 0.225189
+7591.5 0.224385
+7601.5 0.224738
+7611.5 0.225587
+7621.5 0.226597
+7631.5 0.228928
+7641.5 0.232252
+7651.5 0.236955
+7661.5 0.241852
+7671.5 0.24604
+7681.5 0.247924
+7691.5 0.248015
+7701.5 0.24673
+7711.5 0.244373
+7721.5 0.241802
+7731.5 0.238095
+7741.5 0.233777
+7751.5 0.22837
+7761.5 0.222046
+7771.5 0.213078
+7781.5 0.199583
+7791.5 0.180581
+7801.5 0.156823
+7811.5 0.130334
+7821.5 0.103585
+7831.5 0.0788306
+7841.5 0.0576372
+7851.5 0.0406466
+7861.5 0.0277262
+7871.5 0.018528
+7881.5 0.012305
+7891.5 0.00826874
+7901.5 0.00570614
+7911.5 0.00400084
+7921.5 0.00286948
+7931.5 0.00203922
+7941.5 0.00146461
+7951.5 0.00106776
+7961.5 0.000784746
+7971.5 0.000581088
+7981.5 0.000432432
+7991.5 0.000324602
+8001.5 0.000246103
+8011.5 0.000187665
+8021.5 0.000143742
+8031.5 0.000111208