In dosc91/mtqgam: Mouse-Tracking Data in QGAMs

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

library(mtqgam)
library(itsadug)
library(qgam)
library(ggplot2)

# all not shown stuff

load("C:/Users/Adomo/Dropbox/HHU_2373/PhD/Experiment_02_+_03/01a_Analyse/new_qgams/01_mtqgam_data/qgams_nm_base_x.RData")
tmp.x.1 <- qdo(qgams_nm_base_x, 0.5)
qgams_x <- qgams_nm_base_x

The mtqgam package was created to simplify working with mouse-tracking data in QGAMs. Aiding the ENGS and the VAR project of the DFG-FOR 2373 "Spoken Morphology" research unit, this package is under development.

This vignette gives an overview of functions included in the mtqgam package. Please contact the author in case of questions.

---

Overview

This is a full list of all functions currently contained in mtqgam:

• better_parametric_plot - Better Parametric Plots
• better_smooth_plot - Better Smooth Plots
• better_interaction_plot - Better Interaction Plots
• facet_parametric_plot - Multi-Panel Parametric Plots
• facet_smooth_plot - Multi-Panel Smooth Plots
• extract_t - Extract t Coordinates
• extract_x - Extract x Coordinates
• extract_y - Extract y Coordinates

Note: Due to size reasons, no exemplary data set is included in this package.

---

