Welcome to Fruitbat’s documentation!

This is the documentation for the fruitbat package, an easy and convenient way to estimate the redshift of Fast Radio Bursts. Fruitbat was created by Adam Batten

Introduction

What are FRBs?

Fast Radio Bursts (FRBs) are a class of radio frequency transients that currently have an unknown astrophysical origin [1]. FRB are characterised by their large dispersion measures (DMs; \(~100 - 2500\ \rm{pc\ cm^{-3}}\)) and short durations (\(30\ \mu \rm{s} - 30\ \rm{ms}\)).

For a database of all currently known FRBs see frbcat.org

[1]	At the time of writing (Feburary 2019) an optical counterpart of FRBs has not been detected.

Getting started

Installation

You can install the latest release of fruitbat from PyPi by running the following:

pip install fruitbat

You can install the latest deveopment version of fruitbat by cloning the repository:

git clone https://github.com/abatten/fruitbat
cd fruitbat
pip install .

Requirements

• Numpy >= 1.12.0
• Astropy >= 2.0.0
• Scipy >= 1.0.0
• Pyymw16 >= 2.0.4

Pyymw16 is a python wrapper for the YMW16 galactic dispersion measure model.

Using Fruitbat

A detailed explanation of this example can be viewed at Using Fruitbat.

Example Calculation

import fruitbat

# Create a Frb Object with DM and Galactic Coordinates
FRB180110 = fruitbat.Frb("FRB180110", dm=715.7, gl="7.8", gb="-51.9")

# Calculate the DM contribution from the Milky Way
FRB180110.calc_dm_galaxy(model="ymw16")

# Calculate the Redshift of the FRB using the relation from Zhang (2018)
FRB180110.calc_redshift(method="zhang2018", cosmology="planck2018")

Using Fruitbat

Example

Methods and Cosmology

When calculation the redshift of an FRB there are varius methods that you can choose from.

Methods

There are various methods

Cosmology

Each method in fruitbat has a list of pre-calculated lookup tables with different cosmologies. The table below lists the parameters that are used for each cosmology.

Cosmological Parameters
Keyword	\(H_0\)	\(\Omega_b\)	\(\Omega_m\)	\(\Omega_\Lambda\)
'wmap2013'	\(69.32\)	\(0.04628\)	\(0.2865\)	\(0.7135\)
'planck2013'	\(67.80\)	\(0.04816\)	\(0.3063\)	\(0.6920\)
'planck2015'	\(67.74\)	\(0.04860\)	\(0.3089\)	\(0.6911\)
'planck2018'	\(67.66\)	\(0.04897\)	\(0.3111\)	\(0.6889\)
'eagle'	\(67.77\)	\(0.04825\)	\(0.307\)	\(0.693\)

Guidelines

Reference

If you use FRBz please cite our paper….

License

BSD 3-Clause License

Copyright (c) 2019, Adam Batten
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

* Redistributions of source code must retain the above copyright notice, this
  list of conditions and the following disclaimer.

* Redistributions in binary form must reproduce the above copyright notice,
  this list of conditions and the following disclaimer in the documentation
  and/or other materials provided with the distribution.

* Neither the name of the copyright holder nor the names of its
  contributors may be used to endorse or promote products derived from
  this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

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, w_obs=None, s_peak_obs=None, f_obs=None, utc=None, dm_uncert=0.0, z_uncert=0.0)

Create a Frb object using the observered properties of a FRB to properties including

To define a Frb object all it requires is an observed dispersion measure.

Parameters:

