% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/tpm_functions.R
\name{tpm}
\alias{tpm}
\title{Build the transition probability matrix from unconstrained parameter vector}
\usage{
tpm(
  beta,
  Z = NULL,
  Eta = NULL,
  byrow = FALSE,
  ref = NULL,
  ad = NULL,
  report = TRUE,
  param = NULL
)
}
\arguments{
\item{beta}{parameters; either
\itemize{
   \item a vector of length \code{nStates * (nStates-1)}, or
   \item a matrix of dimension \code{c(nStates * (nStates-1), p+1)} if design matrix \code{Z} is also provided.
}}

\item{Z}{optional covariate design matrix with or without intercept column, i.e. of dimension \code{c(nObs, p)} or \code{c(nObs, p+1)}.
If provided, \code{beta} needs to be a matrix of dimension \code{c(nStates * (nStates-1), p+1)}.}

\item{Eta}{optional pre-calculated matrix of linear predictors of dimension \code{c(nObs, nStates * (nStates-1))}.
If provided, \code{Z} and \code{beta} will be ignored.}

\item{byrow}{logical indicating if each transition probability matrix should be filled by row.
Defaults to \code{FALSE}, but should be set to \code{TRUE} if one wants to work with a matrix of beta parameters returned by popular HMM packages like \code{moveHMM}, \code{momentuHMM}, or \code{hmmTMB}.}

\item{ref}{optional integer vector of length \code{nStates} giving, for each row, the column index of the reference state 
(its predictor is fixed to 0). Defaults to the diagonal (\code{ref = 1:nStates}).}

\item{ad}{logical; whether to use automatic differentiation. Determined automatically — for debugging only.}

\item{report}{logical; if \code{TRUE} (default), \code{delta}, \code{Gamma}, \code{allprobs}, and \code{trackID} are reported from the fitted model. Requires \code{ad = TRUE}.}

\item{param}{depricated, please use argument \code{beta} instead.}
}
\value{
Transition probability matrix of dimension \code{c(nStates, nStates)} or array of such matrices of dimension \code{c(nStates, nStates, nObs)} if \code{Z} or \code{Eta} is provided.
}
\description{
Markov chains are parametrised in terms of a transition probability matrix \eqn{\Gamma}, for which each row contains a conditional probability distribution of the next state given the current state.
Hence, each row has entries between 0 and 1 that need to sum to one. 

For numerical optimisation, we parameterise in terms of unconstrained parameters, thus this function computes said matrix from an unconstrained parameter vector via the inverse multinomial logistic link (also known as softmax) applied to each row.
}
\examples{
## homogeneous Markov chain
# 2 states: 2 = 2*(2-1) free off-diagonal elements
par <- rep(-2, 2)
Gamma <- tpm(par)
# 3 states: 6 = 3*(3-1) free off-diagonal elements
par <- rep(-3, 6)
Gamma <- tpm(par)
# 4 states: 12 = 4*(4-1) free off-diagonal elements
par <- rep(-4, 12)
Gamma <- tpm(par)

## inhomogeneous Markov chain
# t.p.m. depends on covariates
z1 <- runif(100); z2 <- runif(100) # 2 covariates
Z <- cbind(1, z1, z2) # design matrix
beta0 <- c(-2, -2); beta1 = c(1, -2); beta2 = c(2, -1) # coefficients for intercept and covariates
beta <- cbind(beta0, beta1, beta2) # coefficient matrix; with intercepts!
Gamma <- tpm(beta, Z) # array with 100 slices
}
\seealso{
Other transition probability matrix functions: 
\code{\link{generator}()},
\code{\link{generator_g}()},
\code{\link{tpm_ct}()},
\code{\link{tpm_emb}()},
\code{\link{tpm_emb_g}()},
\code{\link{tpm_g}()},
\code{\link{tpm_g2}()},
\code{\link{tpm_p}()}
}
\concept{transition probability matrix functions}
