************************************* :mod:`plot` --- Graphical facilities ************************************* .. module:: plot :synopsis: 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 :class:`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 :class:`matplotlib.axes.Axes` instance to be used by the chart or ``None`` to create a new window. Functions ========= .. function:: 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. .. function:: 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. .. function:: 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 :mod:`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.