cnfa: Climate-niche factor analysis
In CENFA: Climate and Ecological Niche Factor Analysis

Description Usage Arguments Details Value References See Also Examples

Performs climate-niche factor analysis using climate raster data and species presence data.

cnfa(x, s.dat, ...)

## S4 method for signature 'GLcenfa,Raster'
cnfa(
  x,
  s.dat,
  filename = "",
  progress = FALSE,
  parallel = FALSE,
  n = 1,
  cl = NULL,
  keep.open = FALSE,
  ...
)

## S4 method for signature 'GLcenfa,Spatial'
cnfa(
  x,
  s.dat,
  field,
  fun = "last",
  filename = "",
  progress = FALSE,
  parallel = FALSE,
  n = 1,
  cl = NULL,
  keep.open = FALSE,
  ...
)

## S4 method for signature 'Raster,Raster'
cnfa(
  x,
  s.dat,
  scale = TRUE,
  filename = "",
  progress = FALSE,
  parallel = FALSE,
  n = 1,
  cl = NULL,
  keep.open = keep.open,
  ...
)

## S4 method for signature 'Raster,Spatial'
cnfa(
  x,
  s.dat,
  field,
  fun = "last",
  scale = TRUE,
  filename = "",
  progress = FALSE,
  parallel = FALSE,
  n = 1,
  cl = NULL,
  keep.open = FALSE,
  ...
)

`x`	Raster* object, typically a brick or stack with p climate raster layers, or a `GLcenfa` object
`s.dat`	RasterLayer, SpatialPolygons, or SpatialPoints object indicating species presence or abundance
`...`	Additional arguments for `writeRaster`
`filename`	character. Optional filename to save the Raster* output to file. If this is not provided, a temporary file will be created for large `x`
`progress`	logical. If `TRUE`, messages and progress bar will be printed
`parallel`	logical. If `TRUE` then multiple cores are utilized for the calculation of the covariance matrices
`n`	numeric. Number of CPU cores to utilize for parallel processing
`cl`	optional cluster object
`keep.open`	logical. If `TRUE` and `parallel = TRUE`, the cluster object will not be closed after the function has finished
`field`	field of `s.dat` that specifies presence or abundance. This is equivalent to the `field` argument in `rasterize`
`fun`	function or character. Determines what values to assign to cells with multiple spatial features, similar to the `fun` argument in `rasterize`. Options are 'first', 'last' (default), and 'count' (see Details)
`scale`	logical. If `TRUE` then the values of `x` will get centered and scaled. Depending on the resolution of the climate data and the extent of the study area, this can be quite time consuming. If running this function for multiple species, it is recommended that the data be scaled beforehand using the `GLcenfa` function

The cnfa function is not to be confused with the enfa function. enfa performs ENFA as described by Hirzel et al. (2002) and Basille et al. (2008), and is offered as an alternative to the enfa function in the adehabitatHS package. There are several key differences between ENFA and CNFA.

Whereas ENFA returns a specialization factor that describes the specialization in each ENFA factor, CNFA returns a sensitivity factor sf that describes the sensitivity in each environmental variable. This makes the sensitivity factor more directly comparable to the marginality factor mf, because their dimensions are identical. Sensitivity is calculated by a weighted sum of the amount of specialization found in each CNFA factor, including the marginality factor. As such, the sensitivity factor offers a more complete measure of specialization than ENFA's specialization factor, which does not calculate the amount of specialization found in the marginality factor. As such, CNFA's overall sensitivity (found in the slot sensitivity) offers a more complete measure of niche specialization than ENFA's overall specialization (found in the slot specialization).

The default fun = 'last' gives equal weight to each occupied cell. If multiple species observations occur in the same cell, the cell will only be counted once. fun = 'count' will weight the cells by the number of observations.

If there is too much correlation between the layers of x, the global covariance matrix will be singular, and the overall marginality and overall sensitivity will not be meaningful. In this case, a warning is issued, and marginality and sensitivity are both returned as NA.

Returns an S4 object of class cnfa with the following components:

call: Original function call
mf: Marginality factor. Vector of length p that describes the location of the species Hutchinsonian niche relative to the global niche
marginality: Magnitude of the marginality factor
sf: Sensitivity factor. Vector of length p that describes the amount of sensitivity for each climate variable
sensitivity: Square root of the mean of the sensitivity factor
eig: Named vector of eigenvalues of specialization for each CNFA factor
co: A p x p matrix describing the amount of marginality and specialization in each CNFA factor.
cov: p x p species covariance matrix
g.cov: p x p global covariance matrix
ras: RasterBrick of transformed climate values, with p layers
weights: Raster layer of weights used for CNFA calculation

Rinnan, D. Scott and Lawler, Joshua. Climate-niche factor analysis: a spatial approach to quantifying species vulnerability to climate change. Ecography (2019): <doi:10.1111/ecog.03937>.

Basille, Mathieu, et al. Assessing habitat selection using multivariate statistics: Some refinements of the ecological-niche factor analysis. Ecological Modelling 211.1 (2008): 233-240.

Hirzel, Alexandre H., et al. Ecological-niche factor analysis: how to compute habitat-suitability maps without absence data?. Ecology 83.7 (2002): 2027-2036.

GLcenfa, enfa

mod1 <- cnfa(x = climdat.hist, s.dat = ABPR, field = "CODE")

# using GLcenfa as an initial step
# for multi-species comparison

glc <- GLcenfa(x = climdat.hist)
mod2 <- cnfa(x = glc, s.dat = ABPR, field = "CODE")

# same results either way
all.equal(m.factor(mod1), m.factor(mod2))
all.equal(s.factor(mod1), s.factor(mod2))