sigpyproc.io module

sigpyproc.io.sigproc

sigpyproc.io.sigproc.edit_header(filename, key, value)

Edit a sigproc style header directly in place for the given file.

Parameters:

• filename (str) – name of the sigproc file to modify header.

• key (str) – name of parameter to change (must be a valid sigproc key)

• value (int or float or str) – new value to enter into header

Raises:

ValueError – if the new header to be written to file is longer or shorter than the header that was previously in the file.

Notes

It is up to the user to be responsible with this function, as it will directly change the file on which it is being operated.

sigpyproc.io.sigproc.parse_header_multi(filenames, check_contiguity=True)

Parse the metadata from Sigproc-style file/sequential files.

Parameters:

filenames (str or list of str) – sigproc filterbank files containing the header

Returns:

observational metadata

Return type:

dict

sigpyproc.io.sigproc.parse_header(filename)

Parse the metadata from a single Sigproc-style file.

Parameters:

filename (str) – sigproc filterbank file containing the header

Returns:

observational metadata

Return type:

dict

Raises:

IOError – If file header is not in sigproc format

sigpyproc.io.sigproc.match_header(header1, header2)

Match header keywords between two parsed sigproc headers.

Parameters:

• header1 (dict) – parsed header from file 1.

• header2 (dict) – parsed header from file 2.

Raises:

ValueError – if key values do not match.

sigpyproc.io.sigproc.ensure_contiguity(header)

Check if list of sigproc files are contiguous/sequential.

Parameters:

header (dict) – parsed header of sigproc files

Raises:

ValueError – if files are not contiguous

sigpyproc.io.sigproc.encode_header(header)

Get sigproc format header in binary format.

Returns:

header in binary format

Return type:

bytes

sigpyproc.io.sigproc.encode_key(key, value=None, value_type='str')

Encode given header key to a bytes string.

Parameters:

• key (str) – header key

• value (int or float or str, optional) – value of the header key, by default None

• value_type (str, optional) – type of the header key, by default “str”

Returns:

bytes encoded string

Return type:

bytes

sigpyproc.io.sigproc.parse_radec(src_raj, src_dej)

Parse Sigproc format RADEC float as Astropy SkyCoord.

Parameters:

• src_raj (float) – Sigproc style HHMMSS.SSSS right ascension

• src_dej (float) – Sigproc style DDMMSS.SSSS declination

Returns:

Astropy coordinate class

Return type:

SkyCoord

sigpyproc.io.bits

sigpyproc.io.bits.unpack(array, nbits)

Unpack 1, 2 and 4 bit array. Only unpacks in big endian bit ordering.

Parameters:

• array (numpy.ndarray) – Array to unpack.

• nbits (int) – Number of bits to unpack.

Returns:

Unpacked array.

Return type:

numpy.ndarray

Raises:

ValueError – if nbits is not 1, 2, or 4

sigpyproc.io.bits.pack(array, nbits)

Pack 1, 2 and 4 bit array. Only packs in big endian bit ordering.

Parameters:

• array (numpy.ndarray) – Array to pack.

• nbits (int) – Number of bits to pack.

Returns:

Packed array.

Return type:

numpy.ndarray

Raises:

ValueError – if nbits is not 1, 2, or 4

class sigpyproc.io.bits.BitsInfo(nbits, digi_sigma=_Nothing.NOTHING)

Bases: object

Class to handle bits info.

Raises:

ValueError – if input nbits not in [1, 2, 4, 8, 16, 32]

nbits

digi_sigma

default_sigma = {1: 0.5, 2: 1.5, 4: 6, 8: 6, 16: 6, 32: 6}

property dtype

Type of the data (np.dtype, read-only).

property itemsize

Element size of this data-type object (int, read-only).

property unpack

Whether to unpack bits (bool, read-only).

property bitfact

Bit factor to unpack/pack bits (int, read-only).

property digi_min

Minimum value used to quantize data (int, read-only).

property digi_max

Maximum value used to quantize data (int, read-only).

property digi_mean

Mean used to quantize data (float, read-only).

property digi_scale

Scale used to quantize data (float, read-only).

to_dict()

Get a dict of all property attributes.

Returns:

property attributes

Return type:

dict

sigpyproc.io.fileio

class sigpyproc.io.fileio.FileReader(files, hdrlens, datalens, mode='r', nbits=8)

Bases: _FileBase

A file reader class that can read from multiple files.

Files should have format similar to sigproc.

Parameters:

• files (list[str]) – list of files to be read from

• hdrlens (list[int]) – list of header lengths for each file

• datalens (list[int]) – list of data lengths for each file

• mode (str, optional) – file opening mode, by default “r”

• nbits (int, optional) – number of bits per sample in the files, by default 8

property cur_data_pos

Current position in the data stream.

Type:

int

cread(nunits)

Read nunits (nbytes) of data from the file.

Parameters:

nunits (int) – number of units (nbytes) to be read from the file

Returns:

an 1-D array containing the read data

Return type:

ndarray

Raises:

IOError – if file is closed.

seek(offset, whence=0)

Change the multifile stream position to the given data offset.

offset is always interpreted for a headerless file and is relative to start of the first file.

Parameters:

• offset (int) – Absolute position to seek in the data stream

• whence (int) – 0 (SEEK_SET) 1 (SEEK_CUR)

Raises:

ValueError – if whence is not 0 or 1.

class sigpyproc.io.fileio.FileWriter(file, tsamp, nchans, mode='w', nbits=8, quantize=False, interval_seconds=10, constant_offset_scale=False, **digi_kwargs)

Bases: _FileBase

A file writer class that can write to a sigproc format file.

Parameters:

• file (str) – file to be written to

• mode (str, optional) – file writing mode, by default “w”

• nbits (int, optional) – number of bits per sample in the file, by default 8

• quantize (bool, optional) – whether to quantize the data, by default False

• tsamp (float, optional) – sampling time, by default None

• nchans (int, optional) – number of channels, by default None

• interval_seconds (float, optional) – sample interval used for quantization in seconds, by default 10

• constant_offset_scale (bool, optional) – whether to use constant offset and scale, by default False

• **digi_kwargs (dict) – keyword arguments for the digitizer: digi_mean, digi_scale, digi_min, digi_max

Raises:

ValueError – if quantize is True and outut nbits is 32.

cwrite(ar)

Write an array to file.

Parameters:

ar (ndarray) – a 1-D numpy array

Notes

Regardless of the dtype of the array argument, the data will be packed with a bitsize determined by the nbits attribute of the File instance. To change this attribute, use the _setNbits methods. It is the responsibility of the user to ensure that values in the array do not go beyond the maximum and minimum values allowed by the nbits attribute.

write(bo)

Write the given bytes-like object, bo to the file stream.

Wrapper for io.RawIOBase.write().

Parameters:

bo (bytes) – bytes-like object

close()

Close the currently open file object.

class sigpyproc.io.fileio.Transform(tsamp, nchans, digi_mean, digi_scale, digi_min, digi_max, interval_seconds=10, constant_offset_scale=False)

Bases: object

A class to transform data to the quantized format.

Parameters:

• tsamp (float) – sampling time, by default None

• nchans (int) – number of channels, by default None

• digi_mean (float) – mean of the quantized data

• digi_scale (float) – scale of the quantized data

• digi_min (float) – minimum value of the quantized data

• digi_max (float) – maximum value of the quantized data

• interval_seconds (float, optional) – sample interval used for quantization in seconds, by default 10

• constant_offset_scale (bool, optional) – whether to use constant offset and scale, by default False

property interval_samples

rescale(data)

quantize(data)

sigpyproc.io.pfits

class sigpyproc.io.pfits.Receiver(*, name, nrcvr, basis, hand, sa, rph, tracking_mode, tracking_angle)

Bases: object

Receiver information.

Variables:

• name (str) – Name of the receiver.

• nrcvr (int) – Number of receptors.

• basis (str) – Basis of receptors.

• hand (int) – Hand of receptor basis.

• sa (float) – Symmetry angle of receptor basis.

• rph (float) – Reference source phase.

• tracking_mode (str) – Tracking mode of the receiver platform.

• tracking_angle (float) – Position angle tracked by the receiver.

name

nrcvr

basis

hand

sa

rph

tracking_mode

tracking_angle

class sigpyproc.io.pfits.Backend(*, name, phase, dcc, delay, tcycle, configfile)

Bases: object

Backend information.

Variables:

• name (str) – Name of the backend instrument.

• phase (float) – Phase convention of backend.

• dcc (float) – Downconversion conjugation corrected.

• delay (float) – Backend propn delay from digi. input.

• tcycle (float) – Native cycle time of correlation system.

• configfile (str) – Name of a configuration file used to set up the backend system.

name

phase

dcc

delay

tcycle

configfile

class sigpyproc.io.pfits.PrimaryHdr(filename)

Bases: object

property header

Primary header.

Type:

astropy.io.fits.Header

property observer

Observer name(s).

Type:

str

property project_id

Project name.

Type:

str

property telescope

Telescope name.

Type:

str

property location

Antenna location.

Type:

astropy.coordinates.EarthLocation

property receiver

Receiver information.

Type:

Receiver

property backend

Backend information.

Type:

Backend

property ibeam

Beam number.

Type:

int

property obs_mode

Observation mode.

Type:

str

property date_obs

Observation start date.

Type:

astropy.time.Time

property freqs

Frequency channels.

Type:

FrequencyChannels

property chan_dm

Dispersion measure value used for on-line (normally coherent) dedispersion.

Type:

float

property source

Source name or label for an observation.

Type:

str

property coord

Source coordinates.

Type:

astropy.coordinates.SkyCoord

property tstart

Observation start time.

Type:

astropy.time.Time

class sigpyproc.io.pfits.SubintHdr(filename)

Bases: object

property header

SUBINT header.

Type:

astropy.io.fits.Header

property subint_width

Width of subint table in bytes.

