% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/hplm.R, R/print-export-hplm.R,
%   R/coefficents.sc_plm.R
\name{hplm}
\alias{hplm}
\alias{print.sc_hplm}
\alias{export.sc_hplm}
\alias{coef.sc_hplm}
\title{Hierarchical piecewise linear model / piecewise regression for multiple cases}
\usage{
hplm(
  data,
  dvar,
  pvar,
  mvar,
  model = c("W", "H-M", "B&L-B", "JW"),
  contrast = c("first", "preceding"),
  contrast_level = NA,
  contrast_slope = NA,
  method = c("ML", "REML"),
  control = list(opt = "optim"),
  random.slopes = FALSE,
  lr.test = FALSE,
  ICC = TRUE,
  trend = TRUE,
  level = TRUE,
  slope = TRUE,
  random_trend = FALSE,
  random_level = FALSE,
  random_slope = FALSE,
  fixed = NULL,
  random = NULL,
  ar = 0,
  unequal_variances = FALSE,
  update.fixed = NULL,
  data.l2 = NULL,
  ...
)

\method{print}{sc_hplm}(x, digits = 3, bcsmd = FALSE, casewise = FALSE, ...)

\method{export}{sc_hplm}(
  object,
  caption = NA,
  footnote = NA,
  filename = NA,
  round = 2,
  nice = TRUE,
  casewise = FALSE,
  ...
)

\method{coef}{sc_hplm}(object, casewise = FALSE, ...)
}
\arguments{
\item{data}{A single-case data frame. See \code{\link[=scdf]{scdf()}} to learn about this
format.}

\item{dvar}{Character string with the name of the dependent variable.
Defaults to the attributes in the scdf file.}

\item{pvar}{Character string with the name of the phase variable. Defaults to
the attributes in the scdf file.}

\item{mvar}{Character string with the name of the measurement time variable.
Defaults to the attributes in the scdf file.}

\item{model}{Model used for calculating the dummy parameters (see Huitema &
McKean, 2000). Default is \code{model = "W"}. Possible values are: \code{"B&L-B"},
\code{"H-M"}, \code{"W"}, and deprecated \code{"JW"}.}

\item{contrast}{Sets contrast_level and contrast_slope. Either "first",
"preceding" or a contrast matrix. If NA contrast is ignored.}

\item{contrast_level}{Either "first", "preceding" or a contrast matrix. If NA
contrast_level is a copy of contrast.}

\item{contrast_slope}{Either "first", "preceding" or a contrast matrix. If NA
contrast_level is a copy of contrast.}

\item{method}{Method used to fit your model. Pass \code{"REML"} to maximize the
restricted log-likelihood or \code{"ML"} for maximized log-likelihood. Default
is \code{"ML"}.}

\item{control}{A list of settings for the estimation algorithm, replacing the
default values passed to the function \code{lmeControl} of the \code{nlme} package.}

\item{random.slopes}{If \code{random.slopes = TRUE} random slope effects of the
level, trend, and treatment parameter are estimated.}

\item{lr.test}{If set TRUE likelihood ratio tests are calculated comparing
model with vs. without random slope parameters.}

\item{ICC}{If \code{ICC = TRUE} an intraclass-correlation is estimated.}

\item{trend}{A logical indicating if a trend parameters is included in the
model.}

\item{level}{A logical indicating if a level parameters is included in the
model.}

\item{slope}{A logical indicating if a slope parameters is included in the
model.}

\item{random_trend}{If TRUE, includes a random trend trend effect.}

\item{random_level}{If TRUE, includes a random level trend effect.}

\item{random_slope}{If TRUE, includes a random slope trend effect.}

\item{fixed}{Defaults to the fixed part of the standard piecewise regression
model. The parameter phase followed by the phase name (e.g., phaseB)
indicates the level effect of the corresponding phase. The parameter
'inter' followed by the phase name (e.g., interB) adresses the slope effect
based on the method provide in the model argument (e.g., "B&L-B"). The
formula can be changed for example to include further L1 or L2 variables
into the regression model.}

\item{random}{The random part of the model. Defaults to a random intercept
model. The formula can be changed to include random slope effects for
level, trend, and treatment effects.}

\item{ar}{Maximal lag of autoregression. Modelled based on the
Autoregressive-Moving Average (ARMA) function.}

\item{unequal_variances}{Logical. If set TRUE, estimations are weighted by
phase variances.}

\item{update.fixed}{An easier way to change the fixed model part (e.g., \code{. ~ . + newvariable}).}

\item{data.l2}{A data frame providing additional variables at Level 2. The
scdf File has to have names for all cases and the Level 2 data frame has to
have a column named 'cases' with the names of the cases the Level 2
variables belong to.}

\item{...}{Further arguments passed to the lme function.}

\item{x}{An object returned by \code{\link[=hplm]{hplm()}}}

\item{digits}{The minimum number of significant digits to be use.
If set to "auto" (default), values are predefined.}

\item{bcsmd}{If TRUE, reports between-case standardized mean differences.}

\item{casewise}{Returns the estimations for each case separately}

\item{object}{An scdf or an object exported from a scan function.}

\item{caption}{Character string with table caption. If left NA (default) a
caption will be created based on the exported object.}

\item{footnote}{Character string with table footnote. If left NA (default) a
footnote will be created based on the exported object.}

\item{filename}{String containing the file name. If a filename is given the
output will be written to that file.}

\item{round}{Integer passed to the digits argument used to round values.}

\item{nice}{If set TRUE (default) output values are rounded and optimized for
publication tables.}
}
\value{
An object of class \code{sc_hplm}.
\itemize{
\item \code{model} | List containing infromation about
\item \code{N} | Number of single-cases.
\item \code{formula} | A list containing the fixed and the random formulas of the hplm model.
\item \code{hplm} | Object of class lme contaning the multilevel model.
\item \code{model.0} | Object of class lme containing the zero model.
\item \code{ICC} | List containing intraclass correlation and test parameters.
\item \code{model.without} | Object of class gls containing the fixed effect model.
\item \code{contrast} | List with contrast definitions.
}
}
\description{
The \code{\link[=hplm]{hplm()}} function computes a hierarchical piecewise regression model. It
extends the standard piecewise regression model to multiple cases by
estimating fixed and random effects. The function uses the \code{lme} function of
the \code{nlme} package to fit linear mixed-effects models. The model can include
random intercepts and random slopes for level, trend, and treatment effects.
Additionally, it allows for the inclusion of autoregressive structures and
unequal variances across phases. The function also provides options for
likelihood ratio tests to compare models with and without random slope
effects, as well as the calculation of intraclass correlations (ICC) to
assess the proportion of variance attributable to between-case differences.
This function is particularly useful for analyzing data from multiple
single-case experimental designs (SCEDs) where observations are nested within
cases.
}
\section{Functions}{
\itemize{
\item \code{print(sc_hplm)}: Print results

\item \code{export(sc_hplm)}: Export results as html table (see \code{\link[=export]{export()}})

\item \code{coef(sc_hplm)}: Extract model coefficients

}}
\section{Model specification}{
 The fixed effects part of the model can be
specified using the \code{fixed} argument, while the random effects part can be
specified using the \code{random} argument. If not provided, default formulas
based on the specified model type (e.g., "B&L-B") are created. The function
also allows for the inclusion of autoregressive structures through the \code{ar}
argument and unequal variances across phases through the
\code{unequal_variances} argument.
}

