System and Model Entity Relationships

Overview

This vignette provides a structural view of the core C++ / R interface objects in the bayestransmission package: models, parameter components, system histories, and events. It complements function-level documentation by showing how likelihood evaluation traverses linked event histories (HistoryLink) and consumes parameter components from the active model.

High-Level Data Flow

You create parameter lists in R (e.g. LogNormalModelParams() or LinearAbxModel()).
newCppModel() calls into C++ and constructs a concrete model (e.g. CppLogNormalModel).
A System is built from raw event data (facility, unit, time, patient, type).
A SystemHistory indexes events by unit and patient via HistoryLink objects.
The model’s logLikelihood() iterates over HistoryLinks, combining gap and event contributions from each parameter component (InColParams, OutColParams, InsituParams, test parameters, antibiotics).

Mermaid Class Diagram

Below we attempt to render the Mermaid diagram. If DiagrammeR is not installed, a fallback textual representation is shown.

Entity Relationships (ER)

An alternate ER-style view emphasizing cardinalities:

Note: MODEL here abstracts over any concrete Cpp*Model instance created by newCppModel().

Practical Usage Example

library(bayestransmission)
params <- LogNormalModelParams("LogNormalModel")
model <- newCppModel(params)
# Build a minimal empty system to demonstrate object creation
sys <- CppSystem$new(integer(0), integer(0), numeric(0), integer(0), integer(0))
hist <- CppSystemHistory$new(sys, model, FALSE)
model$logLikelihood(hist)  # should be 0 with no events

Design Rationale

Splitting parameters into distinct components enables targeted updates and diagnostic decomposition of the likelihood. HistoryLink objects provide both sequential (unit-level) and patient-level traversal, allowing gap contributions (time intervals) and instantaneous event contributions to be combined cleanly.

Extensibility

To add a new model variant:

Implement a new C++ class deriving from CppLogNormalModel (or CppBasicModel).
Expose it in the Rcpp Module and add a branch in newModel() and newCppModelInternal().
Provide a constructor helper NewModelParams() mirroring existing parameter list structure.
Update this vignette’s diagram if new parameter components or relationships are introduced.