sigpyproc.readers

sigpyproc.readers#

Classes for reading filterbank and PSRFITS data.

This module contains the FilReader and PFITSReader classes for reading filterbank and PSRFITS data.

Classes

`FilReader`	A class to handle the reading of sigproc format filterbank files.
`PFITSReader`	Reads a filterbank file from a FITS file.
`PulseExtractor`	Extracts a data block from a filterbank file centered on a pulse.

class sigpyproc.readers.FilReader(filenames, *, check_contiguity=True)[source]#

Bases: Filterbank

A class to handle the reading of sigproc format filterbank files.

Parameters:

filenamesstr | Path | Sequence[str | Path]: Filterbank file name(s).
check_contiguitybool, optional: Check if the input files are contiguous, by default True.

Attributes:

bitsinfo: BitsInfo: Bits info of input file data.
chan_stride: int: Channel byte stride in input data.
filename: str: Name of the input file (first file in case of multiple input files).
header: Header metadata of input file.
samp_stride: int: Sample byte stride in input data.

Methods

`read_block`(start, nsamps[, fch1, nchans])	Read a data block from the filterbank file stream.
`read_dedisp_block`(start, nsamps, dm)	Read a block of dedispersed filterbank data.
`read_plan`([gulp, start, nsamps, skipback, ...])	Read sequential filterbank in gulps and yield.

Returns:

Filterbank: Base container of filterbank data with observational metadata.

Notes

To be considered as a Sigproc format filterbank file the header must only contain keywords found in the SIGPROC_SCHEMA dictionary.

property header#

Header metadata of input file.

Returns:

Header: Header object containing metadata of the input file.

property filename#: str: Name of the input file (first file in case of multiple input files).

property bitsinfo#: BitsInfo: Bits info of input file data.

property chan_stride#: int: Channel byte stride in input data.

property samp_stride#: int: Sample byte stride in input data.

read_block(start, nsamps, fch1=None, nchans=None)[source]#

Read a data block from the filterbank file stream.

Parameters:

startint: First time sample of the block to be read.
nsampsint: Number of samples in the block (i.e. block will be nsamps*nchans in size).
fch1float, optional: Frequency of the first channel, by default None (header value).
nchansint, optional: Number of channels in the block, by default None (header value).

Returns:

FilterbankBlock: 2-D array of filterbank data with observational metadata.

Raises:

ValueError: if requested nsamps or nchans are out of range.

read_dedisp_block(start, nsamps, dm)[source]#

Read a block of dedispersed filterbank data.

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

Parameters:

startint: First time sample of the block to be read.
nsampsint: Number of samples in the block (i.e. block will be nsamps*nchans in size).
dmfloat: Dispersion measure to dedisperse at.

Returns:

FilterbankBlock: 2-D array of filterbank data with observational metadata.

Raises:

ValueError: if requested dedispersed nsamps are out of range.

read_plan(gulp=16384, start=0, nsamps=None, skipback=0, description=None, *, quiet=False, allocator=None)[source]#

Read sequential filterbank in gulps and yield.

Parameters:

gulpint, optional: Number of time samples in each read, by default 16384.
startint, optional: Starting sample to read from, by default 0 (start of file).
nsampsint, optional: Total number of samples to read, by default None (end of the file).
skipbackint, optional: Number of samples to skip back after each read, by default 0.
descriptionstr, optional: Annotation for progress bar (rich), by default Calling Stack.
quietbool, optional: Disable progress bar and logging, by default False.
allocatorCallable[[int], Buffer], optional: An allocator callback that returns an object implementing the Python Buffer Protocol interface (PEP 3118) for the data to be read into, by default None.

Yields:

Iterator[tuple[int, int, ndarray]]: Tuple of number of samples read, index of read, and the unpacked data read.

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_r, ii, data in self.read_plan(**plan_kwargs):
        # do something
where data always has contains ``nchans*nsamps`` points.

class sigpyproc.readers.PFITSReader(filename)[source]#

Bases: Filterbank

Reads a filterbank file from a FITS file.

Parameters:

filenamestr: Name of the input file.

Attributes:

bitsinfo: BitsInfo: Bits info of input file data.
filename: str: Name of the input file (first file in case of multiple input files).
header: Header metadata of input file.
pri_hdr: PrimaryHdr: Primary header of input file.
sub_hdr: SubintHdr: Subint header of input file.

Methods

`read_block`(start, nsamps[, fch1, nchans])	Read a data block from the filterbank file stream.
`read_dedisp_block`(start, nsamps, dm)	Read a block of dedispersed filterbank data.
`read_plan`([gulp, start, nsamps, skipback, ...])	Read sequential filterbank in gulps and yield.

property pri_hdr#: PrimaryHdr: Primary header of input file.

property sub_hdr#: SubintHdr: Subint header of input file.

