fruitbat.Frb

class fruitbat.Frb(dm, name=None, raj=None, decj=None, gl=None, gb=None, dm_galaxy=0.0, dm_excess=None, z_host=None, dm_host_est=0.0, dm_host_loc=0.0, dm_index=None, scatt_index=None, snr=None, width=None, peak_flux=None, fluence=None, obs_bandwidth=None, obs_freq_central=None, utc=None, **kwargs)[source]

Create a Frb object using the observered properties of a FRB including dispersion measure (DM) and its sky coordinates. This class utilises various DM-redshift relations as well as the YMW16 galactic DM model in the analysis.

A FRB can be defined simply with a single dm value. This should be the observed DM prior to subtracting the Milky Way, however if you do not provide any additional information, it is asssumed that this value is also the dm_excess (DM - Galactic DM). You can get the estimated redshift by using the method calc_redshift().

To get a more accurate distance estimate you can account for the contribution due to the Milky Way by supplying dm_galaxy or by giving the coordinates of the FRB in ICRS (raj, decj) or Galactic (gl, gb) coordinates and calling the method calc_dm_galaxy() before calling calc_redshift().

Parameters:

dm (float) – The observed dispersion measure of the FRB. This is without Milky Way or host galaxy subtraction. Units: pc cm**-3
Keyword Arguments:
 
  • name (str or None, optional) – The name of the frb object. Default: None
  • raj (str or None, optional) – The right ascension in J2000 coordinates of the best estimate of the FRB position. By default should be given in the ICRS frame. An alternative frame can be specified by also including the keyword frame. e.g. frame='fk5'. Default: None
  • decj (str or None, optional) – The declination in J2000 coordinates of the best estimate of the FRB position. By default should be given in the ICRS frame. An alternative frame can be specified by also including the keyword frame. e.g. frame='fk5'. Default: None
  • gl (str or None, optional) – The Galactic longitude in degrees of the best estimate of the FRB position. Default: None
  • gb (str or None, optional) – The Galactic latitude in degrees of the best estimate of the FRB position. Default: None
Other Parameters:
 
  • dm_galaxy (float, optional) – The modelled contribution to the FRB DM by electrons in the Milky Way. This value is calculated using calc_dm_galaxy() Units: pc cm**-3 Default: 0.0
  • dm_excess (float or None, optional) – The DM excess of the FRB over the estimated Galactic DM. If dm_excess is None, then dm_excess is calculated automatically with calc_dm_excess(). Units: pc cm**-3 Default: None
  • z_host (float or None, optional) – The observed redshift of the localised FRB host galaxy. Default: None
  • dm_host_est (float, optional) – The estimated contribution to the measured FRB DM originating from the FRB’s host galaxy. This value is the amount of DM the host galaxy contributes to the observed DM, not the DM of the host galaxy. Setting this to a non-zero value and setting subtract_host=True when calling calc_redshift() accounts for the DM contribution due to the host galaxy. Units: pc cm**-3 Default: 0.0
  • dm_host_loc (float, optional) – The dispersion measure of a localised FRB host galaxy. This value is not the contribution to the observed DM, but the DM at the host galaxy. The observed DM is dm_host_loc but attenuated by a factor of (1 + z). To use this, the redshift of the host galaxy must be known. Units: pc cm**-3 Default: 0.0
  • dm_index (float or None, optional) – The dispersion measure index of the burst \(\alpha\) such that \(\rm{DM} \propto \nu^{-\alpha}\) Default: None
  • scatt_index (float or None, optional) – The scattering index (\(\beta\)) of the FRB pulse. The scattering index describes how the width (\(\rm{W}\)) of the FRB pulse evolves with frequency \(\nu\) such that \(\rm{W} \propto \nu^{-\beta}\). Default: None
  • snr (float or None, optional) – The signal-to-noise ratio of the burst. Default: None
  • width (float or None, optional) – The observed width of the pulse obtained by a pulse fitting algorithm. Units: ms Default: None
  • peak_flux (float or None, optional) – The observed peak flux density of the burst. Units: Jy Default: None
  • fluence (float or None, optional) – The observed fluence of the FRB. If fluence is None and both width and peak_flux are not None then fluence is automatically calculated with calc_fluence(). Units: Jy ms Default: None
  • obs_bandwidth (float or None, optional) – The observing bandwidth. Units: MHz Default: None
  • obs_freq_central (float or None, optional) – The central observing frequency, Units: MHz Deault: None
  • utc (str or None, optional) – The UTC time of the FRB Burst. Format should be of the form ‘1999-01-01T00:00:00.000’. Default: None

