% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/tpm_functions.R
\name{tpm_p}
\alias{tpm_p}
\title{Build all transition probability matrices of a periodically inhomogeneous HMM}
\usage{
tpm_p(
  tod = 1:24,
  L = 24,
  beta,
  degree = 1,
  Z = NULL,
  byrow = FALSE,
  ad = NULL,
  report = TRUE
)
}
\arguments{
\item{tod}{equidistant sequence of a cyclic variable

For time of day and e.g. half-hourly data, this could be 1, ..., L and L = 48, or 0.5, 1, 1.5, ..., 24 and L = 24.}

\item{L}{length of one full cycle, on the scale of tod}

\item{beta}{matrix of coefficients for the off-diagonal elements of the transition probability matrix

Needs to be of dimension \code{c(nStates *(nStates-1), 2*degree+1)}, where the first column contains the intercepts.}

\item{degree}{degree of the trigonometric link function

For each additional degree, one sine and one cosine frequency are added.}

\item{Z}{pre-calculated design matrix (excluding intercept column)

Defaults to \code{NULL} if trigonometric link should be calculated. 
From an efficiency perspective, \code{Z} should be pre-calculated within the likelihood function, as the basis expansion should not be redundantly calculated. This can be done by using \code{\link{trigBasisExp}}.}

\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 \code{beta} parameters returned by popular HMM packages like \code{moveHMM}, \code{momentuHMM}, or \code{hmmTMB}.}

\item{ad}{optional logical, indicating whether automatic differentiation with RTMB should be used. By default, the function determines this itself.}

\item{report}{logical, indicating whether the coefficient matrix \code{beta} should be reported from the fitted model. Defaults to \code{TRUE}, but only works if \code{ad = TRUE}.}
}
\value{
array of transition probability matrices of dimension \code{c(nStates, nStates, length(tod))}
}
\description{
Given a periodically varying variable such as time of day or day of year and the associated cycle length, 
this function calculates the transition probability matrices by applying the inverse multinomial logistic link (also known as softmax) to linear predictors of the form
\deqn{ 
 \eta^{(t)}_{ij} = \beta_0^{(ij)} + \sum_{k=1}^K \bigl( \beta_{1k}^{(ij)} \sin(\frac{2 \pi k t}{L}) + \beta_{2k}^{(ij)} \cos(\frac{2 \pi k t}{L}) \bigr) }
for the off-diagonal elements (\eqn{i \neq j}) of the transition probability matrix.
This is relevant for modeling e.g. diurnal variation and the flexibility can be increased by adding smaller frequencies (i.e. increasing \eqn{K}).
}
\details{
Note that using this function inside the negative log-likelihood function is convenient, but it performs the basis expansion into sine and cosine terms each time it is called. 
As these do not change during the optimisation, using \code{\link{tpm_g}} with a pre-calculated (by \code{\link{trigBasisExp}}) design matrix would be more efficient.
}
\examples{
# hourly data 
tod = seq(1, 24, by = 1)
L = 24
beta = matrix(c(-1, 2, -1, -2, 1, -1), nrow = 2, byrow = TRUE)
Gamma = tpm_p(tod, L, beta, degree = 1)

# half-hourly data
## integer tod sequence
tod = seq(1, 48, by = 1)
L = 48
beta = matrix(c(-1, 2, -1, -2, 1, -1), nrow = 2, byrow = TRUE)
Gamma1 = tpm_p(tod, L, beta, degree = 1)

## equivalent specification
tod = seq(0.5, 24, by = 0.5)
L = 24
beta = matrix(c(-1, 2, -1, -2, 1, -1), nrow = 2, byrow = TRUE)
Gamma2 = tpm_p(tod, L, beta, degree = 1)

all(Gamma1 == Gamma2) # same result
}
\seealso{
Other transition probability matrix functions: 
\code{\link{generator}()},
\code{\link{generator_g}()},
\code{\link{tpm}()},
\code{\link{tpm_ct}()},
\code{\link{tpm_emb}()},
\code{\link{tpm_emb_g}()},
\code{\link{tpm_g}()},
\code{\link{tpm_g2}()}
}
\concept{transition probability matrix functions}
