sigpyproc.base

class sigpyproc.base.Filterbank

Bases: ABC

Base class exporting methods for the manipulation of frequency-major order pulsar data.

Notes

The Filterbank class should never be instantiated directly. Instead it should be inherited by data reading classes.

abstract property header

Header metadata of input file.

Type:

Header

abstract read_block(start, nsamps)

Read a block of filterbank data.

Parameters:

• start (int) – first time sample of the block to be read

• nsamps (int) – number of samples in the block (i.e. block will be nsamps*nchans in size)

Returns:

2-D array of filterbank data with observational metadata

Return type:

FilterbankBlock

Raises:

ValueError – if requested samples are out of range

abstract read_dedisp_block(start, nsamps, dm)

Read a block of dedispersed filterbank data.

Best used in cases where I/O time dominates reading a block of data.

Parameters:

• start (int) – first time sample of the block to be read

• nsamps (int) – number of samples in the block (i.e. block will be nsamps*nchans in size)

• dm (float) – dispersion measure to dedisperse at

Returns:

2-D array of filterbank data with observational metadata

Return type:

FilterbankBlock

Raises:

ValueError – if requested dedispersed samples are out of range

abstract read_plan(gulp=16384, start=0, nsamps=None, skipback=0, description=None, quiet=False)

A generator used to perform filterbank reading.

Parameters:

• gulp (int, optional) – number of samples in each read, by default 16384

• start (int, optional) – first sample to read from filterbank, by default 0 (start of file)

• nsamps (int, optional) – total number of samples to read, by default None (end of the file)

• skipback (int, optional) – number of samples to skip back after each read, by default 0

• description (str, optional) – description of task show next to progress bar (rich), by default Calling Stack

• quiet (bool, optional) – suppress progress bar and logging, by default False

Yields:

Iterator (tuple(int, int, ndarray)) – An iterable of the values in the sequence.

Raises:

ValueError – If read samples < skipback.

Notes

For each read, the generator yields a tuple x, where:

• x[0] is the number of samples read

• x[1] is the index of the read (i.e. x[1]=0 is the first read)

• x[2] is a 1-D numpy array containing the data that was read

Examples

The normal calling syntax for this is function is:

>>> for nsamps, ii, data in self.read_plan(**plan_kwargs):
        # do something
where data always has contains ``nchans*nsamps`` points.

property chan_stats

Channel statistics of input data.

Type:

ChannelStats

compute_stats(**plan_kwargs)

Compute channelwise statistics of data (upto kurtosis).

Parameters:

**plan_kwargs (dict) – Keyword arguments for read_plan().

compute_stats_basic(**plan_kwargs)

Compute channelwise statistics of data (only mean and rms).

Parameters:

**plan_kwargs (dict) – Keyword arguments for read_plan().

collapse(gulp=16384, start=0, nsamps=None, **plan_kwargs)

Sum across all frequencies for each time sample.

Parameters:

• gulp (int, optional) – number of samples in each read, by default 16384

• start (int, optional) – start sample, by default 0

• nsamps (int, optional) – number of samples to read, by default all

• **plan_kwargs (dict) – Additional Keyword arguments for read_plan().

Returns:

A zero-DM time series

Return type:

TimeSeries

bandpass(**plan_kwargs)

Average across each time sample for all frequencies.

Parameters:

**plan_kwargs (dict) – Keyword arguments for read_plan().

Returns:

the bandpass of the data

Return type:

TimeSeries

dedisperse(dm, gulp=16384, **plan_kwargs)

Dedisperse the data and collapse to a time series.

Parameters:

• dm (float) – dispersion measure to dedisperse to

• gulp (int, optional) – number of samples in each read, by default 16384

• **plan_kwargs (dict) – Additional keyword arguments for read_plan().

Returns:

a dedispersed time series

Return type:

TimeSeries

Notes

If gulp < maximum dispersion delay, gulp is taken to be twice the maximum dispersion delay.

read_chan(chan, gulp=16384, **plan_kwargs)

Read a single frequency channel from the data as a time series.

Parameters:

• chan (int) – channel to retrieve (0 is the highest frequency channel)

• gulp (int, optional) – number of samples in each read, by default 16384

• **plan_kwargs (dict) – Additional keyword arguments for read_plan().

Returns:

selected channel as a time series

Return type:

TimeSeries

Raises:

ValueError – If chan is out of range (chan < 0 or chan > total channels).

invert_freq(filename=None, **plan_kwargs)

Invert the frequency ordering of the data and write to a new file.

Parameters:

• filename (str, optional) – name of output file, by default basename_inverted.fil

• **plan_kwargs (dict) – Additional keyword arguments for read_plan().

Returns:

name of output file

Return type:

str

apply_channel_mask(chanmask, maskvalue=0, filename=None, **plan_kwargs)

Apply a channel mask to the data and write to a new file.

Parameters:

• chanmask (ArrayLike) – boolean array of channel mask (1 or True for bad channel)

• maskvalue (int or float, optional) – value to set the masked data to, by default 0

• filename (str, optional) – name of the output filterbank file, by default basename_masked.fil

• **plan_kwargs (dict) – Additional keyword arguments for read_plan().

Returns:

name of output file

Return type:

str

downsample(tfactor=1, ffactor=1, gulp=16384, filename=None, **plan_kwargs)

Downsample data in time and/or frequency and write to file.

Parameters:

• tfactor (int, optional) – factor by which to downsample in time, by default 1

