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
)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).
a character string specifying which trajectory data should be used.
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.
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.
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.
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).
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.
a logical specifying whether the data should be warped into
standard space. If norm = TRUE, this overrules bounds.
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).
an integer specifying the number of shades for the color
gradient between the first and second, and the second and third color in
colors.
a numeric value specifying the standard deviation of the gaussian smoothing. If zero, smoothing is omitted.
an integer specifying the allowed number of counts per pixel. This arguments limits the maximum pixel color intensity.
boolean. If TRUE (the default), the image is
adjusted so that the mean color intensity matches mean_image and
mean_color.
a numeric value between 0 and 1 specifying the average foreground color intensity across the entire image. Defaults to 0.1.
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.
an integer specifying the width of the aggregate
trajectory. If aggregate_lwd is 0 (the default), the aggregate
trajectory is omitted.
a character value specifying the color of the aggregate trajectory.
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.
an optional integer specifying the seed used for the trajectory sampling.
logical indicating whether function should report its progress.
An object of class mt_object_raw containing in a matrix format
the image's pixel information, the aggregate trajectory, and the colors.
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.
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<U+00FC>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<U+00FC>hberger, & J. G. Johnson (Eds.), A Handbook of Process Tracing Methods (pp. 111-130). New York, NY: Routledge.
mt_heatmap and mt_heatmap_ggplot for plotting trajectory heatmaps.
mt_diffmap for plotting trajectory difference-heatmaps.