Graphical Visualization Modules

Brian S. Yandell

03 August 2026

This sub-guide covers the three visual rendering engines designed to display simulation results: the age-class distribution plot (distPlotApp), the spatial substrate coordinate plotter (substrateApp), and the multi-run envelope graph (envPlotApp).

---

1. Age Class Distributions (distPlotApp)

Defined in R/distPlotApp.R, this panel shows the continuous population demographics (number of individuals grouped by age classes over simulation steps).

Components

• distPlotInput(): Displays configuration check-boxes:
  • Normalize Plot: Toggle relative frequencies per stage class.
  • Include Total: Overlay a total population size line.
• distPlotOutput(): Allocates the plot frame widget on the dashboard.
• distPlotServer():
  • Validates if the active simulation resides under class ewing (single run mode).
  • Triggers ewing_ageclass() to discretize state structures into step-wise tables.
  • Returns a standard ggplot2::autoplot object.

---

2. Spatial Substrate Grid Mappings (substrateApp)

Defined in R/substrateApp.R, this panel maps individual spatial tracking over continuous substrates (e.g. host and parasite movements across leaves and fruits).

Components

• substrateOutput(): Renders the dynamic layout sized proportionally to the active species count.
• substrateServer():
  • Resolves individual coordinates from simres()$pop.
  • For each tracked species, it maps tridiagonal coordinates $(a, b, c)$ into Cartesian coordinates $(x, y)$ using ewing_substrate().
  • Uses cowplot::plot_grid() to arrange and output all sub-plots in a single unified graphic.

---

3. Multi-Simulation Envelope Intervals (envPlotApp)

Defined in R/envPlotApp.R, this panel renders the statistical bounds and confidence bands across multi-run iterations.

Components

• envPlotInput(): Displays the Confidence band checkbox.
• envPlotOutput(): Renders the multi-plot grid.
• envPlotServer():
  • Expects a multi-simulation output structure of class ewing_discrete.
  • Builds envelopes using ewing_envelopes().
  • Displays trajectories and confidence bands using ggplot_ewing_envelopes(). Confidence bands are only enabled if nsim >= 10.

---

4. Summary of Data Transformations & Visualizers

The visualizer components depend on dedicated data transformation classes:

Class Object	Creator Function	Visualizer Function	Description
ewing_ageclass	ewing_ageclass()	autoplot.ewing_ageclass()	Reshapes continuous logs into time-series buckets per stage.
ewing_substrate	ewing_substrate()	autoplot.ewing_substrate()	Converts tridiagonal positions onto 2D Cartesian grids.
ewing_envelopes	ewing_envelopes()	ggplot_ewing_envelopes()	Performs quantile calculations across multiple runs.