The base modules¶

The core and burst modules form the basis of the AmsterDM package. The core module contains a set of practical functions to dedisperse data, calculate a dynamic spectrum, a light curve or a bow-tie plot, while the burst module contains a Burst class that provides a more object-oriented interface to the data, packing all necessary details into a single Burst instance.

The core module¶

The core module contains a set of functions that act on data as two- or three-dimensional NumPy arrays representing the actual data. The frequencies and sampling interval are also input, as are the dispersion measure and an optional dedispersion reference frequency. Some functions require a dispersion measure interval, such as those for creating the data for a bow-tie plot or for estimating and fitting signal-to-noise data. Details for each function are in the API documentation.

The data NumPy array uses (time) samples for the first axis and channel (frequency) for the last axis. For a two-dimensional array, these are the only axes; for a three-dimensional array, the center axis is for the polarization channels. The latter can be of size 1, in which case it is assumed to be Stokes I and is equivalent to a two-dimensional array; size 2, which assumes xx and yy polarization channels; and size 4, which assumes Stokes I, Q, U and V polarization channels. For xx-yy polarization, some functions will correct (dedisperse and bandpass-normalize) the channels individually, then add them together, to produce, for example, a dynamic spectrum or a light curve. For a set of four-Stokes channels, only the first channel is used and Q, U and V are simply ignored.

The frequency input is a one-dimensional list or array that matches the frequency axis of the input data. The sampling interval is a simple float, while the optional reference frequency is also a float. The dispersion measure is a float, while any interval is a tuple or list of two floats, start and end.

All values, except for the data array itself, can (and preferably should have) units attached to them. This can be done with astropy.units, which is used under the hood. This ensures correct interpretation of input values, so that no mistakes between, e.g., seconds and milliseconds are made. If no units are given, frequencies are assumed to be in megahertz (MHz), sampling time in milliseconds (ms) and dispersion measure in cm^-3 pc. For the latter, a constant exists that is this exact unit, amsterdm.constants.DMUNIT.

The burst module¶

The burst module wraps the above functionality into a Burst class that keeps track of the data, frequencies, sampling time and other details. It is usually created from an input data file, either with the Burst.fromfile class method or with the basic open() function. The header of the file should provide enough input to automatically set the frequencies and sampling time correctly, but sometimes manual adjustment may be needed.

When using the open() function for reading a data file, this can be used as a context manager with the with statement, e.g.

with open("somefile.dat") as burst:
    ...  # execute code with burst

Sample time and frequency information for a Burst instance is not set directly with a frequency array, but through specific attributes (corresponding to somewhat standard header keywords). These are

tsamp for the sample time interval. If no unit is given, milliseconds are assumed.
tstart for the starting date-time point of the first sample. If not unit is given, days are assumed.
fch1 for the frequency of the first channel. If no unit is given, MHz is assumed.
foff for the offset between individual channels. This can be negative. If no unit is given, MHz is assumed.
fanchor for the anchoring point of the first frequency fch1. That is, "mid" for the center of the channel, "bottom" for the lower-frequency side of the channel (even with a negative foff) and "top" for the upper-frequency side of the channel.

The above properties can be read and set. The following properties are intended to be read-only:

times is an array of timestamps of the samples, using tsamp and tstart.
reltimes is an array of timestamps of the samples, assuming 0 for the first sample, in seconds.
freqs is an array of frequencies matching the channels, using fch1, foff and fanchor.
cfreq is the central frequency, essentially the midpoint of freqs.

Burst core and plotting methods¶

A Burst instance has methods that match the core functions, without the need to supply the data, frequencies and sampling interval manually, as this is part of the Burst instance.

Similarly, there are various plotting routines available as methods. These routines don’t directly create the figure; that is, they don’t save a figure to file or open a new window with the plot. Instead, these routines return a tuple of a Matplotlib Figure instance and an Axes instance. This is often enough in a notebook to immediately plot the figure, but in a script, the figure may still need to be saved manually. For example

with open("myburst.dat") as burst:
    fig, ax = burst.waterfall()
    fig.savefig("myburst.png")

would do that.

The plotting methods also take an optional ax keyword argument, that contains a Matplotlib Axes instance to draw on. Otherwise, the figure and axes are created on the fly inside the method.

Existing plotting methods are

waterfall creates a waterfall plot (dynamic spectrum plot)
lcplot creates a light curve
bgplot creates a plot with the background summed across the samples, as well as its standard deviation (so background versus frequency)
bowtieplot creates a bow-tie plot
s2nplot creates a signal-to-noise plot, optionally with a Gaussian fit
dmplot creates a combination of a waterfall plot, a light curve and a background plot

The various plotting methods also take a set of keyword arguments for tweaking some aspects of the plots themselves, similar to Matplotlib’s functions. Examples are a color-normalization range (vmin and vmax), logarithmic axes (logscale) or x- and y-labels (xlabel, ylabel). See the examples/plots.py example, or the amsterdm.plot module for more details.