220913: minor improvements in presentation

.Rbuildignore

@@ -7,3 +7,5 @@
 ^codecov\.yml$
 ^CRAN-RELEASE$
 ^\.github$
+^doc$
+^Meta$

.gitignore

@@ -5,3 +5,5 @@
 doc
 Meta
 inst/doc
+/doc/
+/Meta/

DESCRIPTION

@@ -2,7 +2,7 @@ Package: SimCorMultRes
 Type: Package
 Title: Simulates Correlated Multinomial Responses
 Description: Simulates correlated multinomial responses conditional on a marginal model specification.
-Version: 1.8.0
+Version: 1.8.1
 Depends: R(>= 2.15.0)
 Imports:
     evd,
@@ -15,6 +15,7 @@ Suggests:
     knitr,
     multgee (>= 1.2),
     rmarkdown,
+    R.rsp,
     testthat
 Authors@R:
     person(given = "Anestis",
@@ -26,7 +27,9 @@ Authors@R:
 URL: https://github.com/AnestisTouloumis/SimCorMultRes
 BugReports: https://github.com/AnestisTouloumis/SimCorMultRes/issues
 License: GPL-3
-VignetteBuilder: knitr
-RoxygenNote: 7.1.1
+VignetteBuilder: 
+    knitr,
+    R.rsp
+RoxygenNote: 7.2.1
 Roxygen: list(old_usage = TRUE)
 Encoding: UTF-8

README.Rmd

@@ -22,6 +22,7 @@ csl: biometrics.csl
 ```{r setup, include=FALSE}
 knitr::opts_chunk$set(
   tidy = TRUE,
+  tidy.opts = list(width.cutoff = 80),
   collapse = TRUE,
   comment = "#>",
   fig.path = "README-"
@@ -66,22 +67,20 @@ The source code for the development version of `SimCorMultRes` is available on g
 To use `SimCorMultRes`, you should load the package as follows:
 
 ```{r}
-library(SimCorMultRes)
+library("SimCorMultRes")
 ```
 
 ## Usage and functions
 
-This package provides functions to simulate correlated binary, ordinal and nominal responses, which are drawn as realizations of a latent regression model for continuous random vectors as proposed by @Touloumis2016.
+This package provides five core functions to simulate correlated binary (`rbin`), nominal (`rmult.bcl`) and ordinal (`rmult.acl`, `rmult.clm` and `rmult.crm`) responses, which are drawn as realizations of a latent regression model for continuous random vectors as proposed by @Touloumis2016:
 
-
-There are five core functions:
-
-- `rbin` to simulate correlated binary responses,
-- `rmult.bcl` to simulate correlated nominal multinomial responses,
+- `rbin` to simulate correlated binary responses under a marginal model with logit, probit, cloglog and cauchit link function,
+- `rmult.bcl` to simulate correlated nominal multinomial responses under a marginal baseline-category logit model,
 - `rmult.acl` to simulate correlated ordinal responses under a marginal adjacent-category logit model,
 - `rmult.clm` to simulate correlated ordinal responses under a marginal cumulative link model,
-- `rmult.clm` to simulate correlated ordinal responses under a marginal continuation-ratio link model.
+- `rmult.crm` to simulate correlated ordinal responses under a marginal continuation-ratio link model.
 
+All five functions, assume that you provide either the correlation matrix of the multivariate normal distribution in NORTA (via `cor.matrix`) or the latent responses (via the `rlatent`). 
 
 There are also two utility functions:
 
@@ -96,15 +95,22 @@ The following R code illustrates how to use the core function `rbin`:
 ```{r}
 ## See Example 3.5 in the Vignette.
 set.seed(123)
+## define number of random vectors
 sample_size <- 100
+## define size of each random vector
 cluster_size <- 4
+## define intercept of the binary probit regression model
 beta_intercepts <- 0
+## define coefficients of the explanatory variables
 beta_coefficients <- 0.2
-latent_correlation_matrix <- toeplitz(c(1, 0.9, 0.9, 0.9))
+## provide explanatory variables
 x <- rep(rnorm(sample_size), each = cluster_size)
+## define correlation matrix for the multivariate normal distribution in NORTA
+latent_correlation_matrix <- toeplitz(c(1, 0.9, 0.9, 0.9))
+## use rbin function to create the desired dataset
 simulated_binary_responses <- rbin(clsize = cluster_size,
                                    intercepts = beta_intercepts,
-                                   betas = beta_coefficients, xformula = ~x,
+                                   betas = beta_coefficients, xformula = ~  x,
                                    cor.matrix = latent_correlation_matrix,
                                    link = "probit")
 library(gee)

README.md

@@ -4,7 +4,7 @@
 # SimCorMultRes: Simulates Correlated Multinomial Responses
 
 [![Github
-version](https://img.shields.io/badge/GitHub%20-1.8.0-orange.svg)](%22commits/master%22)
+version](https://img.shields.io/badge/GitHub%20-1.8.1-orange.svg)](%22commits/master%22)
 [![R-CMD-check](https://github.com/AnestisTouloumis/SimCorMultRes/workflows/R-CMD-check/badge.svg)](https://github.com/AnestisTouloumis/SimCorMultRes/actions)
 [![Project Status: Active The project has reached a stable, usable state
 and is being actively
@@ -47,27 +47,32 @@ available on github at:
 To use `SimCorMultRes`, you should load the package as follows:
 
 ``` r
-library(SimCorMultRes)
+library("SimCorMultRes")
 ```
 
 ## Usage and functions
 
-This package provides functions to simulate correlated binary, ordinal
-and nominal responses, which are drawn as realizations of a latent
+This package provides five core functions to simulate correlated binary
+(`rbin`), nominal (`rmult.bcl`) and ordinal (`rmult.acl`, `rmult.clm`
+and `rmult.crm`) responses, which are drawn as realizations of a latent
 regression model for continuous random vectors as proposed by Touloumis
-(2016).
+(2016):
 
-There are five core functions:
-
--   `rbin` to simulate correlated binary responses,
--   `rmult.bcl` to simulate correlated nominal multinomial responses,
+-   `rbin` to simulate correlated binary responses under a marginal
+    model with logit, probit, cloglog and cauchit link function,
+-   `rmult.bcl` to simulate correlated nominal multinomial responses
+    under a marginal baseline-category logit model,
 -   `rmult.acl` to simulate correlated ordinal responses under a
     marginal adjacent-category logit model,
 -   `rmult.clm` to simulate correlated ordinal responses under a
     marginal cumulative link model,
--   `rmult.clm` to simulate correlated ordinal responses under a
+-   `rmult.crm` to simulate correlated ordinal responses under a
     marginal continuation-ratio link model.
 
+All five functions, assume that you provide either the correlation
+matrix of the multivariate normal distribution in NORTA (via
+`cor.matrix`) or the latent responses (via the `rlatent`).
+
 There are also two utility functions:
 
 -   `rnorta` for simulating continuous or discrete random vectors with
@@ -82,12 +87,19 @@ The following R code illustrates how to use the core function `rbin`:
 ``` r
 ## See Example 3.5 in the Vignette.
 set.seed(123)
+## define number of random vectors
 sample_size <- 100
+## define size of each random vector
 cluster_size <- 4
+## define intercept of the binary probit regression model
 beta_intercepts <- 0
+## define coefficients of the explanatory variables
 beta_coefficients <- 0.2
-latent_correlation_matrix <- toeplitz(c(1, 0.9, 0.9, 0.9))
+## provide explanatory variables
 x <- rep(rnorm(sample_size), each = cluster_size)
+## define correlation matrix for the multivariate normal distribution in NORTA
+latent_correlation_matrix <- toeplitz(c(1, 0.9, 0.9, 0.9))
+## use rbin function to create the desired dataset
 simulated_binary_responses <- rbin(clsize = cluster_size, intercepts = beta_intercepts,
     betas = beta_coefficients, xformula = ~x, cor.matrix = latent_correlation_matrix,
     link = "probit")
@@ -139,8 +151,9 @@ browseVignettes("SimCorMultRes")
 
 <div id="ref-Touloumis2016" class="csl-entry">
 
-Touloumis, A. (2016) Simulating Correlated Binary and Multinomial
-Responses under Marginal Model Specification: The SimCorMultRes Package.
+Touloumis, A. (2016) [Simulating Correlated Binary and Multinomial
+Responses under Marginal Model Specification: The SimCorMultRes
+Package](https://journal.r-project.org/archive/2016/RJ-2016-034/index.html).
 *The R Journal*, **8**, 79–91.
 
 </div>

inst/NEWS.Rd

@@ -1,7 +1,17 @@
 \name{NEWS}
 \title{NEWS file for the \pkg{SimCorMultRes} package}
 
+\section{Changes in Version 1.8.1 (2022-09-13)}{
+  \subsection{MINOR CHANGES}{
+  \itemize{
+    \item{Improved README.Rmd.}
+    \item{Added `R` journal paper as vignette.}
+    }
+    }
+    }
+
 \section{Changes in Version 1.8.0 (2021-06-10)}{
+  \subsection{MINOR CHANGES}{
   \itemize{
     \item{Corrected naming of variables in formula.}
     \item{Added \code{identity} link in \code{rbin}.}
@@ -12,6 +22,7 @@
     \item{Fixed ORCID in DESCRIPTION.}
     }
     }
+    }
 
 
 \section{Changes in Version 1.7.0 (2019-07-25)}{

vignettes/SimCorMultRes.Rmd

@@ -51,7 +51,7 @@ and where the random variables $\{e^{NO}_{itj}:i=1,\ldots,N \text{,  } t=1,\ldot
 1. $e^{NO}_{itj_1}$ and $e^{NO}_{itj_2}$ are independent random variables provided that $j_1\neq j_2$.
 
 For each subject $i$, the association structure among the clustered nominal responses $\{Y_{it}:t=1,\ldots,T\}$ depends on the joint distribution and correlation matrix of $\{e^{NO}_{itj}:t=1,\ldots,T \text{ and } j=1,\ldots,J\}$. If the random variables $\{e^{NO}_{itj}:t=1,\ldots,T \text{ and } j=1,\ldots,J\}$ are independent then so are $\{Y_{it}:t=1,\ldots,T\}$.
-\newline{}
+
 
 ```{example, Example1, name="Simulation of clustered nominal responses using the NORTA method"}
 Suppose the aim is to simulate nominal responses from the marginal baseline-category logit model
@@ -126,7 +126,8 @@ and where $\{e^{O1}_{it}:i=1,\ldots,N \text{ and } t=1,\ldots,T\}$ are random va
 1. $e^{O1}_{i_1t_1}$ and $e^{O1}_{i_2t_2}$ are independent random variables provided that $i_1 \neq i_2$. 
 
 For each subject $i$, the association structure among the clustered ordinal responses $\{Y_{it}:t=1,\ldots,T\}$ depends on the pairwise bivariate distributions and correlation matrix of $\{e^{O1}_{it}:t=1,\ldots,T\}$. If the random variables $\{e^{O1}_{it}:t=1,\ldots,T\}$ are independent then so are $\{Y_{it}:t=1,\ldots,T\}$.
-\newline{} 
+
+
 ```{example, name="Simulation of clustered ordinal responses conditional on a marginal cumulative probit model with time-varying regression parameters"}
 Suppose the goal is to simulate correlated ordinal responses from the marginal cumulative probit model
 \begin{equation*}
@@ -183,7 +184,8 @@ and where $\{e^{O2}_{itj}:i=1,\ldots,N \text{ , } t=1,\ldots,T \text{ and } j=1,
 1. $e^{O2}_{itj_1}$ and $e^{O2}_{itj_2}$ are independent random variables provided that $j_1\neq j_2$.
 
 For each subject $i$, the association structure among the clustered ordinal responses $\{Y_{it}:t=1,\ldots,T\}$ depends on the joint distribution and correlation matrix of $\{e^{O2}_{itj}:j=1,\ldots,J \text{ and } t=1,\ldots,T\}$. If the random variables $\{e^{O2}_{itj}:j=1,\ldots,J \text{ and } t=1,\ldots,T\}$ are independent then so are $\{Y_{it}:t=1,\ldots,T\}$. 
-\newline{}
+
+
 ```{example,name="Simulation of clustered ordinal responses conditional on a marginal continuation-ratio probit model"}
 Suppose simulation of clustered ordinal responses under the marginal continuation-ratio probit model
 \begin{equation*}
@@ -246,7 +248,6 @@ and where the random variables $\{e^{O3}_{itj}:i=1,\ldots,N \text{,  } t=1,\ldot
 1. $e^{O3}_{itj_1}$ and $e^{O3}_{itj_2}$ are independent random variables provided that $j_1\neq j_2$.
 
 For each subject $i$, the association structure among the clustered ordinal responses $\{Y_{it}:t=1,\ldots,T\}$ depends on the joint distribution and correlation matrix of $\{e^{O3}_{itj}:t=1,\ldots,T \text{ and } j=1,\ldots,J\}$. If the random variables $\{e^{O3}_{itj}:t=1,\ldots,T \text{ and } j=1,\ldots,J\}$ are independent then so are $\{Y_{it}:t=1,\ldots,T\}$.
-\newline{} 
 
 ```{example, Example4, name="Simulation of clustered ordinal responses conditional on a marginal adjacent-category logit model using the NORTA method"}
 Suppose the aim is to simulate ordinal responses from the marginal adjacent-category logit model
@@ -318,7 +319,8 @@ and where $\{e^{B}_{it}:i=1,\ldots,N \text{ and } t=1,\ldots,T\}$ are random var
 1. $e^{B}_{i_1t_1}$ and $e^{B}_{i_2t_2}$ are independent random variables provided that $i_1 \neq i_2$.
 
 For each subject $i$, the association structure among the clustered binary responses $\{Y_{it}:t=1,\ldots,T\}$ depends on the pairwise bivariate distributions and correlation matrix of $\{e^{B}_{it}:t=1,\ldots,T\}$. If the random variables $\{e^{B}_{it}:t=1,\ldots,T\}$ are independent then so are $\{Y_{it}:t=1,\ldots,T\}$.
-\newline{}
+
+
 ```{example, label=BinaryProbit, name="Simulation of clustered binary responses conditional on a marginal probit model using NORTA method"}
 Suppose the goal is to simulate clustered binary responses from the marginal probit model 
 $$\Pr(Y_{it}=1 |\mathbf{x}_{it})=\Phi(0.2x_i)$$
@@ -362,7 +364,8 @@ binary_gee_model <- gee(y ~ x, family = binomial("probit"), id = id,
 # checking the estimated coefficients
 summary(binary_gee_model)$coefficients
 ```
-\textbf{ }
+
+
 ```{example, label=BinaryLogit, name="Simulation of clustered binary responses under a conditional marginal logit model without utilizing the NORTA method"} 
 Consider now simulation of correlated binary responses from the marginal logit model 
 \begin{equation*}
@@ -440,7 +443,6 @@ simulated_binary_dataset <- rbin(clsize = cluster_size,
 colMeans(simulated_binary_dataset$Ysim)
 ```
 
-\textbf{ }
 ```{example, Example2NoCovariates, name="Simulation of clustered nominal responses without covariates"}
 Suppose the aim is to simulate $N=5000$ clustered nominal responses with
 $\Pr(Y_{t}=1)=0.1$, $\Pr(Y_{t}=2)=0.2$, $\Pr(Y_{t}=3)=0.3$ and $\Pr(Y_{t}=4)=0.4$, for all $i$ and $t=1,\ldots,3$. For the sake of simplicity, we assume that the clustered responses are independent. 

vignettes/r_journal_paper.pdf.asis

@@ -0,0 +1,7 @@
+%\VignetteIndexEntry{R Journal paper}
+%\VignetteEngine{R.rsp::asis}
+%\VignetteKeyword{PDF}
+%\VignetteKeyword{HTML}
+%\VignetteKeyword{vignette}
+%\VignetteKeyword{package}
+%\VignetteKeyword{SimCorMultRes}