ilex.frb

class FRB(yaml_file=None, name: str = 'FRBXXXXXX', RA: str = '00:00:00.0000', DEC: str = '00:00:00.0000', MJD: float = 0.0, DM: float = 0.0, bw: int = 336, cfreq: float = 1271.5, t_crop=None, f_crop=None, tN: int = 1, fN: int = 1, t_lim_base=[0.0, 3100.0], f_lim_base=[0.0, 336.0], RM: float | None = None, f0: float | None = None, pa0: float = 0.0, verbose: bool = False, norm='None', dt: float = 0.001, df: float = 1.0, zapchan: str = '', terr_crop=None, t_ref=0.0)[source]

FRB class for Processing of ASKAP FRB data

Parameters:

  • name (str) – Name of FRB

  • RA (str) – Right acension position

  • DEC (str) – Declination position

  • MJD (float) – Modified Julian date in days

  • DM (float) – Dispersion Measure

  • bw (float) – Bandwidth

  • cfreq (float) – Central Frequency

  • t_crop (list) – Crop start and end phase in Time

  • f_crop (list) – Crop start and end phase in Frequency

  • tN (int) – Factor for averaging in Time

  • fN (int) – Factor for averaging in Frequency

  • t_lim (list) – Limits for FRB in Time

  • f_lim (list) – Limits for FRB in Frequency

  • t_lim_base (list) – Base limits of FRB in time (not including t_ref)

  • f_lim_base (list) – Base limits of FRB in freq

  • t_ref (float) – Reference zero-point in time

  • RM (float) – Rotation Measure

  • f0 (float) – Reference Frequency

  • pa0 (float) – Position angle at reference frequency f0

  • zapchan (str) –

    string used for zapping channels, in format -> “850, 860, 870:900”

    each element seperated by a ‘,’ is a seperate channel. If ‘:’ is used, user can specify a range of values

    i.e. 870:900 -> from channel 870 to 900 inclusive of both.

  • verbose (bool) – Enable verbose logging

  • norm (str) –

    Type of normalisation

    [max] - normalise using maximum

    [absmax] - normalise using absolute maximum

    [None] - Skip normalisation

  • terr_crop (list) – bounds for off-pulse region in time [min, max] [ms], default is None

  • yaml_file (str) – parameter yaml file of FRB to load in, default is None

par

parameters for FRB

Type:

FRB_params

this_par

Current instance of ‘par’

Type:

FRB_params

prev_par

Last instance of ‘par’

Type:

FRB_params

metapar

hold meta-parameters for FRB

Type:

FRB_metaparams

this_metapar

Current instance of ‘metapar’

Type:

FRB_metaparams

prev_metapar

Last instance of ‘metapar’

Type:

FRB_metaparams

ds

Dictionary of loaded stokes dynamic spectra

Type:

Dict

pol

Dictionary of loaded Polarisation time series

Type:

Dict

_t

Dictionary of cropped stokes time series

Type:

Dict

_f

Dictionary of cropped stokes spectra

Type:

Dict

_ds

Dictionary of cropped stokes dynamic spectra

Type:

Dict

_freq

Cropped Frequency array [MHz]

Type:

np.ndarray

_time

Cropped time array [ms]

Type:

np.ndarray

verbose

Enable logging

Type:

bool

savefig

Save all created figures to files

Type:

bool

pcol

Color of text for logging

Type:

str

empty

Variable used to initialise FRB instance and data loading

Type:

bool

plot_type

type of plot

[scatter] - scatter plot with error bars

[lines] - line plot with error patches

Type:

str

show_plots

If true, shows plots

Type:

bool

save_plots

If true, saves plots to file

Type:

bool

residuals

if true, a residual panel will appear when plotting a fit using pyfit, default is True

Type:

bool

plotPosterior

if true, will save posterior corner plot when fitting using bayesian method, default is True

Type:

bool

apply_tw

if true, apply time dependant weights when scrunching in time, i.e making spectra, default is True

Type:

bool

apply_fw

if true, apply freq dependant weights when scrunching in freq, i.e. making time profiles, default is True

Type:

bool

fitted_params

dictionary of fitted values, i.e. RM

Type:

dict

calc_polfracs(stk_debias=False, peak_sigma=3.0, peak_average_factor=1, **kwargs)[source]

Calculate polarisation fractions using a number of different methods.

