nenupytf.read.spectrum

Spectrum

The read module contains two main object classes, namely Lane and Spectrum. Both are aiming at easy data selection from NenuFAR/UnDySPuTeD binary files, which are created one for each lane of the backend, depending on the observation setup.

The former is working at the lowest file level, hence handling NenuFAR/UnDySPuTeD files independently from one another.

Spectrum is a higher level object class, able to work on different files from a given observation. Therefore, if for example, a particular observed beam is spread over two lane files (each one covering half of the frequency bandwidth), a full frequency selection would return data gathered from those two files. To do so, Spectrum first determine which files are encompassing the data selection and then calls for Lane to perform the refined selection.

Initialization

The Spectrum object needs to be provided with a path to an observation directory, for e.g., '/path/to/observation', by default the current directory is used.

>>> from nenupytf.read import Spectrum
>>> spectrum = Spectrum('/path/to/observation')

Data selection

High-rate time-frequency data can be selected among different parameters (handled as attributes of the class Spectrum), namely: Spectrum.beam, Spectrum.time and Spectrum.freq. These attributes can also be set while they are passed as keyword arguments in Spectrum.select() and Spectrum.average().

Observation parameters can be quickly displayed to ease the parameter selection thanks to info():

>>> spectrum.info()

Polyphase filter correction

Reconstructed sub-bands may not display a flat bandpass due to polyphase filter response. It may be usefull to correct for this effect and reduce dynamic spectra artefacts.

Several correction options are available, set by user at the Spectrum.select() and Spectrum.average() function levels with the bp_corr keyword. By default, this keyword is set to bp_corr=True to apply a precomputed correction. The default option is pretty fast to apply and is convenient in most situations although it may leave smal artefacts at the sub-band edges. Same kind of artefacts are present if bp_corr='fft', however the computation time is increased as the sub-band bandpasses are corrected within the Fourier domain. bp_corr='median' correction allows for most reduced aretfacts. However, the latter may significantly alter the signal if the dynamic spectrum is not relatively smooth, use with caution!

class nenupytf.read.spectrum.Spectrum(directory='')[source]

Bases: nenupytf.read.obsrepo.ObsRepo

Spectrum is the class designed to work with several lane files from the UnDySPuTeD backend. Once instanciated, a Spectrum object has a view of all file informations within the directory. This means that a selection may involve several lane files to search for data, regardless of the lane index.

Parameters:directory (str, optional) – Directory where observation files are stored
Example: 
>>> from nenupytf.read import Spectrum
>>> s = Spectrum('/path/to/observation/')
average(stokes='I', df=1.0, dt=1.0, bp_corr=True, **kwargs)[source]

Average in time and frequency NenuFAR/UnDySPuTeD high rate time-frequency data.

Data are read by time blocks of size dt before averaging by computing the mean over time. Then, the spectrum is rebinned to a reconstructed frequency axis with spaces around df.

Parameters:
  • stokes (str, optional) – Stokes parameter value to convert raw data to, allowed values are {'I', 'Q', 'U', 'V', 'fracV', 'XX', 'YY'}, defaults to 'I'
  • df (int, float, optional) – Frequency resolution in MHz on which the averaging is performed, defaults to 1.
  • dt (int, float, optional) – Time resolution in seconds on which the average is performed, defaults to 1.
  • bp_corr (bool, str, optional) –

    Compute the bandpass correction, defaults to True, possible values are

    • False: do not compute any correction
    • True: compute the correction with Kaiser
      coefficients
    • 'median': compute a medianed correction
    • 'fft': correct the bandpass using FFT
  • **kwargs – See below for keyword arguments:
  • freq (list, optional) – Frequency range in MHz passed as a lenght-2 list.
  • time (list, optional) – Time range in ISOT or ISO format passed as a length-2 list.
  • beam (int, optional) – Beam index.
Returns:

SpecData object, embedding the stacked averaged spectra
Return type:

SpecData
Example: 
>>> from nenupytf.read import Spectrum
>>> s = Spectrum('/path/to/observation/')
>>> spec = s.average(
        time=['2019-10-03 14:30:00', '2019-10-03 18:31:01.34'],
        freq=[34.5, 40],
        dt=0.01,
        df=0.5,
        stokes='I'
    )

See also

select() SpecData

Warning

This may take a significant time to process depending on the time and frequency ranges and the required time and frequency resolution.

beam

Beam selection.

This attribute can be set either directly or via specific keyword arguments in select() and average().

Default value is 0.

Setter:Beam index
Getter:Beam index
Type:int
Example: 
>>> from nenupytf.read import Spectrum
>>> s = Spectrum('/path/to/observation/')
>>> s.beam = 1
freq

Frequency range selection.

This attribute can be set either directly or via specific keyword arguments in select() and average().

Default value is [obs_fmin, obs_fmax]

Setter:Length-2 list defining the selected frequency range: [freq_min, freq_max] where freq_min and freq_max are in MHz
Getter:Frequency range
Type:list
Example: 
>>> from nenupytf.read import Spectrum
>>> s = Spectrum('/path/to/observation/')
>>> s.freq = [54, 66]
select(stokes='I', bp_corr=True, **kwargs)[source]

Select among the data stored in the directory according to a Spectrum.time range, a Spectrum.freq range and a Spectrum.beam index and return them converted in the chosen Stokes parameter. NenuFAR-TF data can be spread over several lane files. This will select the data nonetheless and concatenate what is needed to ouptut a single SpecData object.

This may be usefull to call for ObsRepo.info() method prior to select the data in order to know the time and frequency boundaries of the observation as well as recorded beam indices.

Parameters:
  • stokes (str, optional) – Stokes parameter value to convert raw data to, allowed values are {'I', 'Q', 'U', 'V', 'fracV', 'XX', 'YY'}, defaults to 'I'
  • bp_corr (bool, str, optional) –

    Compute the bandpass correction, defaults to True, possible values are

    • False: do not compute any correction
    • True: compute the correction with Kaiser

    coefficients * 'median': compute a medianed correction * 'fft': correct the bandpass using FFT

  • **kwargs – See below for keyword arguments:
  • freq (list, optional) – Frequency range in MHz passed as a lenght-2 list.
  • time (list, optional) – Time range in ISOT or ISO format passed as a length-2 list.
  • beam (int, optional) – Beam index.
Returns:

SpecData object, embedding the stacked averaged spectra
Return type:

SpecData
Example: 
>>> from nenupytf.read import Spectrum
>>> s = Spectrum('/path/to/observation/')
>>> spec = s.select(
        time=['2019-10-03 14:30:00', '2019-10-03 14:30:10.34'],
        freq=[34.5, 40],
        stokes='I'
    )

See also

average() SpecData

Warning

This may take a significant time to process depending on the time and frequency ranges.

time

Time range selection.

This attribute can be set either directly or via specific keyword arguments in select() and average().

Default value is [obs_tmin, obs_tmax]

Setter:Length-2 list defining the selected time range: [time_min, time_max] where time_min and time_max are in ISO/ISOT formats
Getter:Time range
Type:list
Example: 
>>> from nenupytf.read import Spectrum
>>> s = Spectrum('/path/to/observation/')
>>> s.time = ['2019-10-03 14:30:00', '2019-10-03 18:31:01.34']