pMEM (version 0.1-1)

genDWF: Distance Weighting Function Generator

Description

Function genDWF generates a distance weighting function on the basis of given arguments.

Usage

genDWF(
  fun = c("linear", "power", "hyperbolic", "spherical", "exponential", "Gaussian",
    "hole_effect"),
  range,
  shape = 1
)

Value

A single-argument function (d) transforming the distances into weights. This function returns a matrix when the distances are provided as a matrix and a numeric vector when the distances are provided as a numeric vector.

Arguments

fun

The function describing the kind of distance weighting: one of 'linear', 'power', 'hyperbolic', 'spherical', 'exponential', 'Gaussian', 'hole_effect', or an unambiguous abbreviation of one of them.

range

A single numeric value giving the range of the distance weighting function (see details).

shape

A single (numeric) shape parameter used by functions 'power' or 'hyperbolic' (ignored by the other functions).

Author

tools:::Rd_package_author("pMEM")

Details

All distance weighting function return the value 1 (or 1+0i) for a distance or 0 (or 0+0i). For functions 'linear', 'power', 'hyperbolic', and 'spherical', argument range corresponds to the distance above which weights have a constant value of 0 (or 0+0i). Functions 'exponential', 'Gaussian', and 'hole_effect' have no definite value beyond d > range, but collapse asymptotically toward 0 either monotonically ('exponential' and 'Gaussian'), or following dampened oscillations about the value 0 ('hole_effect').

Examples

 ## Show examples of distance weighting functions (real-valued)

## Custom display function for this example (real-values):
plotDWF <- function(d, w, label, ylim = c(0,1)) {
  plot(x = d, y = w[,1L], type = "l", ylim = ylim, las = 1L,
       xlab = "Distance", ylab = "", cex.axis = 2, cex.lab=2, lwd = 2)
  lines(x = d, y = w[,2L], col = "red", lwd = 2)
  lines(x = d, y = w[,3L], col = "blue", lwd = 2)
  text(x = 2.5, y = 0.8, label = label, adj = 0, cex = 2)
}

## A set of distances from which to show the corresponding weights:
d <- seq(0,5,0.001)

## Graphical parameters for all the figures:
tmp <- par(no.readonly = TRUE)
par(mar=c(5.1,5.1,0.6,0.6))

## Shapes of the seven distance weighting functions implemented in this
## package for real-valued distances.

## The linear function:

cbind(
  genDWF(fun = "linear", range = 1)(d),
  genDWF(fun = "linear", range = 0.5)(d),
  genDWF(fun = "linear", range = 2)(d)
) -> w

plotDWF(d, w, label="Linear")

## The power function:

cbind(
  genDWF(fun = "power", range = 1, shape = 1)(d),
  genDWF(fun = "power", range = 2, shape = 0.5)(d),
  genDWF(fun = "power", range = 3, shape = 0.5)(d)
) -> w

plotDWF(d, w, label="Power")

## The hyperbolic function:

cbind(
  genDWF(fun = "hyperbolic", range = 1, shape = 1)(d),
  genDWF(fun = "hyperbolic", range = 2, shape = 0.5)(d),
  genDWF(fun = "hyperbolic", range = 0.5, shape = 2)(d)
) -> w

plotDWF(d, w, label="Hyperbolic")

## The spherical function:

cbind(
  genDWF(fun = "spherical", range = 1)(d),
  genDWF(fun = "spherical", range = 0.5)(d),
  genDWF(fun = "spherical", range = 2)(d)
) -> w

plotDWF(d, w, label="Spherical")

## The exponential function:

cbind(
  genDWF(fun = "exponential", range = 1)(d),
  genDWF(fun = "exponential", range = 0.5)(d),
  genDWF(fun = "exponential", range = 2)(d)
) -> w

plotDWF(d, w, label="Exponential")

## The Gaussian function:

cbind(
  genDWF(fun = "Gaussian", range = 1)(d),
  genDWF(fun = "Gaussian", range = 0.5)(d),
  genDWF(fun = "Gaussian", range = 2)(d)
) -> w

plotDWF(d, w, label="Gaussian")

