plot3logit (version 2.2.0)

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 function gg3logit() 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).

Usage

field3logit(
  model,
  delta,
  label = "",
  p0 = NULL,
  alpha = NULL,
  vcov = NULL,
  nstreams = 8,
  narrows = Inf,
  edge = 0.01,
  conf = NA,
  npoints = 100
)
# 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(x) <- value

Arguments

model

either a fitted trinomial model or a matrix of regressor coefficients. See section Compatibility and examples 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.

alpha

numeric vector of length two where constants \(\alpha^{(1)}\) and \(\alpha^{(2)}\) are stored (only for ordinal models), as defined in Equation (7) of santi2019;textualplot3logit.

vcov

(only if the model is read from a matrix, otherwise it will be ignored) variance-covariance matrix of parameter estimates. The elements of the variance-covariance matrix should be ordered according to the matrix of parameter estimates where the categories of the dependent variable are the slow index, whereas the covariates are the fast index.

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 in case that argument p0 is set.

narrows

maximum number of arrows to be drawn per curve.

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 field.

npoints

number of points of the border to be computed for each confidence region.

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.

Value

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

Details

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, whereas 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 last example in section Examples and the help of multifield3logit().

References

See Also

multifield3logit(), gg3logit(), autoplot().

Examples

# NOT RUN {
data(cross_1year)

# }
# NOT RUN {
# 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()
# }
# NOT RUN {
# 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

# }