Optical Host Galaxy Association

This section describes the three modules that connect zdm’s redshift-DM predictions to the PATH (Probabilistic Association of Transients to their Hosts) algorithm. Together they provide physically motivated priors on FRB host galaxy apparent magnitudes, derived from the zdm posterior p(z | DM_EG).

• zdm.optical_params — parameter dataclasses configuring each model

• zdm.optical — host magnitude models and the PATH interface wrapper

• zdm.optical_numerics — numerical evaluation, optimisation, and statistics for fitting the models to CRAFT ICS optical data

Overview

Standard PATH assigns host galaxy candidates a prior based only on galaxy surface density and angular size. The zdm optical modules replace this with a prior informed by p(z | DM_EG): given an FRB’s extragalactic DM, zdm predicts a redshift distribution, which is convolved with a host galaxy luminosity model to produce p(m_r | DM_EG).

The modules are built around a two-layer design:

┌──────────────────────────────────────────────────────────────┐
│                  model_wrapper  (optical.py)                 │
│   Convolves p(m_r|z) with zdm p(z|DM_EG) → p(m_r|DM_EG)   │
│   Estimates P_U (undetected host prior)                      │
│   Plugs into PATH via pathpriors.USR_raw_prior_Oi           │
└──────────────────────────────────────────────────────────────┘
                           │ wraps
┌──────────────────────────────────────────────────────────────┐
│               Host magnitude models  (optical.py)            │
│                                                              │
│   simple_host_model  — parametric p(M_r) histogram          │
│   loudas_model       — mass/SFR-weighted tables (Loudas)    │
│   marnoch_model      — Gaussian fit to known hosts          │
│                        (Marnoch et al. 2023)                │
└──────────────────────────────────────────────────────────────┘
                           │ configured by
┌──────────────────────────────────────────────────────────────┐
│              Parameter dataclasses  (optical_params.py)      │
│                                                              │
│   OpticalState  ←  SimpleParams, LoudasParams,              │
│                     Apparent, Identification                 │
└──────────────────────────────────────────────────────────────┘

Host Magnitude Models

Three models are available, all implementing the same interface get_pmr_gz(mrbins, z) which returns p(m_r | z) for a set of apparent magnitude bin edges at a given redshift.

simple_host_model

A parametric model describing the intrinsic absolute magnitude distribution p(M_r) as N amplitudes (default 10) at uniformly spaced points between Absmin and Absmax. The amplitudes are normalised to sum to unity and interpolated onto a fine internal grid via one of four schemes controlled by AbsModelID:

AbsModelID	Description
0	Step-function histogram — each parameter value applies uniformly to its bin
1	Linear interpolation between parameter points (default)
2	Cubic spline interpolation (negative values clamped to zero)
3	Cubic spline in log-space (parameters are log10 weights)

Conversion from M_r to m_r is controlled by AppModelID:

AppModelID	Description
0	Pure distance modulus, no k-correction (default)
1	Distance modulus plus power-law k-correction 2.5 × k × log10(1 + z)

loudas_model

Uses precomputed p(m_r | z) tables from Nick Loudas, constructed by weighting galaxy luminosities by either stellar mass or star-formation rate. The single free parameter fSFR interpolates between the two:

\[p(m_r | z) = (1 - f_{\rm SFR})\,p_{\rm mass}(m_r | z) + f_{\rm SFR}\,p_{\rm SFR}(m_r | z)\]

Interpolation between tabulated redshift bins is performed in log-z space with a luminosity-distance shift applied to each tabulated distribution before combining, ensuring correct apparent magnitude evolution at low redshift.

marnoch_model

A zero-parameter model based on Marnoch et al. 2023 (MNRAS 525, 994). Fits a Gaussian to the r-band magnitude distribution of known CRAFT ICS FRB host galaxies, with mean and standard deviation described as cubic splines of redshift. No free parameters; the model is fixed by the observed host sample.

The model_wrapper Class

model_wrapper is a survey-independent wrapper around any host model. Its key responsibilities are:

1. Precomputation: at initialisation it calls model.get_pmr_gz for every redshift value in the zdm grid to build a cached p(m_r | z) array.

2. DM integration: init_path_raw_prior_Oi(DM, grid) extracts p(z | DM_EG) from the grid and convolves it with the cached array to produce p(m_r | DM_EG).

3. P_U estimation: estimate_unseen_prior() integrates the magnitude prior against the detection probability curve (logistic function centred on pU_mean with width pU_width) to obtain the prior probability that the true host is below the detection limit.

4. PATH interface: after init_path_raw_prior_Oi is called, pathpriors.USR_raw_prior_Oi is automatically pointed at path_raw_prior_Oi, so PATH uses the zdm-derived prior transparently.

Typical Workflow

The following example shows how to obtain zdm-informed PATH posteriors for a single CRAFT ICS FRB.

from zdm import optical as opt
from zdm import optical_numerics as on
from zdm import loading, cosmology as cos, parameters

# 1. Initialise zdm grid
state = parameters.State()
cos.set_cosmology(state)
cos.init_dist_measures()
ss, gs = loading.surveys_and_grids(survey_names=['CRAFT_ICS_1300'])
g, s = gs[0], ss[0]

# 2. Choose a host magnitude model
model = opt.marnoch_model()               # or simple_host_model / loudas_model

# 3. Wrap it for the survey's redshift grid
wrapper = opt.model_wrapper(model, g.zvals)

# 4. For a specific FRB, look up its DM_EG
frb = 'FRB20190608B'
imatch = opt.matchFRB(frb, s)
DMEG = s.DMEGs[imatch]

# 5. Compute p(m_r | DM_EG) and estimate P_U
wrapper.init_path_raw_prior_Oi(DMEG, g)   # also sets pathpriors.USR_raw_prior_Oi
PU = wrapper.estimate_unseen_prior()

# 6. Run PATH with the zdm prior
P_O, P_Ox, P_Ux, mags, ptbl = on.run_path(frb, usemodel=True, P_U=PU)

To process the full CRAFT ICS sample and compare models, use calc_path_priors() directly. To fit model parameters, pass function() as the objective to scipy.optimize.minimize — see zdm/scripts/Path/optimise_host_priors.py for a complete example.

Parameter Reference

All host galaxy model parameters are held in dataclasses collected by OpticalState. The four constituent dataclasses and their parameters are described below.

SimpleParams

Controls the simple_host_model.

Parameter	Default	Units	Description
Absmin	−25	Mr	Minimum absolute magnitude of the host distribution
Absmax	−15	Mr	Maximum absolute magnitude of the host distribution
NAbsBins	1000	—	Number of internal absolute magnitude bins (fine grid for computing p(mr | z))
NModelBins	10	—	Number of free parameter bins describing p(Mr)
AbsPriorMeth	0	—	Initial prior on absolute magnitudes: 0 = uniform
AbsModelID	1	—	Interpolation scheme for p(Mr): 0 = histogram, 1 = linear, 2 = spline, 3 = log-spline
AppModelID	0	—	Absolute-to-apparent conversion: 0 = distance modulus only, 1 = with power-law k-correction
k	0.0	—	k-correction power-law index (only used when AppModelID=1)

LoudasParams

Controls the loudas_model.

