model_wrapper

class zdm.optical.model_wrapper(model, zvals)

Bases: object

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).

Methods Summary

estimate_unseen_prior()	Calculates PU, the prior that an FRB host galaxy of a particular DM is unseen in the optical image
get_posterior(grid, DM)	Return apparent magnitude and redshift posteriors for a given DM.
init_app_bins()	Initialises bins in apparent magnitude It uses these to calculate priors for any given host galaxy magnitude.
init_path_raw_prior_Oi(DM, grid)	Initialise the apparent magnitude prior for a single FRB DM.
init_zmapping(zvals)	For a set of redshifts, initialise mapping between intrinsic magnitudes and apparent magnitudes
path_base_prior(mags)	Evaluate the apparent magnitude prior p(m_r | DM) at a list of magnitudes.
path_raw_prior_Oi(mags, ang_sizes, Sigma_ms)	Function to pass to astropath module for calculating a raw FRB prior.

Methods Documentation

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)

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)

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_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).

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.

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)

__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)