Creates high-resolution heatmap of trajectory data.

mt_heatmap_raw creates a high-resolution heatmap image of the trajectory data using gaussian smoothing. Note that this function has beta status.

mt_heatmap_raw(
  data,
  use = "trajectories",
  dimensions = c("xpos", "ypos"),
  variable = NULL,
  bounds = NULL,
  xres = 1000,
  upsample = 1,
  norm = FALSE,
  colors = c("black", "blue", "white"),
  n_shades = c(1000, 1000),
  smooth_radius = 1.5,
  low_pass = 200,
  auto_enhance = TRUE,
  mean_image = 0.15,
  mean_color = 0.25,
  aggregate_lwd = 0,
  aggregate_col = "black",
  n_trajectories = NULL,
  seed = NULL,
  verbose = TRUE
)

Arguments

data: a mousetrap data object created using one of the mt_import functions (see mt_example for details). Alternatively, a trajectory array can be provided directly (in this case use will be ignored).
use: a character string specifying which trajectory data should be used.
dimensions: a character vector specifying the trajectory variables used to create the heatmap. The first two entries are used as x and y-coordinates, the third, if provided, will be added as color information.
variable: boolean or numeric vector matching the number of trajectories that if provided will be used as color information. variable is only considered when length(dimensions) < 3.
bounds: numeric vector specifying the corners (xmin, ymin, xmax, ymax) of the plot region. By default (bounds = NULL), bounds are determined based on the data input.
xres: an integer specifying the number of pixels along the x-dimension. An xres of 1000 implies an 1000*N px, where N is determined so that the trajectories aspect ratio is preserved (provided the bounds are unchanged).
upsample: a numeric value by which the number of points used to represent individual trajectories are increased or decreased. Values of smaller than one will improve speed but also introduce a certain level of granularity.
norm: a logical specifying whether the data should be warped into standard space. If norm = TRUE, this overrules bounds.
colors: a character vector specifying two or three colors used to color the background, the foreground (trajectories), and the values of a third dimension (if specified).
n_shades: an integer specifying the number of shades for the color gradient between the first and second, and the second and third color in colors.
smooth_radius: a numeric value specifying the standard deviation of the gaussian smoothing. If zero, smoothing is omitted.
low_pass: an integer specifying the allowed number of counts per pixel. This arguments limits the maximum pixel color intensity.
auto_enhance: boolean. If TRUE (the default), the image is adjusted so that the mean color intensity matches mean_image and mean_color.
mean_image: a numeric value between 0 and 1 specifying the average foreground color intensity across the entire image. Defaults to 0.1.
mean_color: a numeric value between 0 and 1 specifying the average third dimension's color intensity across the entire image. Defaults to 0.1. Only relevant if a third dimension is specified in colors.
aggregate_lwd: an integer specifying the width of the aggregate trajectory. If aggregate_lwd is 0 (the default), the aggregate trajectory is omitted.
aggregate_col: a character value specifying the color of the aggregate trajectory.
n_trajectories: an optional integer specifying the number of trajectories used to create the image. By default, all trajectories are used. If n_trajectories is specified and smaller than the number of trajectories in the trajectory array, then n_trajectories are randomly sampled.
seed: an optional integer specifying the seed used for the trajectory sampling.
verbose: logical indicating whether function should report its progress.

Value

An object of class mt_object_raw containing in a matrix format the image's pixel information, the aggregate trajectory, and the colors.

Details

To create the image, mt_heatmap_raw takes the following steps. First, the function maps the trajectory points to a pixel space with x ranging from 1 to xres and y ranging from 1 to xres divided by the ratio of x and y's value range. Second, the function counts and normalizes the number of trajectory points occupying each of the x,y-pixels to yield image intensities between 0 and 1. Third, the function smooths the image using an approximative guassian approach governed by smooth_radius, which controls the dispersion of the gaussian smoothing. Fourth, the function automatically enhances the image (unless auto_enhance = FALSE) using a non-linear transformation in order to yield a desired mean_image intensity. Fifth, the function translates the image intensity into color using the colors specified in colors. Finally, the function returns the image data in a long format containing the x, y, and color information.

mt_heatmap_raw also offers the possibility to overlay the heatmap with an additional variable, such as for instance velocity, so that both the density of mouse trajectories and the information of the additional variable are visible. In order to do this, specify a third variable label in dimensions and control its appearance using the color and mean_color arguments.

References

Wulff, D. U., Haslbeck, J. M. B., Kieslich, P. J., Henninger, F., & Schulte-Mecklenbeck, M. (2019). Mouse-tracking: Detecting types in movement trajectories. In M. Schulte-Mecklenbeck, A. Kühberger, & J. G. Johnson (Eds.), A Handbook of Process Tracing Methods (pp. 131-145). New York, NY: Routledge.

Kieslich, P. J., Henninger, F., Wulff, D. U., Haslbeck, J. M. B., & Schulte-Mecklenbeck, M. (2019). Mouse-tracking: A practical guide to implementation and analysis. In M. Schulte-Mecklenbeck, A. Kühberger, & J. G. Johnson (Eds.), A Handbook of Process Tracing Methods (pp. 111-130). New York, NY: Routledge.

Author

Dirk U. Wulff