Parameters:

  • debias (bool, optional) – Debiases Stokes L, P and abs(V), abs(Q) and abs(U), by default False.

  • peak_sigma (float, optional) – Provide a threshold in terms of I/Ierr that will be used to mask the data before estimating the peak fraction of each stokes parameter. This will be nessesary to filter out noisy data.

  • peak_average_factor – averaging (downsampling) factor to apply to X(t) stokes profiles to help estimate their peaks

  • float – averaging (downsampling) factor to apply to X(t) stokes profiles to help estimate their peaks

property dynspec_cmap
find_frb(method='sigma', mode='median', sigma: int = 5, rms_guard: float = 10, rms_width: float = 50, rms_offset: float = 60, yfrac: float = 0.95, buffer: float | None = None, padding: float | None = None, dt_from_peak_sigma: float | None = None, **kwargs)[source]

This function uses a number of method of finding the bounds of a burst.

1. Find FRB bounds using a sigma threshold [method = “sigma”] find_optimal_sigma_width(sigma, rms_guard, rms_width, rms_offset)

2. Find FRB width and centroid using a fractional fluence threshold method [method = “fluence”] find_optimal_fluence_width(yfrac)

Note, the centroid of the burst is the point along the burst that splits the fluence 50/50 on either side.

Parameters:

  • method (str) – method to use for finding burst bounds [“sigma”, “fluence”]

  • mode (str) –

    type of algorithm to use when finding optimal fluence width (method = “fluence”)

    [median] -> find burst width by estimating centroid of burst and fluence threshold on either side

    [min] -> find minimum burst width that captures the desired fluence threshold (moving window algorithm)

  • sigma (int) – S/N threshold

  • rms_guard (float) – gap between estiamted pulse region and off-pulse region for rms and baseband estimation, in (ms)

  • rms_width (float) – width of off-pulse region on either side of pulse region in (ms)

  • rms_offset (float) – rough offset from peak on initial S/N threshold in (ms)

  • yfrac (float) – fraction of total fluence on either side of FRB effective centroid to take as FRB bounds

  • buffer (float) – initial width of data in [ms] centered at the peak that will be used to estimate FRB bounds

  • pading (float) – Add additional padding to measured bounds, as a fraction of the width of the burst

  • dt_from_peak_sigma (float) – Determine maximum time resolution (dt) to achieve a peak S/N of dt_from_peak_sigma

  • **kwargs – FRB parameters + FRB meta-parameters

Returns:

  • t_crop (list) – New Phase start and end limits for found frb burst

  • t_ref (float) – Zero point, either the peak or centroid, depending on the method used

fit_RM(method='RMquad', sigma: float | None = None, rm_prior: list = [-1000, 1000], pa0_prior: list = [-1.5707963, 1.5707963], unwrap: bool = False, fit_params: dict | None = None, filename: str | None = None, **kwargs)[source]

Fit Spectra for Rotation Measure

Parameters:

  • method (str, optional) –

    Method to perform Rotation Measure fitting, by default “RMquad”

    [RMquad] - Fit for the Rotation Measure using the standard quadratic method

    [RMsynth] - Use the RM-tools RM-Synthesis method

    [QUfit] - Fit log-likelihood model of Stokes Q and U parameters (see bannister et al 2019 - supplementary)

  • sigma (float, optional) – Apply masking based on S/N threshold given, used in [RMquad, RMsynth, QUfit]

  • rm_prior (list) – priors for rotation measure, used in [QUfit], by default [-1000, 1000]

  • pa0_prior (list) – priors for PA0, used in [QUfit], by default [-pi/2, pi/2] (Shouldn’t need to change)

  • fit_params (dict, optional) –

    keyword parameters for fitting method, by default None

    [RMquad] - Scipy.optimise.curve_fit keyword params

    [RMsynth] - RMtools_1D.run_synth keyword params

    [QUfit] - bilby.run_sampler keyword params

  • filename (str, optional) – filename to save figure to, by default None

Returns:

p – pyfit class fitting structure

Return type:

pyfit.fit

fit_scintband(method='bayesian', priors: dict | None = None, statics: dict | None = None, fit_params: dict | None = None, redo=False, filename: str | None = None, n: int | None = None, **kwargs)[source]

Fit for, Find and plot Scintillation bandwidth in FRB

Parameters:

  • method (str) –

    method for fitting

    [bayesian] - Use Bilby bayesian Statistics

    [least squares] - Use Scipy.Curve_fit least squares

  • priors (dict, optional) – Priors for sampling, by default None

  • statics (dict, optional) – priors to keep constant, by default None

  • fit_params (dict, optional) – extra arguments for Bilby.run_sampler function, by default None

  • redo (bool, optional) – if True, will redo fitting in the case that results are cached, this is mainly for BILBY fitting, default is False

  • filename (str, optional) – Save figure to file, by default None

  • n (float, optional) – Polynomial order, by default None

