Skip to contents

Developer Guide Overview

Brian S. Yandell

10 August 2026

index.Rmd

This document is the main Developer Guide for the ewing package. It serves as a comprehensive developer onboarding resource detailing the package architecture, internal state structures, Shiny module systems, and mathematical coordinate mappings.

This developer guide is structured similarly to the qtl2shiny Developer Guide. See devel_guide.md for the process and design prompts used to build this documentation.

Table of Contents

1. Data Structures and Folder Organization

The package source files reside inside R/ (modular source functions and Shiny sub-modules) and inst/ (external metadata, configurations, and scripts).

The State Object (community)

At the center of any simulation run is a S3 class object of type community, created by init.simulation(). The community structure comprises: - pop: A matrix for each species storing individual attributes. Rows are feature attributes, and columns map to individuals O(n). - org: Organism feature thresholds and rates. - temp: Environmental temperature and degree-day spline thresholds. - count: Historical counts and logs.

For detailed information on state matrices, see dataorg.md.

Input Configurations (Excel & Text files)

The default parameters and connectivity tables are stored under inst/extdata/ and data/: - inst/extdata/default/: Core default simulation organism tables (organism.features.txt, future.host.txt, future.parasite.txt, host.parasite.txt, substrate.host.txt, substrate.parasite.txt, substrate.substrate.txt, temperature.base.txt, temperature.par.txt). - default.xlsx: Baseline Excel spreadsheet containing all configuration parameter sheets. - simdata.rda: Pre-computed discrete simulation runs used for envelope testing.

2. Detailed Sub-Guides

Click the links below to explore specific technical areas of the codebase:

  1. Module Architecture & Flow Understand the high-level layout, modular communication using reactive interfaces, and the central download router framework.
  2. Simulation & Parameters Setup Examine how parameter worksheets are parsed (initParApp.R) and how simulations are stepped forward (simApp.R).
  3. Dynamic Visualizations Trace age class plotting (distPlotApp.R), spatial triangular grids (substrateApp.R), and confidence envelope bounds (envPlotApp.R).
  4. Utility & Companion Modules Explore file exports (downloadApp.R) and developer test applications (futureApp, initApp). Interactive Leaflet GIS exploration is provided by the standalone hexmap package.

3. Complete File & Module Index

Below is an index of all Shiny app and simulation engine files inside the R/ directory, mapped to their design roles:

Source File Module Server / Entry Point UI Hooks Primary Classification Description
ewingApp.R ewingServer() ewingInput(), ewingOutput() Primary Shiny Entry Point Orchestrates overall dashboard panels and handles reactive dynamic tabs switching between nsim = 1 and nsim > 1 modes.
ecosystem_sim.R init_ecosystem_sim() ggplot_ecosystem_sim() Generalized Engine Multi-landscape spatial simulation engine, stepping loops, and get_site_cache_file() site cache resolver.
ecosystemApp.R ecosystemServer() ecosystemInput(), ecosystemOutput() Generalized App Module Interactive multi-landscape simulation platform supporting dynamic site asset resolution.
isle_royale_sim.R init_isle_royale_sim() ggplot_isle_royale_sim() Wrapper Shell Isle Royale backward-compatible wrapper delegating to ecosystem_sim.R.
IsleRoyaleApp.R IsleRoyaleServer() IsleRoyaleInput(), IsleRoyaleOutput() Wrapper Shell Isle Royale Shiny app backward-compatible wrapper delegating to ecosystemApp.R.
initParApp.R initParServer() initParInput(), initParOutput() Configuration/Data Selector Reads default metadata, manages XLSX uploads, and renders HTML summaries of species attributes.
simApp.R simServer() simInput(), simUI() Simulation Orchestrator Renders control sliders for simulation bounds, tracks the nsim toggle, and runs step-wise stochastic iterations.
distPlotApp.R distPlotServer() distPlotInput(), distPlotOutput() Graphical Visualizer Computes and plots age class distribution overlays over runtime steps.
substrateApp.R substrateServer() substrateInput(), substrateOutput() Graphical Visualizer Renders spatial individual mapping on triangular substrates via coordinate translations.
envPlotApp.R envPlotServer() envPlotInput(), envPlotOutput() Graphical Visualizer Plots confidence envelopes of host-parasite numbers for multi-simulation bounds.
downloadApp.R downloadServer() downloadInput(), downloadOutput() Data Export Utility Binds to current plot and table outputs, writing cleanly formatted CSV tables and PDF documents with exit lock protections.
futureApp.R futureServer() futureInput(), futureOutput() Mini App / Debug Tool Independent interface evaluating single continuous future.events runs directly without iterations.
fivePlotApp.R fivePlotApp() (Standalone) Mini App / Explorer Tool Shiny explorer for 5-parameter curve adjustments with click-to-move interactive baseline splines.
fiveShowApp.R fiveShowApp() (Standalone) Mini App / Explorer Tool Shiny explorer for 5-parameter goal search adjustments with click-to-move interactive baseline splines.
fivetimeApp.R fivetimeApp() (Standalone) Mini App / Explorer Tool Shiny explorer showing parameter sensitivity and multi-parameter binary search target goal curves.
initApp.R initServer() initInput(), initOutput() Mini App / Debug Tool Visualizes starting substrate coordinate layouts and species statistics immediately upon initialization.
origEwingApp.R origEwingServer() origEwingInput(), origEwingOutput() Legacy Code (Deprecated) The original monolithic dashboard version preserved for historic regression validation.
multApp.R multServer() multInput(), multOutput() Legacy Code (Deprecated) Original multi-run app wrapper before modularization.