pre-release-introduction.Rmd

---
title: "Modelgraph"
subtitle: An R interface for the `tikz` \LaTeX{} package for making compartmental model flow diagrams
author: Éric Marty
header-includes:
   - \usepackage{array}
   - \tikzstyle{custom}=[fill=white, draw=black]
output:
  pdf_document:
    latex_engine: xelatex
    includes:
      in_header: modelgraphs.tex
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = T,
                      results = "hide")
```

```{css, echo=FALSE}
.body-code {
  background-color: white;
}
```


```{r functions, include=FALSE}
source("R/modelgraph.R")
```


# Introduction

Modelgraph is designed to produce flow diagrams for compartmental models, stored as \LaTeX{} code.

As such, Modelgraph works most seamlessly within an Rmarkdown document with PDF output, where the stored \LaTeX{} code can be embedded in the document directly.

However, the \LaTeX{} code can also be saved to a `.tex` file for inclusion elsewhere.

# Installation

*Requires R >= 4.0*

`modelgraph` is under active development. It will eventually be released as an R package. 
However, it is possible to use modelgraph now in its current state.

All you need to get started is the R script `R/modelgraph.R` and the LaTeX preamble file 
`modelgraphs.tex`.

# Basic setup

Create a Rmarkdown document with PDF output.

In the YAML header of the Rmd document, 
include the preamble file `modelgraphs.tex`, 
and specify `xelatex` as the latex engine. 
Other latex engines may incorrectly render opacity.

\definecolor{shadecolor}{RGB}{250,250,250}
```
  output:
    pdf_document: 
      latex_engine: xelatex
      includes:
        in_header: "modelgraphs.tex"
```

# Build a graph from dataframes of states and flows, using the `modelgraph()` R function.



In the R code, define dataframes of states, flows, and optionally groups.

The `modelgraph()` function takes the dataframes of states, flows and optionally groups of states, and outputs a fragment of \LaTeX{} code as a string. This string can be stored in an R object, and can be rendered in a PDF by using an in-line call to the R object in markdown. The R object can also be output to a `.tex` file. 

## The `states` dataframe:

\begin{tabular}{ l l p{12cm} }
 \texttt{name} & character & Internal name for the state (node), used when referring to the state in code. \\ 
 \texttt{label} & character & (Optional.) Label for the state (node). May included \LaTeX surrounded by \$~\$.
 If ommitted, \texttt{label} = \texttt{name}\\  
 \texttt{class} & character & (Optional.) One of a set of pre-defined "classes", used to set color of all states (nodes) with that class.\\
 \texttt{group} & character & (Optional.) Group to which the state belongs.\\ 
 \texttt{position} & character & (Optional.) Position of the state (node) relative to some other state. (See below) 
\end{tabular}

**Labels:** By default, the state name will be used as the label unless a label is supplied. To ensure no label is written at all, use `""` for the label. However, if `class` is `"invisible"`, no label will be printed for the state unless a label is explicitly supplied.

**Classes:** Predefined classes: "susceptible", "exposed", "infectious", "asymptomatic", "diagnosed", "hospitalized", "recovered", "deceased", "population", "environment", "system", "invisible" (useful for drawing flows from untracked states). It is possible to create custom classes with their own visual style. See Section: **Custom classes**, below.

**Groups:** States may be grouped. For example, you may have multiple Infectious states. A box will be drawn around all states of the same group. Group membership may be defined in the `group` column of the `states` dataframe, or as a list of states in the `states` column of the `groups` dataframe (see below).  Group membership defined in the `groups` dataframe overrides group memberships in the `states` dataframe. 

**Positioning:** By default, each state is drawn to the right of the last state (the previous row in the states dataframe). Explicit positioning of state nodes is specified in teh `position` column using `tikz` commands. For example, `right of=S` or `below left of=R` See <http://mirrors.ctan.org/graphics/pgf/base/doc/pgfmanual.pdf> for a complete syntax. Any simple linear model can be specified without a position column.

## The `flows` dataframe:

\begin{tabular}{ l l p{10cm} }
 \texttt{from} & character & Internal name for the source state (node). \\ 
 \texttt{to} & character & Internal name for the destination state (node). \\ 
 \texttt{label} & character & (Optional.) Label for the flow rate (edge). May include \LaTeX surrounded by \$~\$.\\ 
 \texttt{arrow.properties} & character & (Optional.) Properties of the arrow (edge), separated by commas. (See below.)\\
 \texttt{label.properties} & character & (Optional.) Properties of the label (edge label), separated by commas. (See below.)\\
\end{tabular}

**From and to:** Flows (edges) are defined by specifying the `from` and `to` states (nodes).

**Arrows:** By default, flows are drawn as straight arrows are drawn from source to destination states. Arrow styling can be changed by specifying properties as a single string of comma-separated values in the `arrow.properties` column. To produce curved arrows, it is sufficient to specify the exit angle from the source state, and the entry angle from the desintation state, e.g. `out=30, in=150`. Color, line style, thickness, etc. may also be set. See <http://mirrors.ctan.org/graphics/pgf/base/doc/pgfmanual.pdf> for details.

**Labels:** Labels may be provided, but are not required. Label positioning and styling is passed to `arrow.properties` as a comma-separated string. See <http://mirrors.ctan.org/graphics/pgf/base/doc/pgfmanual.pdf> for details.

## The `groups` dataframe:

\begin{tabular}{ l l p{12cm} }
 \texttt{name} & character & Internal name for the group, used when referring to the state in code. \\ 
 \texttt{label} & character & (Optional.) Label for the group. May include \LaTeX{} surrounded by \$~\$.
 If ommitted, \texttt{label} = \texttt{name}\\  
 \texttt{class} & character & (Optional.) One of a set of pre-defined "classes", used to set color of all states (nodes) with that class.\\
 \texttt{states} & list & (Optional.) List containing a character vector of state names belonging to the group, e.g. `list(c("E", "I"))`. If present, this column overrides the `group` column in the `states` dataframe.\\ 
\end{tabular}

## About \LaTeX{} in labels

\LaTeX{} is allowed in state, flow and group labels. \LaTeX{} must be surrounded with \$ \$, and slashes must be escaped with a second slash. Alternately, surround \LaTeX{} in with \$ \$ and then wrap using the `r"(...)"` raw string  mechanism (see `?Quote`).

## Example 1 (minimal example):

\definecolor{shadecolor}{RGB}{248,248,255}
```{r}
states <- data.frame(
  name = c("S", "I", "R")
  )
