gam.iso {UCS}R Documentation

Compute Iso-Surfaces for GAMs (gam)

Description

Computes iso-surfaces for a generalised association measure (GAM) in standard or ebo-coordinates.

Usage

  gam.iso(name, gamma, f1, f2, N, bsearch.min=NULL, bsearch.max=NULL)
  gam.iso(name, gamme, e, b=1, N=1e6, bsearch.min=NULL, bsearch.max=NULL)

Arguments

name name of a generalised association measure (GAM)
gamma a numerical constant that determines the desired iso-surface \{g = γ\}
f1, f2, N numerical vectors specifying the f1 and f2 coordinates of points in the standard coordinate space, as well as the sample size N
e, b numerical vectors specifying the e and b coordinates of points in the ebo-coordinate space (if the balance b is not specified, it defaults to 1)
N optional numerical vector specifying the sample size N when computing iso-surfaces for a GAM that is not size-invariant in ebo-coordinates (defaults to 1e6)
bsearch.min initial lower boundary for binary search algorithm, when no explicit equation for the iso-surface is available
bsearch.max initial upper boundary for the binary search algorithm

Details

Note that all function arguments except for name must be passed explicitly by name in order to distinguish the two operating modes of gam.iso (standard vs. ebo-coordinates).

When ebo-coordinates are used, the argument N (sample size) can safely be omitted for any size-invariant GAM (in ebo-coordinates). For other GAMs, a default value of 1e6 will be used, corresponding to the typical size of a co-occurrence data set. The argument b (balance) can be omitted for any central GAMs. Otherwise, it defaults to a value of 1, corresponding to the centralized version of the respective GAM.

Use gamma.nbest to compute a suitable γ values for n-best surfaces.

When no explicit equation for the iso-surface of a GAM is available, the gam.iso function uses a binary search algorithm to solve the implicit equation \{g = γ\}. Since some GAMs are only defined for valid frequency signatures (where all four cells of the contingency table are non-negative), the binary search for the o coordinate is confined to the range from 0 to \min\{f_1, f_2\}. When no solution can be found in this range, gam.iso returns NA for the corresponding points. For GAMs where it is safe to search a larger range (notably Poisson.pv and log.likelihood), the boundaries of the search interval can be adjusted with the bsearch.min and bsearch.max parameters. Note that most other GAMs have explicit iso-equations, so these parameters are rarely needed.

Value

a vector of real numbers representing the f or o coordinates of the respective iso-surface; these are the values of f or o that solve the implicit equation \{g = γ\} for the specified values of f1, f2, N or e, b (and N); this vector may contain missing values (NA) for points where no solution is found (see "Details" for more information)

See Also

gam.score, builtin.gams, gamma.nbest

Examples

e <- 10^seq(-2, 1, .1)		# compute iso-line on logarithmic scale
o <- gam.iso("t.score", 2, e=e)

x <- 10^seq(0, 2, .1)		# compute iso-surface over rectangular grid
g <- expand.grid(f1=x, f2=x)
g$f <- gam.iso("t.score", 2, f1=g$f1, f2=g$f2, N=1000)
library(lattice)
wireframe(f ~ f1 * f2, log(g)) 

[Package UCS version 0.5 Index]