API reference

Modules

archive

class scatfit.archive.Candidate(fname)

Psrchive Candidate class.

Parameters:: fname (str) – Path to file

apply_chanmask(mask=None)

Apply given channel mask, where ‘True’ elements represent a bad channel. If no mask is specified, this function will instead infer a mask from the data directly, following what is currently done inside the MeerTRAP pipeline (as of late Oct. 2021):

Run IQRM on the spectral standard deviation of the data, with radius = 0.1 x nchan, threshold = 3.0
Find channels with abnormal ACC1 (autocorrelation coefficient with a lag of 1 sample).

A channel that registers as an outlier in either step is replaced by zeros. The function returns the boolean channel mask that was applied.

Parameters:: mask (ndarray or None) – Behaviour of the function depends on argument type: - boolean ndarray: mask channels for which the mask is True - None: infer using IQRM + ACC1 outlier masking
Returns:: mask_array – The boolean mask that was applied
Return type:: ndarray

property bandpass_acc1: Autocorrelation coefficient with a lag of 1 time sample along the time axis

property bandpass_mean: Mean of the data along the time axis, BEFORE normalisation

property bandpass_std: Standard deviation of the data along the time axis, BEFORE normalisation

property bw: Observing bandwidth in MHz

property dedispersed: Are the data dedispersed?

property dm: Current dispersion measure of the data in pc cm^{-3}

property fcen: Central frequency in MHz

property fch1: Frequency of the first channel (MHz)

property fchn: Frequency of the last channel (MHz)

property foff: Frequency offset between consecutive channels (MHz). Can be negative.

property freqs: Channel frequencies in MHz, in the same order as they appear in the data

property nchans: Number of channels in the data

normalise(): Normalize all channels to zero mean and unit variance, in place. An exception is constant channels, which are just set to zero.

property npol: Number of polarisations of the data

property nsamp: Number of samples in the data

property nsubint: Number of subintegrations of the archive

property period: Topocentric folding period in seconds (from first subint)

scrunched_data(t=1, f=1, select='left')

Returns a copy of the data scrunched in time and frequency

Parameters:

t (int) – Time scrunching factor. If ‘t’ does not divide ‘nsamp’, then some samples will be excluded from the scrunched data. Which samples are excluded depend on the ‘select’ argument.
f (int) – Freq scrunching factor. If ‘f’ does not divide ‘nchan’, an error is raised.
select (str) – Time sample selection policy, either ‘left’ or ‘centre’. The number of samples selected from scrunching is Ns = nsamp - nsamp % t If ‘left’, select the first Ns samples. If ‘centre’, select the middle Ns samples.

Returns:

scrunched – The scrunched data

Return type:

ndarray

set_dm(dm): Set the DM of the data to specified value, by circularly shifting the channels appropriately.

property state: The polarisation state of the data

property times: Time offset of all samples from the start of the data, in seconds

property tsamp: Bin width of profile samples in seconds

property tstart: Start MJD of first time sample at the top frequency channel

zdot()

Apply the Z-dot filter to the data, in place. This is a much better variant of the zero-DM filter. See Men et al. 2019: https://ui.adsabs.harvard.edu/abs/2019MNRAS.488.3957M/abstract

:raises ValueError : if the data are not normalised yet:

zerodm()

Apply the zero-DM filter, that is subtract the mean of the data along the frequency axis from every frequency channel. This method takes care of setting the DM of the data to zero before this operation, and then sets it back to the original DM afterwards.

:raises ValueError : if the data are not normalised yet:

scatfit.archive.load_frb_data(filename, dm, fscrunch, tscrunch, norfi)

Load the FRB data from a psrchive file.

Parameters:

filname (str) – The filterbank file to load.
dm (float) – The dispersion measure to use to dedisperse the data.
fscrunch (int) – The number of frequency channels to sum.
tscrunch (int) – The number of time samples to sum.
norfi (bool) – Do not perform RFI excision.

Returns:

cand – The candidate FRB data.

Return type:

Candidate

dm

scatfit.dm.get_dm_smearing(f_lo, f_hi, dm)

Compute the intra-channel dispersive smearing.

Parameters:

f_lo (float) – The low frequency edge of the channel in MHz.
f_hi (float) – The high frequency edge of the channel in MHz.
dm (float) – The dispersion measure of the source in pc/cm^3.

Returns:

dt – The intra-channel dispersive smearing in ms.

Return type:

float

plotting

