rk.gganimate: Gapminder-style Animations & Data Storytelling for RKWard

rk.gganimate is an advanced RKWard GUI plugin suite that brings the power of gganimate, ggplot2, and srvyr into a point-and-click interface. Designed for data storytelling, it allows researchers to easily aggregate complex survey data (or standard data frames) and render stunning, publication-ready animated GIFs—including Gapminder-style bubble charts, dynamic line charts, and viral Bar Chart Races.

🌟 Key Features

Zero-Code Animations: Generate complex GIFs directly from your datasets without writing ggplot2 syntax.
Built-in Survey Data Prep: Don't have summarized data? Use the Data Prep tool to aggregate massive, weighted survey designs (survey.design) into lightweight 3D cubes (X, Y, Size) ready for animation.
Storytelling Focus: Smart highlighting features automatically dim non-essential data and apply ColorBrewer/SWD palettes to specific targets.
HTML Embedding: Rendered GIFs are automatically embedded and played directly inside your RKWard Output Window.
Multilingual: Fully translated into English, Spanish, French, German, and Portuguese (Brazil).

🚀 What's New in Version 0.0.6

This update brings refined Storytelling controls inspired by Storytelling with Data (SWD) principles, along with crucial UI and engine optimizations:

🎨 SWD Focus Colors: A new "Focus Color" dropdown has been added to the Line Chart and Bar Chart Race components. You can now highlight a specific target (e.g., a specific state or country) using standard SWD palettes (Red, Blue, Orange, Green, Purple, Teal) while all other data points fade into a contextual gray background.
🏷️ Dynamic Line Tracking: The Animated Line Chart now features a "Show dynamic label following the line tip" option, allowing a floating label to chase the head of the line automatically as it reveals over time.
🧭 Legend Position Controls: The Bar Chart Race now includes a dropdown to precisely place your color legends (None, Right, Bottom, Top, Left).
⚙️ Engine & Bug Fixes: Fixed a ggplot2 rendering bug (+<- error) caused by dangling layers in the Bar Chart Race. Additionally, all require() statements are now strictly consolidated into RKWard's ## Preparar block, ensuring cleaner and faster R script generation.

🚀 What's New in Version 0.0.5

This major update expands the plugin suite beyond bubble charts, introducing two highly requested animation formats and advanced storytelling features:

🏎️ Bar Chart Race Component: A brand new tool to generate the viral "Bar Chart Race" animation. It automatically calculates rankings per time period, handles smooth transitions via geom_tile(), and supports injecting logos/images at the end of the bars using ggimage.
📈 Animated Line Chart (SWD): A dedicated tool for line charts using transition_reveal(). Features a "Storytelling" tab to highlight a specific group (drawing its line thicker and in focus color) while keeping the rest as gray background context. Includes a toggle for view_follow() to let the axes dynamically expand as the data grows.
💧 Gapminder Watermark: The Animated Bubble Chart now includes an option to render a massive, transparent dynamic year in the background of the plot, replicating Hans Rosling's iconic Gapminder aesthetic.

🚀 What's New in Version 0.0.4

This major update transforms the plugin into a highly flexible tool for multi-dimensional data storytelling:

Multi-Grouping Data Cubes: The Data Prep tool now accepts multiple grouping variables (e.g., State AND Economic Sector simultaneously), allowing you to build rich, multi-dimensional summary tables from complex survey designs.
Dynamic Plot Filtering: A new dplyr::filter box has been added directly to the Animated Bubble Chart interface. You can now subset your animations on-the-fly (e.g., sec_est == "Manufactura") without needing to create new tables in your workspace.
Smart Ghost-Label Prevention: The internal JavaScript engine was completely refactored. The Color Palette logic and the Storytelling text-tracking (ggrepel) now dynamically attach strictly to the filtered subset, preventing "ghost" labels from invisible categories from ruining your animations.

🚀 What is new in Version 0.0.3

This update focuses on fine-tuning the visual output, adding publication-ready details, and improving the user interface:

✨ New Features & Improvements:

Smart Legend Titles: Added a field to customize the color legend title. If left blank, the plugin intelligently extracts the original variable label (.rk.meta or variable.label) directly from your data frame, keeping your charts looking professional automatically.
Caption Support: Added a dedicated Caption field in the UI to easily include data sources, methodology notes, or credits at the bottom of your animation.
Dynamic Font Scaling: Introduced a "Base Font Size" control. You can now easily scale up all text elements (titles, axes, legends) simultaneously—perfect for generating readable GIFs for PowerPoint presentations or social media.
UI Reorganization: The interface has been streamlined. The overloaded "Labels & Theme" tab is now split into "Labels" (titles, axes, captions) and "Theme & Tracking" (palettes, font sizes, storytelling), providing a cleaner, step-by-step user workflow.
i18n Updates: Translation files (.po/.mo) for Spanish, French, German, and Brazilian Portuguese have been updated to cover all the new UI elements.

🚀 What is new in Version 0.0.2

