plot3logit : Ternary Plots for Interpreting Trinomial Regression Models

This paper presents the R package plot3logit which enables the covariate effects of trinomial regression models to be represented graphically by means of a ternary plot. The aim of the plot is helping the interpretation of regression coefficients in terms of the effects that a change in values of regressors has on the probability distribution of the dependent variable. Such changes may involve either a single regressor, or a group of them (composite changes), and the package permits both cases to be handled in a user-friendly way. Moreover, plot3logit can compute and draw confidence regions of the effects of covariate changes and enables multiple changes and profiles to be represented and compared jointly. Upstream and downstream compatibility makes the package able to work with other R packages or applications other than R .


Introduction
The interpretation of the covariate effect on the probability distribution of the dependent variable of a multinomial regression model is usually neither immediate nor easy. In case of multinomial logit regression, the coefficient of a covariate x referred to the category ν (m) of the dependent variable determines the effect of a unitary change in the value of x on the logarithm of the ratio between the probability of category ν (m) and the probability of the reference category ν (1) of the dependent variable. This entails that the relation between the covariate coefficients and the probability distribution of the dependent variable is non-linear and depends also on covariate coefficients of the other regressors (see Santi, Dickson, and Espa 2019, Equations 5 and 6).
The interpretive difficulty of the parameters of multilogit models is the reason why the coefficient estimates are usually complemented by some estimates or graphical representations of covariate marginal effects. Indeed, both approaches turned out to be fruitful and led to a wide myriad of variants which have been studied from a methodological point of view (see, among the others, Agresti 2013; Fox andWeisberg 2019, 2018;Fox 2003), and have been implemented in R packages such as effects (Fox and Hong 2009), lsmeans (Lenth 2016), emmeans (Lenth 2022), MNLpred (Neumann 2021), DAMisc (Armstrong 2022).
Yet, both estimates and graphical representations of marginal effects are computed and plotted conditionally to some specific values of the covariates (or a subset of them), thus they cannot exhaustively describe the effect of a covariate over the whole space of regressors. In order to overcome this limitation, Tutz and Schauberger (2013) proposed a diagram, which allows for a representation of the direction (increase vs. decrease) and the relative magnitude of the conditional effect of covariates on the probability distribution of the dependent variable. The method, implemented in the R package EffectStars2 (Schauberger 2019), produces a very appealing and intuitive graph, which can be drawn for multinomial models with any number of categories on the dependent variable, however it relies on a reparametrisation of the multinomial logit model based on the symmetric side constraint, which, in some circumstances, may be unfeasible or undesirable.
In case of multinomial logit models where the dependent variable can take only three values (i.e., the trinomial logit models), Santi et al. (2019) show that it is possible to represent the effects of covariates in terms of changes in the probability distribution of the dependent variable by means of a vector field drawn over a ternary plot. Such a representation is possible both conditionally and unconditionally to the values of the covariates, and it can be obtained for changes involving two or more covariates (composite changes).
The graphical representation proposed in Santi et al. (2019) is implemented in R (R Core Team 2022) through package plot3logit (Santi, Dickson, Espa, and Giuliani 2022), available from the Comprehensive R Archive Network (CRAN) at https://CRAN.R-project.org/ package=plot3logit since January 2019.
Package plot3logit can read the results of both categorical and ordinal trinomial logit regression fitted by various functions (see Section 3) and creates a 'multifield3logit' object which may be represented by means of functions either based on standard R graphics or based on the grammar of graphics (Wilkinson 2005). Composite changes and multiple changes of covariates can be easily represented through a simple and flexible syntax, whereas the analysis proposed in Santi et al. (2019) has been extended by including functions for adding confidence regions of the covariate effects to the plots, in order to enrich and improve the interpretation of the results.
The paper is organised as follows. Section 2 briefly shows how to read ternary plots and how the effects of covariate changes on the probability distribution of the dependent variable in a trinomial logit regression can be represented by means of vector fields and arrows on a ternary plot. Section 3 summarizes the features of the package plot3logit. Section 4 illustrates how plot3logit reads estimates from fitted models, and how the vector fields can be customized, computed and represented graphically. Section 5 illustrates how confidence regions are computed and drawn. Section 6 introduces some wrappers. Finally, Section 7 concludes.

