Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,9 @@ src/exozippy/models/NextGen/runtime/
src/exozippy/models/Claret/ATLAS_L_vt2/
src/exozippy/models/Claret/build/
src/exozippy/models/Claret/sources/
# Third-party extinction maps fetched on first use by exozippy-mkdust
# (utilities/mkdust.py): Zelakiewicz+2025 (Zenodo) and Nataf+2013 Table 3.
src/exozippy/models/dustmaps/
src/exozippy/components/evolutionarymodel/testing.ipynb
src/exozippy/components/evolutionarymodel/massradius_mann.py
src/exozippy/components/evolutionarymodel/massradius_mist.py
Expand Down
1 change: 1 addition & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -95,6 +95,7 @@ Each line names when to read the doc. Read it first; do not reconstruct its reas
- Before touching the microlensing likelihood, the seeding (the built-in peak finder; the removed MMEXOFAST keys), or the lens/source body maps, read `src/exozippy/components/mulensing/mulensing.md`.
- Before comparing a microlensing parameter to a published one, converting to or from another modelling code, or "fixing" a microlensing sign, read `src/exozippy/components/mulensing/conventions.md` -- the origins, the parallax signs, `alpha`, `q > 1`, and the mappings onto the other common literature conventions. The Conventions section of paper III carries the same numbered claims. The chi2 tables behind the `alpha` rules (C18, C21, C22) are in `docs/alpha_conventions.md`.
- Before giving the blended light of a microlensing target a parameter of its own, touching the unresolved-background component (its per-band flux, its light-curve tie, its photocenter and proper-motion prior), adding a prior on the background's fluxes or colors, or letting another component read it, read `src/exozippy/components/background/background.md`.
- Before changing the dust-map prior tool (`exozippy-mkdust`: which maps it reads, the default map, the Nataf+2013 conversion to A_V, the widths), read `docs/dust_maps.md`.
- Before touching the red-clump reference (`components/redclump/`), the SED flux-source seam (`Component.sed_flux_sources`) it is read through, the interim source-extinction tie, or how a published clump extinction reaches a fit, read `src/exozippy/components/redclump/redclump.md`.
- Before changing a stellar prior (IMF, the FFP mass function, distance), an empirical stellar or planetary relation, the planet mass coordinate, or the planet radius prior (uniform in R_P/R_*), read `src/exozippy/components/star/star.md`.
- Before touching the galactic model's coordinates -- the galactocentric frame, `line_of_sight_basis`, `galactic_xyz`, `polar_velocity`, the bar angle, or any sign in the velocity transform -- read `src/exozippy/components/galacticmodel/galacticmodel.md`. Positions and velocities come from ONE astropy transform, mirrored in x into genulens's orientation; building either by hand is how review 1.7.1 happened.
Expand Down
113 changes: 113 additions & 0 deletions docs/dust_maps.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,113 @@
# Dust-map priors: `exozippy-mkdust`

`src/exozippy/utilities/mkdust.py`. Given a sky position, it reads every extinction map it can
reach and writes `<name>.dust.params.yaml`: candidate priors on `sed.dust_anchor`, ONE live and
every other commented out (the way `exozippy-mkticsed` comments out non-default catalog rows).
Read this before changing a map, a conversion ratio, a width, or which map is the default.

```
exozippy-mkdust 17:53:48.01 -29:15:47.48 --name KB242087 --outpath .
```

RA/Dec in decimal degrees, or sexagesimal (RA in hours) with colons. A negative sexagesimal Dec
needs no quoting or `--`.

## What it feeds, and why no new key