property header#

Header metadata of input file.

Returns:

Header: Header object containing metadata of the input file.

property filename#: str: Name of the input file (first file in case of multiple input files).

property bitsinfo#: BitsInfo: Bits info of input file data.

read_block(start, nsamps, fch1=None, nchans=None)[source]#

Read a data block from the filterbank file stream.

Parameters:

startint: First time sample of the block to be read.
nsampsint: Number of samples in the block (i.e. block will be nsamps*nchans in size).
fch1float, optional: Frequency of the first channel, by default None (header value).
nchansint, optional: Number of channels in the block, by default None (header value).

Returns:

FilterbankBlock: 2-D array of filterbank data with observational metadata.

Raises:

ValueError: if requested nsamps or nchans are out of range.

read_dedisp_block(start, nsamps, dm)[source]#

Read a block of dedispersed filterbank data.

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

Parameters:

startint: First time sample of the block to be read.
nsampsint: Number of samples in the block (i.e. block will be nsamps*nchans in size).
dmfloat: Dispersion measure to dedisperse at.

Returns:

FilterbankBlock: 2-D array of filterbank data with observational metadata.

Raises:

ValueError: if requested dedispersed nsamps are out of range.

read_plan(gulp=16384, start=0, nsamps=None, skipback=0, description=None, *, quiet=False, allocator=None)[source]#

Read sequential filterbank in gulps and yield.

Parameters:

gulpint, optional: Number of time samples in each read, by default 16384.
startint, optional: Starting sample to read from, by default 0 (start of file).
nsampsint, optional: Total number of samples to read, by default None (end of the file).
skipbackint, optional: Number of samples to skip back after each read, by default 0.
descriptionstr, optional: Annotation for progress bar (rich), by default Calling Stack.
quietbool, optional: Disable progress bar and logging, by default False.
allocatorCallable[[int], Buffer], optional: An allocator callback that returns an object implementing the Python Buffer Protocol interface (PEP 3118) for the data to be read into, by default None.

Yields:

Iterator[tuple[int, int, ndarray]]: Tuple of number of samples read, index of read, and the unpacked data read.

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_r, ii, data in self.read_plan(**plan_kwargs):
        # do something
where data always has contains ``nchans*nsamps`` points.

class sigpyproc.readers.PulseExtractor(filfile, pulse_toa, pulse_width, pulse_dm, min_nsamps=attr_dict['min_nsamps'].default, toa_freq=attr_dict['toa_freq'].default, nchans=attr_dict['nchans'].default)[source]#

Bases: object

Extracts a data block from a filterbank file centered on a pulse.

The extracted block is centered on the given pulse toa at the desired frequency in the band. The block is padded if the pulse is too close to the edge of the filterbank file.

Parameters:

filfilestr: Name of the filterbank file.
pulse_toaint: Time of arrival of the pulse in samples at the toa_freq.
pulse_widthint: Width of the pulse in samples.
pulse_dmfloat: Dispersion measure of the pulse.
toa_freqfloat, optional: Frequency at which the pulse toa is given, by default None (highest frequency)
nchansint, optional: Number of channels to extract, by default None (all channels)
min_nsampsint, optional: Minimum number of samples in the extracted block, by default 256
quietbool, optional: If True, suppresses logging messages, by default False

Attributes:

block_delay: int: Dispersion Block size in samples.
disp_delay: int: Dispersion delay in samples.
filfile
min_nsamps
nchans
nsamps: int: Number of samples in the output block.
nsamps_file: int: Number of samples to read in the file.
nstart: int: Start sample of the output block.
nstart_file: int: Start sample to read in the file.
pulse_dm
pulse_toa
pulse_toa_block: int: Time of arrival of the pulse in the output block.
pulse_width
sub_hdr
t_decimate: int: Decimation factor to consider.
toa_freq

Methods

get_data([pad_mode])

Extract the filterbank block centered on the pulse.

filfile#

pulse_toa#

pulse_width#

pulse_dm#

min_nsamps#

toa_freq#

nchans#

sub_hdr#

property t_decimate#: int: Decimation factor to consider.

property disp_delay#: int: Dispersion delay in samples.

property block_delay#: int: Dispersion Block size in samples.

property nsamps#: int: Number of samples in the output block.

property nstart#: int: Start sample of the output block.

property nstart_file#: int: Start sample to read in the file.

property nsamps_file#: int: Number of samples to read in the file.

property pulse_toa_block#: int: Time of arrival of the pulse in the output block.

get_data(pad_mode='median')[source]#

Extract the filterbank block centered on the pulse.

Parameters:

pad_mode{‘median’, ‘mean’}, optional: Mode for padding the data, by default “median”

Returns:

FilterbankBlock: Data block.

sigpyproc.readers

On this page

sigpyproc.readers#