## The "hole effect" (cardinal sine) function:

cbind(
  genDWF(fun = "hole_effect", range = 1)(d),
  genDWF(fun = "hole_effect", range = 0.5)(d),
  genDWF(fun = "hole_effect", range = 2)(d)
) -> w

plotDWF(d, w, label="Hole effect", ylim=c(-0.2,1))


## Custom display function for this example (complex-values):
plotDWFcplx <- function(d, w, label, ylim) {
  plot(x = Mod(d), y = Re(w[,1L]), type = "l", ylim = ylim, las = 1L,
  xlab = "Distance", ylab = "", cex.axis = 2, cex.lab=2, lwd = 2, lty = 2L)
  lines(x = Mod(d), y = Im(w[,1L]), lwd = 2, lty=3L)
  lines(x = Mod(d), y = Re(w[,2L]), col = "red", lwd = 2, lty = 2L)
  lines(x = Mod(d), y = Im(w[,2L]), col = "red", lwd = 2, lty = 3L)
  lines(x = Mod(d), y = Re(w[,3L]), col = "blue", lwd = 2, lty = 2L)
  lines(x = Mod(d), y = Im(w[,3L]), col = "blue", lwd = 2, lty = 3L)
  text(x = 2.5, y = 0.8, label = label, adj = 0, cex = 2)
  invisible(NULL)
}

## Generated the asymmetric distance metrics for a one-dimensional transect
## and a delta of pi/8 (0.39...):
dd <- complex(modulus=seq(0,5,0.001), argument = pi/8)

## Shapes of the seven distance weighting functions implemented in this
## package for complex-valued distances.

## The linear function:

cbind(
  genDWF(fun = "linear", range = 1)(dd),
  genDWF(fun = "linear", range = 0.5)(dd),
  genDWF(fun = "linear", range = 2)(dd)
) -> ww

plotDWFcplx(dd, ww, label="Linear", ylim=c(-0.4,1))

## The power function:

cbind(
  genDWF(fun = "power", range = 1, shape = 1)(dd),
  genDWF(fun = "power", range = 2, shape = 0.5)(dd),
  genDWF(fun = "power", range = 3, shape = 0.5)(dd)
) -> ww

plotDWFcplx(dd, ww, label="Power", ylim=c(-0.4,1))

## The hyperbolic down function:

cbind(
  genDWF(fun = "hyperbolic", range = 1, shape = 1)(dd),
  genDWF(fun = "hyperbolic", range = 2, shape = 0.5)(dd),
  genDWF(fun = "hyperbolic", range = 0.5, shape = 2)(dd)
) -> ww

plotDWFcplx(dd, ww, label="Hyperbolic", ylim=c(-0.4,1))

## The spherical function:

cbind(
  genDWF(fun = "spherical", range = 1)(dd),
  genDWF(fun = "spherical", range = 0.5)(dd),
  genDWF(fun = "spherical", range = 2)(dd)
) -> ww

plotDWFcplx(dd, ww, label="Spherical", ylim=c(-0.4,1))

## The exponential function:

cbind(
  genDWF(fun = "exponential", range = 1)(dd),
  genDWF(fun = "exponential", range = 0.5)(dd),
  genDWF(fun = "exponential", range = 2)(dd)
) -> ww

plotDWFcplx(dd, ww, label="Exponential", ylim=c(-0.4,1))

## The Gaussian function:

cbind(
  genDWF(fun = "Gaussian", range = 1)(dd),
  genDWF(fun = "Gaussian", range = 0.5)(dd),
  genDWF(fun = "Gaussian", range = 2)(dd)
) -> ww

plotDWFcplx(dd, ww, label="Gaussian", ylim=c(-0.4,1))

## The "hole effect" (cardinal sine) function:

cbind(
  genDWF(fun = "hole_effect", range = 1)(dd),
  genDWF(fun = "hole_effect", range = 0.5)(dd),
  genDWF(fun = "hole_effect", range = 2)(dd)
) -> ww

plotDWFcplx(dd, ww, label="Hole effect", ylim=c(-0.3,1.1))

## Restore previous graphical parameters:
par(tmp)