flows <- data.frame(
  from = c("S", "I"),
  to = c("I", "R"),
  label = c("$\\beta S I$","$\\gamma I$")
  )

# Compile a snipet of LaTeX from the dataframes of states and flows
minimal <- modelgraph(states = states, flows = flows)

```

In the body, use an in-line call to R to reference the object containing the modelgraph \LaTeX{} code. The code will be rendered when the document is knit to PDF.

\definecolor{shadecolor}{RGB}{250,250,250}
```{md, results = "hide"}
`r minimal`
```

`r minimal`

The figure can be resized by wrapping the call in \LaTeX{}. (Use `{\textwidth}` to resize the image to full width, `{.5\textwidth}` for 50\% of full width, etc.):

```{md, results = "hide"}
  \resizebox{\textwidth}{!}{`r minimal`}
```

\resizebox{\textwidth}{!}{`r minimal`}

## Example 2:

Here, we use predefined classes to color the states of an SEIRS model.  

We also group all states into the group called "N".

The curved arrow from R to S is created by specifying the angle the angle of the path out of R and in to S.

The label for the flow from R to S is moved below the arrow.

\definecolor{shadecolor}{RGB}{248,248,255}
```{r}

states <- data.frame(
  name = c("S", "E", "I", "R"),
  label = c("$S$", "$E$", "$I$", "$R$"),
  class = c("susceptible", "exposed", "infectious", "recovered"),
  group = c("N", "N", "N1", "N1"),
  position = c("","right of=S", "right of=E", "right of=I")
  )

flows <- data.frame(
  from = c("S", "E", "I", "R"),
  to = c("E", "I", "R", "S"),
  label = c("$\\beta S I$","$\\alpha E$", "$\\gamma I$", "$\\omega R$"),
  arrow.properties = c("","","","out=-150,in=-30"),
  label.properties = c("above","above", "above", "below")
  )

groups <- data.frame(
  name = c("N", "N1"),
  label = c("$N$", "$N1$"),
  class = c("population", "population")
)