Example

>>> import fruitbat
>>> FRB = fruitbat.Frb(879, gl="12:31:40.5", gb="3:41:10.0")
>>> FRB.calc_dm_galaxy()
>>> FRB.calc_redshift()
calc_comoving_distance()[source]

Calculates the comoving distance to the FRB based on its redshift. To calculate a comoving distance either call calc_redshift() first to determine a redshift estimate or provide a value for dm_host.

Returns:astropy.units.Quantity – The comoving distance to the FRB.
calc_dm_excess()[source]

Calculates the dispersion measure excess of the FRB by subtracting the DM contribution from the Milky Way.

Returns:astropy.units.Quantity – The dispersion measure excess.

Notes

\(\rm{DM_{excess}}\) is calculated as follows:

\[\rm{DM_{excess} = DM - DM_{galaxy}}\]
calc_dm_galaxy(model='ymw16', include_halo=False, return_tau_sc=False)[source]

Calculates the dispersion measure contribution of the Milky Way from either (raj, decj) or (gl, gb). Uses the YMW16 model of the Milky Way free electron column density.

Parameters:
  • model (‘ymw16’ or ‘ne2001’, optional) – The Milky Way dispersion measure model. To use ‘ne2001’ you will need to install the python port. See https://fruitbat.readthedocs.io/en/latest/user_guide/ne2001_installation.html Default: ‘ymw16’
  • include_halo (bool, optional) – Include the DM of the galactic halo which isn’t included in NE2001 or YMW16. This used the YT2020 halo model. Default: False
  • return_tau_sc (bool, optional) – Return the scattering timescale in addition to the DM. Default: False
Returns:

  • dm_galaxy (astropy.units.Quantity) – The dispersion measure contribution from the Milky Way of the FRB.
  • tau_sc (astropy.units.Quantity, optional) – The scattering timescale at 1 GHz (s). Only returns if return_tau_sc is True.
calc_dm_igm()[source]

Calculates the dispersion measure of the intergalactic medium along the line-of-sight of the FRB. This can only be done if the redshift and dispersion measure contribution of the FRB host galaxy is known.

Returns:astropy.units.Quantity – The dispersion measure contribution of the IGM.

Notes

\(\rm{DM_{IGM}}\) is calculated as follows:

\[\rm{DM_{IGM}} = \rm{DM_{excess}} - \frac{\rm{DM_{host, loc}}}{1 + z}\]
calc_energy(use_bandwidth=False)[source]

Calculates the isotropic energy of the FRB. This is the upper limit to the the true energy since the luminosity distance required is also an upper limit to the true luminosity distance.

Parameters:use_bandwidth (bool, optional) – The default method of calculating the energy of a FRB uses obs_freq_central as described in Zhang 2018. However some estimates of the FRB energy instead use obs_bandwidth (see Law et al. 2017). Set to True to use obs_bandwidth instead of obs_freq_central. Default: False
Returns:astropy.units.Quantity – The estimated isotropic energy of the FRB, in units of ergs.

Notes

The energy of a FRB is calculated following that in Zhang 2018.

\[E_{FRB} \simeq \frac{4 \pi}{1 + z} D_{\rm{L}}^2 F_{obs} \nu_c\]

Where \(F_{obs}\) is the fluence of the FRB, \(\nu_c\) is the central observing frequency, \(D_{\rm{L}}\) is the luminosity distance and \(z\) is the estimated redshift.

In Law et al. 2017, the bandwidth (\(B\)) is used instead of \(\nu_c\) to estimate energy.

calc_fluence()[source]

Calculates the observed fluence of the FRB. This requires width and peak_flux to not be None.

Returns:astropy.units.Quantity or None – The fluence of the FRB.

Notes

The fluence (\(\rm{F_{obs}}\)) is calculated as follows:

\[F_{obs} = W_{obs} S_{\nu, p}\]

Where \(W_{obs}\) is the with of the FRB pulse and \(S_{\nu, p}\) is the specific peak flux.

calc_luminosity(use_bandwidth=False)[source]

Calculates the isotropic peak luminosity of the FRB. This is the upper limit to the the true peak luminosity since the luminosity distance required is also an upper limit to the true luminosity distance.

