eo.iso {UCS}R Documentation

Draw Iso-Line of a GAM in the (e,o) Plane (eo)

Description

Draw an iso-line of a generalised association measure (GAM) in the (e,o) plane, either for a specified cutoff threshold γ or an n-best iso-line for a given data set ds. Optionally, the corresponding acceptance region can be shaded or filled with solid colour.

Usage


eo.iso(gam, gamma=0, b=1, N=1e6, n.best=NULL, ds=NULL,
       style=1, fill=solid, solid=FALSE,
       steps=eo.par("steps"), jitter=eo.par("jitter"), bw=bw,
       bsearch.min=NULL, bsearch.max=NULL,
       col=eo.par("col"), lty=eo.par("lty"), lwd=eo.par("lwd"),
       angle=eo.par("angle"), density=eo.par("density"),
       solid.col=eo.par("solid"))

Arguments

gam a character string giving the name of a generalised association measure (GAM). Use the function builtin.gams from the gam module to obtain a list of available GAMs.
gamma a cutoff threshold that determines the iso-line to be drawn (by the implicit equation \{g = γ\}). Use the n.best and ds parameters instead of gamma in order to obtain an n-best iso-line for the data set ds.
b, N optional balance (b) and sample size (N) parameters for GAMs that are not central or size-invariant, respectively. The default b=1 yields the centralised version of a non-central GAM (for details, see Evert 2004, Sec. 3.3)
n.best, ds When these parameters are specified, the cutoff threshold gamma will automatically be determined so as to yield an n-best acceptance region for the data set ds.
jitter If TRUE, use jittered coordinates for computing the n-best cutoff threshold (see above). In this case, the data set has to be annotated with the add.jitter function first.
style an integer specifying the style (colour, line type and width) in which iso-lines will be drawn. The number of styles available depends on the global parameter settings (eo.par). The "factory settings" define 5 different styles for iso-lines.
fill If TRUE, fill in the acceptance region bounded by the given iso-line with shading lines, according to the chosen style and bw mode. See eo.par for details on shading styles.
solid If TRUE, fill the acceptance region with solid colour rather than shading lines, also according to the chosen style and bw mode. Setting solid=TRUE implies fill=TRUE.
steps an integer specifying how many equidistant steps are used for drawing iso-lines. The default value is set with eo.par.
bw If TRUE, the iso-lines are drawn in B/W mode, otherwise in colour mode. This parameter defaults to the state specified with the initial eo.setup call, but can be overridden manually.
col, lty, lwd can be used to override the default style parameters for iso-lines, which are determined automatically from the global settings (eo.par) according to the selected style and bw mode.
angle, density can be used to override the default style parameters for shaded acceptance region, which are determined automatically from the global settings (eo.par) according to the selected style and bw mode.
solid.col can be used to override the default colour for solid filled acceptance regions, which is determined automatically from the global settings (eo.par) according to the selected style and bw mode.
bsearch.min initial lower boundary for binary search algorithm, when no explicit equation for the iso-line is available (see gam.iso for details)
bsearch.max initial upper boundary for the binary search algorithm (see gam.iso)

Details

See the eo.setup help page for a description of the general procedure used to create (e,o) plots. This help page also has links to other (e,o) plotting functions. The "factory setting" styles are described on the eo.par help page.

The cutoff threshold γ can either be specified explicitly (with the gamma parameter) or implicitly as an n-best threshold (with n.best, ds, and optional jitter). The latter method produces the same result as

    gam.iso(gam, gamma=gamma.nbest(ds, gam, n.best, jitter), ...)
  

Visualisation by (e,o) iso-lines is most suitable for GAMs that are both central and size-invariant (see Evert 2004, Sec. 3.3). For non-central measures, the eo.iso function uses a balance value of b = 1, yielding a centralised version of the GAM. Note that many non-central GAMs (especially those based on statistical tests, such as log.likelihood and chi.squared) have only a weak dependency on the balance b, so that their centralised iso-surfaces (i.e. extrusions of the iso-lines along the b-axis) are very similar to the original iso-surfaces. Other GAMs (most notably Dice and similar measures) are highly dependent on b, though. For measures that are not size-invariant, the sample size is arbitrarily set to N = 10^6, which is in a realistic range for real-life data sets. You may wish to modify the default value in order to match a data set shown in the plot (this is not done automatically when the ds parameter is specified), or to demonstrate the dependency of iso-lines on N.

References

Evert, Stefan (2004). The Statistics of Word Cooccurrences: Word Pairs and Collocations. PhD Thesis, IMS, University of Stuttgart.

See Also

eo.par, eo.setup, eo.iso.diff

Examples


## an example can be found on the "eo.setup" help page


[Package UCS version 0.5 Index]