field3logit: Computation of the vector field

Description

field3logit() computes the vector field associated to a change in regressior values (which may involve more than one regressor) of a trinomial logit model either fitted by some multinomial regression function or explicitly specified.

The method plot() draws the ternary plot using standard graphics methods provided by package Ternary. See functions gg3logit() and autoplot() for plotting through the package ggtern based on the grammar of graphics.

Methods as.data.frame(), as_tibble(), fortify() and tidy() permits the graphical information of a field3logit object to be exported in a standardised format (either a data.frame or a tibble).

See santi2022;textualplot3logit for details and examples.

Usage

field3logit(
  model,
  delta,
  label = "",
  p0 = NULL,
  nstreams = 8,
  narrows = Inf,
  edge = 0.01,
  conf = NA,
  npoints = 100,
  alpha = deprecated(),
  vcov = deprecated()
)
# S3 method for field3logit
print(x, ...)
# S3 method for field3logit
plot(x, ..., add = FALSE, length = 0.05)
# S3 method for field3logit
as_tibble(x, ..., wide = TRUE)
# S3 method for field3logit
as.data.frame(x, ..., wide = TRUE)
# S3 method for field3logit
fortify(model, data, ..., wide = TRUE)
# S3 method for field3logit
tidy(x, ..., wide = TRUE)
# S3 method for field3logit
coef(object, ...)
# S3 method for field3logit
vcov(object, ...)
# S3 method for field3logit
labels(object, ...)
# S3 method for field3logit
labels(object) <- value

Value

S3 object of class field3logit structured as a named list or an object of class multifield3logit if delta is a list or syntax <<...>> is used.

Arguments

model: either a fitted trinomial model or a list properly structured. See section Details of extract3logit() and the last example of plot3logit-package.
delta: the change in the values of covariates to be represented. This could be either a numeric vector, the name of a covariate (passed either as a character or an expression), or a mathematical expression involving one or more than one covariates (passed either as a character or an expression). If a list is passed to delta, multiple fields are computed according to parameters passed as components of a 2-level list. See details and examples.
label: label to be used for identifying the field when multiple fields are plotted. See multifield3logit().
p0: list of starting points (ternary coordinates) of the curves of the field. If not specified, field3logit automatically compute nstreams candidate points so that arrows are evenly distributed over the ternary plot area. See Examples.
nstreams: number of stream lines of the field to be computed. In case of ordinal models, this parameter is ineffective, as only one curve can be drawn. The parameter is ineffective also if argument p0 is set.
narrows: maximum number of arrows to be drawn per stream line.
edge: minimum distance between each arrow (or point) and the edge of the ternary plot.
conf: confidence level of confidence regions to be computed for each arrow of the vector field.
npoints: number of points of the border to be computed for each confidence region.
alpha: deprecated argument. It may be removed in a future version of the package.
vcov: deprecated argument. It may be removed in a future version of the package.
x, object: object of class field3logit.
...: other arguments passed to or from other methods.
add: logical argument which specifies whether the field should be added to an existing plot (add = TRUE) or a new ternary plot should be drawn (add = FALSE).
length: length of the edges of the arrow head (in inches).
wide: it allows to choose whether as.data.frame, as_tibble, fortify and tidy should return a data.frame or a tibble in wide (default) or long form.
data: not used. Argument included only for interface compatibility with the generic fortify.
value: value to be assigned.

Details

The content of this section is presented with plenty of details and examples in Sections 4.1 and 4.3 of santi2022;textualplot3logit.

Argument delta could be passed in one of the following formats:

explicitly, as a numeric vector corresponding to the change \(\Delta x\in\bm{R}^k\) in regressors values \(x\in\bm{R}^k\);
implicitly, as a character of the name of the covariate to be considered. In this case, vector \(\Delta x\in\bm{R}^k\) is computed for a unit change of the specified covariate;
as a mathematical expression (passed as an expression or a character object) involving one or more than one covariates. This allows one to analyse the effects of composite covariate changes through an easy-to-write and easy-to-read code without having to cope with explicit numerical specification of vector \(\Delta x\in\bm{R}^k\).

See examples for comparing all three methods.

It is also possible to pass a list to argument delta. In such a case, the function field3logit is run once for every component of delta, and the set of generated field3logit objects is combined into a single object of class multifield3logit. The compoments of the list passed to delta must be named lists whose elements are used as arguments of each call of function field3logit, whilst the arguments specified in the parent call of field3logit are used as default values. It follows that arguments shared by all fields can be specified once in the parent call of field3logit, and only arguments which changes from field to field (such as delta and label) should be set in the lists making up the list passed to delta. See the penultimate example in section Examples and the help of multifield3logit().

Finally, when argument delta is a character, it is possible to indicate the name of a factor covariate between delimiters <<, >>. In that case, field3logit() creates a multifield3logit object where each field corresponds to the effect of each dummy generated by the factor regressor. If more than one regressor is included between delimiters <<, >>, all combinations between dummies are generated. See the last example in section Examples.

Examples

Run this code

data(cross_1year)

# \donttest{
# Fitting the model
mod0 <- nnet::multinom(employment_sit ~ finalgrade + irregularity + hsscore,
  cross_1year)
mod0

# Assessing the effect of "finalgradeHigh" (explicit notation)
field0 <- field3logit(mod0, c(0, 0, 1, 0, 0, 0))
gg3logit(field0) + stat_field3logit()

# Assessing the effect of "finalgradeHigh" (implicit notation)
field0 <- field3logit(mod0, 'finalgradeHigh')
gg3logit(field0) + stat_field3logit()

# Assessing the combined effect of "finalgradeHigh" and
# a decrease of "hsscore" by 10
field0 <- field3logit(mod0, 'finalgradeHigh - 10 * hsscore')
gg3logit(field0) + stat_field3logit()
# }

# Fitting the model
mod1 <- nnet::multinom(employment_sit ~ ., data = cross_1year)

# List passed to argument "delta" for generating "multifield3logit" objects
refpoint <- list(c(0.7, 0.15, 0.15))
depo <- list(
  list(delta = 'durationShort',  label = 'Short duration'),
  list(delta = 'durationLong',   label = 'Long duration'),
  list(delta = 'finalgradeHigh', label = 'High final grade'),
  list(delta = 'finalgradeLow',  label = 'Low final grade')
)
mfields <- field3logit(mod1, delta = depo, p0 = refpoint, narrows = 1)
mfields

# Sintax "<<...>>" for categorical covariates
mfields <- field3logit(
  model = mod1, delta = '<>', label = 'Final grade',
  p0 = refpoint, narrows = 1
)
mfields