Ternary plots and trinomial logit regression
Ternary diagrams were firstly proposed in Bancroft (1897) as a method for representing sets of three numbers from bounded non-negative intervals subject to a constraint on their sum. This is the case of composition data as well as the probabilities of a trinomial random variable. Here we briefly sum up how ternary diagrams work; a more detailed illustration is available in Santi et al. (2019), whereas Howarth (1996 offers a valuable and intriguing history of ternary diagrams. Consider a random element N which takes values in a set of three labels {ν (1) , ν (2) , ν (3) } with probability π (m) ≡ P[N = ν (m) ], m = 1, 2, 3. The probability distribution of N can be represented through the triplets (π (1) , π (2) , π (3) ) ∈ [0, 1] 3 , however the parameter space is actually 2-dimensional, as the sum π (1) + π (2) + π (3) is constrained to equal one, thus if π (1) and π (2) are given, π (3) automatically equals 1 − π (1) − π (2) . 1 Mathematically, triplets (π (1) , π (2) , π (3) ) which are valid probability distributions define a 2-dimensional simplex in the 3-dimensional space [0, 1] 3 , which is denoted by S in the rest of the paper. Formally: The simplex S is the equilateral triangle which constitutes the ternary diagram (see Figure 1). Figure 1a shows how the Cartesian coordinates of a point P = (p 1 , p 2 , p 3 ) in the 3-dimensional space [0, 1] 3 are transposed over the 2-dimensional simplex (the ternary diagram). Note that the value of a coordinate of the point P (say, p 3 ) is the distance between P and the side opposite the vertex labelled with that component (that is, π (3) ).
Since all (and only) the admittable probability distributions of a trinomial random variable can be drawn as a point of the simplex of the ternary diagram, a change in any probability distribution can be represented through an arrow from a reference starting point A towards a final point B. Figure 1b depicts the change of the probability distribution just described, and synthesizes the basic idea for representing the effect of one or more covariates on the probability distribution of the dependent variable of a trinomial logit regression.
In order to make notation clear, the trinomial logistic regression is briefly introduced; a more detailed discussion of the model and the notation adopted in this paper is available in Santi et al. (2019), whereas a wide and in-depth dissertation on the multinomial logit regression can be found in Agresti (2013).
The multinomial logistic (or logit) regression aims at explaining the probability distribution of a multinomial variable by means of a set of regressors, which may be either quantitative or qualitative. If the number of possible values of the dependent variable equals three, we may refer to it as trinomial, and the model as trinomial logit regression.
The multinomial probability distribution belongs to the exponential family (Lehmann and Casella 1998, p. 24-25), and, in case of the trinomial distribution, it is identified by means of natural parameters (η 2 , η 3 ) ∈ R 2 , which are defined as follows: 1 Random element N is typically modeled by means of a random vector which is distributed according to a single-trial multinomial law and it is defined through indicator functions. See Santi et al. (2019) for this formalization of the problem, Johnson, Kemp, and Kotz (2005, p. 505-524) on the multinomial probability distribution, and Agresti (2013) on the modellization of categorical responses.
Equations 2 and 3 justify the interpretation of regression coefficients β (m) j as the effect of a unitary change of the j-th covariate on the logarithm of the ratio between π (m) and π (1) . Now, consider a trinomial logit regression on p covariates x = (x 1 , x 2 , . . . , x p ) (including a constant term) and a profile x 0 ∈ X ⊆ R p , so that (π (x 0 ) ) is the probability distribution associated to x = x 0 . It can be shown (see Santi et al. 2019, Equation 6) that, when x = x 0 + ∆, the probability distribution of the dependent variable changes as follows: with m = 1, 2, 3, where ∆ ∈ R p is the change of covariates, and β (1) = 0 ∈ R p by construction (see Santi et al. 2019).
As Equation 4 shows, the probability distribution after the covariate change ∆ only depends on the probability distribution before change π  Figure 2b shows the same vector field with 95% confidence regions. Coefficient estimates are reported in Table 1.
Relation 4 is thus the theoretical basis which justifies the graphical method proposed in Santi et al. (2019), as it allows one to represent and analyse the regression coefficients β (2) , β (3) over the (2-dimensional) simplex S, instead of the (k-dimensional) space of regressors X .
In the following, an example of the method is provided in order to illustrate some of the capabilities of the package plot3logit, which are discussed in depth in the next sections of the paper.
A trinomial regression is fitted on self-reported votes for US presidential elections in 2016. Data are provided in Democracy Fund Voter Study Group (2017), where a broad and detailed questionnaire was administered to a sample consisting of 8000 people. In this paper, a dataset where only some information collected by Democracy Fund Voter Study Group (2017) is used. The dataset is made available through the package plot3logit under the name USvote2016.
In the following we consider a trinomial logit regression which models the self-reported vote (which may take values "Trump", "Clinton", and "Other") over some voters' characteristics (education level, gender, race, and decade when the voter was born). Here there are the R commands for fitting the model through the package nnet (Venables and Ripley 2002): R> library("nnet") R> data("USvote2016", package = "plot3logit") R> modVote <-multinom(vote~educ + gender + race + birthyr, + data = droplevels(USvote2016), trace = FALSE) Table 1 shows point estimates and standard errors of regression coefficients.
What is hard to assess is the actual effect of gender on the probability distribution of voter's choice, Figure 2a helps in that by representing the effect of covariate genderFemale through a vector field over a ternary diagram.
The direction of arrows in Figure 2a is consistent with the conclusion outlined before, although the diagram shows also that the direction is not constant over the simplex. On the other hand, arrow lengths enable to assess the magnitude of the effect, which is not constant and cannot be directly appraised from estimates in Table 1. Figure 2b includes also the 95% confidence regions in order to assess the degree of uncertainty of the estimates and how uncertainty on regression parameters determines the uncertainty on the effects (note how shapes and sizes of confidence regions changes over the simplex).
Confidence regions are particularly useful when the effect of a covariate change is analysed for some specific profiles (see Figure 3), or when multiple effects are compared with respect to a single (common) profile, as in Figure 4.  Table 1. Figure 3 shows the effects of gender on five voter profiles distinguished only by the racial/ethnic group they belong to. The graph shows how the magnitude of the gender effect changes amongst different groups. Figure 4 shows the effects of covariates on race with respect to a white voter having the same probability of choosing Clinton (33.3%), Trump (33.3%) or other candidates (33.3%). Ternary diagram enables the reader to assess the direction and the magnitude of differences of voters' preferences by voters' race as well as the degree of uncertainty of the estimates by means of 95% confidence regions.
In the rest of the paper it is illustrated and discussed how diagrams like those in Figure 2, 3, and 4 can be drawn by means of package plot3logit.

Features
In summary, the package plot3logit can: • Read the trinomial logit models fitted by functions clm and clm2 of package ordinal Moreover, estimates obtained from other packages or software can be passed explicitly through a properly structured list and processed by plot3logit.
• Handle several sintaxes for expressing the covariate changes and represent them graphically. The current implementation enables the covariate changes to be passed to function field3logit either as numeric vectors, named numeric vectors, or mathematical expressions (through R code).
• Work both under standard R graphics paradigm through package Ternary (Smith 2022), and under the paradigm of the grammar of graphics (Wilkinson 2005) through packages ggtern (Hamilton and Ferry 2018) and ggplot2 (Wickham 2016). Moreover, methods as.data.frame, as_tibble, fortify and tidy enable the graphical data to be easily exported in a standardized format which may be used for drawing ternary fields through other packages or software.
• Fully customize any feature of ternary fields, including position, number, and alignment of arrows.
• Draw and handle several fields over the same plot, so that the effects of different changes of covariates (possibly) with respect to different profiles can be compared.
• Compute and draw confidence regions for each effect of covariate change, so that uncertainty about estimates of effects can be shown visually.
• Quickly compute and draw ternary fields and confidence regions under standard settings through several wrappers which make the code shorter and easier to write and read.

Computation of vector fields
Function field3logit computes the vector field, which represents the effects of covariate changes on the probability distribution of the dependent variable, according to a fitted model. It follows that the two most important arguments of field3logit are the parameter estimates of the model (argument model) and the change of covariate values (argument delta). Further arguments (p0, nstreams, narrows, edge) define other characteristics of the vector field. In this section it is illustrated how all these arguments can be set.

Read model estimates
Model estimates are passed to field3logit by means of argument model; when the trinomial logit model is fitted through any of these functions: • clm, clm2 of package ordinal (Christensen 2019).
field3logit internally invokes the generic extract3logit which automatically extracts all relevant information from the objects returned by those functions. 3 On the other hand, if estimates are not available as output of the previous functions, they may be passed to argument model as a named list consisting of the following components (the order is not relevant): • B: Matrix of regression coefficients. It should be a numeric matrix (or any coercible object) with two columns if the model is cardinal, with only one column if the model is ordinal. The number of rows should be equal to the number of covariates and the names of covariates should be added as row names. The intercepts should be included only in case of categorical models, whereas column names, if provided, are ignored.
• alpha: Intercepts of ordinal models. It should be a numerical vector of length two if the the model is ordinal, otherwise this component should be either set to NULL or missing.
• levels: Vector of possible values of the dependent variable. It should be a character vector of length three, whose first element is interpreted as the reference level, whereas the second and the third elements are associated to the first and second columns of matrix B respectively.
• vcovB: Covariance matrix of regression coefficients. This component is required only if the computation of confidence regions is needed (see Section 5); it should be a numeric matrix (or any coercible object) where the number of rows and columns equals the number of elements of B. Rows and columns should be ordered according to the labels of the dependent variable (slower index), and then to the covariates (faster index).
Here it is an example on how the list should be defined in case of a categorical trinomial logit regression whit four covariates (a constant term, X 1 , X 2 and X 3 ) and where the dependent variable takes values "Class A" (reference level), "Class B", "Class C": 3), + ncol = 2, dimnames = list(c("(Intercept)", "X1", "X2", "X3"))), + levels = c("Class A", "Class B", "Class C")) The list fittedModel may be passed directly to field3logit as argument model, anyway, if fittedModel is passed to extract3logit, an object of class 'model3logit' is returned: When invoked, extract3logit creates a 'model3logit' object and checks the consistency of the information provided, anyway, there is no advantage in calling extract3logit explicitly, as field3logit does it in any case on argument model.
It is also possible to define new S3 methods for generic extract3logit. The code of the new method should collect the information about the fitted model and define a list consisting of the components described above, to which should be added also the following: • readfrom: Character with information about the function that returned the estimates in the form package::function (for example nnet::multinom, MASS::polr, . . . ).
Once the list has been generated, it should be passed to function extract3logit.default, which creates a (complete and standardized) 'model3logit' object and checks on completeness and consistency of the information provided. The output of extract3logit.default should then be returned as the output of the new method.

