rockchalk (version 1.8.157)

getFocal: Select focal values from an observed variable.

Description

This is a generic function with 2 methods, getFocal.default handles numeric variables, while getFocal.factor handles factors. No other methods have been planned for preparation.

Many plotting functions need to select "focal" values from a variable. There is a family of functions that are used to do that. User requests can be accepted in a number of ways. Numeric and character variables will be treated differently. Please see details.

Usage

getFocal(x, ...)
# S3 method for default
getFocal(x, xvals = NULL, n = 3, pct = TRUE, ...)
# S3 method for factor
getFocal(x, xvals = NULL, n = 3, pct = TRUE, ...)
# S3 method for character
getFocal(x, xvals = NULL, n = 3, pct = TRUE, ...)

Value

A vector.

A named vector of values.

Arguments

x

Required. A variable

...

Other arguments that will be passed to the user-specified xvals function.

xvals

A function name (either "quantile", "std.dev.", "table", or "seq") or a user-supplied function that can receive x and return a selection of values.

n

Number of values to be selected.

pct

Default TRUE. Include percentage of observed cases in variable name? (used in legends)

Author

Paul E. Johnson

Details

This is used in functions like plotSlopes or plotCurves.

If xvals is not provided, a default divider for numeric variables will be the algorithm "quantile". The divider algorithms provided with rockchalk are c("quantile", "std.dev.", "table", "seq"). xvals can also be the name of a user-supplied function, such as R's pretty(). If the user supplies a vector of possible values, that selection will be checked to make sure all elements are within a slightly expanded range of x. If a value out of range is requested, a warning is issued. Maybe that should be an outright error?

With factor variables, xvals is generally not used because the only implemented divider algorithm is "table" (see cutByTable), which selects the n most frequently observed values. That is the default algorithm. It is legal to specify xvals = "table", but there is no point in doing that. However, xvals may take two other formats. It may be a user-specified function that can select levels values from x or it may be a vector of labels (or, names of levels). The purpose of the latter is to check that the requested levels are actually present in the supplied data vector x. If the levels specified are not in the observed variable, then this function stops with an error message.

Examples

x <- rnorm(100)
getFocal(x)
getFocal(x, xvals = "quantile")
getFocal(x, xvals = "quantile", n = 5)
getFocal(x, xvals = "std.dev")
getFocal(x, xvals = "std.dev", n = 5)
getFocal(x, xvals = c(-1000, 0.2, 0,5))
x <- factor(c("A","B","A","B","C","D","D","D"))
getFocal(x)
getFocal(x, n = 2)

x <- c("A","B","A","B","C","D","D","D")
getFocal(x)
getFocal(x, n = 2)