Parameter	Default	Units	Description
fSFR	0.5	—	Fraction of FRB hosts tracing star-formation rate (0 = pure mass-weighted, 1 = pure SFR-weighted)
NzBins	10	—	Number of redshift bins for histogram calculations
zmin	0.0	—	Minimum redshift for p(mr) calculation
zmax	0.0	—	Maximum redshift for p(mr) calculation
NMrBins	0	—	Number of absolute magnitude bins
Mrmin	0.0	Mr	Minimum absolute magnitude
Mrmax	0.0	Mr	Maximum absolute magnitude

Apparent

Controls the apparent magnitude grid used by model_wrapper.

Parameter	Default	Units	Description
Appmin	10	mr	Minimum apparent magnitude of the internal grid
Appmax	35	mr	Maximum apparent magnitude of the internal grid
NAppBins	250	—	Number of apparent magnitude bins

Identification

Controls the survey detection completeness model used to compute P_U. The detection probability is modelled as a logistic function: p(detected | m_r) = 1 − p(U | m_r) where

\[p(U | m_r) = \frac{1}{1 + \exp\!\left(\frac{\mu - m_r}{w}\right)}\]

with μ = pU_mean and w = pU_width.

Parameter	Default	Units	Description
pU_mean	26.385	mr	Magnitude at which 50 % of host galaxies are undetected (the survey’s half-completeness limit). Default value is calibrated to VLT/FORS2 R-band observations.
pU_width	0.279	mr	Characteristic width of the completeness rolloff. Smaller values give a sharper transition between detected and undetected regimes.

Optimisation and Statistics

zdm.optical_numerics provides two goodness-of-fit statistics for comparing the model-predicted apparent magnitude prior to observed PATH posteriors across a sample of FRBs:

Maximum-likelihood statistic (calculate_likelihood_statistic())

For each FRB, evaluates

\[\ln \mathcal{L}_i = \log_{10}\!\left(\sum_j \frac{P(O_j|x)}{s_i} + P_{U,i}^{\rm prior}\right)\]

where the sum runs over candidate host galaxies and s_i is a rescale factor that undoes PATH’s internal renormalisation. The total statistic is Σ ln ℒ_i over all FRBs. This is the recommended objective for parameter fitting.

KS-like statistic (calculate_ks_statistic())

Builds normalised cumulative distributions of the model prior and the observed posteriors (weighted by P(O|x)) over apparent magnitude, then returns the maximum absolute difference — analogous to the KS test statistic. Smaller values indicate a better fit.

Both statistics accept a POxcut argument to restrict the sample to FRBs with a confidently identified host (max P(O|x) > threshold), simulating a traditional host-identification approach.

Scripts

Ready-to-run scripts using these modules are in zdm/scripts/Path/:

Script	Purpose
estimate_path_priors.py	Demonstrate zdm-informed PATH priors on all CRAFT ICS FRBs; compare flat vs. model priors; save posterior magnitude histogram
optimise_host_priors.py	Fit host model parameters to the CRAFT ICS sample using scipy.optimize.minimize
plot_host_models.py	Visualise all three host models and compare their PATH posteriors across the CRAFT ICS sample

API Reference

optical_params

Parameter dataclasses for configuring host galaxy models.

zdm.optical_params Module

Classes for optical properties

This philosophy here is to have a class of key parameters that relates to a single class object contained within optical.py. The dataclasses are used to set parameters that initialise their parent classes, which is where all the complicated calculations are performed.

class zdm.optical_params.SimpleParams(Absmin: float = -25, Absmax: float = -15.0, NAbsBins: int = 1000, NModelBins: int = 10, AbsPriorMeth: int = 0, AppModelID: int = 0, AbsModelID: int = 1, k: float = 0.0)

Data class to hold the generic host galaxy class with no pre-specified model

Absmin: float = -25

Absmax: float = -15.0

NAbsBins: int = 1000

NModelBins: int = 10

AbsPriorMeth: int = 0

AppModelID: int = 0

AbsModelID: int = 1

k: float = 0.0

__init__(Absmin: float = -25, Absmax: float = -15.0, NAbsBins: int = 1000, NModelBins: int = 10, AbsPriorMeth: int = 0, AppModelID: int = 0, AbsModelID: int = 1, k: float = 0.0) → None

class zdm.optical_params.LoudasParams(fSFR: float = 0.5, NzBins: int = 10, zmin: float = 0.0, zmax: float = 0.0, NMrBins: int = 0.0, Mrmin: float = 0.0, Mrmax: float = 0.0)

Data class to hold the SFR model from Nick, which models FRBs as some fraction of the star-formation rate.

fSFR: float = 0.5

NzBins: int = 10

zmin: float = 0.0

zmax: float = 0.0

NMrBins: int = 0.0

Mrmin: float = 0.0

Mrmax: float = 0.0

__init__(fSFR: float = 0.5, NzBins: int = 10, zmin: float = 0.0, zmax: float = 0.0, NMrBins: int = 0.0, Mrmin: float = 0.0, Mrmax: float = 0.0) → None

class zdm.optical_params.Identification(pU_mean: float = 26.176, pU_width: float = 0.342)

Data class for holding parameters related to identifying galaxies in an image. These describe the mean and deviation for the function pUgm in optical.py that parameterises p(U|mr)

pU_mean: float = 26.176

pU_width: float = 0.342

__init__(pU_mean: float = 26.176, pU_width: float = 0.342) → None

class zdm.optical_params.Apparent(Appmin: float = 10, Appmax: float = 35, NAppBins: int = 250)

# parameters for apparent mags - used by wrapper

Appmin: float = 10

Appmax: float = 35

NAppBins: int = 250

__init__(Appmin: float = 10, Appmax: float = 35, NAppBins: int = 250) → None

class zdm.optical_params.OpticalState

Initialize the full optical state dataset with the default parameters

__init__()

set_dataclasses()

update_param(param: str, value)

Update the value of a single parameter

Parameters:

• param (str) – name of the parameter

• value – value

Classes

Apparent([Appmin, Appmax, NAppBins])	# parameters for apparent mags - used by wrapper
Identification([pU_mean, pU_width])	Data class for holding parameters related to identifying galaxies in an image.
LoudasParams([fSFR, NzBins, zmin, zmax, ...])	Data class to hold the SFR model from Nick, which models FRBs as some fraction of the star-formation rate.
OpticalState()	Initialize the full optical state dataset with the default parameters
SimpleParams([Absmin, Absmax, NAbsBins, ...])	Data class to hold the generic host galaxy class with no pre-specified model

optical

Host magnitude model classes and the model_wrapper PATH interface.

zdm.optical Module

Optical FRB host galaxy models and PATH interface for zdm.

This module connects zdm redshift-DM grids with the PATH (Probabilistic Association of Transients to their Hosts) algorithm by providing physically motivated priors on FRB host galaxy apparent magnitudes, p(m_r | DM_EG).

Architecture

The module is built around a two-layer design:

Host magnitude models each describes the intrinsic absolute magnitude distribution of FRB host galaxies, p(M_r), and can convert it to an apparent magnitude distribution p(m_r | z) at a given redshift. Three models are provided:

• simple_host_model: parametric histogram of p(M_r) with N free amplitudes (default 10), interpolated linearly or via spline. An optional power-law k-correction can be included. N (or N+1) free parameters.

• loudas_model: precomputed p(m_r | z) tables from Nick Loudas, constructed by weighting galaxies by stellar mass or star-formation rate. Interpolated between tabulated redshift bins with a luminosity-distance shift. Single free parameter fSFR sets the SFR/mass mixing fraction.

• marnoch_model: zero-parameter model. Fits a Gaussian to the r-band magnitude distribution of known CRAFT ICS host galaxies from Marnoch et al. 2023 (MNRAS 525, 994), using cubic splines for the redshift-dependent mean and standard deviation.

``model_wrapper`` a survey-independent wrapper around any host model. Given a zdm Grid and an observed DM_EG, it convolves p(m_r | z) with the zdm p(z | DM_EG) posterior to produce a DM-informed apparent magnitude prior for PATH. It also estimates P_U, the prior probability that the true host is below the survey detection limit.

Typical usage

model = opt.marnoch_model()
wrapper = opt.model_wrapper(model, grid.zvals)
wrapper.init_path_raw_prior_Oi(DMEG, grid)   # DM-specific initialisation
PU = wrapper.estimate_unseen_prior()
# pathpriors.USR_raw_prior_Oi is now set automatically by init_path_raw_prior_Oi

Module-level data

frblistlist of str

TNS names of CRAFT ICS FRBs for which PATH optical data are available (used by the scripts in zdm/scripts/Path/).

class zdm.optical.marnoch_model(OpticalState=None)

Class initiates a model based on Lachlan Marnoch’s predictions for FRB host galaxy visibility in https://ui.adsabs.harvard.edu/abs/2023MNRAS.525..994M/abstract Here, we assume that host galaxy magnitudes have a normal distribution, with mean and standard deviation given by L. Marnoch’s data.

__init__(OpticalState=None)

Initialises the model. There are no variables here.

Parameters:

OpticalState – allows the model to refer to an optical state. However, the model is independent of that state.

load_data()

Loads the Marnoch et al data on r-band magnitudes from FRB hosts

process_rbands()

Build cubic spline fits to the mean and rms of p(m_r) as a function of z.

Reads the per-FRB r-band magnitude columns from self.table, computes their mean (Rbar) and sample standard deviation (Rrms) across all FRBs at each tabulated redshift, then fits two cubic splines:

• self.sbar: CubicSpline interpolating the mean apparent magnitude as a function of redshift.

• self.srms: CubicSpline interpolating the rms scatter as a function of redshift.

These splines are subsequently used by get_pmr_gz to evaluate the Gaussian p(m_r | z) at arbitrary redshifts.

get_pmr_gz(mrbins, z)

Return the apparent magnitude probability distribution p(m_r | z).

Evaluates a Gaussian distribution whose mean and standard deviation are obtained from the cubic splines fit in process_rbands, and integrates it over the provided magnitude bins.

This model has no free parameters; the Gaussian moments are fully determined by the Marnoch et al. 2023 host galaxy data.

Parameters:

• mrbins (array-like of float, length N+1) – Edges of the apparent magnitude bins over which to compute the probability. The output has length N (one value per bin).

• z (float) – Redshift at which to evaluate the magnitude distribution.

Returns:

pmr – Probability in each magnitude bin (sums to ≤ 1; may be less than unity if the Gaussian extends beyond the bin range).

Return type:

np.ndarray, length N

class zdm.optical.loudas_model(OpticalState=None, fname='p_mr_distributions_dz0.01_z_in_0_1.2.h5', data_dir=None, verbose=False)

This class initiates a model based on Nick Loudas’s model of galaxy magnitudes as a function of redshift. The underlying model is a description of galaxies as a function of stellar mass and star-formation rate as a function of redshift.

__init__(OpticalState=None, fname='p_mr_distributions_dz0.01_z_in_0_1.2.h5', data_dir=None, verbose=False)

Initialise the Loudas model, loading precomputed p(m_r | z) tables.

Parameters:

• OpticalState (OpticalState, optional) – optical parameter state. A default OpticalState is created if not provided.

• fname (str) – HDF5 filename containing the Loudas p(m_r | z) tables. Defaults to 'p_mr_distributions_dz0.01_z_in_0_1.2.h5'.

• data_dir (str, optional) – directory containing fname. Defaults to the package data directory zdm/data/optical/.

• verbose (bool) – if True, print progress messages. Defaults to False.

init_pmr(fname, data_dir)

Loads p(mr|z) distributions from Nick Loudas. Note - these are actually distributions in apparent magnitude mr.

Mostly, this wraps around Nick’s code “load_p_mr_distributions”. I’ve kept them separate to distinguish between his code and mine -CWJ.

init_cubics()

initialises cubic splines that interpolate in mr. For later use (speedup!)

get_pmr_gz(mrbins, z)

Return the apparent magnitude probability distribution p(m_r | z).

Interpolates between the two nearest tabulated redshift bins (in log-z space), applying a luminosity-distance shift to each tabulated p(m_r) before combining them. The mass- and SFR-weighted distributions are mixed according to self.fsfr (set via init_args).

The result is normalised so that the bin probabilities sum to unity over the full magnitude range, provided the distribution does not extend significantly beyond mrbins.

Parameters:

• mrbins (array-like of float, length N+1) – Edges of the apparent magnitude bins. Output has length N.

• z (float) – Redshift at which to evaluate the distribution. Values outside the tabulated range are extrapolated from the nearest edge bin.

Returns:

pmr – Probability in each apparent magnitude bin (sums to ≤ 1).

Return type:

np.ndarray, length N

load_p_mr_distributions(data_dir, fname: str = 'p_mr_distributions_dz0.01_z_in_0_1.2.h5') → tuple

This code originally written by Nick Loudas. Used with permission

Load the p(mr|z) distributions from an HDF5 file. :param fname: Input filename. :type fname: str :param output_dir: Directory where the file is stored. Optional (otherwise defaults as below) :type output_dir: str

Returns:

Redshift bin edges. rmag_centers (np.array): Centers of r-band magnitude bins. p_mr_sfr (np.array): p(mr|z) for SFR-weighted population. Shape: (len(zbins) - 1,

rmag_resolution). rmag_resolution(=len(rmag_centers)) is fixed across redshift bins.

p_mr_mass (np.array): p(mr|z) for Mass-weighted population. Shape: (len(zbins) - 1,

rmag_resolution). rmag_resolution(=len(rmag_centers)) is fixed across redshift bins.

Return type:

zbins (np.array)

Note

The PDF in m_r within a given redshift bin [z1,z2] has been computed at the right edge of the bin (z = z2).

give_p_mr_mass(z: float)

Return p(m_r | z) for the stellar-mass-weighted host population.

Uses a nearest-bin lookup (no interpolation) in the tabulated redshift grid. For interpolated results with luminosity-distance shifting, use get_pmr_gz with fSFR=0 instead.

Parameters:

z (float) – Redshift value.

Returns:

p(m_r | z) values at the tabulated r-band magnitude

centres (self.rmags), normalised to sum to unity.

Return type:

np.ndarray

give_p_mr_sfr(z: float)

Return p(m_r | z) for the star-formation-rate-weighted host population.

