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
and bcva_data
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).
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 byRdpack
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 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.
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 vignette.
For more about covariance structures, see the covariance structures 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.
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 specify here the use of C++14
such that
std::make_unique()
is available. Also 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.
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.
.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.
.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.
.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.