• ffactor (int, optional) – factor by which to downsample in frequency, by default 1

• gulp (int, optional) – number of samples in each read, by default 16384

• filename (str, optional) – name of file to write to, by default basename_tfactor_ffactor.fil

• **plan_kwargs (dict) – Additional keyword arguments for read_plan().

Returns:

output file name

Return type:

str

Raises:

ValueError – If number of channels is not divisible by ffactor.

extract_samps(start, nsamps, filename=None, **plan_kwargs)

Extract a subset of time samples from the data and write to file.

Parameters:

• start (int) – start sample to extract

• nsamps (int) – number of samples to extract

• filename (str, optional) – name of output file, by default basename_samps_start_start+nsamps.fil

• **plan_kwargs (dict) – Additional keyword arguments for read_plan().

Returns:

name of new file

Return type:

str

Raises:

ValueError – If start or nsamps are out of bounds.

extract_chans(chans=None, **plan_kwargs)

Extract a subset of channels from the data and write each to file.

Parameters:

• chans (ArrayLike, optional) – channel numbers to extract, by default all channels

• **plan_kwargs (dict) – Keyword arguments for read_plan().

Returns:

names of all files written to disk

Return type:

list of str

Raises:

ValueError – If chans are out of range (chan < 0 or chan > total channels).

Notes

Time series are written to disk with names based on channel number.

extract_bands(chanstart, nchans, chanpersub=None, **plan_kwargs)

Extract a subset of Sub-bands from the data and write each to file.

Parameters:

• chanstart (int) – start channel to extract

• nchans (int) – number of channel to extract

• chanpersub (int, optional) – number of channels in each sub-band, by default nchans

• **plan_kwargs (dict) – Keyword arguments for read_plan().

Returns:

names of all files written to disk

Return type:

list of str

Raises:

• ValueError – If chanpersub is less than 1 or greater than nchans.

• ValueError – If nchans is not divisible by chanpersub.

• ValueError – If chanstart is out of range (chanstart < 0 or chanstart > total channels).

Notes

Filterbanks are written to disk with names based on sub-band number.

requantize(nbits_out, remove_bandpass=False, filename=None, **plan_kwargs)

Eequantize the data and write to a new file.

Parameters:

• nbits_out (int) – number of bits into requantize the data

• remove_bandpass (bool, optional) – remove the bandpass from the data, by default False

• filename (str, optional) – name of output file, by default basename_digi.fil

• **plan_kwargs (dict) – Keyword arguments for read_plan().

Returns:

name of output file

Return type:

str

Raises:

ValueError – If nbits_out is less than 1 or greater than 32.

remove_zerodm(filename=None, **plan_kwargs)

Remove the channel-weighted zero-DM from the data and write to disk.

Parameters:

• filename (str, optional) – name of output file , by default basename_noZeroDM.fil

• **plan_kwargs (dict) – Keyword arguments for read_plan().

Returns:

name of output file

Return type:

str

Notes

Based on Presto implementation of Eatough, Keane & Lyne 2009 [1].

References

[1]

R. P. Eatough, E. F. Keane, A. G. Lyne, An interference removal technique for radio pulsar searches, MNRAS, Volume 395, Issue 1, May 2009, Pages 410-415.

subband(dm, nsub, filename=None, gulp=16384, **plan_kwargs)

Produce a set of dedispersed subbands from the data.

Parameters:

• dm (float) – the DM of the subbands

• nsub (int) – the number of subbands to produce

• filename (str, optional) – output file name of subbands, by default basename_DM.subbands

• gulp (int, optional) – number of samples in each read, by default 16384

• **plan_kwargs (dict) – Additional keyword arguments for read_plan().

Returns:

name of output subbands file

Return type:

str

fold(period, dm, accel=0, nbins=50, nints=32, nbands=32, gulp=16384, **plan_kwargs)

Fold data into discrete phase, subintegration and subband bins.

Parameters:

• period (float) – period in seconds to fold with

• dm (float) – dispersion measure to dedisperse to

• accel (float, optional) – acceleration in m/s/s to fold with, by default 0

• nbins (int, optional) – number of phase bins in output, by default 50

• nints (int, optional) – number of subintegrations in output, by default 32

• nbands (int, optional) – number of subbands in output, by default 32

• gulp (int, optional) – number of samples in each read, by default 16384

• **plan_kwargs (dict) – Additional keyword arguments for read_plan().

Returns:

3 dimensional data cube

Return type:

FoldedData

Raises:

ValueError – If nbands * nints * nbins is too large

Notes

If gulp < maximum dispersion delay, gulp is taken to be twice the maximum dispersion delay.

clean_rfi(method='mad', threshold=3, chanmask=None, custom_funcn=None, filename=None, **plan_kwargs)

Clean RFI from the data.

Parameters:

• method (str, optional) – method to use for cleaning (“mad”, “iqrm”), by default “mad”

• threshold (float, optional) – threshold for cleaning, by default 3

• chanmask (ArrayLike, optional) – User channel mask to use (1 or True for bad channels), by default None

• custom_funcn (Callable, optional) – Custom function to apply to the mask, by default None

• filename (str, optional) – output file name, by default None

• **plan_kwargs (dict) – Additional keyword arguments for read_plan().

Returns:

Filename and mask of cleaned data

Return type:

tuple(str, RFIMask)

Raises:

ValueError – If method is not “mad” or “iqrm”