3. plot — Graphical facilities

Functions in this module produce charts. When called by themselves, they will create their own window. Another way to invoke them is by creating a new matplotlib figure, adding a subplot to it and passing the reference to that matplotlib.axes.Axes object as the axes parameter to the chart functions in this module, which will embed the resulting chart into the figure:

import matplotlib.pyplot as plt

fig = plt.figure()
ax1 = fig.add_subplot(111)
actogram(..., axes=ax1)
plt.show()

The common set of input parameters for each of the functions is this:

dataset

A dataset object (e.g. an instance of readdata.CSVReader).

key

The measurement variable you want to plot.

start

A datetime value. Samples from dataset with earlier dates will be ignored.

end

Also a datetime value indicating the latest value that should be included.

axes

Either a matplotlib.axes.Axes instance to be used by the chart or None to create a new window.

3.1. Functions

plot.activity_dist(dataset, key[, start[, end[, axes[, cumulative[, nozeros]]]]])

This function plots the distribution of values in the raw data. Each vertical line represents the distribution of values on a particular day. They absolute value of a point is its y coordinate and the associated density is coded by the color.

cumulative

A boolean value. If True, the color of a pixel indicates which percentage of values is less or equal than its y coordinate. If False, the probability mass of samples with this exact value will be mapped instead.

nozeros

Also a boolean parameter which specifies, whether zero-valued samples should be excluded or not. Excuding them might be useful since they usually make up a large percentage of the dataset and dwarf all other values.

plot.actogram(dataset, key[, start[, end[, axes[, width[, cmap[, sunlines[, bgcolor[, colorbar]]]]]]]])

The actogram displays the dataset contents as a two-dimensional map, with dates increasing from top to bottom and the daytime from left to right. Optionally, the times when the sun reached certain altitudes on each day in the chart’s time range can be added as an overlay.

width

A number specifying how many days should be displayed in each line. The default value is 1, for a double plot set it to 2.

cmap

The name of matplotlib colormap to be used. The default one is "gnuplot2_r", for a black-and-white palette use "binary".

sunlines

A list of dictionaries containing parameters the sun positions. Following entries can be present:

"rising"

Since the sun crosses a given twice on any day (or not at all), once before noon while it’s rising and the second time after, you have to state which half of the day you are interested in. Set "rising" to True for the morning and to False for the evening.

"angle"

The angular offset in degrees from the horizon downward. For example, for the start of civil twilight you would set "rising" to True and "angle" to 6.0. Negative values, meaning that the sun is above horizon, are also accepted.

"minutes"

A temporal offset from the moment described by "rising" and "angle". To add a line at 30 minutes after sunset, set "rising" to False and "minutes" to 30.

"style"

Another dictionary containing any key-value pairs valid for matplotlib.lines.Line2D.

To draw a 2 pixel wide black line with 50% opacity one hour after the beginning of the nautical morning twilight, the sunlines parameter would look like this:

sunlines = [{'rising': True,
             'angle': 12,
             'minutes': 60,
             'style': {
                 'color': 'black',
                 'linewidth': 2.0,
                 'alpha': 0.5
             }
           }]
actogram(..., sunlines=sunlines)

bgcolor

The color used to paint the background. If set to a contrasting color easily distinguishable from the cmap, it’s an easy way to reveal gaps in the data.

colorbar

A boolean parameter defining whether to display the colorbar or not.

plot.spectrogram(dataset, key[, start[, end[, axes[, ndays[, nfreq[, ofac[, onlysig[, alpha[, silent[, noplot]]]]]]]]]])

This function calculates and plots a Lomb-Scargle spectrogram of the data (see fasper). It also returns the raw data of the spectrum as a 2D array. Each line is a separate spectrum of a window ndays long. From one line to another the window is shifted by one day, i.e. one day is removed from the beginning and another one is appended at the end.

The number of frequencies returned in the spectrum is defined by nfreq. The x axis is labeled with plain numbers representing the frequencies relative to the chosen window length (ndays). Using a data window of one week (ndays = 7), frequency number 1 has a period length of 7 days, frequency number 14 of (7 days / 14) = 12 hours, etc.

ndays

Numerical parameter specifying the length of data window in days.

nfreq

Total number of frequencies to calculate, i.e. the number of columns.

ofac

“Oversampling factor”, used to increase the frequency resolution, but will also lead to a reduction of the maximum returned frequency. With an ofac value of 2 and ndays = 7, the frequency representing 24 h will shift from position 7 to position 14.

onlysig

A boolean parameter; if set to True only those frequencies will be plotted whose error probability is below alpha.

alpha

Error level for onlysig. The default value is 0.05.

silent

Since the calculation takes quite a while, in its course the current date window is printed to give you an indication of process. If you would rather prefer the function not to flood the output, you can set this parameter to True.

noplot

The plotted spectrum can also be captured as the function’s return value. If you only need the spectrum and not the chart, setting noplot to True will achieve this effect.