01-model-definition.Rmd

# Model Initialization

Before one may define the dynamics of their compartmental model they must initialize it using the `flexmodel` function. Here we describe each of the basic and required arguments to `flexmodel` and how to set them. This function allows one to define many details of the model, but in this chapter we cover just the requirements.

* Parameter vector
* State vector
* Start and end dates

Here is a simple SIR model example.

```{r init_model}
sir = flexmodel(
  params = c(beta = 0.1, gamma = 0.01, N = 100),
  state = c(S = 99, I = 1, R = 0),
  start_date = "2020-03-11",
  end_date = "2020-12-01"
)
```

::: {.infobox .caution data-latex="{caution}"}
To learn more about these options, please keep reading this chapter.

To continue building this simple SIR model, please move on to the next chapter, where you can define [Flow Between States].
:::

## Initial Parameter Vector

The parameter vector contains the following kinds of information.

* State transition rates or parameters determining them (e.g. transmission rate, $\beta$)
* Initial numbers of individuals in a compartment or group of compartments (e.g. initial number of exposed individuals, $E_0$)
* Data processing parameters to make observed and simulated time-series more comparable (e.g. fraction of incidence reported as positive tests, $c_\text{prop}$)

In its simplest form these parameters can be specified as a standard named numeric vector. We used this approach above in our SIR example, and this parameter vector can be extracted from the model.

```{r sir_params}
pars_base_sim(sir)
```

McMasterPandemic also has a special `params_pansim` object class for representing parameters. These objects come with descriptions of the meaning of each parameter. An example of this `params_pansim` format can be explored with the following command.

```{r ICU1_params}
rmarkdown::paged_table(describe_params(read_params('ICU1.csv')))
```

See the McMasterPandemic [getting started vignette](https://mac-theobio.github.io/McMasterPandemic/articles/getting_started.html) for more info on `params_pansim` objects.

## Initial State Vector

The state vector is used to declare the names of the state variables. In the SIR example above we did this via a named numeric vector, and these names become the names of the initial state vector.

```{r sir_state}
state_init(sir)
```

The numbers in this vector can be used as initial values in simulations, but often the initial values will depend on the parameters (see `do_make_state` TODO). In these cases where the initial state is computed as opposed to specified, the `state` argument to `flexmodel` can just be character vector giving the names of the state variables.

Classic McMasterPandemic also has a `state_pansim` object type (TODO: describe).

## Start and End Date

The simulation model takes a step every day. The `start_date` and `end_date` arguments give start and end of these simulations. The format of these dates can be supplied in any format that is accepted by `as.Date` without any formatting options.

## Next Steps

Models can be initialized with more complex features including time-varying parameters, hazard steps, and model linearization for computing state vectors that lead to greater stability (TODO: link to chapters/sections).

But before getting to these complexities there is something more important: definition of the flows of individuals amongst the states (TODO: link to next chapter).