fv: Create a Function Value Table

Description

Advanced Use Only. This low-level function creates an object of class "fv" from raw numerical data.

Usage

fv(x, argu = "r", ylab = NULL, valu, fmla = NULL, alim = NULL, labl = names(x), desc = NULL, unitname = NULL, fname = NULL, yexp = ylab)

Arguments

A data frame with at least 2 columns containing the values of the function argument and the corresponding values of (one or more versions of) the function.

argu

String. The name of the column of x that contains the values of the function argument.

ylab

Either NULL, or an Rlanguage expression representing the mathematical name of the function. See Details.

valu

String. The name of the column of x that should be taken as containing the function values, in cases where a single column is required.

fmla

Either NULL, or a formula specifying the default plotting behaviour. See Details.

alim

Optional. The default range of values of the function argument for which the function will be plotted. Numeric vector of length 2.

labl

Optional. Plot labels for the columns of x. A vector of strings, with one entry for each column of x.

desc

Optional. Descriptions of the columns of x. A vector of strings, with one entry for each column of x.

unitname

Optional. Name of the unit (usually a unit of length) in which the function argument is expressed. Either a single character string, or a vector of two character strings giving the singular and plural forms, respectively.

fname

Optional. The name of the function itself. A character string.

yexp

Optional. Alternative form of ylab more suitable for annotating an axis of the plot. See Details.

Value

An object of class "fv", see fv.object.

Details

This documentation is provided for experienced programmers who want to modify the internal behaviour of spatstat. Other users please see fv.object.

The low-level function fv is used to create an object of class "fv" from raw numerical data.

The data frame x contains the numerical data. It should have one column (typically but not necessarily named "r") giving the values of the function argument for which the function has been evaluated; and at least one other column, containing the corresponding values of the function.

Typically there is more than one column of function values. These columns typically give the values of different versions or estimates of the same function, for example, different estimates of the $K$ function obtained using different edge corrections. However they may also contain the values of related functions such as the derivative or hazard rate.

argu specifies the name of the column of x that contains the values of the function argument (typically argu="r" but this is not compulsory).

valu specifies the name of another column that contains the recommended estimate of the function. It will be used to provide function values in those situations where a single column of data is required. For example, envelope computes its simulation envelopes using the recommended value of the summary function.

fmla specifies the default plotting behaviour. It should be a formula, or a string that can be converted to a formula. Variables in the formula are names of columns of x. See plot.fv for the interpretation of this formula.

alim specifies the recommended range of the function argument. This is used in situations where statistical theory or statistical practice indicates that the computed estimates of the function are not trustworthy outside a certain range of values of the function argument. By default, plot.fv will restrict the plot to this range.

fname is a string giving the name of the function itself. For example, the $K$ function would have fname="K". ylab is a mathematical expression for the function value, used when labelling an axis of the plot, or when printing a description of the function. It should be an Rlanguage object. For example the $K$ function's mathematical name $K(r)$ is rendered by ylab=substitute(K(r), NULL).

If yexp is present, then ylab will be used only for printing, and yexp will be used for annotating axes in a plot. (Otherwise yexp defaults to ylab). For example the cross-type $K$ function $K_{1,2}(r)$ is rendered by something like ylab=substitute(Kcross[i,j](r), list(i=1,j=2)) and yexp=substitute(Kcross[list(i,j)](r), list(i=1,j=2)) to get the most satisfactory behaviour.

labl is a character vector specifying plot labels for each column of x. These labels will appear on the plot axes (in non-default plots), legends and printed output. Entries in labl may contain the string "%s" which will be replaced by fname. For example the border-corrected estimate of the $K$ function has label "%sbord(r)" which becomes "Kbord(r)".

desc is a character vector containing intelligible explanations of each column of x. Entries in desc may contain the string "%s" which will be replaced by ylab. For example the border correction estimate of the $K$ function has description "border correction estimate of %s".

Examples

Run this code

df <- data.frame(r=seq(0,5,by=0.1))
  df <- transform(df, a=pi*r^2, b=3*r^2)
  X <- fv(df, "r", substitute(A(r), NULL),
              "a", cbind(a, b) ~ r,
              alim=c(0,4),
              labl=c("r", "%s[true](r)", "%s[approx](r)"),
              desc=c("radius of circle",
                     "true area %s",
                     "rough area %s"),
              fname="A")
  X