% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ACDE.R
\name{ACDE}
\alias{ACDE}
\title{Fit AE, ACE or ADE biometric mixed models to nuclear family data}
\usage{
ACDE(model, data, type = c("AE", "ACE", "ADE"), method = "ML")
}
\arguments{
\item{model}{Fixed-effects formula.}

\item{data}{Data frame in long format (one row per individual).}

\item{type}{Model type: \code{"AE"}, \code{"ACE"} or \code{"ADE"}.}

\item{method}{Estimation method: \code{"ML"} (default) or \code{"REML"}.}
}
\value{
Object of class \code{"ACDEfit"} containing:
\itemize{
\item fit \code{nlme::lme} object
\item var Variance components (A,C,D,E)
\item h2 Narrow-sense heritability
\item c2 Shared environment (ACE only)
\item d2 Dominance (ADE only)
\item H2 Broad-sense heritability (ADE only)
}
}
\description{
Fits classical biometric variance–decomposition models using a linear
mixed model formulation implemented with \link[nlme:lme]{nlme::lme}.
}
\details{
The function estimates additive genetic (A), shared environmental (C),
dominance genetic (D), and unique environmental (E) variance components
from \strong{nuclear family data (parents and offspring)} in long format.

Supported family structures:
\itemize{
\item Parent-child trios (one offspring)
\item Nuclear families with \strong{any number of siblings}
}

The function automatically detects the family structure and selects the
correct additive-genetic parameterisation.

Only AE, ACE and ADE models are fitted.

Phenotypic variance is decomposed as
\deqn{V_P = V_A + V_C + V_D + V_E}

The model is fitted as a linear mixed model with family-level random
effects and individual residual variance.
\subsection{Automatic family detection}{

The function detects whether families contain one or multiple offspring.
\itemize{
\item \strong{Trios:} collapsed additive parameterisation.
\item \strong{Siblings:} transmission decomposition parameterisation.
}
}

\subsection{Trio parameterisation}{

Additive effects represented as:
\deqn{A = 0.5 Mother + 0.5 Father + 1 Child}

This reproduces the expected parent–offspring covariance:
\deqn{Cov = 1/2 V_A}
}

\subsection{Multi-sibling parameterisation}{

Additive genetic variance is decomposed into:
\itemize{
\item maternal transmission (\eqn{A_m})
\item paternal transmission (\eqn{A_f})
\item Mendelian sampling (\eqn{M_s})
}

For offspring:
\deqn{A = A_m + A_f + M_s}

Total additive variance:
\deqn{V_A = 2(\sigma^2_{Am} + \sigma^2_{Af}) + \sigma^2_{Ms}}

This produces correct covariances:
\itemize{
\item Parent–offspring: \eqn{1/2 V_A}
\item Sibling–sibling:  \eqn{1/2 V_A}
}

This formulation generalises to \strong{any number of siblings}.
}

\subsection{Identifiability of C and D}{

Nuclear family data cannot fully separate shared environment (C)
and dominance (D). ACE and ADE models should be interpreted jointly.
}
}
\note{
This complements \code{\link[=pbsize]{pbsize()}} and \code{\link[=fbsize]{fbsize()}}.
}
\section{Required columns in \code{data}}{

\itemize{
\item familyid Nuclear family identifier.
\item var1 Maternal transmission coefficient.
\item var2 Paternal transmission coefficient.
\item var3 Offspring (Mendelian sampling) indicator.
}

These variables encode expected genetic transmission and \strong{are not role
indicators}.

Coding for a nuclear family:

\preformatted{
role     var1  var2  var3
-------------------------
father     0     1     0
mother     1     0     0
child      1     1     1
}

For \strong{multiple siblings}, each offspring receives identical coding:

\preformatted{
role     var1  var2  var3
-------------------------
father     0     1     0
mother     1     0     0
sib1       1     1     1
sib2       1     1     1
sib3       1     1     1
}
}

\examples{
library(nlme)
set.seed(1)

simulate_families <- function(n_fam = 200)
{
  VA <- 0.4; VC <- 0.2; VD <- 0.1; VE <- 0.3
  out <- list()

  for(f in 1:n_fam){
    Cfam <- rnorm(1,0,sqrt(VC))
    Af <- rnorm(1,0,sqrt(VA))
    Am <- rnorm(1,0,sqrt(VA))

    make_child <- function(){
      Mend <- rnorm(1,0,sqrt(0.5*VA))
      A  <- 0.5*(Af+Am)+Mend
      D  <- rnorm(1,0,sqrt(VD))
      E  <- rnorm(1,0,sqrt(VE))
      A + D + Cfam + E
    }

    out[[f]] <- data.frame(
      familyid=f,
      role=c("father","mother","sib1","sib2","sib3"),
      y=c(
        Af + Cfam + rnorm(1,0,sqrt(VE)),
        Am + Cfam + rnorm(1,0,sqrt(VE)),
        make_child(), make_child(), make_child()
      )
    )
  }

  dat <- do.call(rbind,out)

  dat$var1 <- as.integer(dat$role=="mother")
  dat$var2 <- as.integer(dat$role=="father")
  dat$var3 <- as.integer(grepl("sib", dat$role))
  dat
}

dat <- simulate_families()

AE  <- ACDE(y~1, dat, "AE")
ACE <- ACDE(y~1, dat, "ACE")
ADE <- ACDE(y~1, dat, "ADE")

anova(AE$fit, ACE$fit, ADE$fit)

############################################################
# Create rectangular variance table (important!)
############################################################

summary(AE)
summary(ACE)
summary(ADE)

require(gap.datasets)
model <- bwt ~ male + first + midage + highage + birthyr
AE <- ACDE(model,mfblong)
ACE <- ACDE(model,mfblong,type="ACE")
ADE <- ACDE(model,mfblong,type="ADE")
anova(AE$fit,ACE$fit,ADE$fit)

}
\author{
ChatGPT
}
