Skip to contents

Developer Guide Overview

Brian S. Yandell

03 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 the data/ folder: - default.xlsx: The complete baseline spreadsheet containing all configuration parameters (features, risks, transitions, substrates, and temperature splines). - simdata.rda: Pre-computed discrete simulation runs used for envelope testing. - Flat .txt files: Single-sheet tabular versions of all parameters used for automated unit tests (e.g. organism.features.txt, future.host.txt).

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), Leaflet GIS explorers (leafletApp.R), and developer test applications (futureApp, initApp).

3. Complete File & Module Index

Below is an index of all Shiny app 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.
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.
leafletApp.R leafletServer() leafletInput(), leafletOutput() GIS Companion App Provides interactive map click tracking, connecting dynamically with USGS boundary layers.
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.