scatfit.plotting.plot_center_scaling(t_df, prefix, params)

Plot the scaling of fitted center with frequency.

Parameters:

t_df (DataFrame) – The input data.
prefix (str) – The prefix for the component selection.
params (dict) – Other parameters that affect the output.

scatfit.plotting.plot_chains(fitresult_emcee, params)

Plot the MCMC chains from an emcee sampling run.

Parameters:

fitresult_emcee (MinimizerResult) – The minimizer result object from lmfit.
params (dict) – Other parameters that affect the output.

scatfit.plotting.plot_corner(fitresult_emcee, fnlabel, params)

Make a corner plot.

Parameters:

fitresult_emcee (MinimizerResult) – The minimizer result object from lmfit.
fnlabel (str) – Postfix label for the filename.
params (dict) – Additional plotting parameters.

scatfit.plotting.plot_fluence_scaling(t_df, params)

Plot the scaling of the fitted fluences with frequency.

Parameters:

t_df (DataFrame) – The input data.
params (dict) – Other parameters that affect the output.

scatfit.plotting.plot_frb(cand, plot_range, profile, params): Plot the FRB data.

scatfit.plotting.plot_frb_scat(cand, df, fitresults, plot_range, params, cmap1='Greys', cmap2='YlGnBu', dynspec=True): Plot the dynamic spectrum and the sub-band profiles in a combined figure.

scatfit.plotting.plot_profile_fit(fit_range, sub_profile, fitresult, iband, cfreq, params, fitresult2=None): Plot the profile fit.

scatfit.plotting.plot_profile_models(params)

Plot and compare the profile scattering models.

Parameters:: params (dict) – Additional parameters that affect the processing.

scatfit.plotting.plot_width_scaling(t_df, cand, fitresult, params, allcomp)

Plot the scaling of fitted widths with frequency.

Parameters:

t_df (DataFrame) – The fit results as a DataFrame.
cand (Candidate) – The candidate FRB or pulsar data.
fitresult (dict) – The result object from the fit.
params (dict) – Additional parameters that affect the processing.
allcomp (bool) – Plot the intrinsic width scaling for all profile components.

scatfit.plotting.use_custom_matplotlib_formatting(): Adjust the matplotlib configuration parameters for custom format.

profile_helpers

scatfit.profile_helpers.get_snr_weq(on, off)

Compute the S/N of a profile using its equivalent width. This algorithm is based on Pulsar handbook page 167.

Parameters:

on (array) – The on-pulse profile data.
off (array) – The off-pulse profile data.

Returns:

snr – The S/N of the profile.

Return type:

float

pulsemodels

scatfit.pulsemodels.boxcar(x, width)

A simple boxcar function.

Parameters:

x (array) – The running variable (time).
width (float) – The width of the boxcar function.

Returns:

res – The boxcar data.

Return type:

array

scatfit.pulsemodels.equivalent_width(x, amp)

Compute the boxcar equivalent width.

Parameters:

x (array) – The running variable (time).
amp (array) – The pulse amplitude.

Returns:

weq – The equivalent width.

Return type:

float

scatfit.pulsemodels.full_width_post(x, amp, level)

Compute the full pulse width post scattering numerically.

Parameters:

x (array) – The running variable (time).
amp (array) – The pulse amplitude.
level (float) – The level at which to evaluate the pulse width.

Returns:

width – The full pulse width at the given level.

Return type:

float

scatfit.pulsemodels.gaussian_fwhm(sigma)

The full width at half maximum (W50) of a Gaussian.

Parameters:: sigma (float) – The Gaussian standard deviation.
Returns:: res – The Gaussian W50.
Return type:: float

scatfit.pulsemodels.gaussian_fwtm(sigma)

The full width at tenth maximum (W10) of a Gaussian.

Parameters:: sigma (float) – The Gaussian standard deviation.
Returns:: res – The Gaussian W10.
Return type:: float

scatfit.pulsemodels.gaussian_scattered_afb_instrumental(x, fluence, center, sigma, taus, taui, taud, dc)

A Gaussian pulse scattered in the ISM and affected by analogue (single-sided exponential) instrumental effects from DM-smearing and the detector/signal chain.

This implements Eq. 7 from McKinnon 2014.

Parameters:

