Using ESM Format

Introduction

This vignette demonstrates how to define Mosaic visualizations using ESM (ECMAScript Module) format. ESM allows you to write specifications using JavaScript syntax with full access to Mosaic’s compositional API.

Example: Voronoi Diagram with ESM

This is the same voronoi diagram, but defined using ESM (JavaScript) format:

library(rMosaic)

# Generate synthetic penguins dataset
set.seed(42)
penguins_df <- data.frame(
  bill_length = rnorm(150, mean = 40, sd = 5),
  bill_depth  = rnorm(150, mean = 18, sd = 3),
  species     = sample(c("Adelie", "Gentoo", "Chinstrap"), 150, replace = TRUE)
)

# Define ESM spec as raw JavaScript text
voronoi_esm <- "
const $mesh = Param.value(0);
const $hull = Param.value(0);

export default vconcat(
  plot(
    voronoi(
      from('penguins'),
      { x: 'bill_length', y: 'bill_depth',
        stroke: 'white', strokeWidth: 1,
        strokeOpacity: 0.2, fill: 'species', fillOpacity: 0.2 }
    ),
    hull(
      from('penguins'),
      { x: 'bill_length', y: 'bill_depth',
        stroke: 'species', strokeOpacity: $hull, strokeWidth: 1.5 }
    ),
    delaunayMesh(
      from('penguins'),
      { x: 'bill_length', y: 'bill_depth', z: 'species',
        stroke: 'species', strokeOpacity: $mesh, strokeWidth: 1 }
    ),
    dot(
      from('penguins'),
      { x: 'bill_length', y: 'bill_depth',
        fill: 'species', r: 2 }
    ),
    frame(),
    width(680),
    height(480)
  ),
  hconcat(
    menu({
      label: 'Delaunay Mesh',
      options: [
        { value: 0,   label: 'Hide' },
        { value: 0.5, label: 'Show' }
      ],
      as: $mesh
    }),
    hspace(5),
    menu({
      label: 'Convex Hull',
      options: [
        { value: 0, label: 'Hide' },
        { value: 1, label: 'Show' }
      ],
      as: $hull
    })
  )
);
"

# Run the application with ESM spec
runMosaicApp(
  spec     = voronoi_esm,
  specType = "esm",
  data     = list(penguins = penguins_df),
  title    = "Voronoi Diagram (ESM)"
)

Advantages of ESM Format

  • Compositional API: Use functional composition for complex visualizations
  • Full JavaScript: Access to JavaScript’s expressiveness and control flow
  • Direct Mosaic API: Use Mosaic’s JavaScript API directly
  • Dynamic Logic: Easier to add conditional logic or computations

When to Use ESM

  • Complex visualizations requiring programmatic composition
  • When you’re familiar with Mosaic’s JavaScript API
  • Need advanced control flow or conditional rendering
  • Working from existing Mosaic JavaScript examples

Note: ESM specs run in the browser JavaScript environment and have access to the full Mosaic API, unlike YAML/JSON which are declarative formats. The rMosaic package automatically makes common vgplot functions (like Param, vconcat, plot, voronoi, etc.) available in the module scope, so you can use them directly without the vg. prefix. For functions not explicitly exposed, you can access them via the vg object (e.g., vg.coordinator()).

Comparison of Formats

Format Best For Complexity
YAML Simple specs in R Low
JSON External specs, APIs Low
ESM Advanced features Medium-High

For most use cases, YAML format (R lists) is recommended for its simplicity and R integration.