Uses a nearest-bin lookup (no interpolation) in the tabulated redshift grid. For interpolated results with luminosity-distance shifting, use get_pmr_gz with fSFR=1 instead.

Parameters:

z (float) – Redshift value.

Returns:

p(m_r | z) values at the tabulated r-band magnitude

centres (self.rmags), normalised to sum to unity.

Return type:

np.ndarray

init_args(fSFR)

Set the SFR/mass mixing fraction for the Loudas model.

Parameters:

fSFR (float or array-like of length 1) – fraction of FRB hosts that trace star-formation rate. fSFR=0 gives a purely mass-weighted population; fSFR=1 gives a purely SFR-weighted population. Intermediate values linearly mix the two. If an array is passed, only the first element is used.

init_priors(zlist)

Generates magniude prior distributions for a list of redshifts This allows faster interpolation later.

Currently, this is not used!

class zdm.optical.simple_host_model(OpticalState=None, verbose=False)

A class to hold information about the intrinsic properties of FRB host galaxies. This is a simple but generic model.

Ingredients are:

A model for describing the intrinsic distribution

of host galaxies. This model must be described by some set of parameters, and be able to return a prior as a function of intrinsic host galaxy magnitude. This model is initialised via opstate.AbsModelID. Here, it is just 10 parameters at different absolute magnitudes, with linear/spline interpolation

A model for converting absolute to apparent host magnitudes.

This is by defult an apparent r-band magnitude, though in theory a user can work in whatever band they wish.

Internally, this class initialises:

An array of absolute magnitudes, which get weighted according to the host model. Internal variables associated with this are prefaced “Model”

Note that while this class describes the intrinsic “magnitudes”, really magnitude here is a proxy for whatever parameter is used to intrinsically describe FRBs. However, only 1D descriptions are currently implemented. Future descriptions will include redshift evolution, and 2D descriptions (e.g. mass, SFR) at any given redshift.

__init__(OpticalState=None, verbose=False)

Initialise the simple host magnitude model.

Parameters:

• OpticalState (OpticalState, optional) – optical parameter state providing model configuration (magnitude ranges, number of bins, interpolation scheme, k-correction flag). A default OpticalState is created if not provided.

• verbose (bool, optional) – if True, print which sub-models are being initialised. Defaults to False.

get_args()

function to return args as a vector in the form of init_args

init_abs_bins()

Initialises internal array of absolute magnitudes This is a simple set of uniformly log-spaced bins in terms of absolute magnitude, which the absolute magnitude model gets projected onto.

init_args(Args)

Initialises prior on absolute magnitude of galaxies according to the method.

Parameters:

Args (-) – The prior on absolute magnitudes to set for this model IF AppModelID == 1, then interpret the first as the k-correction

init_model_bins()

Initialises bins for the simple model of an absolute magnitude prior. This is much sparser than the app or abs bins, since these model bins correspond to parameters which may get adjusted by e.g. an MCMC

The base unit here is assumed to be absolute r-band magnitude M, but in principle this works for whatever absolute unit is being used by the model.

get_pmr_gz(mrbins, z)

Return the apparent magnitude probability distribution p(m_r | z).

Converts each apparent magnitude bin centre back to an absolute magnitude using CalcAbsoluteMags, then linearly interpolates the absolute magnitude weight array (self.AbsMagWeights) to obtain a probability density at each bin.

Parameters:

• mrbins (np.ndarray of float, length N+1) – Edges of the apparent magnitude bins. The output has length N, with one probability value per bin centre.

• z (float) – Redshift at which to evaluate the distribution.

Returns:

pmr – Probability density at each apparent magnitude bin centre. Values at the edges of the absolute magnitude range are clamped to the nearest valid bin rather than extrapolated.

Return type:

np.ndarray, length N

Notes

The returned values are NOT renormalised to sum to unity; the sum may be less than one if some absolute magnitudes lie outside the model range [Absmin, Absmax]. This is intentional: the shortfall represents probability mass for hosts too faint or too bright to appear in the apparent magnitude range.

gauss(x, mu=0, sigma=0.1)

simple Gaussian smoothing function

init_abs_mag_weights()

Assigns a weight to each of the absolute magnitudes in the internal array (which generally is very large) in terms of the absolute magnitude parameterisation (generally, only a few parameters)

class zdm.optical.model_wrapper(model, zvals)

Generic functions applicable to all models.

The program flow is to initialise with a host model (“model”), then given arrays of Mr and zvalues, pre-calculate an array of p(Mr|z), and then for individual host galaxies with a p(z|DM) distribution, be able to return priors for PATH.

Internally, the code uses an array of apparent magnitudes, which is used to compare with host galaxy candidates. Internal variables associated with this are prefaced “App”

The Arrays mapping intrinsic to absolute magnitude as a function

of redshift, to allow quick estimation of p(apparent_mag | DM) for a given FRB survey with many FRBs Internal variables associated with this are prefaced “Abs”

The workflow is:

-init with a model class and array of z values. This sets

absolute magnitude bins. The z values should correspond to those from a grid object. Initialisation primarily calls p(Mr|z) repeatedly for all internal Mr and z values, to allow fast evaluation in the future

• set up PATH functions to point to this array:

  pathpriors.USR_raw_prior_Oi = wrapper.path_raw_prior_Oi

• initialise this class for a given init_path_raw_prior_Oi(DM,grid).

  This calculates magnitude priors given p(z|DM) (grid) and p(mr|z) (host model).

__init__(model, zvals)

Initialises model wrapper.

Parameters:

• model (class object) – Model is one of the host model class objects that can calculate p(Mr|z)

• zvals (np.array) – redshift values corresponding to grid object

• opstate (class optical) – state containing optical info

init_app_bins()

Initialises bins in apparent magnitude It uses these to calculate priors for any given host galaxy magnitude. This is a very simple set of uniformly log-spaced bins in magnitude space, and linear interpolation is used between them.

init_zmapping(zvals)

For a set of redshifts, initialise mapping between intrinsic magnitudes and apparent magnitudes

This routine only needs to be called once, since the model to convert absolute to apparent magnitudes is fixed

It is not set automatically however, and needs to be called with a set of z values. This is all for speedup purposes.

Parameters:

zvals (np.ndarray, float) – array of redshifts over which to map absolute to apparent magnitudes.

init_path_raw_prior_Oi(DM, grid)

Initialise the apparent magnitude prior for a single FRB DM.

Computes p(m_r | DM_EG) by convolving the precomputed p(m_r | z) grid (self.p_mr_z) with the zdm posterior p(z | DM_EG) extracted from grid. The result is stored internally so that path_raw_prior_Oi can be called repeatedly for different host galaxy candidates belonging to the same FRB without recomputing the DM integral.

Also computes the probability that the host is undetected: - self.priors: p(m_r | DM) weighted by the detection probability

p(detected | m_r).

• self.PUdist: the magnitude-resolved contribution to P_U.

• self.PU: scalar total prior probability that the host is unseen, returned by estimate_unseen_prior().

After this call, pathpriors.USR_raw_prior_Oi is automatically pointed at self.path_raw_prior_Oi.

Parameters:

• DM (float) – extragalactic dispersion measure of the FRB (pc cm⁻³).

