ENDOASSMsimulator

ENDOASSMsimulator is an R package for generating synthetic, analysis-ready multi-omics datasets for ENDOASSM workflow validation.

The simulator is not intended to predict real Arabidopsis microbiome dynamics. Its role is to create controlled plant-microbiome experiments with explicit ground truth, so downstream analyses can be tested against known biological and ecological relationships.

The simulated experiment follows a discretized soil-plant continuum:

bulk soil (BS) -> rhizosphere (RS) -> root endosphere (RT) -> shoot endosphere (ST)

Genotype, stress treatment and time affect latent host traits. These traits drive host molecular state, physiology, compartment environments and microbial assembly. Microbial abundance and process activity then drive microbial transcripts and metabolites. Host and microbial metabolite pools can also be merged into measured metabolomics features with origin ambiguity.

What The Package Produces

The package is organized into modular simulation layers:

Module	Function	Output class	Main output
M1	simulate_orchestration()	EndoassmDesign	experimental metadata, biological units, host traits, compartment environments, process targets, transition parameters, scenario truth
M2	simulate_microbial_abundance()	EndoassmMicrobialAbundance	strain/ASV abundance, microbial traits, accessory elements, ecological process activity, assembly truth
M3	simulate_microbial_transcriptome()	EndoassmMicrobialTranscriptome	microbial transcript features, true abundance, expected/observed counts, detection and effect truth
M4	simulate_host_transcriptome()	EndoassmHostTranscriptome	host transcript features, true abundance, expected/observed RNA-seq counts, module truth
M5	simulate_host_metabolome()	EndoassmHostMetabolome	host metabolite features, metabolic process state, true abundance, observed metabolomics intensities
M6	simulate_microbial_metabolome()	EndoassmMicrobialMetabolome	microbial metabolite features, producer maps, true abundance, observed metabolomics intensities
M7	simulate_merged_metabolome()	EndoassmMergedMetabolome	measured metabolomics features with host, microbial, shared, transformed and background origins
M8	simulate_physiology()	EndoassmPhysiology	plant physiological process state, true/expected/observed physiology values, measurement truth

Each module returns S4 objects containing both observed analysis tables and truth tables. The truth tables are intended for benchmarking method recovery, not for modelling real biological systems.

Configuration Input

The main input is an EndoassmSimConfig object. It defines:

• compartments and transitions
• design factors such as genotype, stress and time
• replication hierarchy
• batch structure
• baseline ecological process shares
• perturbations linking host traits to ecological process targets
• seed-pool settings
• random seed

Module-specific feature counts and technical parameters are supplied through named manifest lists. This keeps the experimental design separate from choices such as the number of host transcripts, microbial transcripts or metabolite features.

Configs can be created in R:

cfg <- default_endoassm_config(seed = 12345L)

or read from JSON/YAML:

obj <- read_endoassm_config("inst/examples/high_hes_drought_config.json")

cfg <- obj$config
manifests <- obj$manifests

The reader returns:

list(
  config = <EndoassmSimConfig>,
  manifests = <named list>
)

JSON configs can be written from R objects:

write_endoassm_config_json(
  config = cfg,
  manifests = manifests,
  path = "my_scenario.json"
)

Example Configs

The package includes executable example configs in inst/examples/:

• default_endoassm_config.json: default simulator configuration.
• high_hes_drought_config.json: high heterogeneous selection (HeS) drought versus well-watered control scenario with host transcript/metabolite sizes.
• high_hes_drought_microbial_omics_config.json: high HeS drought scenario with 100 microbial ASVs, 1000 microbial transcript features and 500 microbial metabolite features.

HeS values in these configs are simulator ground-truth process shares. They are not estimated from generated data and are not iCAMP outputs. The intended workflow is to generate data with known assembly-process truth, then run iCAMP or other inference methods externally and evaluate whether they recover the known signal.

Minimal Workflow

Host-side high-HeS drought example:

obj <- read_endoassm_config("inst/examples/high_hes_drought_config.json")

cfg <- obj$config
manifests <- obj$manifests

design <- simulate_orchestration(cfg)
microbes <- simulate_microbial_abundance(
  cfg, design,
  manifest = manifests$microbial_abundance
)
host_tx <- simulate_host_transcriptome(
  cfg, design,
  manifest = manifests$host_transcriptome
)
host_met <- simulate_host_metabolome(
  cfg, design, host_tx,
  manifest = manifests$host_metabolome
)
phys <- simulate_physiology(cfg, design, host_tx, host_met)

Microbial-omics high-HeS drought example:

obj <- read_endoassm_config(
  "inst/examples/high_hes_drought_microbial_omics_config.json"
)

cfg <- obj$config
manifests <- obj$manifests

design <- simulate_orchestration(cfg)
microbes <- simulate_microbial_abundance(
  cfg, design,
  manifest = manifests$microbial_abundance
)
micro_tx <- simulate_microbial_transcriptome(
  cfg, design, microbes,
  manifest = manifests$microbial_transcriptome
)
micro_met <- simulate_microbial_metabolome(
  cfg, design, microbes, micro_tx,
  manifest = manifests$microbial_metabolome
)

Example Output Tables

Common output tables include:

• sample metadata and biological-unit metadata
• latent host traits
• compartment environments
• process targets and transition parameters
• true strain and ASV abundance
• observed amplicon count tables
• transcript annotation and count tables
• metabolite annotation and intensity tables
• module summaries
• detection truth tables
• effect truth tables
• assembly truth tables

Most observed tables are stored in long format and include explicit identifiers such as sample_id, feature IDs, compartment/context labels and observed values.

Generated Data

Generated datasets are written locally under generated_data/ when scripts are run. This directory is intentionally ignored by git because CSV and RDS outputs can be large and are reproducible from the JSON configs and generator scripts.

Validation

The package includes testthat coverage for the orchestration module and all simulation modules. The currently used validation command is:

testthat::test_local(".")

For package-level checks:

R CMD build .
R CMD check --no-manual --no-build-vignettes ENDOASSMsimulator_0.1.0.tar.gz