VDIF Header

⚠️ WARNING: this software is in a pre-release state. Installation can only be done by downloading and running as a local module, and test coverage is not guaranteed.

A simple Python library for parsing and validating the format and values of VDIF¹ headers in radio telescope data files.

When you work in the domain of VLBI astronomy or space domain awareness, you are forever relying on large binary data files which are difficult to examine. So whenever you work on software that interprets it, you have to wonder every time it crashes whether it is the software or you.

With this library, it's quick to inspect header values and you'll see printed warnings whenever something's awry. It's great for when you want to quickly check why mark5access is yelling at you, but if you need the actual frame content—or want to do more complex stuff with VDIF data in Python—you probably want to use baseband instead.

Usage

This shows minimal working examples for different usage modes. For more detailed usage information, see the vdifheader documentation.

As a Package

When imported as a package, users have access to two main methods:

• get_first_header(input_filepath) - method returns the first header in the provided file as a VDIFHeader object.
• get_headers(input_filepath, count=None) - iterator method returns the first count headers in the provided file, as a iterator² of VDIFHeader objects. If count is negative, zero or None, default behaviour is to parse all headers found in the file.

🧠 REMEMBER: Python iterators are very fast for large input, but are consumed if operated on. So if you write output = some_iterator() and then iterate over output (e.g. for item in output), the output will now be empty.

import vdifheader as vh

input_filepath = './some_input_file.vdif'

# get some headers
headers = vh.get_headers(input_filepath, count=5) # as iterator (fast)
headers_list = list(headers) # as list (sticks around)
for header in headers_list:
    header.print_summary()

# do stuff with a header
first_header = headers_list[0]
timestamp = first_header.get_timestamp()
print(f"\n\nParsed {len(headers_list)} starting at: {timestamp}")
print(f"Source station: {first_header.get_station_information()}")

# export its values somewhere
first_header.to_csv(output_filepath='./some_input_file_vdif.csv')

Output:

ERROR: unassigned_field value should always be 0.
WARNING: vdif_version value > 1 not recognised.

Parsed 5 starting at: 2021-09-21 04:20:00+00:00
Source station: Moprah, Australia

As a Script

When run as a script, simply specify a file to validate and any additional configuration options. Options include:

• show usage/help
• parse only a certain number of headers
• show output in a certain format

% python -m vdifheader -h
usage: vdifheader [-h] [-n NUM | -a] [-v | -b] INPUT_FILE

Parse and validate VDIF headers

positional arguments:
  INPUT_FILE

optional arguments:
  -h, --help           show this help message and exit
  -n NUM, --count NUM  number of headers to parse
  -a, --all            parse all headers in file
  -v, --values         show values output
  -b, --binary         show raw binary output
%
% python -m vdifheader some_input_file.vdif
ERROR: unassigned_field value should always be 0.
WARNING: vdif_version value > 1 not recognised.

As an Interactive Script

When passing -i to the Python interpreter, the provided script will run but leave the interpreter open afterwards for the user to continue the session with variable memory and declarations intact. In this mode, after completion of the script, the following values will be set:

• first_header - the first header parsed from the provided file.
• headers - a list of all headers parsed from the provided file.

% python -i -m vdifheader --count 5 some_input_file.vdif
ERROR: unassigned_field value should always be 0.
WARNING: vdif_version value > 1 not recognised.
>>> first_header.station_id
Mp
>>> len(headers)
5

For detailed usage information, see the vdifheader documentation.

License

This project is licensed under the terms of the GNU General Public License, version 3. This is a copyleft license.

Planned Improvements

• Handling of Extended Data fields.
• Write values back to valid binary header of type bytes.
• Output header values to formats such as iniFile/csv/json/dict.
• Populate appropriate README.rst and requirements.txt to index a 1.0 on PyPi.

Footnotes

1. VLBI Data Interchange Format (source: vlbi.org) ↩

2. Iterators in Python are a type of method that generates a result, rather than returns a result. For operating over potentially large input, this means not waiting for the whole thing to be loaded into memory before starting work (see: wiki.python.org). ↩