• grid (Grid) – initialised zdm grid object providing p(z, DM).

get_posterior(grid, DM)

Return apparent magnitude and redshift posteriors for a given DM.

Computes p(z | DM) from the grid and convolves it with the precomputed self.maghist to obtain p(m_r | DM).

Note: from PATH’s perspective this is a prior on host magnitude, but from zdm’s perspective it is a posterior on redshift given DM.

This method predates init_path_raw_prior_Oi and may not be actively used in current scripts.

Parameters:

• grid (Grid) – initialised zdm grid object providing p(z, DM).

• DM (float or np.ndarray) – FRB extragalactic DM(s) in pc cm⁻³.

Returns:

probability distribution of apparent magnitude

given DM, p(m_r | DM).

pz (np.ndarray): probability distribution of redshift given DM,

p(z | DM).

Return type:

papps (np.ndarray)

estimate_unseen_prior()

Calculates PU, the prior that an FRB host galaxy of a particular DM is unseen in the optical image

This requires initialisation of init_path_raw_prior_Oi

NOTE: The total normalisation of priors in the magnitude range

may be less than unity. This is because some probability may fall outside of the magnitude range being examined. Hence, the correct normalisation is found by summing the visible magnitudes, and subtracting them from unity.

Parameters:

mag_limit (float) – maximum observable magnitude of host galaxies

Returns:

probability PU of true hist being unseen in the optical

image.

Return type:

PU (float)

path_base_prior(mags)

Evaluate the apparent magnitude prior p(m_r | DM) at a list of magnitudes.

Linearly interpolates self.priors (which already incorporates the detection probability p(detected | m_r)) at each requested magnitude, converting from the internally normalised sum-to-unity convention to a probability density by dividing by the bin width self.dAppmag.

Unlike path_raw_prior_Oi, this method does NOT divide by the galaxy surface density Sigma_m, so it returns the raw magnitude prior without the PATH normalisation factor.

Parameters:

mags (list or tuple of float) – apparent r-band magnitudes of candidate host galaxies at which to evaluate the prior.

Returns:

prior probability density p(m_r | DM) evaluated

at each magnitude in mags.

Return type:

Ois (np.ndarray)

path_raw_prior_Oi(mags, ang_sizes, Sigma_ms)

Function to pass to astropath module for calculating a raw FRB prior.

NOTE: as of all recent PATH iterations, the galaxy angular

size should NOT be included in the calculation, since this gets integrated over in estimating the offset error. Nonetheless, this function must accept an ang_size argument.

NOTE2: Before using this function, the call “init_path_raw_prior_Oi”

must be called. This is because the full prior requires a zDM grid and an FRB DM, yet this cannot be passed to raw_prior_Oi within PATH.

Parameters:

• mags (tuple, float) – host galaxy r-band magnitudes

• ang_sizes (tuple, float) – host galaxy angular sizes (arcsec I believe)

• Sigma_ms (tuple, float) – galaxy densities on the sky

Returns:

priors on host galaxy magnitdues mags

Return type:

Ois (tuple)

zdm.optical.load_marnoch_data()

Loads the Marnoch et al data on r-band magnitudes from FRB hosts

zdm.optical.get_pz_prior(grid, DM)

Returns posterior redshift distributiuon for a given grid and DM magnitude distribution for FRBs of DM given a grid object

Parameters:

• grid (class grid object) – grid object modelling p(z,DM)

• DM (float or np.ndarray of floats) – FRB dispersion measure, pc cm^-3

Returns:

probability distribution in redshift space

Return type:

pz (np.ndarray)

zdm.optical.SimplekApparentMags(Abs, k, zs)

Convert absolute to apparent magnitudes with a power-law k-correction.

Applies the distance modulus plus a k-correction of the form 2.5 * k * log10(1 + z).

Parameters:

• Abs (float or np.ndarray) – absolute magnitude(s) M_r.

• k (float) – k-correction power-law index. k=0 reduces to a pure distance modulus (identical to SimpleApparentMags).

• zs (float or np.ndarray) – redshift(s) of the galaxies.

Returns:

apparent magnitude(s). Scalar if both inputs are

scalar; 1-D array if one is scalar and one is an array; 2-D array of shape (NAbs, Nz) if both are arrays (computed via np.outer).

Return type:

ApparentMags

zdm.optical.SimplekAbsoluteMags(App, k, zs)

Convert apparent to absolute magnitudes with a power-law k-correction.

Inverse of SimplekApparentMags: subtracts the distance modulus and k-correction 2.5 * k * log10(1 + z) from the apparent magnitude.

Parameters:

• App (float or np.ndarray) – apparent magnitude(s) m_r.

• k (float) – k-correction power-law index. k=0 reduces to a pure distance modulus (identical to SimpleAbsoluteMags).

• zs (float or np.ndarray) – redshift(s) of the galaxies.

Returns:

absolute magnitude(s). Scalar if both inputs are

scalar; 1-D array if one is scalar and one is an array; 2-D array of shape (NApp, Nz) if both are arrays (computed via np.outer).

Return type:

AbsoluteMags

zdm.optical.SimpleAbsoluteMags(App, zs)

Convert apparent to absolute magnitudes using the distance modulus only.

Subtracts 5 * log10(D_L / 10 pc) from the apparent magnitude, where D_L is the luminosity distance in Mpc. No k-correction is applied.

Parameters:

• App (float or np.ndarray) – apparent magnitude(s) m_r.

• zs (float or np.ndarray) – redshift(s) of the galaxies.

Returns:

absolute magnitude(s). Scalar if both inputs are

scalar; 1-D array if one input is scalar and one is an array; 2-D array of shape (NApp, Nz) if both are arrays (computed via np.outer).

Return type:

AbsoluteMags

zdm.optical.SimpleApparentMags(Abs, zs)

Convert absolute to apparent magnitudes using the distance modulus only.

Adds 5 * log10(D_L / 10 pc) to the absolute magnitude, where D_L is the luminosity distance in Mpc. No k-correction is applied.

Parameters:

• Abs (float or np.ndarray) – absolute magnitude(s) M_r.

• zs (float or np.ndarray) – redshift(s) of the galaxies.

Returns:

apparent magnitude(s). Scalar if both inputs are

scalar; 1-D array if one input is scalar and one is an array; 2-D array of shape (NAbs, Nz) if both are arrays (computed via np.outer).

Return type:

ApparentMags

zdm.optical.p_unseen_Marnoch(zvals, plot=False)

Return the probability that an FRB host galaxy is unseen in typical VLT observations.

Digitises Figure 3 of Marnoch et al. 2023 (MNRAS 525, 994), which shows p(U | z) — the cumulative probability that a host galaxy at redshift z falls below the VLT/FORS2 R-band detection limit. A cubic polynomial is fit to the digitised curve and evaluated at the requested redshifts. Values are clamped to [0, 1].

Parameters:

• zvals (float or np.ndarray) – redshift(s) at which to evaluate p(U | z).

• plot (bool) – if True, save a diagnostic comparison plot of the raw digitised data, linear interpolation, and polynomial fit to p_unseen.pdf. Defaults to False.

Returns:

p(U | z) evaluated at each element of zvals,

clamped to the range [0, 1].

Return type:

fitv (np.ndarray)

