% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/indicator_plrange.R
\name{indicator_plrange}
\alias{indicator_plrange}
\title{Power-law range indicator}
\usage{
indicator_plrange(mat, merge = FALSE, xmin_bounds = NULL)
}
\arguments{
\item{mat}{A logical matrix, or a list of logical matrices}

\item{merge}{Controls whether the patch-size distributions of the input 
matrices are merged together before computing the power-law range. Setting 
this value to \code{TRUE} makes the function return a single value even 
if multiple matrices are given as input.}

\item{xmin_bounds}{A vector of two integer values, defining a range in which 
to search for the best xmin (see Details).}
}
\value{
A \code{data.frame} with columns \code{minsize}, \code{maxsize} which are the
  observed minimum and maximum patch sizes, the estimated \eqn{x_{min}} as column
  \code{xmin} and the value of the power-law range as \code{plrange}. If multiple
  matrices were provided, then a list of data.frames is returned
}
\description{
Compute the power-law range of a matrix
}
\details{
Some ecosystems show typical changes in their patch-size 
distribution as they become more and more degraded. In particular, an 
increase in the truncation of the patch-size distribution (PSD) is expected 
to occur. The power-law range (PLR) measures the truncation of the PSD 
in a single value (see also \code{\link{patchdistr_sews}} for more details). 

To compute the PLR, power-laws are fitted with a variable 
minimum patch size (\eqn{x_{min}}) and the one with the lowest Kolmogorov-Smirnov
distance to the empirical distribution is retained. PLR is then computed 
using this best-fitting \eqn{x_{min}} as: 

\deqn{\frac{log(x_{max}) - log(x_{min})}{log(x_{max}) - log(x_{smallest})}}{ (log(xmax) - log(xmin))/(log(xmax) - log(xsmallest))}

where \eqn{x_{max}}{x_max} is the maximum observed patch size, and 
\eqn{x_{smallest}}{x_smallest} is the minimum observed patch size.
}
\examples{
\donttest{
forestgap.plr <- indicator_plrange(forestgap) 
do.call(rbind, forestgap.plr) # convert results to data.frame

# Restrict to small xmins 
forestgap.plr2 <- indicator_plrange(forestgap, xmin_bounds = c(1, 10)) 
do.call(rbind, forestgap.plr2) 
}
}
\references{
Clauset, A., Shalizi, C. R., & Newman, M. E. (2009). 
  Power-law distributions in empirical data. SIAM review, 51(4), 661-703.

Berdugo, M., Kefi, S., Soliveres, S. & Maestre, F.T. (2017). Plant spatial 
patterns identify alternative ecosystem multifunctionality states in 
global drylands. Nature in Ecology and Evolution.
}
\seealso{
\code{\link{patchdistr_sews}}
}