Specification of covariate changes
The change of regressor values may be expressed in three different ways.
Firstly, it may be passed to field3logit explicitly as a numeric vector where each component specifies the change of the corresponding regressor. The vector is thus the same denoted by ∆ in Equation 4.
Consider, for example, the effect of the dummy variable genderFemale, which is the seventh covariate (including the constant term) of the model stored in modVote. The vector ∆ should be defined as follows: R> Delta <-rep(0, 17) R> Delta[7] <-1 R> Delta It is worth noting that attribute Effect of the 'multifield3logit' object obtained from the former command coincides with attribute Explicit effect of the latter 'field3logit' object.
The use of named numeric vectors and R code (passed as a character) for expressing changes of covariates makes the field3logit function easy to use, especially when changes are fractional or involve several covariates. Consider, for example, the following two equivalent commands based on the object fittedModel previously generated: R> field3logit(model = fittedModel, delta = c(X1 = 0.5, X2 = -2, X3 = 1)) R> field3logit(model = fittedModel, delta = "0.5 * X1 + X3 -2 * X2") The code is easy-to-read, easy-to-write, and does not depend on the order that covariates have in the formula of the fitted model, unlike what happens when the explicit vector of covariate changes is passed to field3logit.

As diagram in
Argument p0 enables one to set the starting points of the stream lines, in order to customize the behavior of field3logit. Argument p0 should be structured as a list whose components are numeric vectors of ternary coordinates (see object ptsAB, defined before). Bottom-left graph in Figure 5 shows an example where points A = (0.3, 0.4, 0.3) and B = (0.5, 0.1, 0.4) are set as starting points of two stream lines.
Finally, argument narrows sets the maximum number of arrows which should be computed for each stream line. 4 Bottom-right graph in Figure 5 shows the same field drawn in the bottom-left graph, but narrows = 1. Default value of narrows is Inf, so that arrows are added to a stream line until the edge set through argument edge has been reached.

