build_formulas.Rd

% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/iDAS_functions.R
\name{build_formulas}
\alias{build_formulas}
\title{Construct Model Formulas for Two- or Three-Factor Analysis}
\usage{
build_formulas(formatted_factors, test_func, random_effect)
}
\arguments{
\item{formatted_factors}{A named list containing the formatted factor names
(e.g., \code{factor1_tmp}, \code{factor2_tmp}, \code{factor3_tmp}) and optionally
\code{random_effect_tmp} if using a mixed-effects model. Typically produced by
an internal or auxiliary formatting function.}

\item{test_func}{A character string indicating which model-fitting approach to use.
Currently supports \code{"lm"} (no random effect) and \code{"lmer"} (mixed-effects).}

\item{random_effect}{A factor or \code{NULL}. If \code{test_func = "lmer"}, this
should be a valid factor; if \code{test_func = "lm"}, it must be \code{NULL}.}
}
\value{
A named list of formula strings. The exact list structure depends on the
number of non-\code{NULL} factors in \code{formatted_factors}:
\itemize{
\item \strong{Two-factor case}:
\code{list(
        full = <full_model_formula>,
        int_null = <interaction_null_formula>,
        int_alt = <interaction_alt_formula>,
        f1 = <factor1_formula>,
        f2 = <factor2_formula>
      )}

\if{html}{\out{<div class="sourceCode">}}\preformatted{\\item **Three-factor case**:
  \code{list(
        lm_full = <full_model_formula>,
        lm_int_alt2way = <two_way_interaction_formula>,
        lm_int_altf1f2 = <omitting_f1f2_interaction_formula>,
        lm_int_altf1f3 = <omitting_f1f3_interaction_formula>,
        lm_int_altf2f3 = <omitting_f2f3_interaction_formula>,
        lm_int_null = <no_interaction_formula>,
        lm_f1 = <factor1_formula>,
        lm_f2 = <factor2_formula>,
        lm_f3 = <factor3_formula>
      )}
}\if{html}{\out{</div>}}

}
}
\description{
This function builds model formula strings for either two or three factors,
with optional random effects. When \code{test_func} is \code{"lm"}, the
function assumes no random effect (\code{random_effect = NULL}). When
\code{test_func} is \code{"lmer"}, a random effect must be provided.
Supported factors:
\itemize{
\item Two-factor scenario: \code{factor1_tmp} and \code{factor2_tmp}.
\item Three-factor scenario: \code{factor1_tmp}, \code{factor2_tmp}, and \code{factor3_tmp}.
}
}
\details{
The function calculates \code{num_factors} internally by counting
how many non-\code{NULL} items exist in \code{formatted_factors} (apart from
the random effect) and dividing by 2. This must yield either 2 or 3
(representing two- or three-factor designs). Otherwise, it raises an error.
\enumerate{
\item For \code{test_func = "lm"}, \code{random_effect} must be \code{NULL}.
\item For \code{test_func = "lmer"}, \code{random_effect} must be a valid factor.
}
}
\examples{
\dontrun{
# Example for a two-factor linear model:
my_factors <- list(
  factor1_tmp = "Group",
  factor2_tmp = "Treatment",
  random_effect_tmp = NULL  # Not used for 'lm'
)
formulas_2f <- build_formulas(my_factors, test_func = "lm", random_effect = NULL)
print(formulas_2f)

# Example for a three-factor mixed-effects model:
my_factors_3 <- list(
  factor1_tmp = "Group",
  factor2_tmp = "Treatment",
  factor3_tmp = "Time",
  random_effect_tmp = "Subject"  # random effect for 'lmer'
)
formulas_3f <- build_formulas(my_factors_3, test_func = "lmer", random_effect = factor("Subject"))
print(formulas_3f)
}

}
\keyword{internal}