Better Parametric Plots {#better_parametric_plot}

The better_parametric_plot function creates a point-range plot for the specified parametric predictor term. It basically is a wrapper for itsadug's plot_parametric function, adding the variability and flexibility of ggplot2 objects.

The functions requires a QGAM model. The QGAM model can either be the output of qgam::qgam, the output of qgam::mqgam, or a single QGAM model extracted from a qgam::mqgam object. Specify the quantile you wish to plot when using the output of qgam::mqgam. In all cases, the pred argument is required. This is the parametric effect you wish to plot.

An 'Old' Parametric Plot

old.plot <- plot_parametric(tmp.x.1, 
                            pred = list(Condition = c("matched", "mismatched")), 
                            print.summary=F)

A Better Parametric Plot

using a single QGAM extracted from a qgam::mqgam object OR created using qgam::qgam

better_parametric_plot(qgam = tmp.x.1, pred = "Condition")

using the output of qgam::mqgam

better_parametric_plot(qgam = qgams_x, quantile = 0.5, pred = "Condition")

Modifications

You can change the order of the predictor levels displayed on the y axis:

better_parametric_plot(qgam = tmp.x.1, pred = "Condition",
                       order = c("mismatched", "matched"))

Plots created with better_parametric_plot can be modified using common ggplot2 functions:

better_parametric_plot(qgam = tmp.x.1, pred = "Condition",
                       color = c("purple", "blue")) +
                       theme_classic() +
                       labs(subtitle = "This is a subtitle")

---

Better Smooth Plots {#better_smooth_plot}

The better_smooth_plot function creates a line plot for the specified parametric predictor term. It basically is a wrapper of the base R plot function used for the visualisation of GAMs, adding the variability and flexibility of ggplot2 objects.

The functions requires a QGAM model. The QGAM model can either be the output of qgam::qgam, the output of qgam::mqgam, or a single QGAM model extracted from a qgam::mqgam object. Specify the quantile you wish to plot when using the output of qgam::mqgam. In all cases, the pred argument is required. This is the smooth you wish to plot.

Note: In previous versions, smooth_term was specified instead of pred instead. This argument is now obsolete. Please use pred instead.

An 'Old' Smooth Plot

old.plot <- plot(tmp.x.1, 
                 select = 6)

A Better Smooth Plot

using a single QGAM extracted from a qgam::mqgam object OR created using qgam::qgam

better_smooth_plot(qgam = tmp.x.1, pred = "PIT")

using the output of qgam::mqgam

better_smooth_plot(qgam = qgams_x, quantile = 0.5, pred = "PIT")

Modifications

Plots created with better_smooth_plot can be modified using common ggplot2 functions:

better_smooth_plot(qgam = tmp.x.1, pred = "PIT",
                   fill = "purple") +
                   theme_classic() +
                   labs(subtitle = "This is a subtitle")

---

Better Interaction Plots {#better_interaction_plot}

The better_interaction_plot function creates either a smooth plot with confidence intervals (for numeric:factor interactions) or a point plot with confidence interval ranges (for factor:factor interactions) using ggplot2. The underlying functions are similar to better_parametric_plot and better_smooth_plot (as introduced above). Using similar underlying functions, better_interaction_plot adds the variability and flexibility of ggplot2 to plots of interactions.

The functions requires a QGAM model. The QGAM model can either be the output of qgam::qgam, the output of qgam::mqgam, or a single QGAM model extracted from a qgam::mqgam object. Specify the quantile you wish to plot when using the output of qgam::mqgam. In all cases, the pred and the cond argument are required. pred is the parametric effect you wish to plot; cond is either the (parametric or smooth) term pred is in interaction with.

factor:factor Interaction Plots

The better_interaction_plot automatically checks whether the variable given as pred input is numeric or a factor. In case of factors, plots of the following type are created.

using a single QGAM extracted from a qgam::mqgam object OR created using qgam::qgam

better_interaction_plot(qgam = tmp.x.1, pred = "Condition", cond = "correct")

using the output of qgam::mqgam

better_interaction_plot(qgam = qgams_x, quantile = 0.5, pred = "Condition", cond = "correct")

Modifications

Plots created with better_smooth_plot can be modified using common ggplot2 functions:

better_interaction_plot(qgam = qgams_x, quantile = 0.5, pred = "Condition", cond = "correct",
                        color = c("purple", "blue")) +
                        theme_classic() +
                        labs(subtitle = "This is a subtitle")

numeric:factor Interaction Plots

The better_interaction_plot automatically checks whether the variable given as pred input is numeric or a factor. In case of numeric variables, plots of the following type are created. By default, these plots are presented in facets.

using a single QGAM extracted from a qgam::mqgam object OR created using qgam::qgam

better_interaction_plot(qgam = tmp.x.1, pred = "PIT", cond = "Condition")

using the output of qgam::mqgam

better_interaction_plot(qgam = qgams_x, quantile = 0.5, pred = "PIT", cond = "Condition")

Modifications

Plots created with better_smooth_plot can be modified using common ggplot2 functions:

better_interaction_plot(qgam = qgams_x, quantile = 0.5, pred = "PIT", cond = "Condition",
                        fill = "purple") +
                        theme_classic() +
                        labs(subtitle = "This is a subtitle")

no_facet Plots

Interactions of type numeric:factor can also be plotted in a single plot. To achieve this, specify the type argument as no_facet.

better_interaction_plot(qgam = tmp.x.1, pred = "PIT", cond = "Condition", type = "no_facet")

---

Multi-Panel Parametric Plots {#facet_parametric_plot}

The facet_parametric_plot function creates a multi-panel plot of better_parametric_plots.

The functions requires a collection of QGAM models. The QGAM models should be the output of qgam::mqgam. Additionally, the pred argument is required. This is the parametric effect you wish to plot.

A Multi-Panel Parametric Plot

facet_parametric_plot(qgam = qgams_x, pred = "Condition")

Modifications

Plots created with facet_parametric_plot have standard colors for levels of the pred argument. These, of course, can be changed:

facet_parametric_plot(qgam = qgams_x, pred = "Condition",
                      color = c("purple", "green"))

Plots created with facet_parametric_plot can be modified using common ggplot2 functions:

facet_parametric_plot(qgam = qgams_x, pred = "Condition") +
                   theme_classic() +
                   theme(strip.background = element_rect(fill = "steelblue2"))

Plots created with facet_parametric_plot use a free scale, i.e. the scale of the axes of the individual facets is adapted to the range of its values. This can be changed by specifying the scale argument:

facet_parametric_plot(qgam = qgams_x, pred = "Condition",
                      scale = "fixed")

---

Multi-Panel Smooth Plots {#facet_smooth_plot}

The facet_smooth_plot function creates a multi-panel plot of better_smooth_plots.

The functions requires a collection of QGAM models. The QGAM models should be the output of qgam::mqgam. Additionally, the pred argument is required. This is the smooth you wish to plot.

A Multi-Panel Parametric Plot

facet_smooth_plot(qgam = qgams_x, pred = "PIT")

Modifications

Plots created with facet_smooth_plot have a standard color for the confidence interval of the pred argument. This color, of course, can be changed:

facet_smooth_plot(qgam = qgams_x, pred = "PIT",
                      fill = "purple")

Plots created with facet_smooth_plot can be modified using common ggplot2 functions:

facet_smooth_plot(qgam = qgams_x, pred = "PIT") +
                   theme_classic() +
                   theme(strip.background = element_rect(fill = "steelblue2"))

Plots created with facet_smooth_plot use a free scale, i.e. the scale of the axes of the individual facets is adapted to the range of its values. This can be changed by specifying the scale argument:

facet_smooth_plot(qgam = qgams_x, pred = "PIT",
                      scale = "fixed")

---

Extract t Coordinates {#extract_t}

The extract_t function extracts the t coordinates, i.e. the time values, from a time-normalized mousetrap object.

The function requires time-normalized mouse-tracking data, an ID column as part of the time-normalized data set, and the number of timestamps used for time-normalizing.

# extract time-normalized data
tn_tracks <- as.data.frame(mt_data$tn_trajectories)

# add ID columns
tn_tracks$ID <- mt_data$data$ID

# use function
extract_t(tn_data = tn_tracks,
ID_column = tn_tracks$ID,
timestamps = 140)

---

Extract x Coordinates {#extract_x}

The extract_x function extracts the x coordinates from a time-normalized mousetrap object.

The function requires time-normalized mouse-tracking data, an ID column as part of the time-normalized data set, and the number of timestamps used for time-normalizing.

# extract time-normalized data
tn_tracks <- as.data.frame(mt_data$tn_trajectories)

# add ID columns
tn_tracks$ID <- mt_data$data$ID

# use function
extract_x(tn_data = tn_tracks,
ID_column = tn_tracks$ID,
timestamps = 140)

---

Extract y Coordinates {#extract_y}

The extract_y function extracts the y coordinates from a time-normalized mousetrap object.

The function requires time-normalized mouse-tracking data, an ID column as part of the time-normalized data set, and the number of timestamps used for time-normalizing.

# extract time-normalized data
tn_tracks <- as.data.frame(mt_data$tn_trajectories)

# add ID columns
tn_tracks$ID <- mt_data$data$ID

# use function
extract_x(tn_data = tn_tracks,
ID_column = tn_tracks$ID,
timestamps = 140)

---

References

Csárdi, G. (2021). cli: Helpers for Developing Command Line Interfaces. R package version 3.0.0. URL: https://CRAN.R-project.org/package=cli

Fasiolo M., Goude Y., Nedellec R., & Wood S. N. (2017). Fast calibrated additive quantile regression. URL: https://arxiv.org/abs/1707.03307

Hester, J. (2020). glue: Interpreted String Literals. R package version 1.4.1. https://CRAN.R-project.org/package=glue

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.

van Rij J, Wieling M, Baayen R, & van Rijn H (2020). itsadug: Interpreting Time Series and Autocorrelated Data Using GAMMs. R package version 2.4.

Wickham, H. (2016). ggplot2: Elegant Graphics for Data Analysis. Springer-Verlag New York.

Wickham, H. (2020). tidyr: Tidy Messy Data. R package version 1.1.2. https://CRAN.R-project.org/package=tidyr

---

Please message the author at [e-mail] in case of any questions, errors or ideas.

dosc91/mtqgam documentation built on Sept. 29, 2023, 9:38 a.m.