---
title: "Package Structure"
package: mmrm
output:
  rmarkdown::html_vignette:
          toc: true
vignette: |
  %\VignetteIndexEntry{Package Structure}
  %\VignetteEncoding{UTF-8}
  %\VignetteEngine{knitr::rmarkdown}
editor_options:
  chunk_output_type: console
---

# Introduction

As `mmrm` package is built on `TMB` with complex structure, it might be hard for new developers to onboard.
To make it easier for new developers to join, this documentation is created.

# Package Structures

`mmrm` is an R package, and the following sections describe all files/folders that are contained in this package as well as the repository.

## `data`

The `data/` folder is where `mmrm` example data sets is stored.
See the documentation for [`fev_data`](https://openpharma.github.io/mmrm/main/reference/fev_data.html) and [`bcva_data`](https://openpharma.github.io/mmrm/main/reference/bcva_data.html) for details.

## `data-raw`

The `data-raw/` folder contains source code to produce simulated example data sets.
Currently it contains `bcva_data.R` (and its associated helper file) producing the `bcva_data` data set,
and the cached results for comparing mmrm and other implementations.

## `design`

The `design/` folder is where design documents, prototype scripts and SAS code for comparisons are stored.
When we have a new idea for a specific implementations, we can add our design doc including prototype implementations in an `Rmd` file in this folder.

Note that this folder is not part of the actual R package but only part of the git repository.
Different folders contain R scripts and `Rmd` files for different topics, for example:

### `SAS`

The `design/SAS/` folder contains programs to run MMRM models in SAS and the corresponding SAS outputs.
The results will be used for integration tests (see [integration tests](../CONTRIBUTING.html#add-integration-tests)).

### `TMB`

The `design/TMB/` folder is where prototypes of the first `mmrm` implementations with `TMB` are stored.

## `inst`

Files in the `inst/` folder will be kept after installation of the R package.

- `jss.csl` is specifying the Journal of Statistical Software citation style used by `Rdpack` references.
- `REFERENCES.bib` keeps a list of all referenced literature.
- `WORDLIST` is kept up-to-date for all non-English words, allowing the package to pass a spell-checker.

## `man`

The `man/` folder contains all function documentation generated by `roxygen2`.
Please do not edit any file in this folder, otherwise you may run into problems.

## `NAMESPACE`

Since we use `roxygen2` also the `NAMESPACE` file is automatically generated and usually does not need to be edited manually. 

Note that there can be exceptions, e.g. when removing a previously exported function from the package, in which case a manual deletion of the corresponding entry might be necessary to unblock `roxygen2`.

## `NEWS.md`

This file lists the user facing changes (new features, bug fixes, etc.) and should be updated during the development and cleaned before each release. It is important for the user experience to understand the changes between the releases.

## `R`

This folder contains all the source code written in R, just like every other R packages.
Please refer to the [documentation page](https://openpharma.github.io/mmrm/main/reference/) for details of the user facing API.

## `README`

We use the `Rmd` file `README.Rmd` and knit this to the corresponding `md` file. This file specifies the landing page on the `pkgdown` website and the GitHub repository and should hence be nice, succinct and clean.

## `simulations`

This folder contains simulation scripts and results to compare `mmrm` with other software or modifications in `mmrm`. Please refer to the `README` files in the subfolders for details.

## `src`

This folder includes all the source code written in `C++`, either using `Rcpp` or `TMB` frameworks.

### `chol_cache.h`

This file contains classes for caching the Cholesky factorizations efficiently.

### `covariance.h`

This file includes the implementations of covariance structures with suitable parameterization,
and the calculation of lower triangular part of Cholesky factorization of the covariance matrix.

For more about the implementations and why Cholesky factorization is needed, see the  [model fitting algorithm](algorithm.html#covariance-matrix-model) vignette.

For more about covariance structures, see the [covariance structures](covariance.html) vignette.

### `derivatives.h`

This file contains classes to enable automatic differentiation calculation which are important for the coefficient covariance matrix calculations and Kenward-Roger and Satterthwaite degrees of freedom calculations.

### `empirical.cpp`

This file implements the coefficient covariance matrix calculations.

### `exports.cpp`

This file contains the `Rcpp` interfaces to the coefficient covariance matrix, Kenward-Roger, Jacobian and prediction calculations.

### `jacobian.cpp`

This file implements the Jacobian calculations which are needed for the Satterthwaite degrees of freedom.

### `kr_comp.cpp`

This file implements the `P`, `Q` and `R` matrix calculations which are needed for the Kenward-Roger degrees of freedom.

### `Makevars`

This file specifies additional flags used in the source code compilation. 
We ask `TMB` to use the `TMB` automatic differentiation framework (instead of the default `CppAD` framework) to be more efficient, and disable useless warnings from the `Eigen` library compilation.

Note that additional flags such as `-Wno-ignored-attributes` cannot be included here because they are compiler specific. These can instead be specified in local `~/.R/Makevars` files.

### `mmrm.cpp`

This file is the core part where the likelihood is calculated.
The objective function reads input from R and performs the calculations inside.

### `predict.cpp`

This file implements the prediction calculations.

### test files

Files starting with `test-` are tests or helper files to run tests.
(It is important to also aim for high unit test coverage of the source code.)

### `tmb.cpp` and `tmb_includes.h`

These two files includes the TMB module.

### `utils.h`

This files includes utilities that used internally.

## `tests`

The `tests/` folder includes all the unit tests for the R functions, using the `testthat` package.

## `vignettes`

The `vignettes/` folder includes `Rmd` documentation files to helps the user understand more about the usage, detail, etc. These vignettes are rendered into `.html` files which are deployed on the package website.

## Other files

There are other files that can be helpful in package development and are used in `mmrm`.

### `_pkgdown.yml`

This file is the configuration file for our `pkgdown`-based website.
`pkgdown` is used to covert our package documentation (`man/`, `vignettes/`) into our package website.

For more, visit [pkgdown documentation](https://pkgdown.r-lib.org/).

### `.gitignore`

This file will specify untracked files/file patterns that git should ignore.

### `.lintr`

This file serves as configuration for `lintr` to do the static code analysis.
Please install `lintr` package in your developing system to enable the analysis.
It will provide you information about errors, style issues, etc.

For more, visit [lintr documentation](https://lintr.r-lib.org/).

### `.pre-commit-config.yaml`

This file includes the configurations that we use for `pre-commit`.
`pre-commit` is a tool that help us identify simple issues before we submit our code.
For more, visit [pre-commit documentation](https://pre-commit.com/).

### `.Rbuildignore`

This file specifies which files and folders in the repository should not be included when building the R package. 

Please note that it is important to know that these are regular expressions. Hence, when we want to specify an exact file name we need to use e.g. the `^cache$` format, just using `cache` instead could match additional files or folders with `cache` being part of the name. This can lead to problems.