# Group membership here is defined int he states dataframe. Alternately, group 
# pembership could be defined by adding a states column to the group dataframe.
#   groups$states <- list(c("S", "E", "I", "R"))

# Compile a snipet of LaTeX from the dataframes of states and flows
SEIRS_modelegraph <- modelgraph(states, flows, groups)
```

\definecolor{shadecolor}{RGB}{250,250,250}
```{md, results = "hide"}
  `r SEIRS_modelegraph`
```

`r SEIRS_modelegraph`

# Export the graph as a \TeX{} file (`.tex`)

\definecolor{shadecolor}{RGB}{248,248,255}
```{r}
# Save R object as a `.tex` fragment file
# This file will be have the extension ".tex" 
# and can be included in a LaTex or Rmd document
saveModelgraph(SEIRS_modelegraph, "SEIRS_modelegraph")

# # Save R object as a standalone `.tex` file
# This file will be have the extension ".tex" 
# and can be included in a LaTex or Rmd document or rendered to PDF directly.
# The page size is cropped to the dimensions of the tikz picture (modelgraph).
saveModelgraph(SEIRS_modelegraph, stem = "SEIRS_modelegraph_standalone", standalone=TRUE)

# Save as `.pdf` file (will also create a standalone .tex file).
# The page size is cropped to the dimensions of the tikz picture (modelgraph).
saveModelgraph(SEIRS_modelegraph, stem = "SEIRS_modelegraph_standalone", format="pdf")

# Save as `.png` file (will also create a standalone .tex file and a .pdf file).
# Default dpi is 300 (sufficient for publication).
saveModelgraph(SEIRS_modelegraph, stem = "SEIRS_modelegraph_standalone", format="png",
               dpi = 600)

# Save as `.tiff` file (will also create a standalone .tex file and a .pdf file).
# Default dpi is 300 (PLOS requires dpi in range 300-600).
# Default compression is "LZW" (required by PLOS). 
# Compression may be one of "none", "LZW", "PackBits", "RLE", "JPEG", "deflate".
saveModelgraph(SEIRS_modelegraph, stem = "SEIRS_modelegraph_standalone", format="tiff",
               dpi = 600, compression = "LZW")
```


# Include a \TeX{} fragment file built with `modelgraphs.tex`:

In the YAML header of the Rmd document, include the preamble file `modelgraphs.tex`:
```
  output:
    pdf_document: 
      includes:
        in_header: "modelgraphs.tex"
```

In the body of the Rmd document, include the model file using the \LaTeX{} command `\input{file}`:

```
  \resizebox{\textwidth}{!}{
    \input{stoch-fitting-v1.tex}
    }
```
  \resizebox{\textwidth}{!}{
    \input{stoch-fitting-v1.tex}
    }

## Inputting a standalone tex file

```
\resizebox{\textwidth}{!}{
  \input{SEIRS_modelegraph_standalone.tex}
  }
