pl_fit: Distribution-fitting functions
In spatialwarnings: Spatial Early Warning Signals of Ecosystem Degradation

pl_fit

R Documentation

Distribution-fitting functions

Description

These functions fit parametric distributions to a set of discrete values.

Usage

pl_fit(dat, xmin = 1)

exp_fit(dat, xmin = 1)

lnorm_fit(dat, xmin = 1)

tpl_fit(dat, xmin = 1)

Arguments

`dat`	The set of values to which the distribution are fit
`xmin`	The minimum possible value to consider when fitting the distribution

Details

These functions will fit distributions to a set of values using maximum-likelihood estimation. In the context of the 'spatialwarnings' package, they are most-often used to fit parametric distributions on patch size distributions. As a result, these functions assume that the data contains only integer, strictly positive values. The type of distribution depends on the prefix of the function: 'pl' for power-law, 'tpl' for truncated power-law, 'lnorm' for lognormal and 'exp' for an exponential distribution.

In the context of distribution-fitting, 'xmin' represents the minimum value that a distribution can take. It is often used to represent the minimum scale at which a power-law model is appropriate (Clauset et al. 2009), and can be estimated on an empirical distribution using xmin_estim. Again, please note that the fitting procedure assumes here that xmin is equal or grater than one.

Please note that a best effort is made to have the fit converge, but it may sometimes fail when the parameters are far from their usual range, and numerical issues may occur. It is good practice to make sure the fits are sensible when convergence warnings are reported.

For reference, the shape of the distributions is as follow:

power-law: x^{-a} where a is the power-law exponent
exponential: exp(-bx) where b is the truncation rate of the exponential
truncated power-law: x^{-a}exp(-bx) where a and b are the exponent of the power law and the rate of truncation

The lognormal form follows the standard definition.

The following global options can be used to change the behavior of fitting functions and/or produce more verbose output:

spatialwarnings.constants.reltol

the relative tolerance to use to compute the power-law normalizing constant

sum_{k=1}^{\infty} x^{ak}e^{-bk}

. Increase to increase the precision of this constant, which can be useful in some cases, typically with large sample sizes. Default is 1e-8.

spatialwarnings.constants.maxit

the maximum number of iterations to compute the normalizing constant of a truncated power-law. Increase if you get a warning that the relative tolerance level (defined above) was not reached. Default is 1e8

spatialwarnings.debug.fit_warn_on_bound

logical value. Warn if the fit is at the boundary of the valid range for distribution parameter

spatialwarnings.debug.fit_warn_on_NA

logical value. Warn if the returned fit has NA/NaN parameters

Value

A list containing at list the following components:

type: The type of distribution fitted (as a character string)
method: The method used for the fit - here, maximum likelihood, 'll'
ll: The log likelihood at the estimated parameter values
xmin: The value of xmin used for the fit
npars: The number of parameters of the distribution

Additionally, this list may have one or more of the following elements depending on the type of distribution that has been fitted:

plexpo: The exponent of the power-law
cutoff: The rate of truncation, for truncated power law and exponential fits
meanlog: The mean of the lognormal distribution
sdlog: The s.d. of the lognormal distribution

References

Clauset, Aaron, Cosma Rohilla Shalizi, and M. E. J. Newman. 2009. “Power-Law Distributions in Empirical Data.” SIAM Review 51 (4): 661–703. https://doi.org/10.1137/070710111.

Examples


# Fit an exponential model to patch size distribution 
exp_fit(patchsizes(forestgap[[8]]))
 
# Use the estimated parameters as an indicator function


get_truncation <- function(mat) { 
   c(exp_cutoff = exp_fit(patchsizes(mat))$cutoff)
}
trunc_indic <- compute_indicator(forestgap, get_truncation)
plot(trunc_indic)
plot(indictest(trunc_indic, nulln = 19))

spatialwarnings documentation built on Sept. 11, 2024, 8:55 p.m.