zdm.optical.simplify_name(TNSname)

Reduce a TNS FRB name to a six-character YYMMDD[L] identifier.

Strips the leading FRB prefix (if present) and the year’s century digits, retaining only the six-digit date plus any trailing letter suffix, to allow case-insensitive matching between survey entries and external FRB catalogues.

Parameters:

TNSname (str) – FRB name in TNS format, e.g. 'FRB20180924B' or '20180924B'.

Returns:

simplified six-character identifier, e.g. '180924B'

(six digits plus optional letter).

Return type:

name (str)

zdm.optical.matchFRB(TNSname, survey)

Find the index of an FRB in a survey by TNS name.

Uses simplify_name to normalise both the query name and the survey entries, so minor formatting differences (century digits, trailing letters) do not prevent a match.

Parameters:

• TNSname (str) – TNS name of the FRB to look up, e.g. 'FRB20180924B'.

• survey (Survey) – loaded survey object whose frbs["TNS"] column contains TNS names of detected FRBs.

Returns:

index into survey.frbs of the first matching FRB,

or None if the FRB is not found in the survey.

Return type:

int or None

zdm.optical.plot_frb(name, ralist, declist, plist, opfile)

Plot an FRB localisation and its PATH host galaxy candidates.

Produces a scatter plot showing the FRB position and a set of deviated/sampled positions colour-coded by their PATH posterior P(O|x), overlaid with circles representing candidate host galaxies scaled by their angular size. All coordinates are shown in arcseconds relative to the FRB position.

Parameters:

• name (str) – TNS FRB name (e.g. 'FRB20180924B'), used to load the FRB object and the corresponding PATH candidate table.

• ralist (np.ndarray) – right ascension values (degrees) of deviated FRB positions to plot, colour-coded by plist.

• declist (np.ndarray) – declination values (degrees) of deviated FRB positions.

• plist (np.ndarray) – PATH posterior values P(O|x) for the deviated positions, used to set the colour scale.

• opfile (str) – output file path for the saved figure.

zdm.optical.pUgm(mag, mean, width)

Return the probability that a galaxy is undetected as a function of magnitude.

Models the survey detection completeness as a logistic function that transitions from ~0 (bright, always detected) to ~1 (faint, never detected) with a smooth rolloff centred on mean:

p(U | m) = 1 / (1 + exp((mean - m) / width))

Parameters:

• mag (float or np.ndarray) – r-band apparent magnitude(s) at which to evaluate the detection-failure probability.

• mean (float) – magnitude at which p(U | m) = 0.5 (the 50% completeness limit of the survey).

• width (float) – characteristic width of the completeness rolloff in magnitudes. Smaller values give a sharper transition.

Returns:

probability of non-detection at each

magnitude in mag, in the range [0, 1].

Return type:

pU (float or np.ndarray)

Functions

SimpleAbsoluteMags(App, zs)	Convert apparent to absolute magnitudes using the distance modulus only.
SimpleApparentMags(Abs, zs)	Convert absolute to apparent magnitudes using the distance modulus only.
SimplekAbsoluteMags(App, k, zs)	Convert apparent to absolute magnitudes with a power-law k-correction.
SimplekApparentMags(Abs, k, zs)	Convert absolute to apparent magnitudes with a power-law k-correction.
get_pz_prior(grid, DM)	Returns posterior redshift distributiuon for a given grid and DM magnitude distribution for FRBs of DM given a grid object
load_marnoch_data()	Loads the Marnoch et al data on r-band magnitudes from FRB hosts
make_interp_spline(x, y[, k, t, bc_type, ...])	Create an interpolating B-spline with specified degree and boundary conditions.
matchFRB(TNSname, survey)	Find the index of an FRB in a survey by TNS name.
pUgm(mag, mean, width)	Return the probability that a galaxy is undetected as a function of magnitude.
p_unseen_Marnoch(zvals[, plot])	Return the probability that an FRB host galaxy is unseen in typical VLT observations.
plot_frb(name, ralist, declist, plist, opfile)	Plot an FRB localisation and its PATH host galaxy candidates.
simplify_name(TNSname)	Reduce a TNS FRB name to a six-character YYMMDD[L] identifier.

Classes

CubicSpline(x, y[, axis, bc_type, extrapolate])	Piecewise cubic interpolator to fit values (C2 smooth).
loudas_model([OpticalState, fname, ...])	This class initiates a model based on Nick Loudas's model of galaxy magnitudes as a function of redshift.
marnoch_model([OpticalState])	Class initiates a model based on Lachlan Marnoch's predictions for FRB host galaxy visibility in https://ui.adsabs.harvard.edu/abs/2023MNRAS.525..994M/abstract Here, we assume that host galaxy magnitudes have a normal distribution, with mean and standard deviation given by L.
model_wrapper(model, zvals)	Generic functions applicable to all models.
simple_host_model([OpticalState, verbose])	A class to hold information about the intrinsic properties of FRB host galaxies.

optical_numerics

Numerical evaluation, optimisation, and statistics for fitting host models.

zdm.optical_numerics Module

Numerical routines for evaluating and optimising FRB host galaxy magnitude models.

This module is the numerical workhorse for the PATH integration in zdm, analogous to iteration.py for the zdm grid. It provides:

• ``function`` objective function passed to scipy.optimize.minimize that evaluates a goodness-of-fit statistic for a given set of host model parameters against the CRAFT ICS optical data.

• ``calc_path_priors`` inner loop that runs PATH on a list of FRBs across one or more surveys/grids, collecting priors, posteriors, and undetected-host probabilities for each FRB.

• ``run_path`` runs the PATH algorithm for a single named FRB, loading its candidate host galaxies from the frb package data and applying colour corrections to convert to r-band.

• ``calculate_likelihood_statistic`` and ``calculate_ks_statistic`` — goodness-of-fit statistics comparing the model apparent magnitude prior to the observed PATH posteriors across all FRBs.

• ``make_cumulative_plots`` plotting routine for visualising cumulative magnitude distributions for one or more models simultaneously.

• ``make_wrappers``, ``make_cdf``, ``flatten``, ``get_cand_properties`` supporting utilities.

zdm.optical_numerics.function(x, args)

Objective function for scipy.optimize.minimize over host model parameters.

Updates the host magnitude model with parameter vector x, runs PATH on all FRBs, computes the chosen goodness-of-fit statistic, and returns a scalar value suitable for minimisation (i.e. smaller is better).

Parameters:

• x (np.ndarray) – Parameter vector passed to model.init_args(x). Its meaning depends on the model (e.g. absolute magnitude bin weights for simple_host_model, or fSFR for loudas_model).

• args (list) –

  Packed argument tuple with the following elements, in order:

  • frblist (list of str): TNS names of FRBs to evaluate.

  • ss (list of Survey): surveys in which the FRBs may appear.

  • gs (list of Grid): zdm grids corresponding to those surveys.

  • model: host magnitude model instance (must implement init_args).

  • POxcut (float or None): if not None, restrict the statistic to FRBs whose best host candidate has P(O|x) > POxcut.

  • istat (int): statistic to use — 0 for KS-like statistic, 1 for maximum-likelihood (returned as negative log-likelihood so that minimisation maximises the likelihood).