Representation of vector fields
The vector fields computed by field3logit may be represented through functions provided by package Ternary (Smith 2022) which is based on standard R graphics, or functions of package ggtern (Hamilton and Ferry 2018), which extends package ggplot2 (Wickham 2016) to ternary diagrams, and it is based on the programming paradigm referred to as "grammar of graphics" (see e.g., Wickham 2016; Wickham and Grolemund 2016) illustrated in Wilkinson (2005).

Plotting by means of package Ternary
Two functions of plot3logit enable to draw vector fields of 'multifield3logit' objects through package Ternary.
Function TernaryField takes a 'multifield3logit' object as first argument and permits the vector field to be added to an existing ternary diagram created by function TernaryPlot of package Ternary. Both name and argument structure of TernaryField are consistent with other functions defined in package Ternary (such as TernaryPoint, TernaryPolygon, . . . ).
The S3 method of generic plot takes a 'multifield3logit' object as first argument and may either draw the ternary diagram from scratch (if argument add is set to FALSE), or add the vector field to an existing ternary plot (if add = TRUE), and in that case it basically works as a wrapper of TernaryField.
Some examples of the graphical rendering of vector fields drawn by means of package Ternary are shown in Figure 5.
Clearly, package plot3logit does not limit in any way the customization of the graphs made available by methods of standard R graphics and by package Ternary (see manuals of plot3logit and Ternary for details).

