Arrival Times Measurements

To perform measurements using the arrival times method rather than the Gaussian ACF methods, use the arrivaltimes module.

import arrivaltimes

The arrivaltimes module is largely independent from the rest of FRBGUI and can be used solely through scripting. The function arrivaltimes.measureburst is the main entry point into the module and performs most of the work of measurement. The module can display an interactive plot window to help with marking bursts, masking channels, and determining initial guesses through measureburst’s show option.

`arrivaltimes` module

arrivaltimes.fitgauss(data, duration, redchisq=1)

Fits a gaussian fit to the the data (using gauss_model)

Estimates the uncertainty in data as np.std(data[0:len(data)//NOISE_WIDTH_FACTOR])

arrivaltimes.fitgaussmix(data, duration, xos, sigmas=None, fix_xos=False, tol=0.01)

arrivaltimes.fitrows(wfall, dt, freqs, plot=False, bname='')

arrivaltimes.gauss_model(x, a, xo, sigma)

arrivaltimes.gaussmix_model(x, *p)

arrivaltimes.line_model(nu, dtdnu, t_b)

arrivaltimes.listnpzs(path): List all npz files in path

arrivaltimes.measure_allmethods(filename, show=True, p0tw=0.01, p0bw=100, **kwargs)

Collect spectro-temporal measurements of a burst using multiple techniques. Utility for comparing the result of spectro-temporal measurements of a burst obtained from the following techniques: 1. arrival times method 2. ACF method 3. direct 2d gaussian with three gaussian forms

Parameters:

filename (str) – path to .npz of burst in frbgui burst format
kwargs – keywords to pass to measureburst for loading/processing the waterfall. measureburst with loadonly=True is used to load the burst.

arrivaltimes.measureburst(filename, xos=[], cuts=[], sigmas=None, fix_xos=False, tolms=0.01, targetDM=None, correctTimes=False, downfactors=(1, 1), subtractbg=False, bw_filter='data_cutoff', bw_width_factor=3, snr_cutoff=3, t_filter_factor=2, crop=None, masks=[], submasks=None, bandmask_thres=None, measure_drift=True, show=True, figsize=(10, 8), show_components=False, show_arrtime=False, cmap_norm='linear', cmap='viridis', save=True, outdir='', outfmt='.png', return_arrivaltimes=False, return_fig=False, loadonly=False, save_solutions=False, load_solutions=None, hide_legend=False, legendloc=1, label_components=False, pslopeidx=-1, tpoint='tstart')

Measure spectro-temporal properties of a burst, and output a figure

Compute the inverse sub-burst slope (dt/dnu) using the per-row arrival time method.

Compute the duration and bandwidth by finding a 1-dimensional gaussian model to the integrated time series and spectrum, respectively. The duration and bandwidth are the 1 sigma widths of either fit.

Compute the center frequency as the center of the 1d spectrum model.

If multiple components are present, split them up and measure individually. The number of components to fit for is equal to len(xos).

Parameters:

filename (str) – filename to .npz of a dedispersed burst waterfall. File is expected to follow frbgui’s Burst Format.
xos (List[float] or 2-tuple of List[float], optional) – List of times in ms of sub-burst centers. Can be approximate. If a 2-tuple, the second list is used as the location(s) to cut the waterfall. Using the cuts option instead is equivalent to using the 2 tuple option.
cuts (List[float], optional) – List of times in ms to cut the waterfall. Useful for blended bursts. User must make sure their cuts make sense (i.e. in between burst centers). Typically, if one cut is needed, then all bursts should be cut as well even if well separated.
sigmas (List[float], optional) – initial guesses for the width sigma when finding the 1-dimensional gaussian model to the time series. Must be the same length as xos
fix_xos (bool, optional) – Default False. Whether or not to fix the passed xos when fitting the 1d model. Useful when bursts are blended and one can visually distinguish where a burst should be from the waterfall even if it appears completely absorbed in the integrated time series.
tolms (float, optional) – Tolerance in milliseconds to use when fix_xos is True. Default is 0.01 ms.
targetDM (float, optional) – the DM (pc/cm^3) to perform the measurement at. Default is to perform the measurement at the DM of the npz file.
correctTimes (bool, optional) – Shift xos and cuts to account for dispersive shift when applying a targetDM other than the burst DM. Note that this shift will occur even when fix_xos is True.
downfactors (tuple[int], optional) – 2-tuple of factors to downsample by in frequency and time (respectively)
subtractbg (bool, tuple[bool], optional) – Perform a second background subtraction on subbursts. By default will do a background subtraction using 10% of channels on the whole waterfall. Pass (False, False) to skip both rounds of background subtraction.
bw_filter (str, optional) –
The type of spectral/bandwidth filter to apply on arrival times. Default is 'data_cutoff'. Options are

1. 'data_cutoff': filter out arrival times in channels where the 1σ on-pulse mean amplitude is < 3 (see snr_cutoff) times the noise standard deviation 2. 'model_cutoff': filter out arrival times in channels where the 1d spectral model amplitude is < 3 (see snr_cutoff) times the noise standard deviation 3. 'model_width': filter out arrival times that lie beyond a multiple of the 1d spectral model width (σ). See bw_width_factor.
bw_width_factor (int, optional) – When using bw_filter=model_width, 3σ of the burst bandwidth is applied as a spectral filter. For bursts with lots of frequency structure this may be inadequate, and this parameter can be used to override the filter width. It’s recommended to try downsampling first. Note that a high bw_width_factor such as 10-15 likely indicates the bandwidth measurement is being understimated.
snr_cutoff (int, optional) – The S/N cutoff to use when bw_filter='data_cutoff' or bw_filter='model_cutoff'. By default equals 3.
t_filter_factor (int, optional) – By default 2σ of the burst duration is applied as a temporal filter.
outdir (str, optional) – string of output folder for figures. Defaults to ‘’.
crop (tuple[int], optional) – pair of indices to crop the waterfall in time
masks (List[int], optional) – frequency indices to mask. Masks are applied before downsampling
submasks (tuple[List[int]], optional) – tuple of length xos of lists of indices to mask on a subcomponent’s waterfall. Note that contrary to masks, these are applied after downsampling. Indices are scaled from the original size to the downsampled size and so can cover more than one channel. The length of submasks must match the length of xos. Example: To specify a mask on the 4th component of a waterfall with 4 components, pass submask=([],[],[],[22]). This is also a good way to filter out misbehaving components in an otherwise well-measured waterfall and is useful for complicated bursts.
bandmask_thres (float or list[float], optional) – The intensity threshold in the integrated spectrum above which points should be ignored when performing burst fits. This is primarily useful for masking scintillation peaks in order to obtain more accurate burst bandwidth measurements. The appropriate level can be inferred from the output plot, or, if there are multiple components, using the plot output when show_components=True, since the spectrum normally shown is integrated over all components. When a single value is specified, it will be applied to all components if there are more than one. To specify a different threshold for each component, pass a list of values, using None when no spectral masking is to be applied. For example: a 3-component waterfall may have bandmask_thres=[None, 0.1, 0.12]. Note that this will only affect the bandwidth measurement and not interact with the arrival times in each channel.
measure_drift (bool, optional) – When True (default), and if len(xos) > 1 (i.e. there are multiple burst components), will measure the drift rate using the times and center frequencies of the bursts to fit a line. Will also plot a corresponding line showing the drift rate measurement. Set to False to disable this behaviour.
show (bool, optional) – if True show interactive figure window for each file
figsize (tuple, optional) – figsize passed to matplotlib used for main output figure.
show_components (bool, optional) – if True show figure window for each sub-burst
show_arrtime (bool or List[int], optional) – if True, show a diagnostic plot with statistical and fit information for each frequency channel. If instead a list of frequency channels are provided, then only those frequency channels will be shown. Frequency channels listed need only be to the nearest integer. See also return_arrivaltimes option.
cmap_norm (str, optional) – The colormap normalization norm parameter passed to matplotlib’s imshow command when plotting the waterfall. Default is ‘linear’, other options are ‘log’, ‘symlog’, ‘logit’, or matplotlib’s Normalize class.
cmap (str, optional) – matplotlib colormap to use for waterfall
return_arrivaltimes (bool, optional) – If True, will return a dataframe of the arrival times per channel
return_fig (bool, optional) – if True, return the matplotlib figure. The figure will not be closed.
save (bool, optional) – if True save a figure displaying the measurements.
loadonly (bool, optional) – if True will perform loading steps such as masking, dedispersing, and downsampling, then return a tuple of wfall, freqs, times_ms, t_popt, DM, etc.
outfmt (str, optional) – string of file format to save figure as. Default is ‘.png’. Include the ‘.’ character.
save_solutions (bool, optional) – setting to True will save a file inside of the folder specified by outdir that contains the fit solution data for the 1d time series and the spectrum of each component. Useful for reviewing measurements of bursts with many components that take a long time to analyse. Output filename will be of the form f'{bname}.sols.npz'. Default False
load_solutions (str, optional) – Filename of solutions file generated by save_solutions option. Default is None
hide_legend (bool, optional) – Hides the legend in the output if True.
legendloc (int or str, optional) – Set the location of the legend. Passed to matplotlib’s loc argument when the legend is called.
label_components (bool, optional) – If True, label components filters in the time series plot. Useful for complicated waterfalls.
pslopeidx (int, optional) – Index of component to show in the time vs. frequency (i.e. slope) plot. Default is last component (-1).
tpoint (str, optional) – One of ‘tstart’ (default), ‘tend’, or ‘xo’. Use to measure the slope based on the central peak in each channel, or based on the ending time in each channel.

Returns:

results list of lists where each list is the result of the measurement.

This array can be used to make a pandas dataframe in the following way:

resultsdf = pd.DataFrame(
        data=results,
        columns=arrivaltimes.results_columns
).set_index('name')

where the columns of the dataframe are

'name',
'DM',
'center_f (MHz)',
'center_f_err',
'duration (ms)',
'duration_err',
'bandwidth (MHz)',
'bandwidth_err',
'dtdnu (ms/MHz)',
'dtdnu_err',
'redchisq_t',     # reduced chi-squared of time series fit
'redchisq_nu',    # reduced chi-squared of component-wise spectrum fit
'redchisq_dtdnu', # reduced chi-squared of component-wise slope fit
'tb (ms)', # t_b
'tb_err'

arrtimesdf (pd.DataFrame): Only returned when return_arrivaltimes is True. fig (matplotlib.fig): Matplotlib figure. Only returned when return_fig is True.

Return type:

(list)

arrivaltimes.measuredrifts(df, show_plot=True, verbose=False, search_paths=[])

Using a results spreadsheet created from measureburst, find bursts with multiple components and compute their drift rate using the t0 and center_f measurement data.

Parameters:

df –
show_plot (bool, optional) – If True, show a plot of the drift rate measurement. False by default.
search_paths (list[str], optional) – If provided, and if show_plot is True, will search for a corresponding .npz file of the burst waterfall and load it in order to display a plot of the waterfall with the measured drift rate overlaid.
verbose (bool, optional) – If True, print a lot of information about the drift measurement, including the components used.

arrivaltimes.plotburst(data, band, retfig=False, extent=None)

arrivaltimes.printd(*args)

arrivaltimes.smallestdivisor(n)

arrivaltimes.zero_line_model(nu, dtdnu)

Arrival Times Measurements

arrivaltimes module

`arrivaltimes` module