% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/twoPhaseSPMLglm_.R
\name{twoPhaseSPML}
\alias{twoPhaseSPML}
\title{Performs inference on two-phase studies data via semiparametric maximum likelihood.}
\usage{
twoPhaseSPML(
  formula,
  miscov,
  auxvar,
  family = gaussian,
  data,
  start.values = NULL,
  control = list()
)
}
\arguments{
\item{formula}{regression formula, note that if it does not contain the
missing-by-design variable, \code{miscov}, it will return results under
the null hypothesis. Hypothesis testing corresponds to the score
statistic. Otherwise, estimates and hypothesis testing occur under the
alternative hypothesis leading to Wald statistics. All the elements in
\code{formula} except \code{miscov} must be present in \code{data0} and
\code{data1}.}

\item{miscov}{right hand side formula with the missing-by-design
covariate(s), i.e. the potential causal locus (loci). Must be present in
\code{data1} but absent in \code{data0}.}

\item{auxvar}{right hand side formula with the auxiliary variable(s),
i.e. the GWAS SNP from phase 1. Must be present in \code{data0} and
\code{data1}.}

\item{family}{member of the exponential family (see \code{\link{family}};
\sQuote{quasi} models not available). Default \code{gaussian()}.}

\item{data}{a data frame containing data from both phases. Phase 2 data is assumed to be the result of the \code{complete.cases} with both \code{miscov} and \code{auxvar}. Missing values in variables other than \code{miscov} are not allowed and may lead to unexpected errors.}

\item{start.values}{a named list with initial values for the regression
parameters (\code{betas}) and/or the joint distribution between
\code{miscov} and \code{auxvar} (\code{q}). Defaults to \code{NULL}.}

\item{control}{a list of parameters for controlling the fitting process, i.e., number or EM iterations, tolerance and whether a trace is requested, it is passed to \code{\link{twoPhaseSPML.control}}.}
}
\value{
An object of class \code{"twoPhaseSPML"}, which is a list
  containing:
  \describe{
    \item{theta}{named numeric vector of estimated regression coefficients.}
    \item{qGZ}{data frame with the estimated joint distribution of
      \code{miscov} and \code{auxvar}.}
    \item{dispersion}{estimated dispersion parameter (variance for
      Gaussian; 1 for other families).}
    \item{iter}{integer, number of EM iterations performed.}
    \item{ll}{log-likelihood at convergence.}
    \item{df}{degrees of freedom for the test statistic.}
    \item{Sobs}{(null model only) observed score test statistic.}
    \item{Sexp}{(null model only) expected score test statistic.}
    \item{var_theta}{(alternative model only) named numeric vector of
      marginal variances for \code{theta}.}
    \item{Wobs}{(alternative model only) observed Wald test statistic.}
    \item{Wexp}{(alternative model only) expected Wald test statistic.}
    \item{qG}{data frame with the estimated marginal distribution of
      \code{miscov}.}
    \item{formula}{the \code{formula} used.}
    \item{miscov}{the \code{miscov} formula used.}
    \item{family}{the \code{family} object used.}
    \item{null.model}{logical, \code{TRUE} when the model was fitted under
      \eqn{H_0}.}
  }
}
\description{
Performs inference on two-phase studies data via semiparametric maximum likelihood.
}
\details{
The function implements the semiparametric maximum likelihood (SPML)
estimator for two-phase genetic association studies described by
Espin-Garcia et al. The EM algorithm alternates between an E-step that
computes observation weights based on the current estimate of the joint
distribution of the missing covariate and the auxiliary variable, and an
M-step that updates the regression coefficients and the non-parametric
distribution via iteratively re-weighted least squares and a closed-form
update, respectively.

When \code{miscov} is absent from \code{formula}, inference is performed
under \eqn{H_0} and score statistics are returned. When \code{miscov} is
included in \code{formula}, inference is performed under \eqn{H_a} and
Wald statistics are returned.
}
\examples{

data.table::setDTthreads(1)
data <- DataGeneration_TPD(N=200)
set.seed(1)
R <- rep(0, nrow(data))
R[sample(nrow(data), 175)] <- 1   # random phase 2 subsample of 500
data[R == 0, c("G1")] <- NA

# Null model (score test)
res_Ho <- twoPhaseSPML(
  formula = Y ~ Z,
  miscov  = ~ G1,
  auxvar  = ~ Z,
  data   = data
)
print(res_Ho)

# Alternative model (Wald test)
res_Ha <- twoPhaseSPML(
  formula = Y ~ Z + G1,
  miscov  = ~ G1,
  auxvar  = ~ Z,
  data   = data
)
print(res_Ha)

}