Strict Rule #3 Compliance: Fixed a scoping issue in the Data Prep module. The generated R code now correctly hardcodes the output object (tabla_animacion), preventing RKWard from duplicating objects or losing metadata upon saving.
Survey Design Parsing Fix: Rewrote the JS getCol() helper with a robust regex to properly parse deeply nested survey.design variables. It now correctly identifies the actual column names (e.g., ent, year) instead of getting stuck on the internal [["variables"]] list structure.

⚙️ Prerequisites

You must have RKWard installed along with the following R packages:

install.packages(c("ggplot2", "gganimate", "gifski", "transformr", "srvyr", "dplyr", "ggimage"))

🚀 Installation

You can install this plugin directly from GitHub using devtools:

# Install the plugin
# remotes::install_github("AlfCano/rk.gganimate")
install.packages("rk.gganimate", repos = c('https://alfcano.r-universe.dev', 'https://cloud.r-project.org'))

Once installed, open RKWard, navigate to Settings -> Configure RKWard -> Plugins, and activate rk.gganimate.

🛠️ Usage Workflow

This plugin adds a two-step toolkit under Survey -> Graphs -> Animations.

1. Data Prep for Animation (srvyr)

This tool crunches heavy survey data (millions of rows) into a lightweight table (one row per group per year) required for Gapminder-style animations.

Source Data & Filters: Select your survey.design object.
Grouping Dimensions: Select the Time variable (e.g., year) and one or more Grouping variables (e.g., State and Sector).
Metrics: Select your continuous variable (to calculate the mean for the Y-Axis) and your categorical variable + target level (to calculate the % for the X-Axis).
Click Submit. A summarized table (tabla_animacion) will be saved to your workspace.

2. Animated Bubble Chart

Variables: Select tabla_animacion. Map your calculated X, Y, Size, and Color variables. Use the new Optional Filter box to dynamically subset your animation (e.g., Sector == 'Manufacturing').
Labels & Theme: Set titles, tweak the color palette, and use the Storytelling frame to track specific bubbles (e.g., type Puebla, Jalisco to only display names for those specific bubbles while they move).
Render & Export: Set your FPS and duration. Click Submit. The GIF will be rendered and embedded directly into your RKWard HTML output window!

3. Animated Line Chart

Shows growth over time using transition_reveal().

Perfect for tracking GDP, population, or unemployment rates.
Enable Free scales (view_follow) to make the camera "chase" the line as it goes off-chart.

4. Bar Chart Race

The viral sliding bar ranking chart.

Just provide the Category, Value, and Time variables. The plugin does the heavy lifting of ranking the Top N categories per frame and creating the cubic-in-out smooth transitions.

🧪 The Testing Workflow

To test the generated plugin and see the Storytelling tracking in action, paste this into the RKWard console to create a mock summarized dataset:

# Create a Mock Summarized Dataset (Gapminder Style)
set.seed(123)
mock_anim_data <- expand.grid(Year = 2010:2020, State = c("Puebla", "Jalisco", "Nuevo Leon", "CDMX", "Oaxaca"))
mock_anim_data$Income <- runif(nrow(mock_anim_data), 10000, 30000) + (mock_anim_data$Year - 2010) * 1000
mock_anim_data$Poverty_Pct <- runif(nrow(mock_anim_data), 20, 60) - (mock_anim_data$Year - 2010) * 1.5
mock_anim_data$Population <- runif(nrow(mock_anim_data), 1e6, 5e6)

Step-by-step Test:

Open Survey > Graphs > Animations > 2. Animated Bubble Chart
- Data Frame: Select mock_anim_data
- X Axis: Select Poverty_Pct
- Y Axis: Select Income
- Time / Frame Variable: Select Year
- Bubble Size: Select Population
- Color / Group Category: Select State
Go to the Labels & Theme Tab:
- Main Title: Type Poverty vs Income (2010-2020)
- Plot Theme: Minimal
- Storytelling: Check the "Highlight specific bubbles" box.
- Exact name(s) to track: Type Puebla, Nuevo Leon
Go to the Render & Export Tab:
- Frames per second: 10
- Duration: 8 seconds
- Save GIF as: Choose a folder on your computer (e.g., your Desktop) and name it test_animation.gif.
Click Submit!
- Note: Rendering a GIF takes a few seconds. Wait until RKWard says "Animation successfully saved".

Result: Check your Desktop. You will have a fluid 8-second animation where all bubbles move, but only "Puebla" and "Nuevo Leon" have a bold, floating label tracking their exact movement across the screen!

🌍 Internationalization (i18n)

The graphical interface automatically adapts to your RKWard language settings. Currently supported languages:

🇺🇸 English (Default)
🇪🇸 Spanish (Español)
🇫🇷 French (Français)
🇩🇪 German (Deutsch)
🇧🇷 Portuguese (Português do Brasil)

📝 License and Author

Author: Alfonso Cano (@AlfCano) Email: alfonso.cano@correo.buap.mx

Assisted by: Gemini, a large language model from Google.
License: GPL (>= 3)

This project is licensed under the GPL (>= 3) License.