Parameters:use_bandwidth (bool, optional) – The default method of calculating the luminosity of a FRB uses obs_freq_central as described in Zhang 2018. However some estimates of the FRB luminosity instead use obs_bandwidth (see Law et al. 2017). Set to True to use obs_bandwidth instead of obs_freq_central. Default: False
Returns:astropy.units.Quantity – The estimated isotropic peak luminosity of the FRB in units of ergs/s.

Notes

The luminosity of a FRB is calculated following that in Zhang 2018.

\[L_{FRB} \simeq 4 \pi D_{\rm{L}}^2 S_{\nu, p} \nu_c\]

Where \(S_{\nu, p}\) is the specific peak flux of the FRB, \(\nu_c\) is the central observing frequency, \(D_{\rm{L}}\) is the luminosity distance.

In Law et al. 2017, the bandwidth (\(B\)) is used instead of \(\nu_c\) to estimate luminosity.

calc_luminosity_distance()[source]

Calculates the luminosity distance to the FRB based on its redshift. To calculate a luminosity distance either call calc_redshift() first to determine a redshift estimate or provide a value for dm_host.

Returns:astropy.units.Quantity – The luminosity distance to the FRB.
calc_redshift(method='Batten2021', cosmology='Planck18', subtract_host=False, lookup_table=None)[source]

Calculate the redshift of the FRB from its dm, dm_excess or dm_excess - dm_host_est.

Parameters:
  • method (str, optional) – The dispersion meausre -redshift relation to use when calculating the redshift. Avaliable methods: [‘Ioka2003’, ‘Inoue2004’, ‘Zhang2018’, ‘Batten2021’]. Default: ‘Inoue2004’
  • cosmology (str, optional) – The cosmology to assume when calculating the redshift. Avaliable cosmologies: [‘WMAP5’, ‘WMAP7’, ‘WMAP9’, ‘Planck13’, ‘Planck15’, ‘Planck18’, ‘EAGLE’]. Default: ‘Planck18’
  • subtract_host (bool, optional) – Subtract dm_host_est from the dm_excess before calculating the redshift. This is is used to account for the dispersion measure that arises from the FRB host galaxy. Default: False
  • lookup_table (str or None, optional) – The path to the lookup table file. If lookup_table=None a table will attempted to be loaded from the data directory based on the method name. Default: None
Returns:

float – The redshift of the FRB.

Notes

The methods section in the documentation has a description for each of the builtin methods.

The cosmology section in the documentation has a list of the cosmological parameters for each cosmology

calc_redshift_conf_int(method='Batten2021', sigma=1, scatter_percentage=0, **calc_redshift_kwargs)[source]

Calculates the mean redshift and the confidence interval of an FRB from its dm, dm_excess or dm_excess - dm_host_est.

Parameters:
  • method (str, optional) – The dispersion meausre-redshift relation to use when calculating the redshift. Avaliable methods: %(meth)s. Default: ‘Batten2020’
  • cosmology (str, optional) – The cosmology to assume when calculating the redshift. This value is overided if using a hydrodynamic method. Avaliable cosmologies: %(cosmo)s. Default: ‘Planck18’
  • sigma (int (1, 2, 3, 4, 5), optional) – The width of the confidence interval in units of standard deviation. sigma=1 is the 68% confidence interval.
  • scatter_percentage (float, optional) – The amount of line of Default: 0
  • subtract_host (bool, optional) – Subtract dm_host_est from the dm_excess before calculating the redshift. This is is used to account for the dispersion measure that arises from the FRB host galaxy. Default: False
  • lookup_table (str or None, optional) – The path to the lookup table file. If lookup_table=None a table will attempted to be loaded from the data directory based on the method name. Default: None
Returns:

  • float – The extimated redshift of the FRB.
  • float – The redshift confidence interval the FRB.

Notes

The methods section in the documentation has a description for each of the builtin methods.

The cosmology section in the documentation has a list of the cosmological parameters for each cosmology

calc_redshift_pdf(method='Batten2021', cosmology='Planck18', prior='uniform', subtract_host=False, lookup_table=None)[source]

Calc

calc_skycoords(frame=None)[source]

Calculates the skycoord position on the sky of the FRB from (raj, decj) or (gl, gb). If both (raj, decj) and (gl, gb) are given, preference is given to (raj, decj).