x (array) – The running variable (time).
fluence (float) – The fluence of the pulse, i.e. the area under it.
center (float) – The mean of the Gaussian, i.e. its location.
sigma (float) – The Gaussian standard deviation.
taus (float) – The scattering time in the ISM.
taui (float) – The scattering time due to instrumental effects in the receiver or signal chain (e.g. integration time constant).
taud (float) – The scattering time due to intra-channel dispersive smearing.
dc (float) – The vertical offset of the profile from the baseline.

Returns:

res – The profile data.

Return type:

array

scatfit.pulsemodels.gaussian_scattered_dfb_instrumental(x, fluence, center, sigma, taus, taud, dc)

A Gaussian pulse scattered in the ISM and affected by digital (boxcar-like) instrumental effects. Convolving approach. We neglect instumental receiver or signal chain effects.

This implements Eq. 2 from Loehmer et al. 2001.

Parameters:

x (array) – The running variable (time).
fluence (float) – The fluence of the pulse, i.e. the area under it.
center (float) – The mean of the Gaussian, i.e. its location.
sigma (float) – The Gaussian standard deviation.
taus (float) – The scattering time in the ISM.
taud (float) – The scattering time due to intra-channel dispersive smearing.
dc (float) – The vertical offset of the profile from the baseline.

Returns:

res – The profile data.

Return type:

array

scatfit.pulsemodels.pbf_isotropic(plot_range, taus)

A pulse broadening function for isotropic scattering.

Parameters:

plot_range (array) – The evaluation variable (time) in ms.
taus (float) – The scattering time in ms.

Returns:

res – The profile data.

Return type:

array

Raises:

RuntimeError – If the window array is too short to fit the vast majority of the exponential sweep, i.e. taus is too large for the given time span.

scatfit.pulsemodels.scattered_profile(x, fluence, center, sigma, taus, dc)

A scattered pulse profile.

Implemented using numerical convolution with a pulse broadening function.

Parameters:

x (array) – The running variable (time).
fluence (float) – The fluence of the pulse, i.e. the area under it.
center (float) – The mean of the Gaussian, i.e. its location.
sigma (float) – The Gaussian standard deviation.
taus (float) – The scattering time.
dc (float) – The vertical offset of the profile from the baseline.

Returns:

res – The profile data.

Return type:

array

pulsemodels_python

scatfit.pulsemodels_python.bandintegrated_model(x, fluence, center, sigma, taus, dc, f_lo, f_hi, nfreq)

A true frequency band-integrated profile model.

The total (sub-)band-integrated profile is the superposition (weighted sum or weighted mean) of several profiles that evolve with frequency across the bandwidth of the frequency (sub-)band, one for each frequency channel. Namely, the individual profiles evolve with frequency (scattering, pulse width, fluence). For large fractional bandwidths or at low frequencies (< 1 GHz), the profile evolution across the band cannot be neglected, i.e. the narrow-band approximation fails.

We compute the frequency evolution across the band between f_lo and f_hi at nfreq centre frequencies. The total profile is then the weighted sum over the finite frequency grid. Ideally, one would use an infinitesimally narrow grid here.

Parameters:

x (array) – The running variable (time).
fluence (float) – The fluence of the pulse, i.e. the area under it.
center (float) – The mean of the Gaussian, i.e. its location.
sigma (float) – The Gaussian standard deviation.
taus (float) – The scattering time.
dc (float) – The vertical offset of the profile from the baseline.
f_lo (float) – The centre frequency of the lowest channel in the sub-band.
f_hi (float) – The centre frequency of the highest channel in the sub-band.
nfreq (int) – The number of centre frequencies to evaluate.

Returns:

res – The profile data.

Return type:

array

scatfit.pulsemodels_python.gaussian_normed(x, fluence, center, sigma)

A normed Gaussian function.

Parameters:

x (array) – The running variable (time).
fluence (float) – The fluence of the pulse, i.e. the area under it.
center (float) – The mean of the Gaussian, i.e. its location.
sigma (float) – The Gaussian standard deviation.

Returns:

res – The profile data.

Return type:

array

scatfit.pulsemodels_python.scattered_gaussian_pulse(x, fluence, center, sigma, taus, dc)

A scattered Gaussian pulse. Analytical approach, assuming thin screen scattering.

We use a standard implementation of an exponentially modified Gaussian here, see https://docs.scipy.org/doc/scipy/reference/generated/scipy.stats.exponnorm.html

Parameters:

