% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/is_leslie_matrix.R
\name{is_leslie_matrix}
\alias{is_leslie_matrix}
\title{Determine if a matrix is a Leslie matrix population model}
\usage{
is_leslie_matrix(A, includes_mat_F = TRUE)
}
\arguments{
\item{A}{Matrix to be tested}

\item{includes_mat_F}{A logical argument (default `TRUE`) indicating whether
A is expected to include fecundity. The idea here is that A may not include
fertility, but could still be a valid Leslie matrix if fertility was truly
measured to be 0, or if fertility was not measured at all. Thus, this
argument relaxes the test for the first row of A summing to a positive
value.}
}
\value{
A logical value indicating whether the matrix is a Leslie matrix or
not
}
\description{
Checks if a given matrix is a Leslie matrix.
}
\details{
A formal Leslie matrix satisfies the following conditions:
* All elements are non-negative.
* The subdiagonal elements (survivals), excluding the last column, are all
  between 0 and 1.
* The sum of the elements in the first row (fecundities) is positive (unless
  `includes_mat_F = FALSE`).
* The upper triangle, excluding the first row, contains only 0s.
* The diagonal, excluding the top-left corner (`A[1,1]`), contains only 0s.
* The lower triangle, excluding the subdiagonal, contains only 0s.

**Plus-group extension.** In some models the oldest age class is an open-
ended *plus group* representing individuals that have survived beyond the
maximum explicitly modelled age. These individuals remain in the last class
with probability `A[n,n] > 0`. This function accepts such matrices by also
exempting the bottom-right corner (`A[n,n]`) from the diagonal-zero
requirement. When a plus-group matrix is passed to `leslie_collapse`, the
`A[n,n]` term is correctly carried through the internal `leslie_expand` step.
}
\examples{
# Standard Leslie matrix
A <- matrix(c(
  0.1, 1.2, 1.1,
  0.1, 0.0, 0.0,
  0.0, 0.2, 0.0
), nrow = 3, byrow = TRUE)
is_leslie_matrix(A) # true

# Plus-group Leslie matrix: A[n,n] > 0 is permitted
A_plus <- matrix(c(
  0.1, 1.2, 1.1,
  0.1, 0.0, 0.0,
  0.0, 0.2, 0.3
), nrow = 3, byrow = TRUE)
is_leslie_matrix(A_plus) # true

# Not a Leslie matrix: non-zero off-diagonal elements
A <- matrix(c(
  0.1, 1.2, 1.1,
  0.1, 0.2, 0.1,
  0.2, 0.3, 0.3
), nrow = 3, byrow = TRUE)
is_leslie_matrix(A) # false

# leslie_mpm1 is a plus-group Leslie matrix (A[n,n] > 0)
data(leslie_mpm1)
A <- leslie_mpm1$matU + leslie_mpm1$matF
is_leslie_matrix(A) # true

}
\seealso{
Other transformation: 
\code{\link{leslie_collapse}()},
\code{\link{mpm_collapse}()},
\code{\link{mpm_rearrange}()},
\code{\link{mpm_split}()},
\code{\link{mpm_standardize}()},
\code{\link{name_stages}()},
\code{\link{repro_stages}()},
\code{\link{scale_mpm_to_lambda1}()},
\code{\link{standard_stages}()}
}
\author{
Owen Jones <jones@biology.sdu.dk>
}
\concept{transformation}