Returns:

stat – Goodness-of-fit statistic (smaller is better). For istat=1 this is the negative log-likelihood.

Return type:

float

zdm.optical_numerics.make_wrappers(model, grids)

returns a list of model wrapper objects for given model and grids

Parameters:

• model – one of the optical model class objects

• grids – list of grid class objects

Returns:

list of wrappers around model, one for each grid

Return type:

wrappers

zdm.optical_numerics.make_cdf(xs, ys, ws, norm=True)

Build a weighted empirical CDF evaluated on a fixed grid.

For each grid point x in xs, accumulates the weights ws[i] of all observations ys[i] that fall below x. The result is a non-decreasing array that can be compared to a model prior CDF.

Parameters:

• xs (np.ndarray) – Grid of x values at which to evaluate the CDF (e.g. apparent magnitude bin centres). Must be sorted in ascending order.

• ys (array-like) – Observed data values (e.g. host galaxy apparent magnitudes).

• ws (array-like) – Weight for each observation in ys (e.g. PATH posteriors P_Ox). Must have the same length as ys.

• norm (bool, optional) – If True (default), normalise the CDF so that its maximum value is 1. Set to False to preserve the raw cumulative weight sum.

Returns:

cdf – Weighted empirical CDF evaluated at each point in xs.

Return type:

np.ndarray, shape (len(xs),)

zdm.optical_numerics.calc_path_priors(frblist, ss, gs, wrappers, verbose=True, usemodel=True, P_U=0.1)

Run PATH on a list of FRBs and return priors, posteriors, and P_U values.

For each FRB in frblist, searches all surveys in ss for a match, computes the zdm-derived apparent magnitude prior (if usemodel=True), and runs PATH to produce host association posteriors. Results for all FRBs are collected into parallel lists (one entry per FRB).

Also writes a CSV file allgalaxies.csv (if it does not already exist) containing the magnitude and VLT/FORS2 R-band columns for all candidate host galaxies across all FRBs.

Parameters:

• frblist (list of str) – TNS names of FRBs to process (e.g. ['FRB20180924B', ...]).

• ss (list of Survey) – Survey objects to search for each FRB. The first survey containing a given FRB is used.

• gs (list of Grid) – zdm grids corresponding to each survey in ss.

• wrappers (list of model_wrapper) – One model_wrapper per grid (from make_wrappers), used to compute DM-dependent apparent magnitude priors.

• verbose (bool, optional) – If True, print a warning for each FRB not found in any survey. Defaults to True.

• usemodel (bool, optional) – If True, use the zdm-derived magnitude prior from wrappers and estimate P_U from the model. If False, use PATH’s built-in inverse prior and the supplied fixed P_U. Defaults to True.

• P_U (float, optional) – Fixed prior probability that the host galaxy is undetected. Only used when usemodel=False. Defaults to 0.1.

Returns:

• nfitted (int) – Number of FRBs successfully matched to a survey and processed.

• AppMags (np.ndarray) – Internal apparent magnitude grid (from the last processed wrapper).

• allMagPriors (list of np.ndarray) – One array per FRB giving p(m_r | DM_EG) on the AppMags grid. Entries are None when usemodel=False.

• allObsMags (list of np.ndarray) – One array per FRB listing the r-band magnitudes of PATH candidate host galaxies.

• allPO (list of np.ndarray) – One array per FRB giving the PATH prior P_O for each candidate.

• allPOx (list of np.ndarray) – One array per FRB giving the PATH posterior P(O|x) for each candidate.

• allPU (list of float) – Prior P_U (probability of unseen host) for each FRB.

• allPUx (list of float) – Posterior P(U|x) (probability host is unseen, given data) for each FRB.

• sumPU (float) – Sum of allPU across all FRBs.

• sumPUx (float) – Sum of allPUx across all FRBs.

• frbs (list of str) – TNS names of the FRBs that were successfully matched and processed.

• dms (list of float) – Extragalactic DM (pc cm⁻³) for each FRB in frbs.

zdm.optical_numerics.calculate_likelihood_statistic(NFRB, AppMags, AppMagPriors, ObsMags, ObsPosteriors, PUobs, PUprior, plotfile=None, POxcut=None)

Compute the total log-likelihood of the observed PATH posteriors given the model prior.

For each FRB, evaluates log10(Σ P(O_i|x) / rescale + P_U_prior), where the rescale factor accounts for PATH’s internal renormalisation of posteriors relative to the model prior. Summing over all FRBs gives the total log-likelihood returned to the caller.

Parameters:

• NFRB (int) – Number of FRBs to sum over.

• AppMags (np.ndarray, shape (NMAG,)) – Apparent magnitude grid used to compute the model prior (not used directly in this function, but kept for API consistency with calculate_ks_statistic).

• AppMagPriors (list of np.ndarray, length NFRB) – Model prior p(m_r | DM_EG) on the AppMags grid, one array per FRB.

• ObsMags (list of np.ndarray, length NFRB) – Observed r-band magnitudes of PATH candidate host galaxies, one array per FRB (length NCAND varies by FRB).

• ObsPosteriors (list of np.ndarray, length NFRB) – PATH posterior P(O_i|x) for each candidate, one array per FRB.

• PUobs (list of float, length NFRB) – PATH posterior P(U|x) — probability that the true host is undetected — for each FRB, as returned by PATH after renormalisation.

• PUprior (list of float, length NFRB) – Model prior P_U for each FRB, as estimated by wrapper.estimate_unseen_prior().

• plotfile (str or None, optional) – If provided, save a diagnostic plot comparing prior and posterior magnitude distributions to this file path. Defaults to None.

• POxcut (float or None, optional) – If not None, restrict the statistic to FRBs whose maximum P(O|x) exceeds this threshold (simulates requiring a confident host ID). Defaults to None.

Returns:

stat – Total log10-likelihood summed over all NFRB FRBs. Larger values indicate a better fit. Multiply by -1 for use as a minimisation objective.

Return type:

float

zdm.optical_numerics.flatten(xss)

Flatten a list of lists into a single flat list.

zdm.optical_numerics.calculate_ks_statistic(NFRB, AppMags, AppMagPriors, ObsMags, ObsPosteriors, PUobs, PUprior, plotfile=None, POxcut=None, plotlabel=None, abc=None, tag='')

Compute a KS-like goodness-of-fit statistic between model prior and observed posteriors.

Builds cumulative magnitude distributions for both the model prior and the PATH posteriors, normalised by the number of FRBs, and returns the maximum absolute difference between them — analogous to the KS test statistic.

Optionally produces a plot comparing the two cumulative distributions.

Parameters:

• NFRB (int) – Number of FRBs used for normalisation.

• AppMags (np.ndarray, shape (NMAG,)) – Apparent magnitude grid on which priors are defined.

• AppMagPriors (list of np.ndarray, length NFRB) – Model prior p(m_r | DM_EG) on AppMags, one array per FRB.

• ObsMags (list of np.ndarray, length NFRB) – Observed r-band magnitudes of PATH candidate galaxies, one per FRB.

• ObsPosteriors (list of np.ndarray, length NFRB) – PATH posteriors P(O_i|x) for each candidate, one array per FRB.

