sigpyproc.base

sigpyproc.base

class sigpyproc.base.Filterbank

Bases: abc.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, verbose=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

  • verbose (bool, optional) – whether to display progress bar, 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, filename=None, **plan_kwargs)

Set the data in the given channels to zero.

Parameters

  • chanmask (ArrayLike) – binary channel mask (0 for bad channel, 1 for good)

  • 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.

previous

sigpyproc.foldedcube

next

sigpyproc.utils