Asmmrm package is built onTMB withcomplex structure, it might be hard for new developers to onboard. Tomake it easier for new developers to join, this documentation iscreated.
mmrm is an R package, and the following sectionsdescribe all files/folders that are contained in this package as well asthe repository.
dataThedata/ folder is wheremmrm example datasets is stored. See the documentation forfev_dataandbcva_datafor details.
data-rawThedata-raw/ folder contains source code to producesimulated example data sets. Currently it containsbcva_data.R (and its associated helper file) producing thebcva_data data set, and the cached results for comparingmmrm and other implementations.
designThedesign/ folder is where design documents, prototypescripts and SAS code for comparisons are stored. When we have a new ideafor a specific implementations, we can add our design doc includingprototype implementations in anRmd file in thisfolder.
Note that this folder is not part of the actual R package but onlypart of the git repository. Different folders contain R scripts andRmd files for different topics, for example:
SASThedesign/SAS/ folder contains programs to run MMRMmodels in SAS and the corresponding SAS outputs. The results will beused for integration tests (seeintegrationtests).
TMBThedesign/TMB/ folder is where prototypes of the firstmmrm implementations withTMB are stored.
instFiles in theinst/ folder will be kept afterinstallation of the R package.
jss.csl is specifying the Journal of StatisticalSoftware citation style used byRdpack references.REFERENCES.bib keeps a list of all referencedliterature.WORDLIST is kept up-to-date for all non-English words,allowing the package to pass a spell-checker.manTheman/ folder contains all function documentationgenerated byroxygen2. Please do not edit any file in thisfolder, otherwise you may run into problems.
NAMESPACESince we useroxygen2 also theNAMESPACEfile is automatically generated and usually does not need to be editedmanually.
Note that there can be exceptions, e.g. when removing a previouslyexported function from the package, in which case a manual deletion ofthe corresponding entry might be necessary to unblockroxygen2.
NEWS.mdThis file lists the user facing changes (new features, bug fixes,etc.) and should be updated during the development and cleaned beforeeach release. It is important for the user experience to understand thechanges between the releases.
RThis folder contains all the source code written in R, just likeevery other R packages. Please refer to thedocumentationpage for details of the user facing API.
READMEWe use theRmd fileREADME.Rmd and knitthis to the correspondingmd file. This file specifies thelanding page on thepkgdown website and the GitHubrepository and should hence be nice, succinct and clean.
simulationsThis folder contains simulation scripts and results to comparemmrm with other software or modifications inmmrm. Please refer to theREADME files in thesubfolders for details.
srcThis folder includes all the source code written inC++,either usingRcpp orTMB frameworks.
chol_cache.hThis file contains classes for caching the Cholesky factorizationsefficiently.
covariance.hThis file includes the implementations of covariance structures withsuitable parameterization, and the calculation of lower triangular partof Cholesky factorization of the covariance matrix.
For more about the implementations and why Cholesky factorization isneeded, see themodelfitting algorithm vignette.
For more about covariance structures, see thecovariance structures vignette.
derivatives.hThis file contains classes to enable automatic differentiationcalculation which are important for the coefficient covariance matrixcalculations and Kenward-Roger and Satterthwaite degrees of freedomcalculations.
empirical.cppThis file implements the coefficient covariance matrixcalculations.
exports.cppThis file contains theRcpp interfaces to thecoefficient covariance matrix, Kenward-Roger, Jacobian and predictioncalculations.
jacobian.cppThis file implements the Jacobian calculations which are needed forthe Satterthwaite degrees of freedom.
kr_comp.cppThis file implements theP,Q andR matrix calculations which are needed for theKenward-Roger degrees of freedom.
MakevarsThis file specifies additional flags used in the source codecompilation. We askTMB to use theTMBautomatic differentiation framework (instead of the defaultCppAD framework) to be more efficient, and disable uselesswarnings from theEigen library compilation.
Note that additional flags such as-Wno-ignored-attributes cannot be included here becausethey are compiler specific. These can instead be specified in local~/.R/Makevars files.
mmrm.cppThis file is the core part where the likelihood is calculated. Theobjective function reads input from R and performs the calculationsinside.
predict.cppThis file implements the prediction calculations.
Files starting withtest- are tests or helper files torun tests. (It is important to also aim for high unit test coverage ofthe source code.)
tmb.cpp andtmb_includes.hThese two files includes the TMB module.
utils.hThis files includes utilities that used internally.
testsThetests/ folder includes all the unit tests for the Rfunctions, using thetestthat package.
vignettesThevignettes/ folder includesRmddocumentation files to helps the user understand more about the usage,detail, etc. These vignettes are rendered into.html fileswhich are deployed on the package website.
There are other files that can be helpful in package development andare used inmmrm.
_pkgdown.ymlThis file is the configuration file for ourpkgdown-based website.pkgdown is used tocovert our package documentation (man/,vignettes/) into our package website.
For more, visitpkgdowndocumentation.
.gitignoreThis file will specify untracked files/file patterns that git shouldignore.
.lintrThis file serves as configuration forlintr to do thestatic code analysis. Please installlintr package in yourdeveloping system to enable the analysis. It will provide youinformation about errors, style issues, etc.
For more, visitlintrdocumentation.
.pre-commit-config.yamlThis file includes the configurations that we use forpre-commit.pre-commit is a tool that help usidentify simple issues before we submit our code. For more, visitpre-commit documentation.
.RbuildignoreThis file specifies which files and folders in the repository shouldnot be included when building the R package.
Please note that it is important to know that these are regularexpressions. Hence, when we want to specify an exact file name we needto use e.g. the^cache$ format, just usingcache instead could match additional files or folders withcache being part of the name. This can lead toproblems.