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.