filtools package

class filtools.FilterbankIO

Bases: object

This class deals with reading from and writing to sigproc filterbank files.

To read a filterbank file, first set up a new FilterbankIO object, and use the read_header() method to read the header parameters. The FilterbankIO object is then ready to be used for reading. To read the file, we use the read_block() method to read samples from the file.

Example:

inputfile = filtools.FilterbankIO()
inputfile.read_header("example.fil")
data = inputfile.read_block(1024) # Reads 1024 samples from the file

Note

Currently FilterbankIO supports sigproc data files with the following properties:

• Single IF (i.e. single polarisation)
• Fixed channel bandwidth (i.e. each channel has same bandwidth/offset)

And, data type is one of:

• 1-bit unsigned integer
• 2-bit unsigned integer
• 4-bit unsigned integer
• 8-bit unsigned integer
• 16-bit unsigned integer
• 32-bit floating point

header

The header dict can be used to provide direct access to the sigproc header parameters. Parameters changed here before calling write_header() can change the ouput header parameters. However, it is usually best to access information about the data using the other methods provided below, as the structure can be re-used for other data types.

bits_per_sample()

Number of bits per sample in data file

centre_frequency()

The centre frequency

channel_bandwidth()

The channel bandwidth.

clone_header()

Create a new FilterbankIO object with the header parameters copied from this object

Returns:A new FilterbankIO object

close()

Close the input file, reset the read/write state of the FilterbankIO object

current_position()

Print the current position of the file pointer in samples.

The next call to read_block() or write_block() will read or write from this sample.

frequency_table()

Get an array of centre frequency of each channel

get_reader()

This method returns a function optimised to read the input data.`

get_writer()

Returns an optimised write function. Used by write_block().

mjd_at_sample(sample)

Get the MJD at given sample number

read_block(nsamples, dtype=<class 'numpy.float32'>)

Read a block of data.

This will read up to nsamples from the file, returning a 2-d array indexed first by sample and then by channel. i.e. the shape of the returned array will be (nsamples_read,nchannels).

If the file has reached the end of file, then less than nsamples will be read, and if past the end of the file, an array of size (0,nchannels) will be returned.

Note

On first call this method is dynamically replaced using get_reader() to define an optimised verison of the reader method. This should be invisiable to most users.

Parameters:

• nsamples – The number of samples to read.
• dtype – A numpy compatible data type. Data will be converted to this type using the astype numpy method, and should be at least large enough to hold the read data types.

Returns:

A 2-d numpy array of requested type.

read_header(filename)

Read header from sigproc filterbank file

Parameters:filename (str) – filename to read Returns:Number of bytes read (i.e. size of header)

This method will also put the FilterbankIO object in a state for reading the file, i.e. enabling the read_block() method.

Header parameters can be accessed by the methods of the FilterbankIO object, or by direct interface with the sigproc API using the header dict member.

reference_dm()

sample_interval()

The time between each sample

seconds_since(sample, mjdref)

Get the number of seconds since mjdref at sample number sample.

Parameters:

• sample – Integer sample number
• refmjd – Reference mjd

Returns:

seconds since mjdref at sample sample

seconds_since_start(sample)

Get the number of seconds since start of observation at sample number sample.

seek_to_sample(sample)

Position the file pointer at given sample number (index from zero).

The next call to read_block() or write_block() will start at the given sample. E.g.

fil.seek_to_sample(100)
block = fil.read_block(128) # block[0] is sample number 100

set_bits_per_sample(*args, **kwargs)

set_frequency_table(*args, **kwargs)

set_reference_dm(*args, **kwargs)

set_sample_interval(*args, **kwargs)

set_total_channels(*args, **kwargs)

total_bytes()

Compute the total number of bytes in the file

total_channels()

The total number of frequency channels in the file

total_samples()

The total number of samples in the file

write_block(block)

Write a block of data to a file opened for writing.

The data block should be a numpy array in the same format as would be obtained from read_block(). The data will be truncated and cast to the required type to write to the file using the ndarray.astype method from numpy.

The block should have shape (nsamples,nchannels), where nsamples is the number of samples to write.

Parameters:block – A 2-d numpy array to write.

Note

On first call this this method is dynamically replaced using get_writer() to define an optimised verison of the writer method. This should be invisiable to most users.

write_header(filename)

Write the current state to a new sigproc filterbank file

Parameters:filename – filename to write Returns:Number of bytes written (i.e. size of header)

This method will also put the FilterbankIO object in a state for writing data to the file, i.e. enabling the write_block() method.

class filtools.FluxScale(scale=1, offset=0)

Bases: object

Helps scaling flux density data to the data format.

This is used either by directly specifying a scale and offset to apply, or by setting a gain and Tsys value, or by specifying physical telescope parameters to define the gain and Tsys.

init(tsamp, bw, npol_avg=2)

Call this once you have set the gain and tsys to set up the scaling.

Parameters:

• tsamp – sample time in seconds.
• bw – channel bandwidth in MHz.
• npol_avg – Number of polarisations that have been averaged already (1 or 2).

set_gain_from_file(file)

Read a yaml file with a telescope definition. Properties are: tsys, n_antenna, diameter, efficiency and/or gain.

set_gain_from_physical(ndish, D, efficiency)

Specify physical parameters to determine gain.

Parameters:

• ndish – Number of antennas
• D – Diameter of each antenna (m).
• efficiency – Efficiency of the observing system (antenna efficiency).

to_file_units(buffer)

Convert from flux density units to file units

to_flux_units(buffer)

Convert from file units to flux density units

class filtools.SimpleIntegerise(thresh=1e-08)

Bases: object

Converts floats to integers assuming previously digitised data had a uniform underlying distribution.

Parameters:thresh – Ignore values below this to improve performance (default 1e-8).

__call__(block)

Convert a block of floating point data to integers.

Subpackages

• filtools.inject_pulsar package
  • Submodules
  • filtools.inject_pulsar.ism_models module
  • filtools.inject_pulsar.phase_models module
  • filtools.inject_pulsar.pulse_models module

Submodules

filtools.sigproc module

class filtools.sigproc.FilterbankIO

Bases: object

This class deals with reading from and writing to sigproc filterbank files.

To read a filterbank file, first set up a new FilterbankIO object, and use the read_header() method to read the header parameters. The FilterbankIO object is then ready to be used for reading. To read the file, we use the read_block() method to read samples from the file.

Example:

inputfile = filtools.FilterbankIO()
inputfile.read_header("example.fil")
data = inputfile.read_block(1024) # Reads 1024 samples from the file

Note

Currently FilterbankIO supports sigproc data files with the following properties:

• Single IF (i.e. single polarisation)
• Fixed channel bandwidth (i.e. each channel has same bandwidth/offset)

And, data type is one of:

• 1-bit unsigned integer
• 2-bit unsigned integer
• 4-bit unsigned integer
• 8-bit unsigned integer
• 16-bit unsigned integer
• 32-bit floating point

header

The header dict can be used to provide direct access to the sigproc header parameters. Parameters changed here before calling write_header() can change the ouput header parameters. However, it is usually best to access information about the data using the other methods provided below, as the structure can be re-used for other data types.

bits_per_sample()

Number of bits per sample in data file

centre_frequency()

The centre frequency

channel_bandwidth()

The channel bandwidth.

clone_header()

Create a new FilterbankIO object with the header parameters copied from this object

Returns:A new FilterbankIO object

close()

Close the input file, reset the read/write state of the FilterbankIO object

current_position()

Print the current position of the file pointer in samples.

The next call to read_block() or write_block() will read or write from this sample.

frequency_table()

Get an array of centre frequency of each channel

get_reader()

This method returns a function optimised to read the input data.`