```

\resizebox{\textwidth}{!}{
  \input{SEIRS_modelegraph_standalone.tex}
  }

## Inputting a PDF created with `saveModelgraph()`

```
![](SEIRS_modelegraph_standalone.pdf){width=50%}
or `knitr::include_graphics("SEIRS_modelegraph_standalone.pdf")`
```

![](SEIRS_modelegraph_standalone.pdf){width=50%}

![](SEIRS_modelegraph_standalone.png){width=50%}

# Visual style

The file `modelgraphs.tex` is a \LaTeX{} preamble file that includes pre-defined TikZ styles for use in making compartmental flow dagrams. The `class` of a state or group is defined in the preable as a TikZ style. Styles are also used to control other aspects of the graph, such as opacity, outlining, positioning, etc.

The modelgraph classes and other styles have been designed with infectious disease modeling semantics in mind.

## Available state and group classes:##

\begin{tabular}{ l l p{12cm} }
 \texttt{susceptible} & \textcolor{susceptible.color}{\Huge$\bullet$} Blue \\ 
 \hline
 \texttt{exposed} & \textcolor{exposed.color}{\Huge$\bullet$} Yellow \\ 
 \texttt{latent} & \textcolor{latent.color}{\Huge$\bullet$} Yellow \\ 
 \hline
 \texttt{infectious} & \textcolor{infectious.color}{\Huge$\bullet$} Red \\ 
 \texttt{infected} & \textcolor{infectious.color}{\Huge$\bullet$} Red \\ 
 \texttt{symptomatic} & \textcolor{infectious.color}{\Huge$\bullet$} Red \\ 
 \texttt{asymptomatic} & \textcolor{infectious.color}{\Huge$\circ$} White with red outline \\
 \hline
 \texttt{diagnosed} & \textcolor{diagnosed.color}{\Huge$\bullet$} Grey \\ 
 \texttt{hospitalized} & \textcolor{hospitalized.color}{\Huge$\bullet$} Purple \\ 
 \hline
 \texttt{recovered} & \textcolor{recovered.color}{\Huge$\bullet$} Green \\ 
 \texttt{removed} & \textcolor{removed.color}{\Huge$\bullet$} Green \\ 
 \hline
 \texttt{deceased} & \textcolor{deceased.color}{\Huge$\bullet$} Dark Magenta \\ 
 \hline
 \texttt{population} & \textcolor{population.color}{\Huge$\bullet$} Grey \\ 
 \texttt{environment} & \textcolor{environment.color}{\Huge$\bullet$} Purple \\ 
 \texttt{undefined} & \textcolor{black}{\Huge$\circ$} White with black outline. \\ 
 \texttt{system} & White with thick dashed grey outline. \\ 
 \hline
 \texttt{invisible} & No circle is drawn. A label may still be drawn if desired.\\ 
\end{tabular}

Groups are drawn at a lower opacity than states.

Additional "add-on" classes may be used in combination with those above.

\begin{tabular}{ l l p{12cm} }
 \texttt{marked} & Outlines the circle in a thick, darker line of the same color.
\end{tabular}

Usage: Combine classes in a comma-separated string.

```{r}
states <- data.frame(name = c("S", "I_undetected", "I_detected"),
  label = c("$S$", "$I_u$", "$I_d$"),
  class = c("susceptible", "infectious", "infectious, marked")
  )
```

# Custom classes and styles

The color of a class can be redefined as by including the following code in the YAML header of the Rmd document.

Fire example to redefine the color of the `hospitalized` class as the hex color #3366FF, include the following command in your YAML header:

```
  header-includes:  
    - \definecolor{hospitalized.color}{HTML}{3366FF}
```

It is possible to create custom classes with manually defined visual styles.  

To do this, insert a `\tikzstyle{}` command in the YAML header, under `header-includes`.

For example, to create a custom class called "myclass" which will draw the state as a circle with a red outline and white fill, include the following code in the YAML header of the Rmd document:

```
  header-includes:  
    - \tikzstyle{myclass}=[fill = white, draw = red, draw opacity = 1.0]
```

Predefined classes may also be redefined in the same manner:

```
  header-includes:  
    - \tikzstyle{susceptible}=[fill = white, draw = blue, draw opacity = 1.0]