Plotting by means of package ggtern
Vector fields of 'multifield3logit' objects can be drawn through package ggtern by means of the constructor gg3logit, the statistics stat_field3logit, stat_conf3logit, stat_3logit, and the S3 method of generic autoplot for class field3logit.
As opposed to ggplot2 (and thus ggtern) philosophy, which only accepts 'data.frame's (or any other object of child classes, such as 'tibble') as input for argument data, package plot3logit handles both 'data.frame's and 'field3logit' objects.
This choice has been made in order to make the code simple, as if a 'multifield3logit' object is passed to gg3logit, the conversion to a data.frame and the initialization of aesthetic parameters (through the function aes) passed to argument mapping are carried out automatically.
On the contrary, if a data.frame (or any coercible object, including objects of child classes) is passed to argument data of gg3logit, the following aesthetics must be specified: • x, y, z are required by: -stat_field3logit as ternary coordinates of the starting points of the arrows.
-stat_conf3logit as ternary coordinates of the points on the edge of confidence regions (see Section 5).
• xend, yend, zend are required by stat_field3logit as ternary coordinates of the ending points of the arrows.
• group is always required as it identifies the groups of the graphical objects (arrows and their confidence regions).
• type is always required as it specifies the type of graphical object (arrows or confidence regions) the row of the data.frame refers to.
Furthermore, the following variables of a fortified 'field3logit' or a 'multifield3logit' object (see next section) 5 may be useful for defining other standard aesthetics (such as fill, colour, . . . ): • label identifies a field through a label, thus it is useful for distinguishing the fields in a 'multifield3logit' object.
• idarrow identifies each group of graphical objects (arrows and their confidence regions) within every field. Unlike variable group, idarrow is not a global identifier of graphical objects.
'multifield3logit' objects and confidence regions are illustrated in depth in the next sections of the paper.
As a first example on function gg3logit, it follows the R code for plotting the ternary diagram in Figure 2a: R> fieldFemale <-field3logit(modVote, "genderFemale") R> gg3logit(fieldFemale) + stat_field3logit() According to the previous code, when a 'multifield3logit' object is passed to gg3logit, the syntax is particularly short, as no aesthetic has to be set. On the contrary, if a fortified 'multifield3logit' object is passed to gg3logit, several aesthetics have to be initialized and the code is longer and less easy to read.
In order to compare the two syntaxes, consider the structure of the fortified object fieldFemale: 6 5 An object is referred to as fortified whenever it is processed by the method fortify (see e.g., Wickham 2016), and thus it is structured as a data.frame which contains the information available in the original object. By extension, an object may be referred to as fortified whenever it is processed through functions such as as.data.frame, as_tibble, tidy.
6 The seed of random number generator is set (through set.seed) in order to make the results of fortify fully reproducible. If the seed is not set, the labels of columns idarrow and group will be different at each execution of fortify. R> set.seed(3109) R> fortfieldFemale <-fortify(field3logit(modVote, "genderFemale")) R> set.seed(NULL) R> fortfieldFemale # A tibble: 106 × 10 label idarrow group type Clinton Trump Other Clinton_end <fct> <fct> <fct> <fct> <dbl> <dbl> <dbl> If fortfieldFemale is passed to gg3logit, the code for drawing the diagram in Figure 2a becomes considerably longer: R> gg3logit(fortfieldFemale, aes(x = Clinton, y = Trump, z = Other, + xend = Clinton_end, yend = Trump_end, zend = Other_end, group = group, + type = type)) + stat_field3logit() The simplicity of the former syntax is apparent, whereas the latter does not provide any practical advantage in terms of greater flexibility, notwithstanding the greater verbosity. This is the reason why the former syntax has been implemented, even though it deviates from orthodox ggplot2 philosophy, that requires that only 'data.frame' objects can be passed to argument data.