The SED's sight-line dust profile (`components/sed/sed.md`, "The sight-line dust profile")
samples one total, `sed.dust_anchor`: the extinction at the profile's anchor, in A_V unless the
system config names `sed: {dust_anchor_band: <filter>}`. A red-clump map states the extinction to
the clump, at the bar, which is where the anchor sits when the fit has a red clump or a galactic
model (the bar's mean distance); with neither, the anchor is the whole column, a few percent more
at |b| ~ 3-4 deg. So every map value is an ordinary `{mu, sigma, citation}` prior on
`sed.dust_anchor`. The prior needs the profile on: two or more SED objects at different
distances, or `sed: {distance_constrains_av: true}` for one.

A line written in a band other than V (marked `[band X]` in the file) also needs
`sed: {dust_anchor_band: X}` in the system config; without it the number is read as A_V. The
file says so above the lines. The live line is always A_V, so it can never be misread that way.

With calibrated red-clump rows in the fit (`components/redclump/redclump.md`), use none of the
bulge maps: they are built from the same clump stars, so the clump would be counted twice.

## The default

Following Nataf's 2026 recommendation for bulge sight lines, the live line is the FIRST of these
that gives a usable value:

1. Surot et al. (2020), VVV E(J-Ks) (VizieR J/A+A/644/A140; the nearest node in a 1' cone).
2. Zelakiewicz et al. (2025), UKIRT A_Ks (Zenodo record 14919461, fetched md5-checked on first
use; the 2' x 2' pixel holding the target). A pixel the authors flag as a lower limit is
written, marked, and never the default.
3. Nataf et al. (2013), OGLE-III A_I and E(V-I) (Table 3 from the OGLE archive, fetched size- and
md5-checked; the nearest reliable point within 600", as the OGLE calculator does).
4. Schlafly & Finkbeiner (2011)'s recalibrated SFD E(B-V) (IRSA), only at |b| >= 5 deg: it is the
whole column, and not valid toward the inner bulge.

Surot's map covers Zelakiewicz's, so Zelakiewicz is the default only when Surot is unreachable;
the file then says which preferred map it passed over and why (a failed query is listed as
FAILED with the error, and logged as a WARNING).

### Why the default is A_V converted by hand, not Ks

`sed.md` lets a map's value enter in its own band (`dust_anchor_band`), converted by the fit's
law. That is the right channel for a Ks map ONLY once the law's near-infrared slope is right. The
fit's law today is CCM89 + O'Donnell, tabulated at R_V = 3.1 or with a fitted R_V, and its
near-infrared slope is fixed: at R_V = 3.1, A_V/A_Ks ~ 8.4, while the bulge measures 13-15
(Nataf et al. 2016's median 13.44; 15.3 from the Nataf et al. 2013 means below). A Ks anchor would
put ~40% too little dust in V and I, the bands most microlensing data are in. So the live line
converts the map to A_V with Nataf et al. (2013)'s bulge ratios, and the Ks-native lines are
written commented. They become the better choice when the law's near-infrared slope is fitted.

## The conversions and widths

- **Nataf et al. (2013) bulge means.** A_I = 1.217 E(V-I) (their eq. 29 at the mean R_JKVI) and
R_JKVI = E(J-Ks)/E(V-I) = 0.3433 (their Sec. 8.1). Hence A_V = A_I + E(V-I) = 2.217 E(V-I), and

A_V / E(J-Ks) = (1.217 + 1) / 0.3433 = 6.458.

- **The ratio's sight-line scatter, 7%.** Over the reliable Table 3 sight lines with E(V-I) > 0.5,
(A_I + E(V-I)) / (R_JKVI E(V-I)) has mean 6.465 (agreeing with 6.458) and a fractional standard
deviation of 0.070 (0.070 again for |b| < 3). That is the width a mean ratio carries on one
sight line; it is added in quadrature to the map's own error.
- **Surot et al. (2020):** A_V = 6.458 E(J-Ks); sigma from the node's E(J-Ks) error and the 7%.
The catalog's error is the error of the node MEAN (the star-to-star dispersion is sqrt(20) times
larger); the anchor is a pencil-beam value whose per-object scatter the profile models
separately (`star.av_frac`, `redclump.av_frac`), so the mean's error is the right one. The
Ks line is A_Ks = 0.422167 E(J-Ks), Surot's own measured VVV bulge vector (their eq. 1), in
`Paranal/VISTA.Ks`.
- **Zelakiewicz et al. (2025):** A_Ks to E(J-Ks) through the same Surot vector, then the Nataf
ratio: A_V = 6.458 / 0.422167 A_Ks = 15.30 A_Ks. The width adds a 10% term for the A_Ks to
E(J-Ks) step, the spread of published bulge A_Ks/E(J-Ks) (0.422 Surot et al. 2020, 0.428
Alonso-Garcia et al. 2017, 0.423 Nagatomo et al. 2019, 0.49 Wang & Chen 2019), to the map error
(the mean of the asymmetric errors) and the 7%. The Ks line is written in `2MASS/2MASS.Ks`:
UKIRT WFCAM K has no bolometric-correction column.
- **Nataf et al. (2013) Table 3:** A_V = A_I + E(V-I) directly, no NIR step. The width is the
listed differential reddening S_E(V-I) propagated, (A_I/E(V-I) + 1) S_E(V-I); a point that lists
S_E(V-I) = 0 gets Nataf's 9% field-scale granularity (their eq. 20), and the note says so. The
A_I line is in `Generic/Cousins.I`.
- **SFD:** A_V = 3.1 E(B-V) on the Schlafly & Finkbeiner (2011) recalibration, sigma from the 5'
standard deviation IRSA reports.

On KMT-2024-BLG-2087 ((l, b) = (0.64, -1.70)) the two independent routes agree: Zelakiewicz's
A_Ks = 0.216 gives A_V = 3.30 +/- 0.86 and Nataf's OGLE-III point gives A_V = 3.36 +/- 0.35.

## Maps it does not read

Listed in every output with the reason, and never approximated:

- Zucker et al. (2025), 3D: a multi-GB cube read through the `dustmaps` package, not a web
query; it saturates at A_V ~ 12 and does not reach the bulge itself.
- Green et al. (2019), Bayestar19: the `dustmaps` package (multi-GB); dec > -30 only.
- Gonzalez et al. (2012), BEAM: an interactive web calculator only; Surot et al. (2020)
supersedes it over the same VVV area.
- VVV-ExMaps (the BaSTI web service of Surot et al. 2020): needs a user ID; the same map is read
from VizieR.
- Marshall et al. (2006): a 15', Besancon-model 3D map; not read.

## Tests

`tests/test_mkdust.py`: each reader on a fixture in the map's own format (no network), the
default order and a failed query, the SFD latitude rule, the CLI's negative Dec, every written
line parsing as YAML with references.bib citations, and the live line resolving as the
`sed.dust_anchor` prior of a dust-profile system.
1 change: 1 addition & 0 deletions pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -234,6 +234,7 @@ exozippy-gui = "exozippy.gui.app:main"
# main()s, kept for the historical `python scripts/X.py` spelling).
exozippy-getdata = "exozippy.utilities.getdata:main"
exozippy-mkticsed = "exozippy.utilities.mkticsed:main"
exozippy-mkdust = "exozippy.utilities.mkdust:main"
exozippy-exofast2exozippy = "exozippy.utilities.exofast2exozippy:main"
# Example data that is NOT redistributed with EXOZIPPy (licence
# compatibility -- see components/pharmacokinetics/fetch_theoph.py).
Expand Down
13 changes: 12 additions & 1 deletion scripts/zenodo_publish.py
Original file line number Diff line number Diff line change
Expand Up @@ -835,7 +835,18 @@ def load_registry(path: Path):


def _q(s: str) -> str:
"""A double-quoted Python string literal, as ruff format writes it."""
"""A Python string literal, as ruff format writes it.

Double-quoted, unless the text holds a double quote and no single one:
then ruff prefers single quotes to escaping (a Zenodo title that quotes
its paper's title, e.g. 'Data for "..."').
"""
if '"' in s and "'" not in s:
return (
"'"
+ json.dumps(s, ensure_ascii=True)[1:-1].replace('\\"', '"')
+ "'"
)
return json.dumps(s, ensure_ascii=True)


Expand Down
5 changes: 4 additions & 1 deletion src/exozippy/components/redclump/redclump.md
Original file line number Diff line number Diff line change
Expand Up @@ -125,7 +125,10 @@ through the passband on the clump's own spectrum at the fit's law (the tables, o
A published value is a params-file prior on that element, with its citation:
`redclump.RedClump.extinction_0: {mu: 1.80, sigma: 0.05, citation: ...}` (the owner spelling,
`element_owners`). Better still, when the paper gives the calibrated I_RC and (V-I)_RC, write
them as SED rows naming the clump: that is the measurement, not a derived number.
them as SED rows naming the clump: that is the measurement, not a derived number. A 2D MAP value
(Surot et al. 2020, Zelakiewicz et al. 2025, Nataf et al. 2013) goes on `sed.dust_anchor` instead,
written by `exozippy-mkdust` (`docs/dust_maps.md`) -- and not beside calibrated clump rows,
since the maps are built from the same clump stars.

This REPLACES the monochromatic inversions (review 2.9.16(b)): `extinction.
av_from_band_extinction` / `av_from_colour_excess` and mkticsed's `band_extinction` (which now
Expand Down
6 changes: 4 additions & 2 deletions src/exozippy/components/sed/defaults.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -65,8 +65,10 @@ sed:
# The anchored total: the extinction in sed.dust_anchor_band (default A_V
# itself) at the anchor -- the red clump's distance when a clump is in the
# fit, else the whole column. It carries the AMOUNT; the bins only the
# shape. A 2D map's value is a prior HERE (mu/sigma + citation), in the
# map's own band (dust_anchor_band), with no law conversion by hand.
# shape. A 2D map's value is a prior HERE (mu/sigma + citation):
# `exozippy-mkdust` writes one per map (docs/dust_maps.md), the default as
# A_V through Nataf+2013's bulge ratios, since the law's fixed NIR slope
# makes a Ks anchor (dust_anchor_band) put too little dust in the optical.
# DEFAULT_WEAK: a user's A_V start on a star seeds it (a hint), and this
# default yields to any other start. Lower bound strictly positive (the
# anchor-band inversion divides by the band extinction).
Expand Down
2 changes: 1 addition & 1 deletion src/exozippy/components/sed/sed.md
Original file line number Diff line number Diff line change
Expand Up @@ -233,7 +233,7 @@ The tie has a second table source since 2026-10-20: tables EXOZIPPy generates it

**The anchor: one sampled total, the bins only shape** (ruling 12). `A(d) = A_anchor C(d) / C(d_anchor)`. `sed.dust_anchor` is sampled directly (DEFAULT_WEAK, so a user's start on any star seeds it): the well-measured total is one axis, not a curved ridge through K log-increments. `d_anchor` is the red clump's SAMPLED distance when a clump is in the fit (an `SEDFluxSource` with `extinction_anchor=True`; at most one); else, with a galactic model, the Galactic bar's MEAN distance on the sight line (`GalacticModel.bar_distance_moments`, the distance a clump block's prior is centered on), a FIXED number, not sampled; else infinity (`C(inf) = sum 10**z_k`: the whole column), with a DEBUG line. The bar, not the column, because a red-clump extinction map (Surot et al. 2020, Zelakiewicz et al. 2025) states the extinction TO THE CLUMP, at the bar, and a source behind the bar sees 3-5% more at |b| ~ 3-4 deg (JDE 2026-11-10). The clump's own `redclump.av = A(d_clump) (1 + redclump.av_frac)`, `av_frac` ~ N(0, 0.09) (Nataf et al. 2013's field-scale granularity: the centroid measures the pencil beam to 9%), which SUPERSEDES PR 2's interim `av_ratio` tie (kept only with the profile off; `clump_constrains_source_av: true` under the profile raises).

**The anchor's band** (`sed: {dust_anchor_band: <filter>}`). Absent: the anchor IS A_V (no conversion; every shipped example). With a filter (a NIR map's 2MASS Ks), `sed.dust_anchor` is the extinction in THAT band, integrated through the passband on a reference red-clump spectrum (Teff 4700 K, logg 2.5, [Fe/H] 0 -- the giants the maps are built from) at the fit's law, so a map value is a prior natively with no hand conversion and, under `fit_rv_dust`, a tight A_Ks no longer makes A_V and R_V a curved ridge. `sed.av_anchor` (derived, reported) is A_V at the anchor: the band-integrated A_band(A_V) inverted on the SED's OWN grid (`bc_node`, table or spectral path) by three fixed-point steps from the A_V = 1 ratio, converging to < 1e-5 (the ratio A_band/A_V varies by a few percent over A_V 1-8). The filter must have a BC column (it is requested through `sed_flux_filters`). Why A_V is the default and not A_I: it keeps every shipped example bit-identical, it is the grid's own axis, and every per-star `av` the BC path consumes is A_V.
**The anchor's band** (`sed: {dust_anchor_band: <filter>}`). Absent: the anchor IS A_V (no conversion; every shipped example). With a filter (a NIR map's 2MASS Ks), `sed.dust_anchor` is the extinction in THAT band, integrated through the passband on a reference red-clump spectrum (Teff 4700 K, logg 2.5, [Fe/H] 0 -- the giants the maps are built from) at the fit's law, so a map value is a prior natively with no hand conversion and, under `fit_rv_dust`, a tight A_Ks no longer makes A_V and R_V a curved ridge. `sed.av_anchor` (derived, reported) is A_V at the anchor: the band-integrated A_band(A_V) inverted on the SED's OWN grid (`bc_node`, table or spectral path) by three fixed-point steps from the A_V = 1 ratio, converging to < 1e-5 (the ratio A_band/A_V varies by a few percent over A_V 1-8). The filter must have a BC column (it is requested through `sed_flux_filters`). Why A_V is the default and not A_I: it keeps every shipped example bit-identical, it is the grid's own axis, and every per-star `av` the BC path consumes is A_V. **A map value** comes from `exozippy-mkdust` (`docs/dust_maps.md`), which writes every map it can read as a commented `sed.dust_anchor` line and leaves one live. The live line is A_V converted with Nataf et al. (2013)'s bulge ratios, not a native Ks line: the law's near-infrared slope is fixed (A_V/A_Ks ~ 8.4 at R_V = 3.1 against the bulge's 13-15), so a Ks anchor would put ~40% too little dust in V and I until that slope is fitted.

