The maraca package now supports built-in plot animations. This feature is useful for sprucing up presentations or highlighting the temporal nature of step-wise outcomes.

This is an experimental feature, so despite doing some testing during development there might be some problems or unexpected behavior during usage. Please take a minute to report any wrong behavior to allow us to improve the functionality.

Note that in order to create an animation, the gganimate package needs to be installed. Furthermore, if the output should be as a gif, the gifski package is required. Alternatively, if either the av or ffmpeg package is installed, a video file is created. As a final alternative, if no dependency is installed, a list of image files is returned.

In this vignette, we will show you how to easily animate a figure by calling the animate_plot() function.

Usage

Basic Static Maraca Plot

First we have to create a maraca object.

library(maraca)

data(hce_scenario_a, package = "maraca")

data <- hce_scenario_a
column_names <- c(
    outcome = "GROUP",
    arm = "TRTP",
    value = "AVAL0"
)

step_outcomes <- c(
  "Outcome I", "Outcome II", "Outcome III", "Outcome IV"
)
last_outcome <- "Continuous outcome"

arm_levels = c(active = "Active", control = "Control")

mar <- maraca(
  data, step_outcomes, last_outcome, arm_levels, column_names, 
  fixed_followup_days = 3*365,
  compute_win_odds = TRUE
)

## Static plot
plot(mar)

Animate Basic Maraca Plot

We create an animation by simply calling the animate_plot() function.

animate_plot(mar)
## Warning in png(tmpf): unable to open connection to X11 display ''
## Warning: Cannot get dimensions of plot table. Plot region might not be fixed
## Caused by error in `.External2()`:
## ! unable to start device PNG

The animate_plot() function takes the same plotting parameters as the standard maraca plot() function.

animate_plot(mar,
             continuous_grid_spacing_x = 20,
             density_plot_type = "scatter",
             vline_type = "mean",
             remove_outliers = TRUE,
             theme = "color1")
## Warning in png(tmpf): unable to open connection to X11 display ''
## Warning: Cannot get dimensions of plot table. Plot region might not be fixed
## Caused by error in `.External2()`:
## ! unable to start device PNG

Animation plot options

Controlling Animation Speed and Duration

There are additional input parameters to control the speed and duration of the animation:

frames_per_step: int
- The frame rate of the animation in frames/sec. By default, the rate is 10 frames/sec.
gif_duration: int or float
- This defines how long the animation should be in seconds. By default, the animation is 10 seconds long.
end_duration: int or float
- This defines how many frames the animation should pause on the last frame before re-starting. By default, it pauses for 20 frames.
speed_factor: int or float
- This factor tries to balance the times that it takes to animate the step outcomes towards the last outcome. If not provided (NULL), the function tries to estimate a number that approximately leads to a similar speed between them. The user can try to experiment with manually setting the number to get the best speed.

Sequential Animation of Each Group/Arm

Another way of adapting the animation is by deciding in which order the treatment arms should be displayed. anim_order sets which of the treatment arms should be animated first - “active”, “control” or “both” (at the same time, default).

Size of animation output

The anim_width and anim_height parameters can be used to change how big the animation should be.

Example gif

The below example shows how to modify those parameters.

animate_plot(mar,
             frames_per_step = 12,
             gif_duration = 20,
             end_duration = 40,
             speed_factor = 8,
             anim_order = "control",
             anim_width = 800,
             anim_height = 600,
             continuous_grid_spacing_x = 20)
## Warning in png(tmpf): unable to open connection to X11 display ''
## Warning: Cannot get dimensions of plot table. Plot region might not be fixed
## Caused by error in `.External2()`:
## ! unable to start device PNG

Animating Alternative Maraca Plots

The animation utility can handle any permutation of maraca plot you would like.

For instance, it is possible to animate binary endpoints (either for the final or any step outcomes).

data("hce_scenario_a")
# Create data with binary version of 2 step outcomes and
# continuous final endpoint
bin_data <- hce_scenario_a

idx_bin <- bin_data$GROUP %in% c("Outcome III", "Outcome IV")
# Binary version (>= 0/< 0), coded as 1
bin_data[idx_bin,"AVAL0"] <- bin_data[idx_bin,"AVAL0"] >= 500
bin_data[idx_bin,"AVAL"] <- bin_data[idx_bin,"AVAL0"] +
  bin_data[idx_bin,"GROUPN"]
# Remove 0 rows (only include patients that had the outcome)
bin_data <- bin_data[bin_data$AVAL0 != 0,]

# Index of all continuous outcome rows
idx_cont <- bin_data$GROUP == "Continuous outcome"
# Rename outcome
bin_data[idx_cont,"GROUP"] <- "Binary outcome"
# Binary version (>= 0/< 0)
bin_data[idx_cont,"AVAL0"] <- bin_data[idx_cont,"AVAL0"] >= 0
bin_data[idx_cont,"AVAL"] <- bin_data[idx_cont,"AVAL0"] +
  bin_data[idx_cont,"GROUPN"]
last_outcome_binary <- "Binary outcome"


mar_binary <- maraca(
  bin_data, step_outcomes, last_outcome_binary,
  arm_levels, column_names,
  fixed_followup_days = 3*365,
  compute_win_odds = TRUE,
  # Important change: Add information that last endpoint is
  # not continuous (the default)
  step_types = c("tte","tte","binary","binary"),
  last_type = "binary"
)

animate_plot(mar_binary, anim_order = "control")
## Warning in png(tmpf): unable to open connection to X11 display ''
## Warning: Cannot get dimensions of plot table. Plot region might not be fixed
## Caused by error in `.External2()`:
## ! unable to start device PNG

The animate_plot() function can also be used directly for a adhce object (output from hce package).

Rates_A <- c(1.72, 1.74, 0.58, 1.5, 1)
Rates_P <- c(2.47, 2.24, 2.9, 4, 6)
hce_dat <- hce::simHCE(n = 2500, TTE_A = Rates_A, TTE_P = Rates_P,
              CM_A = -6, CM_P = 3, CSD_A = 15, CSD_P = 16, fixedfy = 3,
              seed = 31337)

animate_plot(hce_dat, compute_win_odds = TRUE, lowerBetter = TRUE,
             trans = "reverse")
## Warning in png(tmpf): unable to open connection to X11 display ''
## Warning: Cannot get dimensions of plot table. Plot region might not be fixed
## Caused by error in `.External2()`:
## ! unable to start device PNG

For boxplots, the animation just displays the entire boxplots at once, rather than gradually building them up.

animate_plot(mar,
             density_plot_type = "box",
             anim_order = "control",
             continuous_grid_spacing_x = 20)
## Warning in png(tmpf): unable to open connection to X11 display ''
## Warning: Cannot get dimensions of plot table. Plot region might not be fixed
## Caused by error in `.External2()`:
## ! unable to start device PNG

Saving the Animation

If the gifski package is used and a gif output is created (gif_output = TRUE), the animation can be saved directly from the animate_plot() function. By default, the gif gets saved to a tmp folder and displayed in the Viewer window. In order to save it to a file for later re-use instead, a file name needs to be provided to the gif_file_name parameter.

# Example - do not run
# animate_plot(mar, gif_file_name = "tmp/maraca_anim.gif")

Maraca Plots - Animation

Kevin Anderson, Monika Huhn

2025-11-20