Plotting by means of other packages/software
Besides the integration with packages Ternary and ggtern, package plot3logit guarantees a full downstream compatibility with other R packages or other applications through the S3 methods of generics as.data.frame, as_tibble (package tibble, Müller and Wickham 2021), fortify (package ggplot2, Wickham 2016), and tidy (package broom, Robinson and Hayes 2022) for classes 'field3logit' and 'multifield3logit'. All four methods are equivalent, except that as.data.frame returns a data.frame, whereas the others return a tibble.
The mentioned methods enable the graphical information (arrows, confidence regions and labels) of a 'field3logit' or a 'multifield3logit' object to be exported in a standardized table which can be read by any other R package or can be stored on disk through standard R commands (such as write.csv, for example) and then be read by applications other than R.

Handling multiple fields
When the results of a multinomial regression are analysed, the comparison between the effects of various changes in covariate values may be of interest. Figure 4 shows how this kind of comparisons may be carried out by means of ternary plots.
Each arrow in Figure 4 is associated to a distinct change in the value of one covariate, thus, diagram in Figure 4 may be interpreted as a superimposition of five vector fields consisting of a single arrow each, and having the same profile as a reference point. This is actually the way Figure 4 has been generated.
Assume that we are interested in comparing the effects of all dummies on race in the model on United States (US) elections. Let us thus define a list whose elements are lists where only varying arguments to be passed to function field3logit are specified as named components: R> race_effects <-list( + list(delta = "raceBlack", label = "Black"), + list(delta = "raceHispanic", label = "Hispanic"), + list(delta = "raceAsian", label = "Asian"), + list(delta = "raceMixed", label = "Mixed"), + list(delta = "raceOther", label = "Other") + ) If race_effects is passed to argument delta of field3logit, in this way: R> mfieldrace <-field3logit(model = modVote, delta = race_effects, + p0 = refprofile, narrows = 1) R> mfieldrace the function field3logit is run once for every element of race_effects, and the set of 'multifield3logit' objects are combined into a single object of class 'multifield3logit'. When field3logit is applied to each element of race_effects, the arguments specified in the parent call of field3logit are used as default values, which are then overwritten by those specified in each element of race_effects.
The expedient just described enables the 'multifield3logit' objects to be generated through a short and efficient syntax even if several 'multifield3logit' objects are involved.
The syntax just described, however, can be simplified further when the fields to be generated involve dummy variables of the same qualitative covariate (encoded as factor). In that case, argument delta should indicate the name of the original covariate between delimiters < < and > >, and field3logit will create a 'multifield3logit' object where each field corresponds to the effect of each dummy variable.
The following code shows how the previous commands can be simplified further: R> field3logit(model = modVote, delta = "<<race>>", p0 = refprofile, + narrows = 1) If more than one regressor is included between delimiters < <, > >, all combinations between dummies are generated, and if only some of the fields are actually needed, the 'multifield3logit' object can be subsetted through the S3 method "[".

