spaMM: make.scaled.dist – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

make.scaled.dist

Scaled distances between unique locations

Description

This function 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é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. control.dist$method provide access to the distances implemented in the proxy package, as well as to "EarthChord" and "Earth" methods defined in spaMM (see Details).

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 in the 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.

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 distances computed from longitude and latitude (proxy implements "Geodesic" and "Chord" distances but they do not use such coordinates: instead, they use Euclidean distance for 2D computations, i.e. Euclidean distance between points on a circle rather than on a sphere). spaMM implements two such distances: "Earth" and "EarthChord", using longitude and latitude inputs in that order (see Examples). The "EarthChord" distance is the 3D Euclidean distance “through Earth”. The "Earth" distance is also known as the orthodromic or great-circle distance, on the Earth surface. Both distances return values in km and are based on approximating the Earth by a sphere of radius 6371.009 km.

Value

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

Examples

data("blackcap")
## a biologically not very meaningful, but syntactically correct example of rho.mapping
fitme(migStatus ~ 1 + Matern(1|longitude+latitude+means),
      data=blackcap, fixed=list(nu=0.5,phi=1e-6),
      init=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; 
# Matern(1|latitude+longitude) should cause a warning
fitme(migStatus ~ 1 + Matern(1|longitude+latitude),data=blackcap,
      method="ML", fixed=list(nu=0.5,phi=1e-6),
      control.dist=list(dist.method="Earth"))

spaMM

Mixed-Effect Models, with or without Spatial Random Effects

v3.10.0

CeCILL-2

Authors

François Rousset [aut, cre, cph] (<https://orcid.org/0000-0003-4670-0371>), Jean-Baptiste Ferdy [aut, cph], Alexandre Courtiol [aut] (<https://orcid.org/0000-0003-0637-2959>), GSL authors [ctb] (src/gsl_bessel.*)

Initial release

2022-02-06