\section{Random slopes}{
 By setting the \code{random.slopes} argument to TRUE, the
model will include random slope effects for level, trend, and treatment
effects. This allows for individual differences in how cases respond to
these effects.
}

\section{Likelihood ratio tests}{
 If the \code{lr.test} argument is set to TRUE,
the function will perform likelihood ratio tests to compare models with and
without random slope effects. This helps to determine whether including
random slopes significantly improves model fit.
}

\section{Intraclass correlation}{
 If the \code{ICC} argument is set to TRUE, the
function will calculate the intraclass correlation coefficient (ICC) to
assess the proportion of variance attributable to between-case differences.
This provides insight into the degree of similarity among observations
within the same case.
}

\examples{

## Compute hplm model on a MBD over fifty cases (restricted log-likelihood)
hplm(exampleAB_50, method = "REML", random.slopes = FALSE)

## Analyzing with additional L2 variables
Leidig2018 |>
  add_l2(Leidig2018_l2) |>
  hplm(update.fixed = .~. + gender + migration + ITRF_TOTAL*phaseB,
       slope = FALSE, random.slopes = FALSE, lr.test = FALSE
  )

}
\seealso{
Other regression functions: 
\code{\link{bplm}()},
\code{\link{fetch}()},
\code{\link{mplm}()},
\code{\link{plm}()},
\code{\link{print.sc_ac}()},
\code{\link{print.sc_bctau}()},
\code{\link{trend}()}
}
\author{
Juergen Wilbert
}
\concept{regression functions}
