Skip to main content

Python utilities for Breakthrough Listen SETI observations

Project description

Build Status Documentation Status codecov JOSS status

Breakthrough Listen I/O Methods for Python.

Filterbank + Raw file readers

This repository contains Python 2/3 readers for interacting with Sigproc filterbank (.fil), HDF5 (.h5) and guppi raw (.raw) files, as used in the Breakthrough Listen search for intelligent life.


The latest release can be installed via pip directly from this repository:

python3 -m pip install -U

Or, the latest version of the development code can be installed from the github repo and then run python install or pip install . (with sudo if required), or by using the following terminal command:

python3 -m pip install -U

To install everything required to run the unit tests, run:

python3 -m pip install -e .[full]

You will need numpy, h5py, astropy, scipy, and matplotlib as dependencies. A pip install should pull in numpy, h5py, and astropy, but you may still need to install scipy and matplotlib separately. To interact with compressed files, you'll need the hdf5plugin package too.

Note that h5py generally needs to be installed in this way:

$ python3 -m pip install --no-binary=h5py h5py

Command line utilities

After installation, some command line utilities will be installed:

  • watutil, for reading/writing/plotting blimpy filterbank files (either .h5 or .fil format).
  • rawutil, for plotting data in guppi raw files.
  • fil2h5, for converting .fil files into .h5 format.
  • h52fil, for converting .h5 files into .fil format.
  • bldice, for dicing a smaller frequency region from (either from/to .h5 or .fil).
  • matchfils, for checking if two .fil files are the same.

Use the -h flag to any of the above command line utilities to display their available arguments.

Reading blimpy filterbank files in .fil or .h5 format

The blimpy.Waterfall provides a Python API for interacting with filterbank data. It supports all BL filterbank data products; see this example Jupyter notebook for an overview.

From the python, ipython or jupiter notebook environments.

from blimpy import Waterfall
fb = Waterfall('/path/to/filterbank.fil')
#fb = Waterfall('/path/to/filterbank.h5') #works the same way
data =

Reading guppi raw files

The Guppi Raw format can be read using the GuppiRaw class from

from blimpy import GuppiRaw
gr = GuppiRaw('/path/to/guppirawfile.raw')

header, data = gr.read_next_data_block()


from blimpy import GuppiRaw
gr = GuppiRaw('/path/to/guppirawfile.raw')

for header, data_x, data_y in gr.get_data():
    # process data

Note: most users should start analysis with filterbank files, which are smaller in size and have been generated from the guppi raw files.

Using blimpy inside Docker

The blimpy images are pushed to a public repository after each successful build on Travis. If you have Docker installed, you can run the following commands to pull our images, which have the environment and dependencies set up for you.

For python3, use:

docker pull fx196/blimpy:py3_kern_stable

For python2, use:

docker pull fx196/blimpy:py2_kern_stable

Here is a more complete guide on using blimpy in Docker.

Further reading

A detailed overview of the data formats used in Breakthrough Listen can be found in our data format paper. An archive of data files from the Breakthrough Listen program is provided at

If you have any requests or questions, please lets us know!

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for blimpy, version 2.0.2
Filename, size File type Python version Upload date Hashes
Filename, size blimpy-2.0.2-py3-none-any.whl (315.6 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size blimpy-2.0.2.tar.gz (85.0 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page