Returns:

p – pyfit class structure

Return type:

pyfit.fit

fit_tscatt(method='bayesian', npulse=1, priors: dict | None = None, statics: dict | None = None, fit_params: dict | None = None, redo=False, filename: str | None = None, **kwargs)[source]

Fit a series of gaussian’s convolved with a one-sided exponential scattering tai using BILB

Parameters:

  • method (str) –

    method for fitting

    [bayesian] - Use Bilby bayesian Statistics

    [least squares] - Use Scipy.Curve_fit least squares

  • npulse (int, optional) – Number of gaussian to fit, by default 1

  • priors (dict, optional) – Priors for sampling, by default None

  • statics (dict, optional) – Priors to keep constant during fitting, by default None

  • fit_params (dict, optional) – Keyword parameters for Bilby.run_sampler, by default None

  • redo (bool, optional) – if True, will redo fitting in the case that results are cached, this is mainly for BILBY fitting, default is False

  • filename (str, optional) – filename to save final plot to, by default None

Returns:

p – pyfit class structure

Return type:

pyfit.fit

get_data(data_list='dsI', get=False, ignore_nans=False, stk_debias=False, stk_ratio=False, stk_sigma=None, **kwargs)[source]

Make new instance of loaded data. This will take a crop of the loaded mmap-ed stokes data, pass it through the back-end processing function and save the data in memory in the ._ds, _t, _f, _time and _freq class instance attributes.

Parameters:

  • data_list (List(str) or str, optional) – List of data products to load in, by default “dsI”

  • get (bool, optional) – Return new crops of data, by default False and will only save data instances to class container attributes

  • ignore_nans (bool, optional) – If true, if nans exist in data, they will be removed before saving the data instance

  • stk_debias – If true, tL/fL and tP/fP will be debiased

  • bool – If true, tL/fL and tP/fP will be debiased

  • optional – If true, tL/fL and tP/fP will be debiased

  • stk_ratio – If true, calculate X/I for t and f products

  • bool – If true, calculate X/I for t and f products

  • optional – If true, calculate X/I for t and f products

  • stk_sigma (float, optional) – Mask X/I data by ratio_rms_threshold * rms

Returns:

data – Dictionary of processed data crops, by default None if get = False

Return type:

Dict, optional

get_freqs()[source]

Get Frequencies

load_data(dsI: str | None = None, dsQ: str | None = None, dsU: str | None = None, dsV: str | None = None, yaml_file: str | None = None, mmap=True, _init=False)[source]

Load Stokes HTR data

Parameters:

  • dsI (str) – Filename of stokes I dynamic spectra

  • dsQ (str) – Filename of stokes Q dynamic spectra

  • dsU (str) – Filename of stokes U dynamic spectra

  • dsV (str) – Filename of stokes V dynamic spectra

  • yaml_file (str) – parameter yaml file for FRB, default is None

  • mmap (bool) – Enable memory mapping for loading

  • _init (bool) – For initial Data loading

plot_PA(Ldebias_threshold=2.0, stk2plot='ILV', flipPA=False, stk_ratio=False, fit_params: dict | None = None, filename: str | None = None, save_files=False, **kwargs)[source]

Plot Figure with PA profile, Stokes Time series data, and Stokes I dyspec. If RM is not specified, will be fitted first.

Parameters:

  • Ldebias_threshold (float, optional) – Sigma threshold for PA masking, by default 2.0

  • stk2plot (str, optional) –

    string of stokes to plot, for example if “QV”, only stokes Q and V are plotted,

    by default “IQUV”, choice between “IQUVLP”

  • flipPA (bool, optional) – Plot PA between [0, 180] degrees instead of [-90, 90], by default False

  • stk_ratio (bool, optional) – Plot Stokes ratios in time series ax, by default False

  • fit_params (dict, optional) –

    keyword parameters for fitting method, by default None

    [RMquad] - Scipy.optimise.curve_fit keyword params

    [RMsynth] - RMtools_1D.run_synth keyword params

  • filename (str, optional) – filename of figure to save to, by default None

  • save_files (Bool, optional) – if true, will save 1D .npy file with PA and .npy file with PAerrs, by default False

Returns:

fig – Return figure instance

Return type:

figure

plot_crop(stk='I', filename=None, **kwargs)[source]

Plot current crop of of data along with off-pulse crop if given

Parameters:

  • stk (str, optional) – Stokes data to plot, by default “I”

  • filename (str, optional) – name of file to save figure image, by default None

