Adding and modifying layers

On this page, we take a look at all the available plotting features. Let’s start off by creating a simple time series:

[1]:
from astropy import units as u
from astropy.timeseries import TimeSeries
ts = TimeSeries(time_start='2016-03-22T12:30:31', time_delta=3 * u.s, n_samples=10)
ts['flux'] = [10, 11, 9, 10, 2, 3, 5, 12, 11, 10]
ts['error'] = [2, 2.5, 2, 1.5, 2, 2, 1.5, 1.5, 2., 2.5]

Creating an interactive figure

To create an interactive figure, use the InteractiveTimeSeriesFigure class:

[2]:
from aas_timeseries import InteractiveTimeSeriesFigure
fig = InteractiveTimeSeriesFigure()

Note on adding and modifying layers

Before we look at specific examples of layers, let’s take a look at a couple of general patterns. First, interactive plots are defined by a collection of layers (e.g. markers, lines, shaded areas, text) that you can add using fig.add_* methods. These methods take all the arguments that can be used to customize a layer, e.g.:

fig.add_markers(time_series=ts, column='flux', label='Flux', color='red')

The add_* methods typically return an object that can be used to further customize the layer, so the above is equivalent to:

markers = fig.add_markers(time_series=ts, column='flux', label='Flux')
markers.color = 'red'

Second, add_* layers take a label= argument that is used to define the name of the layer as shown in the list of layers (accessible from the top right menu in each interactive plot).

Markers

To add markers, use the add_markers method:

[3]:
markers = fig.add_markers(time_series=ts, column='flux', label='Flux')

We can then use preview_interactive to view the current version of the interactive plot.

[4]:
fig.preview_interactive()

As mentioned above, because we wrote markers =, we can further change the properties of the markers after they have been added to the figure - for example, we can change the marker size:

[5]:
markers.size = 40
fig.preview_interactive()

If you want to show error bars, you can pass the error argument to add_markers, specifying a column to use for the uncertainties, or you can set it on the markers object after the fact:

[6]:
markers.error = 'error'
fig.preview_interactive()
fig.save_vega_json('test_error.json')

Lines

Adding a line is done in a similar way using the add_line method:

[7]:
line = fig.add_line(time_series=ts, column='flux', label='Flux')
[8]:
fig.preview_interactive()

Note that by using the same label as for the markers and error bars, this layer combined with the markers will appear as a single entry in the figure legend. As for markers, the returned line object can be used to update properties of the line, e.g.:

[9]:
line.width = 2
fig.preview_interactive()

Vertical and horizontal lines

In some cases it can be useful to indicate specific points in time with vertical lines, or certain y-axis values with horizontal lines. These can be added with the add_vertical_line and add_horizontal_line methods:

[10]:
vertical_line = fig.add_vertical_line(ts.time[5], label='Special event')
horizontal_line = fig.add_horizontal_line(10, label='Baseline flux')
[11]:
fig.preview_interactive()

Ranges

There are three kinds of ranges that can be added to plots. First, if your time series has columns that can serve as the lower and upper values for a range as a function of time. Let’s create two such columns to demonstrate:

[12]:
ts['flux_lo'] = ts['flux'] - ts['error']
ts['flux_hi'] = ts['flux'] + ts['error']

And we can now plot a time-dependent range using add_range:

[13]:
frange = fig.add_range(time_series=ts, column_lower='flux_lo',
                       column_upper='flux_hi', label='Range')
fig.preview_interactive()

It is also possible to define horizontal and vertical ranges in a similar way to horizontal and vertical lines using add_vertical_range and add_horizontal_range:

[14]:
vrange = fig.add_vertical_range(ts.time[4], ts.time[6], label='Vertical Range')
hrange = fig.add_horizontal_range(8, 11, label='Horizontal Range')
[15]:
fig.preview_interactive()

Text labels

Text labels can be added using the add_text method:

[16]:
text = fig.add_text(time=ts.time[1], value=5, text='Here be dragons', label='Text')
[17]:
fig.preview_interactive()

Removing layers

To remove a layer, call its remove method:

[18]:
text.remove()
[19]:
fig.preview_interactive()