dm (float) – The observed dispersion measure of the FRB. This is without Milky Way or host galaxy subtraction. Units: \(\rm{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. Default: None
• decj (str or None, optional) – The declination in J2000 coordinates of the best estimate of the FRB position. 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. Units: \(\rm{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: \(\rm{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 from 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. Units: \(\rm{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). Units: \(\rm{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 of the burst. Default: None
• w_obs (float or None, optional) – The observed width of the pulse obtained by a pulse fitting algorithm. Units: \(\rm{ms}\) Default: None
• s_peak_obs (float or None, optional) – The observed peak flux density of the burst. Units: \(\rm{Jy}\) Default: None
• f_obs (float or None, optional) – The observed fluence of the FRB. If f_obs is None and both w_obs and s_peak_obs are not None then f_obs is automatically calculated by w_obs x s_peak_obs Units: \(\rm{Jy\ ms}\) Default: None
• utc (str or None, optional) – The UTC time of the FRB Burst. Default: None
• dm_uncert (float, optional) – The uncertainty in the dispersion measure. Units: \(\rm{pc\ cm^{-3}}\) Default: 0.0
• z_uncert (float, optional) – The uncertainty in the redshift of the FRB. Default: 0.0

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_dm_excess()

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

Returns:dm_excess – The dispersion measure excess. Return type:float

Notes

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

\[DM_{excess} = DM - DM_{galaxy}\]

calc_dm_galaxy(model='ymw16')

Calculates the dispersion measure contribution of the Milky Way from either (raj, decj) or (gl, gb).

Parameters:model (str, optional) – The Milky Way dispersion measure model. Default: ymw16

calc_dm_igm()

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:dm_igm – The dispersion measure contribution of the IGM. Return type:float

Notes

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

\[DM_{IGM} = DM_{excess} - \frac{DM_{host,loc}}{1 + z}\]

calc_f_obs()

Calculates the observed fluence of the FRB. This requires w_obs and s_peak_obs to not be None.

Returns:The fluence of the FRB. Return type:float

Notes

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

\[\rm{F_{obs} = W_{obs} \times S_{peak, obs}}\]

calc_redshift(method='inoue2004', cosmology='Planck18', subtract_host=False)

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

Parameters:

• method (str, optional) – The approximation to use when calculating the redshift. Avaliable methods: ioka2003, inoue2004, zhang2018
• cosmology (str, optional) – The method inoue2004 has the option to choose which cosmology to assume when performing the redshift estimation. Avaliable cosmologies: WMAP5, WMAP7, WMAP9, Planck13, Planck15, 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.

Returns:

The redshift of the FRB.

Return type:

float

Notes

The methods section in the documentation has a discription of each methods and where they should apply.

The cosmology section of the documentation has a list of the cosmological parameters used in each cosmology method.

calc_skycoords()

Calculates the skycoord position on the sky of the FRB from (raj, decj) or (gl, gb).

Returns:The sky coordinates of the FRB. Return type:astropy.coordinates.sky_coordinate.SkyCoord

decj

astropy.coordinates.angles.Latitude or None – The declination in J2000 coordinates of the best estimate of the FRB position.

dm

float – The observed dispersion measure of the FRB.

dm_excess

float – The dispersion measure with the Milky Way component subtracted.

dm_galaxy

float – The Milky Way component of the dispersion measure.

dm_host_est

float – The dispersion measure from the FRB host galaxy

dm_host_loc

float – The dispersion measure from a localised FRB host galaxy

dm_igm

f_obs

The Milky Way component of the dispersion measure.

gb

astropy.coordinates.angles.Latitude or None – The latitude in galactic coordinates of the best estimate of the FRB position.

gl

astropy.coordinates.angles.Longitude or None – The longitude in galactic coordinates of the best estimate of the FRB position.

name

str – The name of the FRB object.

raj

astropy.coordinates.angles.Longitude or None – The right accension in J2000 coordinates of the best estimate of the FRB position.

s_peak_obs

**float or None* – The observed peak flux density of the burst. Units*

skycoords

astropy.coordinates.sky_coordinate.SkyCoord or None – The skycoords of the FRB. This is calculated from either (raj, decj) or (gl, gb).

w_obs

float or None – The observed width of the pulse obtained by a pulse fitting algorithm. Units: \(\rm{ms}\)

z

float or None – 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 using calc_redshift().

z_host

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

fruitbat.estimate

fruitbat.estimate.redshift(dm, dm_uncert=0.0, method='inoue2004', cosmology='Planck18')

Returns the redshift of a given dispersion measure using a specified DM-z relation.

Parameters:

• dm (float) – Dispersion Measure. Units: \(\rm{pc\ cm^{-3}}\)
• dm_uncert (float or None) – The uncertainty in the dispersion measure. Units: \(\rm{pc\ cm^{-3}}\)
• method (string, optional) – The DM-z relation to use to calculate the redshift. Avaliable methods are: ioka2003, inoue2004, zhang2018. Default: ‘inoue2004’
• cosmology (string, optional) – Avaliable cosmologies: WMAP5, WMAP7, WMAP9, Planck13, Planck15, Planck18. Default: ‘planck2018’

Returns:

• z (float) – Redshift
• z_err (float) – The uncertianty in the redshift estimation. If dm_uncert is None then z_err = 0.

Notes

Cosmology has a list of the cosmological parameters used in each cosmology method.

fruitbat.estimate.methods(string=False)

Defines the list of avaliable method keywords.

Methods currently avaliable: ioka2003, inoue2004, zhang2018

Parameters:string (bool, optional) – If True, return a string of keywords instead of a list. Returns:A list containing the valid method keywords. If string=True it returns a single string listing all the keywords. Return type:list or str

fruitbat.utils

Utility functions for Fruitbat

fruitbat.utils.create_lookup_table(filename, method, cosmology, zmin=0, zmax=30, num_samples=100000.0)

Creates a lookup table

Parameters:

• filename (str) –
• method (str) –
• cosmology (dict) – A dictionary containing the cosmology parameters for the Hubble constant, Matter density, Baryon density and Dark Energy density. cosmology must contain values for the following keys: 'H0', 'Omega_m', 'Omega_b', 'Omega_L'
• zmin (int or float, optional) – The minimum redshift in the table. Default: 0
• zmax (int or float, optional) – The maximum redshift in the table. Default: 30
• num_samples (int, optional) – The number of dispersion measure samples to perform before interpolation. Default: 100000

Returns:

Return type:

None

fruitbat.utils.load_lookup_table(filename, data_dir='data')

Opens a saved .npy file containing an interpolated 1D function.

Parameters:

• filename (str) – The name of the file to load.
• data_dir (str, optional) – The directory containing the data. The whole path must be specified except if data_dir == ‘data’ then it will search in the data subdirectory of the source code. Default: ‘data’

Returns:

Function

Return type:

scipy.interpolate.interpolate.interp1d

fruitbat.cosmology

Module for defining different cosmologies

fruitbat.cosmology.WMAP5()

WMAP5 instance of FlatLambdaCDM cosmology

(from Komatsu et al. 2009, ApJS, 180, 330, doi: 10.1088/0067-0049/180/2/330. Table 1 (WMAP + BAO + SN ML).)

fruitbat.cosmology.WMAP7()

WMAP7 instance of FlatLambdaCDM cosmology

(from Komatsu et al. 2011, ApJS, 192, 18, doi: 10.1088/0067-0049/192/2/18. Table 1 (WMAP + BAO + H0 ML).)

fruitbat.cosmology.WMAP9()

WMAP9 instance of FlatLambdaCDM cosmology

(from Hinshaw et al. 2013, ApJS, 208, 19, doi: 10.1088/0067-0049/208/2/19. Table 4 (WMAP9 + eCMB + BAO + H0, last column))

fruitbat.cosmology.Planck13()

Planck13 instance of FlatLambdaCDM cosmology

(from Planck Collaboration 2014, A&A, 571, A16 (Paper XVI), Table 5 (Planck + WP + highL + BAO))

fruitbat.cosmology.Planck15()

Planck15 instance of FlatLambdaCDM cosmology

(from Planck Collaboration 2016, A&A, 594, A13 (Paper XIII), Table 4 (TT, TE, EE + lowP + lensing + ext))

fruitbat.cosmology.Planck18()

Planck18 instance of FlatLambdaCDM cosmology

(from Planck 2018 results. VI. Cosmological Parameters, A&A, submitted, Table 2 (TT, TE, EE + lowE + lensing + BAO))

fruitbat.cosmology.create_cosmology(parameters=None, name=None)

A wrapper to create custom astropy cosmologies.

The only avaliable cosmology types in this method are: FlatLambdaCDM, FlatwCDM, LambdaCDM and wCDM. See astropy.cosmology for more details on these types of cosmologies. To create a cosmology of a type that isn’t listed above, it will have to be created directly using astropy.cosmology.

Parameters:

• parameters (dict or None) – A dictionary containing the cosmological parameters. The names of the parameters must conform to the same format as the parameters used in astropy.cosmology. If parameters is None then default values for each parameter is used.
• name (str or None, optional) –
• name of the cosmology. Default (The) –

Returns:

Return type:

cosmology

Notes

Default parameter values:

params = {'H0': 70, 'Om0': 0.3, 'Oc0': 0.26, 'Ob0': 0.04, 'Neff': 3.04,
          'flat': True, 'Tcmb0': 0.0, 'm_nu': 0.0, 'w0': -1}

If 'flat' is set to False then a value of 'Ode0' (current dark energy density) should be specified.

fruitbat.cosmology.builtin()

Create a dictionary of the builtin cosmologies with keywords and functions.

Returns:A dictionary containing the keywords and function for each cosmology. Return type:dict

fruitbat.cosmology.keys()

Returns a string constaining all the keywords for builtin cosmologies.