plot_data(data='dsI', ax=None, stk_debias=False, stk_ratio=False, stk_sigma=None, filename: str | None = None, **kwargs)[source]

General Plotting function, choose to plot either dynamic spectrum or time series data for all stokes parameters

Parameters:

  • data (str, optional) – type of data to plot, by default “dsI”

  • ax (axes, optional) – Axes object to plot data into

  • stk_debias (bool, optional) – If True, Any L or P data plotted will be debiased

  • stk_ratio (bool, optional) – If True, any t or f data will be converted to X/I and plotted

  • stk_sigma – Mask Stokes ratios by ratio_rms_threshold * rms

  • optional – Mask Stokes ratios by ratio_rms_threshold * rms

  • filename (str, optional) – filename to save figure to, by default None

Returns:

fig – Return Figure Instance

Return type:

figure

plot_periodgram(plot_log=False, filename=None, **kwargs)[source]

Plot ACF of time series

plot_log: bool

Also plot log y-axis

plot_poincare(stk_type='f', stk_sigma=2.0, plot_data=True, plot_model=False, n=5, normalise=True, plot_1D_stokes=False, filename=None, **kwargs)[source]

Plot Stokes data on a Poincare Sphere.

Parameters:

  • filename (str, optional) – filename to save figure to, by default None

  • stk_type (str, optional) –

    types of stokes data to plot, by default “f”

    [f] - Plot as a function of frequency

    [t] - Plot as a function of time

  • stk_sigma (float, optional) –

    Error threshold used for masking stokes data in the case that stokes/I is being calculated

    this avoids deviding by potentially small numbers and getting weird results,by default 2.0

  • plot_data (bool, optional) – Plot Data on Poincare sphere, by default True

  • plot_model (bool, optional) – Plot Polynomial fitted data on Poincare sphere, by default False

  • normalise (bool, optional) – Plot data on surface of Poincare sphere (this will require normalising stokes data), by default True

  • n (int, optional) – Maximum order of Polynomial fit, by default 5

  • plot_1D_stokes (bool, optional) – if True, plot 1D stokes line plots seperately in another figure

  • **kwargs (Dict) – FRB parameter keywords

Returns:

fig – Return figure instance

Return type:

figure

plot_stokes(ax=None, stk_debias=False, stk_sigma=2.0, stk_type='f', stk2plot='IQUV', stk_ratio=False, filename: str | None = None, **kwargs)[source]

Plot Stokes data, by default stokes I, Q, U and V data is plotted

Parameters:

  • ax (_axes_) – matplotlib.pyplot.axes object to plot to, default is None

  • stk_debias (bool, optional) – Plot stokes L and/or P debias, by default False

  • stk_sigma (float, optional) – sigma threshold for error masking, data that is I < sigma * Ierr, mask it out or else weird overflow behavior might be present when calculating stokes ratios, by default 2.0

  • stk_type (str, optional) – Type of stokes data to plot, “f” for Stokes Frequency data or “t” for time data, by default “f”

  • stk2plot (str, optional) – string of stokes to plot, for example if “QV”, only stokes Q and V are plotted, by default “IQUV”

  • stk_ratio (bool, optional) – if true, plot stokes ratios S/I

  • filename (str, optional) – name of file to save figure image, by default None

  • **kwargs (Dict) – FRB parameter keywords

Returns:

fig – Return figure instance

Return type:

figure

save_data(data_list=None, name=None, save_yaml=False, yaml_file=None, stk_debias=False, stk_ratio=False, **kwargs)[source]

Save current instance data

Parameters:

  • data_list (List(str), optional) – List of data to save, by default None

  • name (str, optional) – Common Pre-fix for saved data, by default None, if None the name parameter of the FRB class will be used.

  • stk_debias (bool) – Debias Stokes data before saving

  • stk_ratio (bool) – Save stokes ratios

set(**kwargs)[source]

Set FRB parameters, see class parameters

zap_channels(chans: str | None = None, zapzeros: bool = False, zapzerosmargin: float = 1e-05, resetzap: bool = False, interactive=False, **kwargs)[source]

Zap channels (uses Stokes I freq spectrum)

Parameters:

  • chans (str, optional) – Channels to zap, by default None

  • zapzeros (bool, optional) – zap channels at or close to zero, by default False

  • zapzerosmargin (float) – margin close to zero at which to zap channels, ratio of max channel flux

  • resetzap (bool, optional) – reset channels zapped, by default False

  • interactive (bool, optional) – Enable interactive zapping mode

  • **kwargs (dict) – Standard frb parameters that can be overidden (zapchan cannot be overidden)