**Each object's own coordinate.** `star.av_frac` ~ N(0, 0.03) per read star (Sale 2012's per-star term; JDE's 0.02-0.05), bounds [-0.9, 10] as validity limits (A_V > 0). THE one spelling of the width is its sigma, `star.<name>.av_frac: {sigma: 0.05}`. Under the profile `av_frac` joins the `STAR_KNOBS` (pinned and inactive on unread stars, as av), counts in `PHOTOMETRIC_DOF` in place of av, and the errscale count adds the anchor once (and under the split the near R_V and the boundary); the z_k are prior-only shape and are not counted. An orbit group links `av_frac` instead of `av` (`Star.orbit_linked_params`: a derived member would raise). A derived av has no lower grid barrier (A(d) > 0 by construction; a barrier at 0 would tax a nearby lens), and keeps the grid's upper one, as `loggsed` does.

Expand Down
15 changes: 14 additions & 1 deletion src/exozippy/components/sed/sed.py
Original file line number Diff line number Diff line change
Expand Up @@ -583,7 +583,7 @@ def prefix(self):

@classmethod
def get_utilities(cls):
from ...utilities import mkticsed
from ...utilities import mkdust, mkticsed
from ...utilities.registry import (
UtilitySpec,
argparse_subprocess_runner,
Expand All @@ -602,6 +602,19 @@ def get_utilities(cls):
build_parser=mkticsed.build_parser,
run=argparse_subprocess_runner("exozippy.utilities.mkticsed"),
),
UtilitySpec(
name="mkdust",
label="Dust-map prior for the sight line",
description=(
"Query the extinction maps at a position and write the "
"sed.dust_anchor prior (every map, all but one commented "
"out)."
),
component_keys=["sed"],
available=True,
build_parser=mkdust.build_parser,
run=argparse_subprocess_runner("exozippy.utilities.mkdust"),
),
]