• PUobs (list of float) – Posterior P(U|x) for each FRB (not used directly in the statistic, kept for API consistency).

• PUprior (list of float) – Prior P_U for each FRB (not used directly, kept for API consistency).

• plotfile (str or None, optional) – If provided, save a CDF comparison plot to this path. Defaults to None.

• POxcut (float or None, optional) – If not None, restrict to candidates with P(O|x) > POxcut and normalise both CDFs to unity (simulates the approach of selecting only confidently identified hosts). Defaults to None.

• plotlabel (str or None, optional) – Text label placed in the centre-bottom of the plot. Defaults to None.

• abc (str or None, optional) – Panel label (e.g. '(a)') placed in the upper-left corner of the figure in figure-coordinate space. Defaults to None.

• tag (str, optional) – String prefix added to the legend labels "Observed" and "Prior". Defaults to "".

Returns:

stat – Maximum absolute difference between the observed and prior cumulative distributions. Smaller values indicate a better fit.

Return type:

float

zdm.optical_numerics.make_cumulative_plots(NMODELS, NFRB, AppMags, AppMagPriors, ObsMags, ObsPosteriors, PUobs, PUprior, plotfile, plotlabel, POxcut=None, abc=None, onlyobs=None, greyscale=[], addpriorlabel=True)

Plot cumulative apparent magnitude distributions for multiple host models on one figure.

Computes the same normalised prior and observed CDFs as calculate_ks_statistic, but for NMODELS models simultaneously, overlaying them on a single figure with distinct line styles.

All list-valued parameters that appear in calculate_ks_statistic gain an additional leading dimension of size NMODELS here.

Parameters:

• NMODELS (int) – Number of models to plot.

• NFRB (list of int, length NMODELS) – Number of FRBs for each model, used for normalisation.

• AppMags (list of np.ndarray, length NMODELS) – Apparent magnitude grid for each model.

• AppMagPriors (list of lists of np.ndarray, shape (NMODELS, NFRB, NMAG)) – Model prior p(m_r | DM_EG) for each model and FRB.

• ObsMags (list of lists of np.ndarray, shape (NMODELS, NFRB, NCAND)) – Observed candidate magnitudes for each model and FRB.

• ObsPosteriors (list of lists of np.ndarray, shape (NMODELS, NFRB, NCAND)) – PATH posteriors P(O_i|x) for each model and FRB.

• PUobs (list, length NMODELS) – Posterior P(U|x) per model (not used directly in the plot).

• PUprior (list, length NMODELS) – Prior P_U per model (not used directly in the plot).

• plotfile (str) – Output file path for the saved figure.

• plotlabel (list of str, length NMODELS) – Legend label prefix for each model.

• POxcut (float or None, optional) – If not None, restrict to candidates with P(O|x) > POxcut and normalise CDFs to unity. Defaults to None.

• abc (str or None, optional) – Panel label (e.g. '(a)') placed in the upper-left corner in figure-coordinate space. Defaults to None.

• onlyobs (int or None, optional) – If not None, only draw the observed CDF for the model with this index (useful when all models share the same observations). The observed line is then labelled "Observed" without a model prefix. Defaults to None.

• greyscale (list of int, optional) – Indices of models whose observed CDF should additionally be drawn in grey (for background reference). Defaults to [].

• addpriorlabel (bool, optional) – If True (default), append ": Prior" to each model’s legend entry. Set to False to use only plotlabel[imodel] as the label.

Return type:

None

zdm.optical_numerics.get_cand_properties(frblist)

Load PATH candidate host galaxy properties for a list of FRBs.

Reads the pre-generated PATH CSV files from the frb package data directory (frb/data/Galaxies/PATH/<FRB>_PATH.csv) and extracts the columns ['ang_size', 'mag', 'ra', 'dec', 'separation'] for each FRB.

Parameters:

frblist (list of str) – TNS FRB names (e.g. ['FRB20180924B', ...]).

Returns:

one DataFrame per FRB,

each with columns ang_size, mag, ra, dec, and separation.

Return type:

all_candidates (list of pd.DataFrame)

zdm.optical_numerics.run_path(name, P_U=0.1, usemodel=False, sort=False)

Run the PATH algorithm on a single FRB and return host association results.

Loads the FRB object and its pre-generated PATH candidate table from the frb package, applies colour corrections to convert candidate magnitudes to r-band (using fixed offsets: I → R: +0.65, g → R: −0.65), sets up the FRB localisation ellipse and offset prior, and evaluates PATH posteriors.

The magnitude prior used for the candidates is:

• usemodel=False: PATH’s built-in 'inverse' prior (uniform in log surface density).

• usemodel=True: the 'user' prior, which must be set externally by pointing pathpriors.USR_raw_prior_Oi at a model_wrapper method before calling this function (typically done by wrapper.init_path_raw_prior_Oi).

The offset prior is always the 'exp' model from PATH’s 'adopted' standard priors, with scale 0.5 arcsec.

Parameters:

• name (str) – TNS name of the FRB (e.g. 'FRB20180924B').

• P_U (float, optional) – Prior probability that the true host galaxy is undetected. Defaults to 0.1.

• usemodel (bool, optional) – If True, use the externally set user prior for candidate magnitudes. Defaults to False.

• sort (bool, optional) – If True, sort the returned arrays by P(O|x) in ascending order. Defaults to False.

Returns:

• P_O (np.ndarray) – Prior probability P(O_i) for each candidate host galaxy.

• P_Ox (np.ndarray) – Posterior probability P(O_i|x) for each candidate.

• P_Ux (float) – Posterior probability P(U|x) that the true host is undetected.

• mags (np.ndarray) – R-band apparent magnitudes of the candidates (after colour correction).

• ptbl (pd.DataFrame) – Full PATH candidate table loaded from the CSV file, with an additional 'frb' column set to name.

Functions

calc_path_priors(frblist, ss, gs, wrappers)	Run PATH on a list of FRBs and return priors, posteriors, and P_U values.
calculate_ks_statistic(NFRB, AppMags, ...[, ...])	Compute a KS-like goodness-of-fit statistic between model prior and observed posteriors.
calculate_likelihood_statistic(NFRB, ...[, ...])	Compute the total log-likelihood of the observed PATH posteriors given the model prior.
flatten(xss)	Flatten a list of lists into a single flat list.
function(x, args)	Objective function for scipy.optimize.minimize over host model parameters.
get_cand_properties(frblist)	Load PATH candidate host galaxy properties for a list of FRBs.
make_cdf(xs, ys, ws[, norm])	Build a weighted empirical CDF evaluated on a fixed grid.
make_cumulative_plots(NMODELS, NFRB, ...[, ...])	Plot cumulative apparent magnitude distributions for multiple host models on one figure.
make_wrappers(model, grids)	returns a list of model wrapper objects for given model and grids
run_path(name[, P_U, usemodel, sort])	Run the PATH algorithm on a single FRB and return host association results.

References

• Marnoch et al. 2023, MNRAS 525, 994 — FRB host galaxy r-band magnitude model (https://doi.org/10.1093/mnras/stad2353)

• Macquart et al. 2020, Nature 581, 391 — Macquart relation / p(DM | z)

• Aggarwal et al. 2021, ApJ 911, 95 — PATH algorithm for probabilistic host association