plot_variable {Rtrack}

Plot path metrics.

Description

Plots the metrics that have been calculated from path coordinates.

Usage

plot_variable(
  variable,
  experiment,
  factor = NA,
  factor.colours = "auto",
  x.axis = NA,
  type = NA,
  point.type = NA,
  transparency = 0.25,
  exclude.probe = FALSE,
  boundaries = NA,
  legend = TRUE,
  titles = TRUE,
  margins = c(5, 4, 4, 8),
  ...
)

Arguments

variable

The variable/metric that should be plotted. See Details for the ways to specify this.

experiment

The rtrack_experiment object as returned from read_experiment.

factor

The factor (from the table in experiment$factors) by which the data should be grouped. Each factor level will be plotted as a separate series. If not specified, all values are plotted together in one series.

factor.colours

A colour to be used for each factor level. If not specified, colours will be automatically generated. The vector of colours is returned to allow additional plot customisation.

x.axis

The scale of the x axis. "Day" will add a labelled axis with tick marks at each day. If this parameter is set to "Trial", then tick marks are added for each trial. If set to "none", then no x axis will be drawn. Default (NA) selects an option appropriate for the experiment type.

type

The type of plot to draw. Either "p" for a side-by-side stripchart with individual points, "l" for a line graph showing medians and whiskers/error bars for upper and lower quartiles, "b" for both of these overlaid, or NA (the default) indicating that the function should choose the most appropriate type for the plot.

point.type

The type of point to draw. Either "o" for open circles, "x" for filled circles or any of the integer values allowed by R (see the pch option for par).

transparency

A value from 0 (fully transparent) to 1 (fully opaque) governing the transparency of the points. If filled symbols are used, then transparency can help distinguish overlapping points.

exclude.probe

Should data from probe trials be excluded (see Details).

boundaries

Where should the boundaries between arena types be drawn (see Details).

legend

Should a legend be added. Default is TRUE.

titles

Should titles be drawn. Default is to add a main title and titles for the x and y axes. These can be suppressed and added afterwards (using title). This might be helpful for localising to a different language for example.

margins

The margins of the plot (see the option mar in par). The defaults should usually be fine, but they can be overridden if, for example, factor names are very long.

...

Other parameters that control some aspects of the plot. The values for lwd, las, pch and cex can be adjusted in this way.

Details

Many of the summary metrics (as returned in the summary component of the calculate_metrics output are useful for analysis in their own right. These can be plotted as mean values over each trial with standard error bars. If a factor is provided, then one data series will be plotted for each level of the factor. To view data for mutliple factors, they will need to be collapsed into one composite factor for plotting using this function. If probe trials were used, then "latency to goal" and several other variables do not make much sense, so the data for the probe trials can be suppressed. For this to work, a column named "Probe" must be present in the experiment description spreadsheet and must contain the value "TRUE" for each probe trial.

The variable parameter can either be specified as the name of one of the summary metrics, the name of one of the columns from the experiment description, or as a numeric vector. In the latter case, the numeric vector must be the same length as the number of tracks in the experiment.

Boundaries are drawn (as broken vertical lines) between different arena types (for example between acquisition and goal reversal phases of a Morris water maze experiment). By default, these are added between each unique arena definition. If this is not appropriate, then this can be overridden by providing the boundaries parameter with a matrix or data.frame with two columns for the day and trial number respectively. Multiple boundaries can be defined by entering the day and trial index into rows of this table. Use boundaries = NULL to suppress boundary lines altogether.

Value

A named vector of colours used for each factor level.

Examples

# This function relies on data too large to include in the package.
# For a worked example, please see the vignette "Rtrack MWM analysis"
# in the online package documentation at
# https://rupertoverall.net/Rtrack/.