@classmethod
Expand Down
2 changes: 2 additions & 0 deletions src/exozippy/latex/references.bib
Original file line number Diff line number Diff line change
Expand Up @@ -451,3 +451,5 @@ @article{Bensby:2013
@article{Green:2014, title={A Method for Mapping the Three-dimensional Distribution of Dust in the {Milky Way}}, volume={783}, DOI={10.1088/0004-637X/783/2/114}, number={2}, journal={\apj}, author={Green, Gregory M. and Schlafly, Edward F. and Finkbeiner, Douglas P. and others}, year={2014}, pages={114} }
@article{Sale:2012, title={{3D} extinction mapping using hierarchical {Bayesian} models}, volume={427}, DOI={10.1111/j.1365-2966.2012.21662.x}, number={3}, journal={\mnras}, author={Sale, Stuart E.}, year={2012}, pages={2119} }
@article{Schlafly:2016, title={The Optical-infrared Extinction Curve and its Variation in the {Milky Way}}, volume={821}, DOI={10.3847/0004-637X/821/2/78}, number={2}, journal={\apj}, author={Schlafly, E. F. and Meisner, A. M. and Stutz, A. M. and others}, year={2016}, pages={78} }
@article{Schlafly:2011, title={Measuring Reddening with {Sloan Digital Sky Survey} Stellar Spectra and Recalibrating {SFD}}, volume={737}, DOI={10.1088/0004-637X/737/2/103}, number={2}, journal={\apj}, author={Schlafly, Edward F. and Finkbeiner, Douglas P.}, year={2011}, pages={103} }
@article{Zelakiewicz:2025, title={A Near-Infrared Extinction and Reddening Map Towards the {Galactic} Bulge Using {UKIRT}}, volume={170}, journal={\aj}, author={Zelakiewicz, Aiden S. and Johnson, Samson A. and Gaudi, B. Scott and Bryden, Geoffrey and Nataf, David M. and Shvartzvald, Yossi}, year={2025}, pages={328}, eprint={2509.25440}, archivePrefix={arXiv}, note={Map data: Zenodo, doi:10.5281/zenodo.14919461} }
Loading
Loading