get_writer()

Returns an optimised write function. Used by write_block().

mjd_at_sample(sample)

Get the MJD at given sample number

read_block(nsamples, dtype=<class 'numpy.float32'>)

Read a block of data.

This will read up to nsamples from the file, returning a 2-d array indexed first by sample and then by channel. i.e. the shape of the returned array will be (nsamples_read,nchannels).

If the file has reached the end of file, then less than nsamples will be read, and if past the end of the file, an array of size (0,nchannels) will be returned.

Note

On first call this method is dynamically replaced using get_reader() to define an optimised verison of the reader method. This should be invisiable to most users.

Parameters:

• nsamples – The number of samples to read.
• dtype – A numpy compatible data type. Data will be converted to this type using the astype numpy method, and should be at least large enough to hold the read data types.

Returns:

A 2-d numpy array of requested type.

read_header(filename)

Read header from sigproc filterbank file

Parameters:filename (str) – filename to read Returns:Number of bytes read (i.e. size of header)

This method will also put the FilterbankIO object in a state for reading the file, i.e. enabling the read_block() method.

Header parameters can be accessed by the methods of the FilterbankIO object, or by direct interface with the sigproc API using the header dict member.

reference_dm()

sample_interval()

The time between each sample

seconds_since(sample, mjdref)

Get the number of seconds since mjdref at sample number sample.

Parameters:

• sample – Integer sample number
• refmjd – Reference mjd

Returns:

seconds since mjdref at sample sample

seconds_since_start(sample)

Get the number of seconds since start of observation at sample number sample.

seek_to_sample(sample)

Position the file pointer at given sample number (index from zero).

The next call to read_block() or write_block() will start at the given sample. E.g.

fil.seek_to_sample(100)
block = fil.read_block(128) # block[0] is sample number 100

set_bits_per_sample(*args, **kwargs)

set_frequency_table(*args, **kwargs)

set_reference_dm(*args, **kwargs)

set_sample_interval(*args, **kwargs)

set_total_channels(*args, **kwargs)

total_bytes()

Compute the total number of bytes in the file

total_channels()

The total number of frequency channels in the file

total_samples()

The total number of samples in the file

write_block(block)

Write a block of data to a file opened for writing.

The data block should be a numpy array in the same format as would be obtained from read_block(). The data will be truncated and cast to the required type to write to the file using the ndarray.astype method from numpy.

The block should have shape (nsamples,nchannels), where nsamples is the number of samples to write.

Parameters:block – A 2-d numpy array to write.

Note

On first call this this method is dynamically replaced using get_writer() to define an optimised verison of the writer method. This should be invisiable to most users.

write_header(filename)

Write the current state to a new sigproc filterbank file

Parameters:filename – filename to write Returns:Number of bytes written (i.e. size of header)

This method will also put the FilterbankIO object in a state for writing data to the file, i.e. enabling the write_block() method.