spaMM (version 2.0.0)

make_scaled_dist: Scaled distances between unique locations

Description

This fonction computes scaled distances from whichever relevant argument it can use (see Details). The result can directly by used as input for computation of the Mat<U+00E9>rn correlation matrix. It is usually called internally by HLCor, so that users may ignore it, except if they wish to control the distance used through control.dist$method, or the parametrization of the scaling through control.dist$rho.mapping.

Usage

make_scaled_dist(uniqueGeo, uniqueGeo2=NULL, distMatrix, rho, 
                 rho.mapping=seq_len(length(rho)), 
                 dist.method="Euclidean",
                 return_matrix=FALSE)

Arguments

uniqueGeo

A matrix of geographical coordinates (e.g. 2 columns for latitude and longitude), without replicates of the same location.

uniqueGeo2

NULL, or a second matrix of geographical coordinates, without replicates of the same location. If NULL, scaled distances among uniqueGeo locations are computed. Otherwise, scaled distances between locations in the two input matrices are computed.

distMatrix

A distance matrix.

rho

A scalar or vector of positive values. Scaled distance is computed as <distances in each coordinate> * rho, unless a non-trivial rho.mapping is used.

rho.mapping

A set of indices controlling which elements of the rho scale vector scales which dimension(s) of the space in which (spatial) correlation matrices of random effects are computed. Scaled distance is generally computed as <distances in each coordinate> * rho[rho.mapping]. As shown inthe Example, if one wishes to combine isotropic geographical distance and some environmental distance, the coordinates being latitude, longitude and one environmental variable, the scaled distance may be computed as (say) (lat,long,env) *rho[c(1,1,2)] so that the same scaling rho[1] applies for both geographical coordinates. In this case, rho should have length 2 and rho.mapping should be c(1,1,2).

dist.method

method argument of proxy::dist function (by default, "Euclidean", but other distances are possible (see Details).

return_matrix

Whether to return a matrix rather than a proxy::dist or proxy::crossdist object.

Value

A matrix or dist object. If there are two input matrices, rows of the return value correspond to rows of the first matrix.

Details

The function uses the distMatrix argument if provided, in which case rho must be a scalar. Vectorial rho (i.e., different scaling of different dimensions) is feasible only by providing uniqueGeo.

The dist.method argument gives access to distances implemented in the proxy package, or to user-defined ones that are made accessible to proxy through its database. Of special interest for spatial analyses are spherical distances. proxy implements the "Geodesic" distance which does not use longitude and latitude as coordinates. For this reason, spaMM implements an "Earth" method for proxy::dist, which uses longitude and latitude (in that order: see Examples) as coordinates for computing orthodromic distances in km. The Earth radius used for spherical approximation is 6371.009 km.

Examples

data(blackcap)
## a biologically not very meaningful, but syntactically correct example of rho.mapping
corrHLfit(migStatus ~ 1 + Matern(1|latitude+longitude+means),data=blackcap,
          HLmethod="ML",ranFix=list(nu=0.5,phi=1e-6),
          init.corrHLfit=list(rho=c(1,1)),
          control.dist=list(rho.mapping=c(1,1,2)))
## Using orthodromic distances: order of variables in Matern(.|longitude+latitude) matters
corrHLfit(migStatus ~ 1 + Matern(1|longitude+latitude),data=blackcap,
          HLmethod="ML",ranFix=list(nu=0.5,phi=1e-6),
          control.dist=list(dist.method="Earth"))