## plott

Plot sensor time series against time in a single or multi-paneled figure with linked x-axes.

## Syntax

[ax,h]=plott(varargin) % Matlab & Octave plott(X, fsx=NULL, r=FALSE, offset=0, date_time_axis=TRUE, recording_start=NULL, panel_heights=rep.int(1, length(X)), panel_labels=names(X), line_colors, interactive=FALSE, par_opts, ...) #R

## Description

Plot sensor time series against time in a single or multi-paneled figure with linked x-axes. This is useful for comparing measurements across different sensors. The time axis is automatically displayed in seconds, minutes, hours, or days according to the span of the data.

## Inputs

#### Matlab & Octave

Input var | Description | Units | Default value |
---|---|---|---|

X, Y, etc. | are sensor structures or vectors/matrices of time series data. | N/A | N/A |

fsx, fsy, etc. | are the sampling rates in Hz for each data object. Sampling rates are not needed when the data object is a sensor structure. | Hz | N/A |

r | is an optional argument which has several uses: If r='r', the direction of the y-axis is reversed for the data object being plotted. This is useful for plotting dive profiles which match the physical situation i.e., with greater depths lower in the display. Note that 'r' is the default for a sensor structure if the axes field has a value of 'D' for down. If r='i', the preceding data is taken as irregularly sampled. The data must have at least 2 columns with the first one being the sampling times. In this case, data are plotted as single points rather than a continuous line. If r is a number, it specifies the number of seconds time offset for the preceding data object. A positive value means that these data were collected later than the other objects and so should be plotted more to the right-hand side. Note that the correct time offset is automatically used if the input is a sensor structure with a start_offset field. | N/A | N/A |

#### R

Input var | Description | Units | Default value |
---|---|---|---|

X | List whose elements are either lists (containing data and metadata) or vectors/matrices of time series data. See details. | N/A | N/A |

fsx | (Optional) A numeric vector whose length matches the number of sensor data streams (list elements) in X. (If shorter, fsx will be recycled to the appropriate length). fsx gives the sampling rate in Hz for each data object. Sampling rates are not needed when the data object(s) X are list(s) that contain sampling rate information – and beware, because fsx (if given) will override sensor metadata. | Hz | N/A |

r | (Optional) Logical. Should the direction of the y-axis be flipped? Default is FALSE. If r is of length one (or shorter than the number of sensor data streams in X) it will be recycled to match the number of sensor data streams.data object that it follows if r='r'. Reversed y-axes are useful, for example, for plotting dive profiles which match the physical situation (with greater depths lower in the display). If r is a number, it specifies the number of seconds time offset for the preceding data object. | Logical | FALSE |

offset | (Optional) A vector of offsets, in seconds, between the start of each sensor data stream and the start of the first one. For example, if acceleration data collection started and then depth data collection commenced 436 seconds later, then the offset for the depth data would be 436. | N/A | N/A |

date_time_axis | (Optional) Logical. Should the x-axis units be date-times rather than time-since-start-of-recording? Ignored if \code{recording_start} is not provided and X does not contain metadata on recording start time. Defaults is TRUE. | Logical | TRUE |

recording_start | (Optional) The start time of the tag recording as a POSIXct object. If provided, the time axis will show calendar date/times; if not, it will show days/hours/minutes/seconds (as appropriate) since time 0 = the start of recording. If a character string is provided it will be coerced to POSIXct with as.POSIXct. | N/A | N/A |

panel_heights | (Optional) A vector of relative or absolute heights for the different panels (one entry for each sensor data stream in X). Default is equal-height panels. If panel_heights is a numeric vector, it is interpreted as relative panel heights. To specify absolute panel heights in centimeters using lcm (see help for graphics::layout). | N/A | N/A |

panel_labels | (Optional) A list of y-axis labels for the panels. Defaults to names(X). | N/A | names(X) |

interactive | (Optional) Should an interactive figure (allowing zoom/pan/etc.) be produced? Default is FALSE. Interactive plotting requires the zoom package for its zoom::zm function. | Logical | FALSE |

par_opts | (Optional) A list of options to be passed to graphics::par before plotting. Default is mar=c(1,5,0,0), oma=c(2,0,2,1), las=1, lwd=1, cex=0.8. | N/A | N/A |

line_colors | (Optional) A list of colors for lines for multivariate data streams (for example, if a panel plots tri-axial acceleration, it will have three lines – their line colors will be the first three in this list). May be specified in any specification R understands for colors. Defaults to c(“#000000”, “#009E73”, “#9ad0f3”, “#0072B2”, “#e79f00”, “#D55E00”) | N/A | N/A |

… | Additional arguments to be passed to plot. | N/A | N/A |

## Outputs

Output var | Description | Units |
---|---|---|

ax | is a vector of handles to the axes created in Matlab or Octave. There is no numeric return for R | N/A |

h | is a cell array of vectors of handles to the lines plotted in Matlab or Octave. There is a cell of handles for each axis. There is no numeric return for R | N/A |

## Notes & assumptions

- Matlab & Octave: r is useful for plotting dive profiles which match the physical situation i.e., with greater depths lower in the display. If r is a number, it specifies the number of seconds time offset for the preceding data object. A positive value means that these data were collected later than the other objects and so should be plotted more to the right-hand side.
- This is a flexible plotting tool which can be used to display and explore sensor data with different sampling rates on a uniform time grid. Zooming any of the panels should cause all of the panels to zoom in or out to match the x-axis.

## Example

### Matlab & Octave

The example below uses data from the file testset1.nc. You can download it from the animaltags website's example data sets. If the file is saved in your current working directory, load it via:

testset1 = load_nc(‘testset1.nc’)

plott(testset1.P.data, testset1.P.sampling_rate, 'r', testset1.A.data, testset1.A.sampling_rate)

### R

The example below uses data from the file testset1.nc. You can download it from the animaltags website's example data sets. If the file is saved in your current working directory, load it via:

testset1 <- load_nc(‘testset1.nc’)

list <- list(depth = testset1$P$data, A = testset1$A$data) plott(list, testset1$P$sampling_rate, r = c(TRUE, FALSE))

## About

bugs@animaltags.org Last modified: 27 July 2017