Compiler details

The R code in animint.R defines the animint compiler. This page attempts to describe the design of the compiler, to make it easier to improve.

The main function is animint2dir (gg2animint is deprecated since 2 June 2014) which is called on a list of ggplots and options.

• it creates an environment called meta in which all plot meta-data will be stored.
• it calls parsePlot(meta) on each ggplot. Since meta is an environment, it can be modified inside parsePlot.
  • parsePlot calls ggplot2::ggplot_build(meta$plot), which returns a list of panels and a list of data.frames for each layer, with evaluated aes. For example, if you wrote aes(year, color=region) then you will get a data.frame with columns x and color (not year and region).
  • for every layer/geom we call saveLayer:
    • it assigns each layer a unique integer ID in meta$geom.count.
    • it contains some geom-specific code for converting the ggplot_build data.frame to a TSV file to read in JavaScript/D3.
    • it breaks the data into "chunks" which are separate TSV files that roughly correspond to subsets of data that will be shown onscreen at the same time (not always true, sometimes the TSV file has data for several subsets that will be shown onscreen at different times). Refer to chunk_order on the renderer details page for more information about chunks.
    • it calls the recursive function saveChunks which saves a TSV file for every chunk.
  • after all the layers in this plot have been processed, we make links from one layer/geom to the next in order to later preserve drawing order in multi-layer plots.
  • the final job of parsePlot is to extract plot-specific themes/options such as plot labels specified via xlab("axes label") and width in pixels specified via theme_animint(width=200).
• After calling parsePlot on every ggplot, animint2dir analyzes the plots and options to determine if the plot is animated, the first selection, etc.
• The final job of animint2dir is to save the plot.json meta-data file. It contains all of the data about variable names, chunks, legends, geom types, selectors, etc. But it contains none of the actual data to plot (those data were already saved in TSV files for each chunk).

Logic behind separating data into chunks

The animint compiler outputs 1 plot.json file and a TSV file for every chunk. This makes rendering the plot super fast for large data sets: to draw plot at first, you only need to download the plot.json and the first chunk shown onscreen.