% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/optimJTC_.R
\name{optimTP.LM}
\alias{optimTP.LM}
\title{Lagrange-multiplier optimal phase 2 design for a two-phase genetic association study.}
\usage{
optimTP.LM(
  formula,
  miscov,
  auxvar,
  strata,
  family,
  n,
  data,
  beta,
  p_gz,
  disp = NULL,
  optimMeasure,
  K.idx = NULL,
  min.nk = NULL,
  logical.sub = NULL
)
}
\arguments{
\item{formula}{A two-sided \code{\link{formula}} specifying the regression
model of interest, e.g.\code{Y ~ G + Z}.  All variables except
\code{miscov} must be present in \code{data}.}

\item{miscov}{Right-hand-side formula identifying the missing-by-design
covariate(s) (the sequencing variant), e.g.\code{~ G}.}

\item{auxvar}{Right-hand-side formula identifying the auxiliary variable
(the GWAS tag SNP), e.g.\code{~ Z}.  Must be present in \code{data}.}

\item{strata}{Right-hand-side formula defining the stratification variables
used to cross-tabulate \code{data}, e.g.\code{~ Z + S}.  All variables
must be present in \code{data}.}

\item{family}{GLM family object (see \code{\link{family}}).  Passed
directly to the information-matrix calculations.  Default:
\code{gaussian()}.}

\item{n}{Integer.  Target phase 2 sample size (number of individuals to
be sequenced).}

\item{data}{A \code{data.frame} containing the phase 1 data.  Must include
all variables in \code{formula} (except those in \code{miscov}),
\code{auxvar}, and \code{strata}.}

\item{beta}{Named or unnamed numeric vector of assumed regression
coefficients, with one element per term in \code{formula} (including
the intercept).  These define the operating point at which the
Fisher information is evaluated.  Setting \code{beta[G] = 0} triggers
the score-test (null-model) criterion; any non-zero value triggers the
Wald (alternative-model) criterion.}

\item{p_gz}{A \code{data.frame} with the assumed joint distribution of
(\code{miscov}, \code{auxvar}).  Must contain one column per variable
in \code{miscov} and \code{auxvar} plus a column \code{q} holding
non-negative probability masses that sum to 1.  Rows with
\code{q <= 0} are silently removed.  Typically generated by
\code{\link{twoPhaseDesign}} from \code{maf_G} and \code{LD}, or
supplied directly by the user.}

\item{disp}{Numeric dispersion parameter.  For Gaussian and Gamma
families this is the variance (\eqn{\sigma^2}) or dispersion
(\eqn{\phi}), respectively; for binomial and Poisson it is fixed at
1.  If \code{NULL} (default) it is estimated as \code{var(Y)}.}

\item{optimMeasure}{Character string specifying the optimality criterion.
One of \code{"Par-spec"} (parameter-specific: minimise the asymptotic
variance of \code{beta[K.idx]}), \code{"A-opt"} (A-optimality:
minimise \code{trace(FIM^{-1})}), or \code{"D-opt"} (D-optimality:
maximise \code{log det(FIM)}).}

\item{K.idx}{Integer index (or vector of indices) into \code{beta}
identifying the parameter(s) of primary interest for
\code{optimMeasure = "Par-spec"}.  Ignored for A- and D-optimality.
Required when \code{optimMeasure = "Par-spec"}.}

\item{min.nk}{Optional integer scalar or vector of length equal to the
number of strata.  Specifies the minimum number of individuals to
sample from each stratum.  If a scalar, the same minimum is applied to
all strata.  Default: \code{NULL} (no minimum, i.e. zero).}

\item{logical.sub}{Optional logical vector of length \code{nrow(data)}.
If supplied, only the rows where \code{logical.sub = TRUE} are used in
the information calculations (the full \code{data} is still returned).
Useful for sensitivity analyses on subsets.  Default: \code{NULL}.}
}
\value{
A \code{data.frame} with one row per stratum (as defined by
  \code{strata}) and the following columns from
  \code{xtabs(strata, data)}:
  \describe{
    \item{(strata variables)}{The stratification variable values.}
    \item{Freq}{Stratum size \eqn{N_k}.}
    \item{prR_cond_optim}{Optimal conditional sampling probability
      \eqn{n_k / n} (proportional allocation weight).}
    \item{convergence}{Convergence code from the solver (\code{0} = success;
      codes from \code{nloptr::cobyla} or \code{dfoptim::hjkb}).}
  }
}
\description{
Computes stratum-specific sampling fractions that maximise the anticipated
Fisher information for the regression parameters of interest subject to a
fixed total phase 2 sample size.  The optimisation is performed by the
COBYLA algorithm (\code{nloptr}) with a derivative-free fallback
(\code{dfoptim::hjkb}) if COBYLA fails to converge.
}
\details{
The function computes, for each stratum defined by \code{strata}, the
stratum-specific sampling fraction \eqn{\pi_k = n_k / N_k} that maximises
the chosen information criterion.  The optimisation is constrained so that
(i) the total selected sample equals \code{n}, (ii) no stratum is
over-sampled (\eqn{n_k \le N_k}), and (iii) the \code{min.nk} lower
bounds are respected.

The baseline Fisher information uses the empirical score outer-product
estimator \eqn{I_3/N} (see \code{\link{optimTP.GA}} for details).
}
\examples{
\donttest{
data <- DataGeneration_TPD(N = 1000)
data <- data[, c("Y", "Z")]  # phase-1 data: no G column
p_gz <- data.frame(Z = c(0, 0, 0, 1, 1, 1, 2, 2, 2), # theoretical joint distribution
        G1 = c(0, 1, 2, 0, 1, 2, 0, 1, 2), # between G and Z (LD = 0.75, MAF_G = 0.2, MAF_Z = 0.3)
        q = c(0.486, 0.004, 0, 0.143, 0.276, 0.001, 0.011, 0.04, 0.039)) 
        
data$S <- as.numeric(cut(data$Y,
            breaks = quantile(data$Y, probs = c(0, 0.4, 0.8, 1)),
            include.lowest = TRUE))

res_lm <- optimTP.LM(
  formula     = Y ~ Z + G1,
  miscov      = ~ G1,
  auxvar      = ~ Z,
  strata      = ~ Z + S,
  family      = gaussian(),
  n           = 200,
  data        = data,
  beta        = c(2, 0.5, 0.1),
  p_gz        = p_gz,
  optimMeasure = "Par-spec",
  K.idx       = 2L
)
head(res_lm)
}

}
\seealso{
\code{\link{twoPhaseDesign}}, \code{\link{optimTP.GA}}
}