x (array) – The running variable (time).
fluence (float) – The fluence of the pulse, i.e. the area under it.
center (float) – The mean of the Gaussian, i.e. its location.
sigma (float) – The Gaussian standard deviation.
taus (float) – The scattering time.
dc (float) – The vertical offset of the profile from the baseline.

Returns:

res – The profile data.

Return type:

array

sigproc

scatfit.sigproc.load_frb_data(filename, dm, fscrunch, tscrunch, norfi)

Load the FRB data from a SIGPROC filterbank file.

Parameters:

filname (str) – The filterbank file to load.
dm (float) – The dispersion measure to use to dedisperse the data.
fscrunch (int) – The number of frequency channels to sum.
tscrunch (int) – The number of time samples to sum.
norfi (bool) – Do not perform RFI excision.

Returns:

cand – The candidate FRB data.

Return type:

Candidate

simulate

stats_helpers

scatfit.stats_helpers.get_iqr(data, axis)

Compute the interquartile range.

Parameters:

data (array) – The input data as numpy float array.
axis (int) – The data axis to compute the statistic over.

Returns:

iqr – The interquartile range.

Return type:

float

scatfit.stats_helpers.get_robust_std(data, axis, mode='Gaussian')

Compute the robust standard deviation using the IQR.

Parameters:

data (array) – The input data.
axis (int) – The data axis to compute the statistic over.
mode (str) – The underlying distribution to assume when computing the robust standard deviation.

Returns:

sr – The robust standard deviation.

Return type:

float

Raises:

NotImplementedError – If the mode is not implemented.

Applications

apps.fit_frb

scatfit.apps.fit_frb.check_args(args)

Sanity check the commandline arguments.

Parameters:: args (populated namespace) – The commandline arguments.

scatfit.apps.fit_frb.compute_post_widths(fit_range, t_fitresult)

Compute the full post-scattering widths numerically from the Markov chain samples.

Parameters:

fit_range (array of float) – The time sample range, i.e. the dependent variable.
t_fitresult (dict) – The result object from the fit.

Returns:

widths – The post-scattering pulse widths.

Return type:

dict

scatfit.apps.fit_frb.compute_updated_dm(t_df, dm, prefix, params)

Compute an updated dispersion measure by fitting the center versus frequency curve.

Parameters:

t_df (DataFrame) – The input data.
dm (float) – The previous DM.
prefix (str) – The prefix for the component selection.
params (dict) – Additional parameters that affect the processing.

Returns:

updated_dm – The updated DM.

Return type:

dict

scatfit.apps.fit_frb.fit_powerlaw(x, y, err_y, params)

Fit a power law to data.

Parameters:

x (array of float) – The independent variable.
y (array of float) – The dependent variable.
err_y (array of float) – The uncertainty in y.
params (dict) – Additional parameters that affect the processing.

Returns:

fitresult_emcee – The power law fit results from the MCMC run.

Return type:

dict

scatfit.apps.fit_frb.fit_profile(cand, plot_range, fscrunch_factor, smodel, t_params)

Fit an FRB profile.

Parameters:

cand (Candidate) – The candidate FRB or pulsar data.
plot_range (array of float) – The time sample range, i.e. the dependent variable.
fscrunch_factor (int) – The number of frequency channels to integrate.
smodel (str) – The name of the scattering model to use.
t_params (dict) – Additional parameters that affect the processing.

Returns:

df (~pd.DataFrame) – The fit results as a DataFrame.
fitresult (dict) – The result object from the fit.

scatfit.apps.fit_frb.fit_profile_model(fit_range, profile, smodel, params)

Fit a profile model to data.

Parameters:

fit_range (array of float) – The time sample range, i.e. the dependent variable.
profile (array of float) – The profile amplitudes.
smodel (str) – The name of the scattering model to use.
params (dict) – Additional parameters that affect the processing.

Returns:

fitresult_emcee – The power law fit results from the MCMC run.

Return type:

dict

scatfit.apps.fit_frb.linear(x, x0, slope, intercept)

A linear function.

Parameters:

x (array) – The running variable.
x0 (float) – The reference location.
slope (float) – The slope of the line.
intercept (float) – The y value at x0.

Returns:

res – The model data.

Return type:

array

scatfit.apps.fit_frb.parse_args()

Parse the commandline arguments.

Returns:: args – The commandline arguments.
Return type:: populated namespace

apps.simulate_pulse

scatfit.apps.simulate_pulse.parse_args()

Parse the commandline arguments.

Returns:: args – The commandline arguments.
Return type:: populated namespace