API Reference

This section contains detailed documentation for all modules, classes, and functions in the FRB package.

Core Modules

The FRB package is organized into several key modules:

Quick Reference

Most Common Functions

Loading FRBs:

from frb.frb import FRB
frb_obj = FRB.by_name('FRB20121102A')

DM Calculations:

from frb.dm import igm
DM_cosmic = igm.DM_cosmic(z=0.5)
z_est = igm.z_from_DM(DM_obs)

Building FRB Tables:

from frb.frb import build_table_of_frbs
frb_tbl, tbl_units = build_table_of_frbs()

Scattering Analysis:

from frb import turb_scattering as ts
theta = ts.theta_mist(n_e, nu_obs)

Function Index

Core Functions by Category

Dispersion Measure:

`frb.dm.igm.average_DM`	Macquart Relation
`frb.dm.igm.ne_cosmic`	Calculate the average cosmic electron number density as a function of redshift.
`frb.dm.igm.z_from_DM`	Report back an estimated redshift from an input IGM DM Any contributions from the Galaxy and/or host need to have been 'removed'
`frb.dm.igm.average_DMhalos`	Compute average halo DM contribution along FRB sightline.
`frb.dm.cosmic.DMcosmic_PDF`	PDF(Delta) following the McQuinn formalism describing the DM_cosmic PDF
`frb.dm.host.dm_host_from_ssfr`	Estimate DM_host from the surface density of SFR

Scattering:

`frb.turb_scattering.theta_mist`	Estimate the scattering angle for a mist, following the calculations by M.
`frb.turb_scattering.tau_mist`	Temporal broadening for a mist of spherical clouds following the calculations by M.
`frb.turb_scattering.ne_from_tau_mist`	n_e from temporal broadening for a mist of spherical clouds following the calculations by M.

FRB Tables:

`frb.frb.build_table_of_frbs`	Generate a Pandas table of FRB data
`frb.frb.list_of_frbs`	Generate a list of FRB objects for all the FRBs in the Repo

FRB Objects:

`frb.frb.FRB.by_name`	Method to instantiate an FRB by its name
`frb.frb.FRB.grab_host`	Returns the FRBHost object for this FRB

Class Hierarchy

FRB
├── FRB.by_name()
├── FRB.grab_host()
└── FRB.set_ee()

FRBHost
├── FRBHost.by_frb()
├── FRBHost.derived
├── FRBHost.photom
└── FRBHost.get_metaspec()

Constants and Defaults

The package uses several default values and constants:

Cosmological Parameters:

# Default cosmology (defined in frb.defs)
frb_cosmo = astropy.cosmology.Planck18

Default Scattering Parameters:

# Default structure sizes
L_default = 50 * u.kpc      # Structure size
R_default = 1 * u.pc        # Cloud size
fV_default = 1.0           # Filling factor

Physical Constants:

The package uses astropy constants throughout for physical calculations.

Error Handling

The FRB package uses standard Python exception handling:

Common Exceptions:

FileNotFoundError: When FRB data files are not found
ValueError: When invalid parameters are passed to functions
AttributeError: When accessing properties not available for a particular FRB
ImportError: When optional dependencies are not available

Error Handling Example:

try:
   frb_obj = FRB.by_name('NonExistentFRB')
except FileNotFoundError:
    print("FRB data not found")
except ValueError as e:
    print(f"Invalid FRB name: {e}")

Data Types

The package primarily works with astropy quantities and coordinates:

Common Data Types:

astropy.coordinates.SkyCoord - Sky positions
astropy.units.Quantity - Physical quantities with units
astropy.table.Table - Tabular data (catalogues)
numpy.ndarray - Numerical arrays
dict - Configuration and metadata

Unit Conventions:

Dispersion Measure: pc / cm³
Distances: kpc, Mpc, Gpc
Frequencies: MHz, GHz
Time: s, ms, μs
Angles: deg, arcmin, arcsec, mas, μas

Contributing to the API

If you’re contributing new functions or classes:

Follow the existing documentation style
Include comprehensive docstrings
Add type hints where appropriate
Include examples in docstrings
Update this API documentation