---
title: "Implement Modular Computational Health Economic Models"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Implement Modular Computational Health Economic Models}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE, warning = FALSE)
```
```{r results='hide', message=FALSE, warning=F}
library(ready4) 
```
```{r echo=FALSE, eval=FALSE}
# The social, economic and service systems that shape population health are complex and thus can be challenging to model. Some health economic modelling projects may therefore be more tractable if broken into smaller tasks and advanced by multiple teams. Such phased and collaborative approaches can be facilitated by use of common frameworks for the development of computational models that are both open and modular. A model module can be used to model a discrete component of a health economic system. 
```

## Motivation
A potentially attractive approach to modelling complex health systems is to begin with a relatively simple computational model and to progressively extend its scope and sophistication. Such an approach could be described as "modular" if it is possible to readily combine multiple discrete modelling projects (potentially developed by different modelling teams) that each independently describe distinct aspects of the system being modelled. 

## Implementation
The `ready4` facilitates modular model development by supplying a template module that enables model developers to avail of the [encapsulation and inheritance features of Object Oriented Programming (OOP)](https://www.ready4-dev.com/docs/framework/implementation/paradigm/object-oriented/). The [ready4 framework](https://www.ready4-dev.com/) uses two of R's systems for implementing OOP - S3 and S4. An in-depth explanation of R's different class system is beyond the scope of this article, but is explored in [Hadley Wickham's Advanced R handbook](https://adv-r.hadley.nz/oo.html). However, it is useful to know some very high level information about S3 and S4 classes:

 - S4 classes are frequently said to be "formal", "strict" or "rigorous". The elements of an S4 class are called slots and the type of data that each slot is allowed to contain is specified in the class definition. An S4 class can be comprised of slots that contain different types of data (e.g. a slot that contains a character vector and another slot that contains tabular data). 
 
 - S3 classes are often described as "simple", "informal" and "flexible". S3 objects attach an attribute label to base type objects (e.g. a character vector, a data.frame, a list), which in turn is used to work out what methods should be applied to the class. 
 
## Use

### ready4 Model Modules
As we use the term, a "model module" is comprised of both a data-structure (an S4 class) and the algorithms (or "methods") that are associated with that data-structure. Model modules can be created from a template - the `ready4` package's `Ready4Module` class. 

We can create an object (`X`) from the `Ready4Module` template using the following command.

```{r}
X <- Ready4Module()
```

However, if we inspect `X` we can see it is of limited use as it contains no data other than an empty element called `dissemination_1L_chr`.

```{r}
str(X)
```

The `Ready4Module` class is therefore not intended to be called directly. Instead, the  purpose of `Ready4Module` is to be the parent class of other model modules. Prototype tools for authoring modules from this template are described [here](https://www.ready4-dev.com/docs/tutorials/develop-models/authoring-modules/).

::: {.card .border-primary .mb-3 style="max-width: 20rem;"}

::: {.card-header}
**ready4 Concept**
:::

::: {.card-body}
::: {.card-title}
#### Module
:::
An instance of `Ready4Module` (or classes that inherit from `Ready4Module`) and its associated methods.
:::
:::

### ready4 Model Sub-modules
In ready4, S3 classes are principally used to help define the structural properties of slots (elements) of model modules and the methods that can be applied to these slots. S3 classes created for these purposes are called **sub-modules**.
 
::: {.card .border-primary .mb-3 style="max-width: 20rem;"}

::: {.card-header}
**ready4 Concept**
:::

::: {.card-body}
::: {.card-title}
#### Sub-Module
:::
An instance of an informal (S3) class and its associated methods that describes, validates and applies algorithms to a slot of a Module.
:::
:::