mousetrap (version 1.2.0)

mt_plot_riverbed: Plot density of mouse positions across time steps.

Description

mt_plot_riverbed creates a plot showing the distribution of one trajectory variable (e.g., the x-positions or velocity) per time step.

Usage

mt_plot_riverbed(data, use = "tn_trajectories", y = "xpos", y_range = NULL, y_bins = 250, facet_row = NULL, facet_col = NULL, facet_data = "data")

Arguments

data

mousetrap data object containing the data to be plotted.

use

character string specifying the set of trajectories to use in the plot. The steps of this set will constitute the x axis. Defaults to 'tn_trajectories', which results in time steps being plotted on the x axis.

y

variable in the mousetrap data object to be plotted on the output's y dimension. Defaults to 'xpos', the cursor's x coordinate.

y_range

numerical vector containing two values that represent the upper and lower ends of the y axis. By default, the range is calculated from the data provided.

y_bins

number of bins to distribute along the y axis (defaults to 250).

facet_row

an optional character string specifying a variable in data[[facet_data]] that should be used for (row-wise) faceting. If specified, separate riverbed plots for each level of the variable will be created.

facet_col

an optional character string specifying a variable in data[[facet_data]] that should be used for (column-wise) faceting. If specified, separate riverbed plots for each level of the variable will be created.

facet_data

a character string specifying where the (optional) data containing the faceting variables can be found.

Details

This function plots the relative frequency of the values of a trajectory variable separately for each of a series of time steps. This type of plot has been used in previous research to visualize the distribution of x-positions per time step (e.g., Scherbaum et al., 2010).

mt_plot_riverbed usually is applied to time-normalized trajectory data as all trajectories must contain the same number of values.

References

Scherbaum, S., Dshemuchadse, M., Fischer, R., & Goschke, T. (2010). How decisions evolve: The temporal dynamics of action selection. Cognition, 115(3), 407-416.

See Also

mt_plot for plotting trajectory data.

mt_time_normalize for time-normalizing trajectories.

Examples

# Time-normalize trajectories
mt_example <- mt_time_normalize(mt_example)
  
# Create riverbed plot for all trials
mt_plot_riverbed(mt_example)

## Not run: 
# # Create riverbed plot for all trials with custom x and y axis labels
# mt_plot_riverbed(mt_example) +
#   ggplot2::xlab("Time step") + ggplot2::ylab("X coordinate")
# 
# # Create separate plots for typical and atypical trials
# mt_plot_riverbed(mt_example, facet_col="Condition")
# 
# # Note that it is also possible to replace the
# # default scale for fill with a custom scale
# mt_plot_riverbed(mt_example, facet_col="Condition") +
#   scale_fill_gradientn(colours=grDevices::heat.colors(9),
#     name="Frequency", trans="log", labels=scales::percent)
# ## End(Not run)