Visualizing models

Oliver Jayasinghe and Rex Parsons

Visualizing cglmm models

The GLMMcosinor package includes two ways to visualize models from cglmm(). Firstly, the function autoplot() creates a time-response plot of the fitted model:

library(GLMMcosinor)

object <- cglmm(
  vit_d ~ X + amp_acro(time,
    group = "X",
    period = 12
  ),
  data = vitamind
)
autoplot(object, x_str = "X")

This function also allows users to superimpose the data points (that the fit is based on) over the fitted model, using the superimpose.data = TRUE argument:

object <- cglmm(
  vit_d ~ X + amp_acro(time,
    group = "X",
    period = 12
  ),
  data = vitamind
)
autoplot(object, x_str = "X", superimpose.data = TRUE)

If there are multiple factors in the model, the user can specify which covariate to be plotted using the x_str argument which accepts a string corresponding to a group name within the original dataset. By default, x_str = NULL and the intercept is plotted (all group levels = 0).

The following examples demonstrate how x_str can be used to produce different plots for the same model. Note how predict.ribbon can be set to FALSE to remove the prediction interval from the plots.

testdata_two_components <- testdata_two_components
testdata_two_components$X <- rbinom(length(testdata_two_components$group),
  2,
  prob = 0.5
)
object <- cglmm(
  Y ~ group + amp_acro(times,
    n_components = 2,
    period = c(12, 6),
    group = c("group", "X")
  ),
  data = testdata_two_components,
  family = poisson()
)
autoplot(object, predict.ribbon = FALSE)

object <- cglmm(
  Y ~ group + amp_acro(times,
    n_components = 2,
    period = c(12, 6),
    group = c("group", "X")
  ),
  data = testdata_two_components,
  family = poisson()
)
autoplot(object, x_str = "X", predict.ribbon = FALSE)

object <- cglmm(
  Y ~ group + amp_acro(times,
    n_components = 2,
    period = c(12, 6),
    group = c("group", "X")
  ),
  data = testdata_two_components,
  family = poisson()
)
autoplot(object, x_str = "group", predict.ribbon = FALSE)

By default, xmin will be set to the minimum time value in the time vector of the original dataframe, and xmax will be set to the maximum time value. If we want to focus on a specific region of the plot, we can define use the xlims argument to specify the x-bounds.

For example, on the plot above, we can adjust the x-limits:

object <- cglmm(
  Y ~ group + amp_acro(times,
    n_components = 2,
    period = c(12, 6),
    group = c("group", "X")
  ),
  data = testdata_two_components,
  family = poisson()
)
autoplot(object, x_str = "group", predict.ribbon = TRUE, xlims = c(13, 15))

To increase the resolution of the plots, the pred.length.out can be increased. If there are multiple periods, the function will automatically generate an appropriate number of points to plot such that the smallest period has sufficient resolution to appreciate cosinor behaviour. This can be adjusted using the points_per_min_cycle_length argument which is 20 by default.

testdata_period_diff <- simulate_cosinor(
  1000,
  n_period = 1,
  mesor = 7,
  amp = c(0.1, 0.4),
  acro = c(1, 1.5),
  family = "poisson",
  period = c(12, 1000),
  n_components = 2
)
object <- cglmm(
  Y ~ amp_acro(times,
    n_components = 2,
    period = c(12, 1000)
  ),
  data = testdata_period_diff,
  family = poisson()
)

autoplot(object, points_per_min_cycle_length = 40)

Polar plots

In addition to time-response plots, the GLMMcosinor package also allows users to create polar plots. In these plots, the plotted point represents the acrophase estimate, and the radius represents the amplitude estimate for a given component. The ellipses represent confidence regions.

model <- cglmm(
  vit_d ~ X + amp_acro(time,
    group = "X",
    period = 12
  ),
  data = vitamind
)
polar_plot(model)

The angle units in the plot can be specified with the radial_units argument. By default, the units are in radians where a complete revolution of the plot \((2\pi)\) represents the maximum period from the model. The units can be changed to degrees, or even to be expressed in the same units as the period specification.

model <- cglmm(
  vit_d ~ X + amp_acro(time,
    group = "X",
    period = 12
  ),
  data = vitamind
)
polar_plot(model, radial_units = "degrees")

By default, the function creates creates polar plots for all components and stitches them together using the make_cowplot = TRUE argument. If the user wishes to plot just one component, they can specify this by using component_index, though the make_cowplot argument must be FALSE for this to register.

The direction that the angle increases in can be changed with the clockwise argument, and the location of the angle = 0 starting point can be specified with the start argument. Hence, if the user wishes to create a polar plot that resembles a clock, this can be done by specifying clockwise = TRUE and start = "top".

The argument: overlay_parameter_info can be used to create a line extending from the origin to the parameter estimate (to visualize the amplitude estimate), and a circular arc extending from the angle starting position (at 0) to the acrophase estimate.

model <- cglmm(
  vit_d ~ X + amp_acro(time,
    group = "X",
    period = 12
  ),
  data = vitamind
)
polar_plot(model, overlay_parameter_info = TRUE)

The background grid can also be customized. The argument grid_angle_segments is used to specify how many sectors the polar grid has, and the n_breaks argument can be used to specify the number of concentric circles.

model <- cglmm(
  vit_d ~ X + amp_acro(time,
    group = "X",
    period = 12
  ),
  data = vitamind
)
polar_plot(model,
  grid_angle_segments = 12,
  clockwise = TRUE,
  start = "top",
  n_breaks = 5
)

If the user wishes to zoom into the confidence ellipses to show relevant information, they can adjust the view from the default full (which plots a full view of the polar plot) to zoom (which enlarges the smallest view window containing all confidence ellipses), or zoom_origin (which enlarges the smallest view window containing all confidence ellipses AND the origin).

model <- cglmm(
  vit_d ~ X + amp_acro(time,
    group = "X",
    period = 12
  ),
  data = vitamind
)
polar_plot(model,
  grid_angle_segments = 12,
  clockwise = TRUE,
  start = "top",
  view = "zoom_origin"
)