\name{simfam_cmp}
\alias{simfam_cmp}
\title{
Generate familial competing risks data
}
\description{
Generates familial competing risks data for specified study design, genetic model and source of residual familial correlation; the generated data frame has the same family structure as that \code{simfam} function, including individual's id, father id, mother id, relationship to proband, generation, gender, current age, genotypes of major or second genes.
}
\usage{
simfam_cmp(N.fam, design = "pop+", variation = "none", interaction = FALSE, 
         depend = NULL, base.dist = c("Weibull", "Weibull"), frailty.dist = "none", 
         base.parms = list(c(0.016, 3), c(0.016, 3)), 
         vbeta = list(c(-1.13, 2.35), c(-1, 2)), allelefreq = 0.02, dominant.m = TRUE, 
         dominant.s = TRUE, mrate = 0, hr = 0, probandage = c(45, 2), 
         agemin = 20, agemax = 100)
% \method{summary}{simulation}(object, \dots)
}

\arguments{
  \item{N.fam}{
Number of families to generate.
}
\item{design}{
Family-based study design used in the simulations. Possible choices are \code{"pop"}, \code{"pop+"}, \code{"cli"}, \code{"cli+"}, \code{"twostage"}, and \code{"noasc"}.  

\code{"pop"} is a population-based design with affected probands; \code{"pop+"} is similar to \code{"pop"} but with mutation-carrying probands; \code{"cli"} is a clinic-based design with affected probands and at least one affected parent and one affected sibling; \code{"cli+"} is similar to \code{"cli"} but with mutation-carrying probands; \code{"twostage"} is a two-stage design that oversamples high-risk families (with at least two affected members); and \code{"noasc"} corresponds to simple random sampling without ascertainment correction. Default is \code{"pop"}.
}

  \item{variation}{
Source of residual familial correlation.  Possible choices are \code{"frailty"} for frailty shared within families, \code{"secondgene"} for a second gene variation, and \code{"none"} for no residual familial correlation. Default is \code{"none"}.
}
 \item{interaction}{
Logical; if \code{TRUE}, allows the interaction between gender and mutation status. Two logical values should be specified for each competing event; if only one logical value is provided, the same logical value will be assumed for both events. Default is \code{FALSE}.
}
 \item{depend}{
Two values shoud be specified for each competing event when \code{frailty.dist = "gamma"} or \code{frailty.dist = "lognormal"}, three values should be specified with \code{frailty.dist = "cgamma"} or \code{frailty.dist = "clognormal"}. The first two values represent the inverse of the variance for each competing event and the third value represents the correlation between the two events.
}
\item{base.dist}{
Choice of baseline hazard distribution. Possible choices are \code{"Weibull"}, \code{"loglogistic"}, \code{"Gompertz"}, \code{"lognormal"} \code{"gamma"}, and \code{"logBurr"}. Default is \code{"Weibull"}. Two distributions should be specified for each competing event. If only one distribution is specified, the same distribution will be assumed for both events.
}
\item{frailty.dist}{
Choice of frailty distribution. Possible choices are \code{"gamma"} for independent gamma, \code{"lognormal"} for independent lognormal, \code{"cgamma"} for correlated gamma, and \code{"clognormal"} for correlated lognormal distribution. Default is \code{NULL}.
}
  \item{base.parms}{
The list of two vectors of baseline parameters for each event should be specified. For example, \code{base.parms = list(c(lambda1, rho1), c(lambda2, rho2))} should be specified for \code{base.dist = c("Weibull", "Weibull")}.

Two parameters \code{base.parms = c(lambda, rho)} should be specified for \code{base.dist = "Weibull"}, \code{"loglogistic"}, \code{"Gompertz"}, \code{"gamma"}, and \code{"lognormal"}, and three parameters should be specified \code{base.parms = c(lambda, rho, eta)} for \code{base.dist="logBurr"}. 
}  	
\item{vbeta}{
List of two vectors of regression coefficients for each event should be specified. 
Each vector contains regression coefficients for gender, majorgene, interaction between gender and majorgene (if \code{interaction = TRUE}), and secondgene (if \code{variation = "secondgene"}). 
}
\item{allelefreq}{
Population allele frequencies of major disease gene. Value should be between 0 and 1. 
Vector of population allele frequencies for major and second disease genes should be provided when \code{variation = "secondgene"}. Default value is \code{allelefreq = 0.02}.}
\item{dominant.m}{Logical; if \code{TRUE}, the genetic model of major gene is dominant, otherwise recessive.}
\item{dominant.s}{Logical; if \code{TRUE}, the genetic model of second gene is dominant, otherwise recessive.}
\item{mrate}{
Proportion of missing genotypes, value between 0 and 1. Default value is 0.}
  \item{hr}{
Proportion of high risk families, which include at least two affected members, to be sampled from the two stage sampling. This value should be specified when \code{design = "twostage"}. Default value is 0. Value should lie between 0 and 1.
}
\item{probandage}{
Vector of mean and standard deviation for the proband age. Default values are mean of 45 years and standard deviation of 2 years, \code{probandage = c(45, 2)}.
}
\item{agemin}{
Minimum age of disease onset or minimum age. Default is 20 years of age.
}
\item{agemax}{
Maximum age of disease onset or maximum age. Default is 100 years of age.
}

}
\details{

\emph{Competing risk model}

Event 1:

\deqn{ h(t|X,Z_1) = h_{01}(t - t_0) Z \exp(\beta_{s1} x_s+\beta_{g1} x_g),}{ h(g|X,Z) = h01(t - t0) * Z1 * exp(\beta s1 * xs + \beta g1 * xg),}

Event 2:

\deqn{ h(t|X,Z_1) = h_{02}(t - t_0) Z \exp(\beta_{s2} x_s+\beta_{g2} x_g),}{ h(g|X,Z) = h02(t - t0) * Z1 * exp(\beta s2 * xs + \beta g2 * xg),}
		
where \eqn{h_{01}(t)}{h01(t)} and \eqn{h_{02}(t)}{h02(t)} are the baseline hazard functions for event 1 and event 2, respectively, \eqn{t_0}{t0} is a minimum age of disease onset, \eqn{Z_1}{Z1} and \eqn{Z_2}{Z2} are frailties shared within families for each event and follow either a gamma, log-normal, correlateg gamma, or correlated log-normal distributions, \eqn{x_s}{xs} and \eqn{x_g}{xg} indicate male (1) or female (0) and carrier (1) or non-carrier (0) of a main gene of interest, respectively.

\emph{Choice of frailty distributions for competing risk models}

\code{frailty.dist = "gamma"} shares the frailties within families generated from a gamma distribution independently for each competing event, where \eqn{Z_j}{Zj} follows Gamma(\eqn{k_j}{kj}, \eqn{1/k_j}{1/kj}). 

\code{frailty.dist = "lognormal"} shares the frailties within families generated from a log-normal distribution independently for each competing event, where \eqn{Z_j}{Zj} follows log-normal distribution with mean 0 and variance \eqn{1/k_j}{1/kj}.

\code{frailty.dist = "cgamma"} shares the frailties within families generated from a correlated gamma distribution to allow the frailties between two events to be correlated, where the correlated gamma frailties (\eqn{Z_1, Z_2}{Z1, Z2}) are generated with three independent gamma frailties (\eqn{Y_0, Y_1, Y_2}{Y0, Y1, Y2}) as follows:

\deqn{Z_1 = (k_0/(k_0 + k_1) Y_0 + Y_1; Z_2 = (k_0/(k_0 + k_2) Y_0 + Y_2,}{Z1 = k0/(k0+k1)Y0 + Y1; Z2 = k0/(k0+k2)Y0 + Y2,} 

where \eqn{Y_0}{Y0} from Gamma(\eqn{k_0}{k0}, \eqn{1/k_0}{1/k0}), \eqn{Y_1}{Y1} from Gamma(\eqn{k_1}{k1}, \eqn{1/(k_0+k_1)}{1/(k0+k1)}), and \eqn{Y_2}{Y2} from Gamma(\eqn{k_2}{k2}, \eqn{1/(k_0+k_2)}{1/(k0+k2)}).

\code{frailty.dist = "clognormal"} shares the frailties within families generated from a correlated log-normal distribution where \eqn{log(Z_j)}{log(Zj)} follows  a normal distribution with mean 0, variance \eqn{1/k_j}{1/kj} and correlation between two events \eqn{k_0}{k0}.

\code{depend} should specify the values of related frailty parameters: \code{c(k1, k2)} with \code{frailty.dist = "gamma"} or \code{frailty.dist = "lognormal"}; \code{c(k1, k2, k0)} for \code{frailty.dist = "cgamma"} or \code{frailty.dist = "clognormal"}. 


The current ages for each generation are simulated assuming normal distributions. However, the probands' ages are generated using a left truncated normal distribution as their ages cannot be less than the minimum age of onset. The average age difference between each generation and their parents is specified as 20 years apart. 

The \code{design} argument specifies the type of family based design to be simulated. Two variants of the population-based and clinic-based design can be chosen: \code{"pop"}, where the proband is affected; \code{"pop+"}, where the proband is affected and a mutation carrier; \code{"cli"}, where the proband is affected and at least one parent and one sibling are also affected; \code{"cli+"}, where the proband is affected, is a mutation carrier, and has at least one affected parent and one affected sibling. 
The two-stage design, \code{"twostage"}, is used to oversample high risk families, where the proportion of high risks families included in the sample is specified by \code{hr}. High risk families often include multiple (at least two) affected members. Finally, \code{design = "noasc"} specifies a design with no ascertainment criteria applied.

Note that simulating family data under the clinic-based designs (\code{"cli"} or \code{"cli+"}) or the two-stage design can be slower since the ascertainment criteria for the high risk families are difficult to meet in such settings. Especially, \code{"cli"} design could be slower than \code{"cli+"} design since the proband's mutation status is randomly selected from a disease population in \code{"cli"} design, so his/her family members are less likely to be mutation carriers and have less chance to be affected, whereas the probands are all mutation carriers, their family members have higher chance to be carriers and affected by disease. Therefore, \code{"cli"} design requires more iterations to sample high risk families than \code{"cli+"} design. 
}
\value{
Returns an object of class \code{'simfam'}, a data frame which contains:
\item{famID}{Family identification (ID) numbers.}
\item{indID}{Individual ID numbers.}
\item{gender}{Gender indicators: 1 for males, 0 for females.}
\item{motherID}{Mother ID numbers.}
\item{fatherID}{Father ID numbers.}
\item{proband}{Proband indicators: 1 if the individual is the proband, 0 otherwise.}
\item{generation}{Individuals generation: 1 = parents of probands, 2 = probands and siblings, 3 = children of probands and siblings.}
\item{majorgene}{Genotypes of major gene: 1 = AA, 2 = Aa, 3 = aa where A is disease gene.}
\item{secondgene}{Genotypes of second gene: 1 = BB, 2 = Bb, 3 = bb where B is disease gene.}
\item{ageonset}{Ages at disease onset in years.}
\item{currentage}{Current ages in years.}
\item{time}{Ages at disease onset for the affected or ages of last follow-up for the unaffected. }
\item{status}{Disease statuses: 1 for affected by event 1, 2 for affected by event 2, 0 for unaffected (censored).
}
\item{mgene}{Major gene mutation indicators: 1 for mutated gene carriers, 0 for mutated gene noncarriers, or \code{NA} if missing.}
\item{relation}{Family members' relationship with the proband:
  \tabular{ll}{
    1  \tab Proband (self) \cr
    2  \tab Brother or sister \cr
    3  \tab Son or daughter \cr
    4  \tab Parent \cr
    5  \tab Nephew or niece \cr
    6  \tab Spouse \cr
    7  \tab Brother or sister in law
  }
  }
\item{fsize}{Family size including parents, siblings and children of the proband and the siblings.}
\item{naff}{Number of affected members by either event 1 or 2 within family.}
\item{df1}{Number of affected members by event 1 within family.}
\item{df2}{Number of affected members by event 2 within family.}
\item{weight}{Sampling weights.}


}
\references{
Choi, Y.-H., Briollais, L., He, W. and Kopciuk, K. (2021) FamEvent: An R Package for Generating and Modeling Time-to-Event Data in Family Designs, Journal of Statistical Software 97 (7), 1-30. doi:10.18637/jss.v097.i07.

Choi, Y.-H., Jung, H., Buys, S., Daly, M., John, E.M., Hopper, J., Andrulis, I., Terry, M.B., Briollais, L. (2021) A Competing Risks Model with Binary Time Varying Covariates for Estimation of Breast Cancer Risks in BRCA1 Families, Statistical Methods in Medical Research 30 (9), 2165-2183. https://doi.org/10.1177/09622802211008945.

Choi, Y.-H., Kopciuk, K. and Briollais, L. (2008) Estimating Disease Risk Associated Mutated Genes in Family-Based Designs, Human Heredity 66, 238-251.

Choi, Y.-H. and Briollais (2011) An EM Composite Likelihood Approach for Multistage Sampling of Family Data with Missing Genetic Covariates, Statistica Sinica 21, 231-253.
}
\author{
Yun-Hee Choi
}
\seealso{
\code{\link{summary.simfam_cmp}, \link{plot.simfam_cmp}, \link{penplot_cmp}}
}
\examples{

## Example 1: simulate competing risk family data from pop+ design using
#  Weibull distribution for both baseline hazards and inducing 
#  residual familial correlation through a correlated gamma frailty.

set.seed(4321)
fam <- simfam_cmp(N.fam = 10, design = "pop+", variation = "frailty", 
       base.dist = "Weibull", frailty.dist = "cgamma", depend=c(1, 2, 0.5), 
       allelefreq = 0.02, base.parms = list(c(0.01, 3), c(0.01, 3)), 
       vbeta = list(c(-1.13, 2.35), c(-1, 2)))


head(fam) 

\dontrun{
  famID indID gender motherID fatherID proband generation majorgene secondgene  ageonset
1     1     1      1        0        0       0          1         3          0 124.23752
2     1     2      0        0        0       0          1         2          0  54.66936
3     1     3      0        2        1       1          2         2          0  32.75208
4     1     4      1        0        0       0          0         3          0 136.44926
5     1    11      1        3        4       0          3         3          0  71.53672
6     1    12      1        3        4       0          3         3          0 152.47073
  currentage     time status true_status mgene relation fsize naff df1 df2 weight
1   65.30602 65.30602      0           2     0        4    25    2   1   1      1
2   68.62107 54.66936      1           1     1        4    25    2   1   1      1
3   47.07842 32.75208      2           2     1        1    25    2   1   1      1
4   45.09295 45.09295      0           2     0        6    25    2   1   1      1
5   25.32819 25.32819      0           1     0        3    25    2   1   1      1
6   22.95059 22.95059      0           2     0        3    25    2   1   1      1
}

summary(fam)

plot(fam, famid = 1) # pedigree plots for family with ID = 1

}
\keyword{Simulation}