DADA

Distributed Acquisition and Data Analysis (DADA) format data files contain a single data frame consisting of an ASCII header of typically 4096 bytes followed by a payload. DADA is defined by its software specification and actual usage; files are described by an ASCII header.

Usage

This section covers reading and writing DADA files with Baseband; general usage is covered in the Using Baseband section. For situations in which one is unsure of a file’s format, Baseband features the general baseband.open and baseband.file_info functions, which are also discussed in Using Baseband. The examples below use the sample file baseband/data/sample.dada, and the the astropy.units and baseband.dada modules:

>>> from baseband import dada
>>> import astropy.units as u
>>> from baseband.data import SAMPLE_DADA

Single files can be opened with open in binary mode. DADA files typically consist of just a single header and payload, and can be read into a single DADAFrame.

>>> fb = dada.open(SAMPLE_DADA, 'rb')
>>> frame = fb.read_frame()
>>> frame.shape
(16000, 2, 1)
>>> frame[:3].squeeze()
array([[ -38.-38.j,  -38.-38.j],
       [ -38.-38.j,  -40. +0.j],
       [-105.+60.j,   85.-15.j]], dtype=complex64)
>>> fb.close()

Since the files can be quite large, the payload is mapped (with numpy.memmap), so that if one accesses part of the data, only the corresponding parts of the encoded payload are loaded into memory (since the sample file is encoded using 8 bits, the above example thus loads 12 bytes into memory).

Opening in stream mode wraps the low-level routines such that reading and writing is in units of samples, and provides access to header information:

>>> fh = dada.open(SAMPLE_DADA, 'rs')
>>> fh
<DADAStreamReader name=... offset=0
    sample_rate=16.0 MHz, samples_per_frame=16000,
    sample_shape=SampleShape(npol=2), bps=8,
    start_time=2013-07-02T01:39:20.000>
>>> d = fh.read(10000)
>>> d.shape
(10000, 2)
>>> d[:3]
array([[ -38.-38.j,  -38.-38.j],
       [ -38.-38.j,  -40. +0.j],
       [-105.+60.j,   85.-15.j]], dtype=complex64)
>>> fh.close()

To set up a file for writing as a stream is possible as well:

.. doctest-requires:: posix
>>> from astropy.time import Time
>>> fw = dada.open('{utc_start}.{obs_offset:016d}.000000.dada', 'ws',
...                sample_rate=16*u.MHz, samples_per_frame=5000,
...                npol=2, nchan=1, bps=8, complex_data=True,
...                time=Time('2013-07-02T01:39:20.000'))
>>> fw.write(d)
>>> fw.close()
>>> import os
>>> [f for f in sorted(os.listdir('.')) if f.startswith('2013')]
['2013-07-02-01:39:20.0000000000000000.000000.dada',
 '2013-07-02-01:39:20.0000000000020000.000000.dada']
>>> fr = dada.open('2013-07-02-01:39:20.{obs_offset:016d}.000000.dada', 'rs')
>>> d2 = fr.read()
>>> (d == d2).all()
True
>>> fr.close()

Here, we have used an even smaller size of the payload, to show how one can define multiple files. DADA data are typically stored in sequences of files. If one passes a time-ordered list or tuple of filenames to open, it uses sequentialfile.open to access the sequence. If, as above, one passes a template string, open uses DADAFileNameSequencer to create and use a filename sequencer. (See API links for further details.)

Further details

Reference/API

baseband.dada Package

Distributed Acquisition and Data Analysis (DADA) format reader/writer.

Functions

info(name, **kwargs)

Collect DADA file information.

open(name[, mode])

Open DADA file(s) for reading or writing.

Classes

DADAFileNameSequencer(template[, header])

List-like generator of DADA filenames using a template.

DADAFrame(header, payload[, valid, verify])

Representation of a DADA file, consisting of a header and payload.

DADAHeader(*args[, verify, mutable])

DADA baseband file format header.

DADAPayload(words, *[, header, ...])

Container for decoding and encoding DADA payloads.

Class Inheritance Diagram

Inheritance diagram of baseband.dada.base.DADAFileNameSequencer, baseband.dada.frame.DADAFrame, baseband.dada.header.DADAHeader, baseband.dada.payload.DADAPayload

baseband.dada.header Module

Definitions for DADA pulsar baseband headers.

Implements a DADAHeader class used to store header definitions in a FITS header, and read & write these from files.

The DADA headers are described in the DADA software specification, at http://psrdada.sourceforge.net/manuals/Specification.pdf

See also DADA Headers.

Classes

DADAHeader(*args[, verify, mutable])

DADA baseband file format header.

Class Inheritance Diagram

Inheritance diagram of baseband.dada.header.DADAHeader

baseband.dada.payload Module

Payload for DADA format.

Classes

DADAPayload(words, *[, header, ...])

Container for decoding and encoding DADA payloads.

Class Inheritance Diagram

Inheritance diagram of baseband.dada.payload.DADAPayload

baseband.dada.frame Module

Classes

DADAFrame(header, payload[, valid, verify])

Representation of a DADA file, consisting of a header and payload.

Class Inheritance Diagram

Inheritance diagram of baseband.dada.frame.DADAFrame

baseband.dada.base Module

Functions

open(name[, mode])

Open DADA file(s) for reading or writing.

info(name, **kwargs)

Collect DADA file information.

Classes

DADAFileNameSequencer(template[, header])

List-like generator of DADA filenames using a template.

DADAFileReader(fh_raw)

Simple reader for DADA files.

DADAFileWriter(fh_raw)

Simple writer/mapper for DADA files.

DADAStreamBase()

Provides sample shape maker and fast index getting/setting.

DADAStreamReader(fh_raw[, squeeze, subset, ...])

DADA format reader.

DADAStreamWriter(fh_raw, header0[, squeeze])

DADA format writer.

Class Inheritance Diagram

Inheritance diagram of baseband.dada.base.DADAFileNameSequencer, baseband.dada.base.DADAFileReader, baseband.dada.base.DADAFileWriter, baseband.dada.base.DADAStreamBase, baseband.dada.base.DADAStreamReader, baseband.dada.base.DADAStreamWriter