Reading and writing frequency-domain data

The FrequencySeries object includes read() and write() methods to enable reading from and writing to files respectively. For example, to read from an ASCII file containing frequency and amplitude columns:

>>> data = FrequencySeries.read('my-data.txt')

The format keyword argument can be used to manually identify the input file-format, but is not required where the file extension is sufficiently well understood.

The read() and write() methods take different arguments and keywords based on the input/output file format, see the following sections for details on reading/writing for each of the built-in formats. Those formats are:

ASCII

GWpy supports writing FrequencySeries data to ASCII in a two-column frequency and amplitude format.

Reading

To read a FrequencySeries from ASCII:

>>> t = FrequencySeries.read('data.txt')

See numpy.loadtxt() for keyword argument options.

Writing

To write a FrequencySeries to ASCII:

>>> t.write('data.txt')

See numpy.savetxt() for keyword argument options.

HDF5

GWpy allows storing data in HDF5 format files, using a custom specification for storage of metadata.

Reading

To read FrequencySeries data held in HDF5 files pass the filename (or filenames) or the source, and the path of the data inside the HDF5 file:

>>> data = FrequencySeries.read('data.h5', 'psd')

Writing

Data held in a FrequencySeries can be written to an HDF5 file via:

>>> data.write('output.hdf', 'psd')

If the target file already exists, an IOError will be raised, use overwrite=True to force a new file to be written.

To add a FrequencySeries to an existing file, use append=True:

>>> data.write('output.h5', 'psd2', append=True)

To replace an dataset in an existing file, while preserving other data, use both append=True and overwrite=True:

>>> data.write('output.h5', 'psd', append=True, overwrite=True)

LIGO_LW XML

Additional dependencies: python-ligo-lw

Alongside storing tabular data, the LIGO_LW XML format allows storing array data. These arrays are stored in <LIGO_LW> elements, which describe the metadata for an array (name, GPS epoch, instrument, etc.), which contain an <Array> element that contains the actual data values.

Note

For more information on the format and the parsing library, see ligo.lw.array.

Reading

To read a FrequencySeries from a LIGO_LW XML file:

>>> data = FrequencySeries.read('data.xml')

If the file contains multiple <Array> elements, you will have to provide additional keyword arguments to select which element to use:

Keyword arguments for FrequencySeries.read with LIGO_LW format

Keyword

Type

Default

Usage

name

str

None

Name of <Array> element to read

epoch

int

None

GPS value of the <Time> element that is the sibling of the desired <Array>

<Param Name>

Other kwargs can be given as the Name of a <Param> element that is the sibling of the desired <Array>, and its value

For example:

>>> data = FrequencySeries.read("psd.xml.gz", name="H1")
>>> data = FrequencySeries.read("psd.xml.gz", epoch=1241492407, f0=0, instrument="H1")

Writing

Writing FrequencySeries to LIGO_LW XML files is not supported, but a contribution that implements this would be welcomed.