Confidence regions
The confidence region of δ can then be mapped to the simplex S with respect to the reference probability distribution π 0 by means of the inverse link function g ← . Hence, the confidence region R can be found as it follows: Clearly, the edge of the confidence region of Equation 7 can be found by considering those points associated to the values δ which satisfy Condition 6 exactly (i.e., with equality instead of inequality).
The package plot3logit enables confidence regions to be computed in two ways, by means of function field3logit or through function add_confregions.
Function field3logit computes the confidence regions for all the arrows in the field according to the value passed to argument conf. If conf is not set or if it is set to NA (default value), confidence regions are not computed. Clearly, the computation is possible only if the variancecovariance matrix of the estimates is available. When computed, confidence regions are part of the 'multifield3logit' object returned by field3logit.
Function add_confregions enables confidence regions to be computed on a 'field3logit' or a 'multifield3logit' object, if not present. Otherwise, it may be used to update confidence regions of a 'field3logit' or a 'multifield3logit' object according to a new confidence level. Since add_confregions returns an object of class 'field3logit' (or 'multifield3logit') equipped with confidence regions, it can be run as follows: R> mfieldrace <-add_confregions(mfieldrace) By default, argument conf is set to 0.95, thus 95% confidence regions are computed, if not differently specified. As in case of field3logit, confidence regions can be computed only if variance-covariance matrix of coefficient estimates is available.
Both function field3logit and add_confregions have an argument named npoints which allows the user to set the number of points used for drawing the edges of confidence regions.

Representation
Confidence regions can be drawn both through package Ternary and ggtern.
In the former case, the S3 method of generic plot works for both 'field3logit' and 'multifield3logit' objects, and it creates a new ternary plot if argument add is set to FALSE (default value), whilst adds a vector field(s) to an existing ternary plot if add is set to TRUE. As in the case of vector fields, confidence regions of a 'multifield3logit' object can be drawn through the function TernaryField (see the help for details).
If package ggtern is used, confidence regions of 'field3logit' and 'multifield3logit' objects can be drawn through the statistic stat_conf3logit, which works analogously to stat_field3logit.

Wrappers
Package plot3logit includes two wrappers which aims at simplifying the syntax when a 'field3logit' or a 'multifield3logit' object is drawn through package ggtern.
The first wrapper is stat_3logit which is a wrapper for: R> stat_field3logit() + stat_conf3logit() stat_3logit has arguments mapping_field and mapping_conf which enables one to specify the aesthetic mappings for stat_field3logit and stat_conf3logit respectively, whereas arguments params_field and params_conf allow one to set the graphical parameters of the two layers.
In order to provide an example, the code for drawing the graph in Figure 4 is reported both with and without wrappers.

Conclusions
Package plot3logit implements the ternary diagrams proposed in Santi et al. (2019) for interpreting the coefficient estimates of a trinomial logit regression. The package has been implemented so as to make it easy to use without losing flexibility. Upstream and downstream compatibility of the package enables the user to read model estimates whatever is the package/software that computed them, whereas the implementation of graphical functions based both on standard R graphics and ggplot2-based graphics, as well as the export methods (as.data.frame, as_tibble, fortify, tidy), provides several graphical tools for drawing the random fields, but does not prevent the user to adopt other graphical packages, or applications other than R.