Type:

int

property nsubint

Number of rows (subints) in subint table.

Type:

int

property poln_type

Polarisation identifier (e.g., AABBCRCI, AA+BB).

Type:

str

property poln_state

Polarisation state (e.g., Coherence).

Type:

str

property npol

Number of polarisation products in the DATA table.

Type:

int

property tsamp

Time per bin or sample (seconds).

Type:

float

property nbits

Number of bits per sample.

Type:

int

property zero_off

Zero offset for data (the nominal data zero in digitiser units).

Type:

float

property signint

Flag to indicate that the data values are signed integers.

Type:

int

property subint_offset

Subint offset for contiguous SEARCH-mode files.

Type:

int

property nchans

Number of frequency channels for each polarisation in the DATA table.

Type:

int

property chan_bw

Channel bandwidth in MHz.

Type:

float

property channel_offset

Channel offset for contiguous SEARCH-mode files.

Type:

int

property subint_samples

Number of samples per subint or table row.

Type:

int

property nsamples

Total number of valid samples in a search-mode file.

Type:

int

property subint_shape

property sub_hdr

property tsubint

Time per subint or table row (seconds).

Type:

float

property offs_sub

Time since the observation start at the centre of first sub-integration (seconds).

Type:

float

property azimuth

Azimuth (degrees).

Type:

astropy.coordinates.Angle

property zenith

Zenith (degrees).

Type:

astropy.coordinates.Angle

property freqs

Frequency channels for first subint.

Type:

sigpyproc.utils.FrequencyChannels

class sigpyproc.io.pfits.PFITSFile(filename)

Bases: object

Handle a PSRFITS file.

Parameters:

filename (str) – Filename of the PSRFITS file.

property filename

Name of file.

Type:

str

property pri_hdr

Primary header.

Type:

PrimaryHdr

property sub_hdr

Subint header.

Type:

SubintHdr

property bitsinfo

Bits information.

Type:

BitsInfo

read_subints(startsub, nsubs, poln_select=1, scloffs=True, weights=True)

Read the digitised data in a given polarization format from a range of PSRFITS SUBINT table.

Parameters:

• startsub (int) – index of start row (subint) to read from the SUBINT table

• nsubs (int) – number of subints to read from the SUBINT table

• poln_select (int, optional) – 1=PP+QQ, 2=PP,QQ, 3=(PP+QQ)^2 4=PP,QQ,PQ,QP, by default 1

• scloffs (bool, optional) – apply scales and offsets when unpacking data, by default False

• weights (bool, optional) – apply weights when unpacking data, by default False

Returns:

subint (row) data in float32 if scloffs or weights applied, otherwise in uint8 with shape (nsamps, nchan).

Return type:

numpy.ndarray

read_subint_pol(isub, poln_select=1, scloffs=True, weights=True)

Read the digitised data in a given polarization format from the PSRFITS SUBINT table.

Parameters:

• isub (int) – index of row (subint) to read from the SUBINT table

• poln_select (int, optional) – 1=PP+QQ, 2=PP,QQ, 3=(PP+QQ)^2 4=PP,QQ,PQ,QP, by default 1

• scloffs (bool, optional) – apply scales and offsets when unpacking data, by default True

• weights (bool, optional) – apply weights when unpacking data, by default True

Returns:

subint (row) data in float32 if scloffs or weights applied, otherwise in uint8 with shape (nsamps, nchan).

Return type:

numpy.ndarray

read_subint(isub, scloffs=True, weights=True)

Read the digitised data from the PSRFITS SUBINT table.

Parameters:

• isub (int) – index of row (subint) to read from the SUBINT table

• scloffs (bool, optional) – apply scales and offsets when unpacking data, by default True

• weights (bool, optional) – apply weights when unpacking data, by default True

Returns:

subint (row) data in float32 if scale_and_offset or weights applied, otherwise in uint8 with shape (nsamps, npol, nchan).

Return type:

numpy.ndarray

read_freqs(isub)

Read the Channel centre frequency from the PSRFITS SUBINT table.

Parameters:

isub (int) – index of row (subint) to read from the SUBINT table

Returns:

Centre frequency for each channel in MHz (NCHAN)

Return type:

FrequencyChannels

read_weights(isub)

Read channel weight (DAT_WTS) column from the SUBINT table.

Parameters:

isub (int) – index of row (subint) to read from the SUBINT table

Returns:

Weights for each channel in the range 0-1 (NCHAN)

Return type:

numpy.ndarray

read_scales(isub)

Read channel data scale factor (DAT_SCL) column from the SUBINT table.

Parameters:

isub (int) – index of row (subint) to read from the SUBINT table

Returns:

Data scale factor for each channel (NCHAN*NPOL)

Return type:

numpy.ndarray

read_offsets(isub)

Read channel data offset (DAT_OFFS) column from the SUBINT table.

Parameters:

isub (int) – index of row (subint) to read from the SUBINT table

Returns:

Data offset for each channel (NCHAN*NPOL)

Return type:

numpy.ndarray