```

Before defining custom styles or redefining styles you should familiarize yourself with `modelgraphs.tex` to understand how styles interact. See <http://mirrors.ctan.org/graphics/pgf/base/doc/pgfmanual.pdf> for a complete syntax of tikz styles.

# Build a graph manually:

You still need `modelgraphs.tex` in the YAML header.

In the body of the Rmd document, instead of including a file or using the `modelgraph()` function, you can write \LaTeX{} `tikz` commands directly. See the documentation for TikZ at <http://mirrors.ctan.org/graphics/pgf/base/doc/pgfmanual.pdf> for the exhaustive syntax.

\LaTeX{} code needs to be treated as a "raw character string" by surrounding it with `r"(...)"`, where `...` is the \LaTeX{} code. 

Note, this mechanism for quoting raw character strings is only available in R version 4 and later. See `?Quote` for more information. To avoid conficts with strings than might be confused as quote delimiters, the mechanism provides for alternate ways to delimit the quoted strings. Here, for example, we use  `r"---(...)---"` to surround the code.

\definecolor{shadecolor}{RGB}{248,248,255}
```{r}
mygraph2 <- r"---(
  \begin{tikzpicture}[modelgraph]

    % states
      \node[susceptible]            (X)                         {$X$};
      \node[exposed]                (L)     [right of=X]        {$L$};
      \node[infectious]             (Y)     [right of=L]        {$Y$};
      \node[hospitalized]           (H)     [right=6cm of Y]    {$H$};
      \node[invisible]              (Yout)  [below of=Y]        {};
      \node[invisible]              (Hout)  [below of=H]        {};
      \node[deceased]               (D)     [right of=Hout]	    {$D$};
      \node[diagnosed]				(Z)     [above of=H]        {$Z$};
      \node[deceased, marked]       (Dr)    [right of=D]        {$D_r$};
      \node[hospitalized, marked]   (A)     [above of=Dr]       {$A$};
      \node[diagnosed, marked]		(Zr)    [above of=A]	    {$Z_r$};

    % flows
      \path [->] 
        
        (X) edge node[above] {infection\\$\frac{\beta_t X Y}{N}$} (L)
        
        (L) edge node[above] {onset of\\transmissibility\\$\eta L$} (Y)

        % (Y) edge[invisible] node {$p_{h,t} \gamma Y$\\hospitalization} (H)
        (Y) edge[invisible] node 
            {hospitalization\\
              $\left\{ 
                \begin{array}{ c l }
                  p_{h,t} p_{h,\mathrm{weekend}}\gamma Y, & \textrm{if weekend} \\
                  p_{h,t} \gamma Y, & \textrm{otherwise}
                \end{array}
              \right.$} 
            (H)
        
        (Y) edge[out=30,in=135] node {} (H)
        (Y) edge[out=30,in=195] node {} (Z)
        (Y) edge[out=30,in=150] node[above = .25cm, near end] 
            {admissions\\reporting} 
            (A)
       
        (Y) edge node[left, align=right, near end] 
            {recovery of undetected infections\\$(1-p_{h,t}) (1-\rho_t) \gamma Y$} 
            (Yout)
            
        (Y) edge[out=90,in=175] node[above = .25cm]
            {detection\\$(1-p_{h,t}) \rho_t \gamma Y$} 
            (Z)

        (Z) edge node[above] {case reporting\\$\gamma_{z,w} Z$} (Zr)

        (H) edge node[left, align=right, near end]
            {recovery\\$(1-p_d)\gamma_h H$}
            (Hout)

        (H) edge node[above right, align = left] {death\\$p_d \gamma_h H$} (D)

        (D) edge node[above] {death\\reporting\\$\gamma_{d,w} D$} (Dr)
        ;
        
    % groups
    \begin{scope}[on background layer]
      \node[nodegroup, diagnosed, fit=(Zr) (A) (Dr),
        label={[diagnosed.color]\textsc{reports}}] (reports) {};
    \end{scope}

    % annotations
    \node [grouplabel, above = .55cm, color=susceptible.color] 
      at (X) {\textsc{susceptible}};
    \node [grouplabel, above = 1 cm, color=exposed.color] 
      at (L) {\textsc{latent}};
    \node [grouplabel, above = 1 cm, align = right, color=infectious.color] 
      at (Y) {\textsc{Infectious}};
    \node [grouplabel, right, color=hospitalized.color] 
      at (H) {\textsc{hospitalized}};
    \node [grouplabel, below = 0, color=deceased.color] 
      at (D) {\textsc{deceased}};
    \node [grouplabel, above = .25cm, color=diagnosed.color] 
      at (Z) {\textsc{diagnosed}};
    \node [grouplabel, text width=1in, right = 1, color=diagnosed.color] 
      at (Zr) {\textsc{case\\reports}};
    \node [grouplabel, text width=1in, right = 1, color=hospitalized.color] 
      at (A) {\textsc{admission\\reports}};
    \node [grouplabel, text width=1in, right = 1, color=deceased.color] 
      at (Dr) {\textsc{death\\reports}};
        

\end{tikzpicture}
)---"


```

The raw string stored in an R object is rendered using an in-line call to R in the body text, as before.

\definecolor{shadecolor}{RGB}{250,250,250}
```{md, results = "hide"}
  \begin{figure}
    \resizebox{\textwidth}{!}{
      `r mygraph2`
      }
    \caption{Graph generated from raw TikZ commands}
  \end{figure}
```

\begin{figure}
  \resizebox{\textwidth}{!}{
    `r mygraph2`
    }
  \caption{Graph generated from raw TikZ commands}
\end{figure}