mt_heatmap_raw: Creates high-resolution heatmap of trajectory data.

In mousetrap: Process and Analyze Mouse-Tracking Data

Creates high-resolution heatmap of trajectory data.

Description

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

Usage

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.

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.

Value

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

Author(s)

Dirk U. Wulff

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.

See Also

mt_heatmap and mt_heatmap_ggplot for plotting trajectory heatmaps.

mt_diffmap for plotting trajectory difference-heatmaps.

mousetrap documentation built on May 29, 2024, 11:39 a.m.