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: igwn-ligolw

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 igwn_ligolw.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.