Survey
- class zdm.survey.Survey(state, survey_name: str, filename: str, dmvals: ndarray, zvals: ndarray = None, NFRB: int = None, iFRB: int = 0, edir=None, rand_DMG=False, survey_dict=None)[source]
Bases:
objectRepresents an FRB survey with instrument properties and detected FRBs.
The Survey class is the primary interface for defining telescope characteristics and loading FRB detections. It computes detection efficiencies across the DM-width-fluence parameter space.
- DMEGs
Extragalactic DM values for detected FRBs.
- Type:
ndarray
- Zs
Redshifts for localized FRBs (None if unknown).
- Type:
ndarray or None
- efficiencies
Detection efficiency grid as function of DM and width.
- Type:
ndarray
Methods Summary
Calculates the maximum searched DM.
Function to handle calculation of efficiencies.
fix_coordinates([verbose])Takes and FRB, and fills out missing coordinate values Note that now, RA, DEC, Gl, and Gb will be present But their default values are None
get_efficiency_from_wlist(wlist, plist[, ...])Gets efficiency to FRBs Returns a list of relative efficiencies as a function of dispersion measure for each width given in wlist
get_internal_coeffs(wlist)Returns indices and coefficients for linear interpolation between intrinsic width values
get_w_coeffs(wlist)Returns indices and coefficients for linear interpolation between width values Bin edges run from [small~1e-10, self.WMin, self.WMin + self.dlowg, ..., self.Wmax] We should use bin centres to determine which linear interpolations we sit between
init_DMEG(DMhalo[, halo_method])Calculates extragalactic DMs assuming halo DM
init_beam([plot, method, thresh])Initialises the beam
Initialise frb-by-frb weights for each value of the beam histogram, based on the value of the beam that the FRB was detected in.
Initialises frb width coefficients for linear interpolation
Initialise coefficients for Yamasaki and Totani 2020 implementation of directionally dependent DMhalo
Checks to see if this is a repeater survey and if so ensures all the relevant information is present.
init_widths([state])Performs initialisation of width and scattering distributions
init_zs()Gets zlist and nozlist and determines which z values to use
Gets zlist and nozlist for repeaters and singles.
make_widths([iz])This routine calculates width distributions of FRBs, which is required to estimate detection efficiency, and (potentially) calculate p(w,tau).
process_dm_mask([edir])Processes a DM mask into units of local DM
Estimates galactic DM according to Galactic lat and lon only if not otherwise provided
process_dmhalo(halo_method)Calculates directionally dependent DMhalo from Yamasaki and Totani 2020 and rescaling to an average of self.DMhalo
process_survey_file(filename[, NFRB, iFRB, ...])Loads a survey file, then creates dictionaries of the loaded variables
randomise_DMG([uDMG])Change the DMG_ISM values to a random value within uDMG Gaussian uncertainty
Methods Documentation
- do_efficiencies()[source]
Function to handle calculation of efficiencies. Allows this to be called externally, e.g. if DM halo model changes
- fix_coordinates(verbose=False)[source]
Takes and FRB, and fills out missing coordinate values Note that now, RA, DEC, Gl, and Gb will be present But their default values are None
- get_efficiency_from_wlist(wlist, plist, model='Quadrature', addGalacticDM=True, edir=None, iz=None)[source]
Gets efficiency to FRBs Returns a list of relative efficiencies as a function of dispersion measure for each width given in wlist
- wlist:
list of intrinsic FRB widths
- plist:
list of relative probabilities for FRBs to have widths of wlist
- model: method of estimating efficiency as function of width, DM, and time resolution
- Takes values of “Quadrature”, “Sammons” (from Mawson Sammons summer project),
“CHIME” or a file name
- addGalacticDM:
- True: this routine adds in contributions from the MW Halo and ISM, i.e.
it acts like DMlist is an extragalactic DM
False: just use the supplied DMlist
- edir:
Directory where efficiency files are contained. Only relevant if specific FRB responses are used
- iz:
izth z-bin where these efficiencies are being calculated
- get_internal_coeffs(wlist)[source]
Returns indices and coefficients for linear interpolation between intrinsic width values
wlist: np.ndarray of observed intrinsic widths or taus
- Returns:
index of lower value iws2 (int): index of upper value dkws1 (float): coefficient for iws1 dkws2 (float): coefficient for iws2
- Return type:
iws1 (int)
- get_w_coeffs(wlist)[source]
Returns indices and coefficients for linear interpolation between width values Bin edges run from [small~1e-10, self.WMin, self.WMin + self.dlowg, …, self.Wmax] We should use bin centres to determine which linear interpolations we sit between
wlist: np.ndarray of observed widths
- Returns:
index of lower value iws2 (int): index of upper value dkws1 (float): coefficient for iws1 dkws2 (float): coefficient for iws2
- Return type:
iws1 (int)
- init_frb_bvals()[source]
Initialise frb-by-frb weights for each value of the beam histogram, based on the value of the beam that the FRB was detected in.
Simply does this by linear interpolation
- init_frb_wvals()[source]
Initialises frb width coefficients for linear interpolation
This is for a slightly different purpose than the init widths routine
- init_halo_coeffs()[source]
Initialise coefficients for Yamasaki and Totani 2020 implementation of directionally dependent DMhalo
- init_repeaters()[source]
Checks to see if this is a repeater survey and if so ensures all the relevant information is present.
- init_widths(state=None)[source]
Performs initialisation of width and scattering distributions
- Parameters:
state (parameters.state object., optional) – if set, assume this state contains new scattering/width parameters
- init_zs_reps()[source]
Gets zlist and nozlist for repeaters and singles. Basically the same as init_zs but for repeaters.
- make_widths(iz=None)[source]
This routine calculates width distributions of FRBs, which is required to estimate detection efficiency, and (potentially) calculate p(w,tau).
The functionality depends on self.width_method, which is set via
- WMETHOD [int: 0-4]:
0: No distribution - calculations performed at total width = 1ms 1: FRB widths are a simple lognormal of self.wlogmean, self.wlogsigma
histogrammed into self.wbins. Describes widths as “total width”, i.e. intrinsic plus scattering.
- 2: FRB widths convolved with frequency-dependent scattering distribution.
Calculates lognormal intrinsic width distribution, and convolves this with a lognormal scattering distribution. NOTE: if wmethod=2, iz must be called with iz=None.
- 3: As above, but allows for redshift dependence of both intrinsic
width and scattering. Distributions both scale width redshift: width with 1+z, scattering with (1+z)^-3
- 4: Use a specific width of a particular FRB. Used for detailed calcs
for individual FRB-by-FRB analyses.
- process_dmg()[source]
Estimates galactic DM according to Galactic lat and lon only if not otherwise provided
- process_dmhalo(halo_method)[source]
Calculates directionally dependent DMhalo from Yamasaki and Totani 2020 and rescaling to an average of self.DMhalo
self.c, self.Gls and self.Gbs should be loaded in process_survey_file
- process_survey_file(filename: str, NFRB: int = None, iFRB: int = 0, min_lat=None, dmg_cut=None, survey_dict=None)[source]
Loads a survey file, then creates dictionaries of the loaded variables
- Parameters:
- randomise_DMG(uDMG=0.5)[source]
Change the DMG_ISM values to a random value within uDMG Gaussian uncertainty
- __init__(state, survey_name: str, filename: str, dmvals: ndarray, zvals: ndarray = None, NFRB: int = None, iFRB: int = 0, edir=None, rand_DMG=False, survey_dict=None)[source]
Initialize an FRB Survey.
- Parameters:
state (parameters.State) – State object containing model parameters.
survey_name (str) – Identifier for the survey (e.g., ‘CRAFT/ICS’).
filename (str) – Path to survey definition file (ECSV format).
dmvals (ndarray) – Extragalactic DM grid values for efficiency calculations.
zvals (ndarray, optional) – Redshift grid values. Required for some width methods.
NFRB (int, optional) – Limit number of FRBs loaded from file.
iFRB (int, optional) – Starting index for FRB selection. Default is 0.
edir (str, optional) – Directory containing pre-computed efficiency files.
rand_DMG (bool, optional) – If True, randomize Galactic DM within uncertainty. Default False.
survey_dict (dict, optional) – Override survey metadata parameters.
- init_widths(state=None)[source]
Performs initialisation of width and scattering distributions
- Parameters:
state (parameters.state object., optional) – if set, assume this state contains new scattering/width parameters
- do_efficiencies()[source]
Function to handle calculation of efficiencies. Allows this to be called externally, e.g. if DM halo model changes
- make_widths(iz=None)[source]
This routine calculates width distributions of FRBs, which is required to estimate detection efficiency, and (potentially) calculate p(w,tau).
The functionality depends on self.width_method, which is set via
- WMETHOD [int: 0-4]:
0: No distribution - calculations performed at total width = 1ms 1: FRB widths are a simple lognormal of self.wlogmean, self.wlogsigma
histogrammed into self.wbins. Describes widths as “total width”, i.e. intrinsic plus scattering.
- 2: FRB widths convolved with frequency-dependent scattering distribution.
Calculates lognormal intrinsic width distribution, and convolves this with a lognormal scattering distribution. NOTE: if wmethod=2, iz must be called with iz=None.
- 3: As above, but allows for redshift dependence of both intrinsic
width and scattering. Distributions both scale width redshift: width with 1+z, scattering with (1+z)^-3
- 4: Use a specific width of a particular FRB. Used for detailed calcs
for individual FRB-by-FRB analyses.
- init_repeaters()[source]
Checks to see if this is a repeater survey and if so ensures all the relevant information is present.
- get_internal_coeffs(wlist)[source]
Returns indices and coefficients for linear interpolation between intrinsic width values
wlist: np.ndarray of observed intrinsic widths or taus
- Returns:
index of lower value iws2 (int): index of upper value dkws1 (float): coefficient for iws1 dkws2 (float): coefficient for iws2
- Return type:
iws1 (int)
- init_frb_bvals()[source]
Initialise frb-by-frb weights for each value of the beam histogram, based on the value of the beam that the FRB was detected in.
Simply does this by linear interpolation
- init_frb_wvals()[source]
Initialises frb width coefficients for linear interpolation
This is for a slightly different purpose than the init widths routine
- get_w_coeffs(wlist)[source]
Returns indices and coefficients for linear interpolation between width values Bin edges run from [small~1e-10, self.WMin, self.WMin + self.dlowg, …, self.Wmax] We should use bin centres to determine which linear interpolations we sit between
wlist: np.ndarray of observed widths
- Returns:
index of lower value iws2 (int): index of upper value dkws1 (float): coefficient for iws1 dkws2 (float): coefficient for iws2
- Return type:
iws1 (int)
- randomise_DMG(uDMG=0.5)[source]
Change the DMG_ISM values to a random value within uDMG Gaussian uncertainty
- process_dmhalo(halo_method)[source]
Calculates directionally dependent DMhalo from Yamasaki and Totani 2020 and rescaling to an average of self.DMhalo
self.c, self.Gls and self.Gbs should be loaded in process_survey_file
- init_halo_coeffs()[source]
Initialise coefficients for Yamasaki and Totani 2020 implementation of directionally dependent DMhalo
- init_zs_reps()[source]
Gets zlist and nozlist for repeaters and singles. Basically the same as init_zs but for repeaters.
- process_survey_file(filename: str, NFRB: int = None, iFRB: int = 0, min_lat=None, dmg_cut=None, survey_dict=None)[source]
Loads a survey file, then creates dictionaries of the loaded variables
- Parameters:
- fix_coordinates(verbose=False)[source]
Takes and FRB, and fills out missing coordinate values Note that now, RA, DEC, Gl, and Gb will be present But their default values are None
- process_dmg()[source]
Estimates galactic DM according to Galactic lat and lon only if not otherwise provided
- get_efficiency_from_wlist(wlist, plist, model='Quadrature', addGalacticDM=True, edir=None, iz=None)[source]
Gets efficiency to FRBs Returns a list of relative efficiencies as a function of dispersion measure for each width given in wlist
- wlist:
list of intrinsic FRB widths
- plist:
list of relative probabilities for FRBs to have widths of wlist
- model: method of estimating efficiency as function of width, DM, and time resolution
- Takes values of “Quadrature”, “Sammons” (from Mawson Sammons summer project),
“CHIME” or a file name
- addGalacticDM:
- True: this routine adds in contributions from the MW Halo and ISM, i.e.
it acts like DMlist is an extragalactic DM
False: just use the supplied DMlist
- edir:
Directory where efficiency files are contained. Only relevant if specific FRB responses are used
- iz:
izth z-bin where these efficiencies are being calculated