Parameters:frame (str or None, optional) – The type of coordinate frame. If frame = None then calc_skycoords() will use a default frame based on the coordinates given. If raj and decj are given the default frame is ‘icrs’. If gl and gb are given the default frame is ‘galactic’. Default: None
Returns:astropy.coordinates.SkyCoord – The sky coordinates of the FRB.
cosmology

The cosmology used to calculate redshift.

Type:str or None
decj

The declination in J2000 coordinates of the best estimate of the FRB position. This is given in the IRCS frame.

Type:astropy.coordinates.Latitude or None
dm

The observed dispersion measure of the FRB. This is without Milky Way or host galaxy subtraction.

Type:astropy.units.Quantity or None
dm_excess

The dispersion measure with the Milky Way component subtracted. This value approximates the dispersion measure of the intergalatic medium by assuming that the host galaxy contributes zero to the observed dispersion measure. This quantity is calculated using calc_dm_excess().

Type:astropy.units.Quantity or None
dm_galaxy

The galactic component of the dispersion measure. This is quantity is calculated using calc_dm_galaxy().

Type:astropy.units.Quantity or None
dm_galaxy_model

The method used to calculate redshift.

Type:str or None
dm_host_est

The estimated dispersion measure from the FRB host galaxy.

Type:astropy.units.Quantity or None
dm_host_loc

The dispersion measure from a localised FRB host galaxy.

Type:astropy.units.Quantity or None
dm_igm

The estimated disperison measure from the IGM. This can be calculated for a FRB for which the redshift of its host galaxy is known. This value is determined using calc_dm_igm().

Type:astropy.units.Quantity or None
dm_index

The dispersion measure index of the burst.

Type:astropy.units.Quantity or None
fluence

The observed fluence of the FRB. This is calculated from calc_fluence().

Type:astropy.units.Quantity or None
gb

The latitude in galactic coordinates of the best estimate of the FRB position.

Type:astropy.coordinates.Latitude or None
gl

The longitude in galactic coordinates of the best estimate of the FRB position.

Type:astropy.coordinates.Longitude or None
method

The method used to calculate redshift.

Type:str or None
name

str The name of the FRB object.

Type:name
obs_bandwidth

The observing bandwidth of the FRB.

Type:astropy.units.Quantity or None
obs_freq_central

The central observing frequency of the FRB.

Type:astropy.units.Quantity or None
peak_flux

The observed peak flux density of the FRB.

Type:astropy.units.Quantity or None
plot_redshift_pdf(*args, **kwargs)[source]

Plots the redshift pdf and confidence interval for an FRB.

Parameters:
  • frb (fruitbat.Frb) – An instance of the fruitbat.Frb class.
  • method (str, optional) – Default: “Batten2021”
  • sigma ([1, 2, 3, 4, 5], optional) – The width of the confidence interval in units of sigma. Default: 1
  • usetex (bool, optional) – Use LaTeX font when creating the figure. Set this to false to disable Latex fonts. Default: True
  • filename (str or None, optional)
Returns:

  • fig (, optional)
  • ax (, optional)
raj

The right accension in J2000 coordinates of the best estimate of the FRB position. This is given in the IRCS frame.

Type:astropy.coordinates.Longitude or None
scatt_index

The scattering index of the burst.

Type:astropy.units.Quantity or None
skycoords

The skycoords of the FRB. This is calculated from either (raj, decj) or (gl, gb) using calc_skycoords().

Type:astropy.coordinates.SkyCoord or None
snr

The signal-to-noise ratio of the burst.

Type:astropy.units.Quantity
utc

astropy.time.Time or None The UTC time of the burst.

width

The observed width of the pulse.

Type:astropy.units.Quantity or None
z

The estimated redshift of the burst. By default this assumes that the entire dm_excess arrives from the IGM and the host galaxy of the FRB and any surrounding material contribute nothing to the total DM. This should be taken as an upper limit to the bursts true redshift. To provide an estimate of the DM contribution due to he host galaxy, set dm_host_est to a non-zero value and use subract_host=True when calling calc_redshift().

Type:astropy.units.Quantity or None
z_conf_int_lower

The lower bound of the redshift confidence interval.

Type:astropy.units.Quantity or None
z_conf_int_upper

The upper bound of the redshift confidence interval.

Type:astropy.units.Quantity or None
z_host

The redshift of the localised FRB host galaxy. Note that this an observed quantity, not the estimated redshift z calculated with calc_redshift().

Type:astropy.units.Quantity or None