Recommended Workflow
- Prepare your raw data.
- Generate the model estimates using
ipv_est(). - Select a chart function and use it with the estimates, a file name, and otherwise default values.
- Customize the appearance using further arguments of the chart function.
- Check the chart’s appearance by opening the created file.
- Repeat 4. + 5. until you are satisfied with the result.
Minimal example:
mydata <- HEXACO[ ,c(2:41, 122:161)] # (1.) HEXACO is a data frame containing raw data
res <- ipv_est(mydata, name = "HA") # (2.) produce a formatted bundle of estimates to use
nested_chart(res, file_name = "test.pdf") # (3.) create a chart with default formattingThere are some additional helper functions, such as the
input_... functions, which enable you to format already
existing model estimates.
Call ?IPV for an overview of all functions.
1. Prepare data
The ipv_est() function is recommended for model
estimation, because it only needs raw data. It automatically estimates
the models underlying IPV charts. Its output can be plugged into the
chart functions directly.
To use this function, your data needs to be formatted as follows:
- long format:
- columns called “test”, “facet”, and “item”, where each item is uniquely allocated to one facet of one test and each item name is unique
- a case identifying column (e.g. “id”)
- a column containing the (numeric) measurement values
- tests without facets are currently only supported in wide format
For example:
#> id value test facet item
#> 1 2 2 H Sinc Sinc1
#> 2 3 3 H Sinc Sinc1
#> 3 4 4 H Sinc Sinc1
#> 4 5 3 H Sinc Sinc1
#> 5 6 3 H Sinc Sinc1
#> 6 7 3 H Sinc Sinc1- wide format:
- all items (indicator variables) are (numeric) columns of a data frame
- the data frame contains only those variables used in the models (or use indexing as in the example)
- all columns are named according to the pattern “test_facet_item”
- all variable names are unique
- all item names (“…_…_item”) are unique at the level of the test (not only at the level of the facet!)
- tests without facets use the pattern “test_item”
- in the simple case of a single test, the pattern is “facet_item”
For example:
#> H_Sinc_Sinc2 H_Sinc_Sinc3 H_Sinc_Sinc4
#> 2 2 3 1
#> 3 2 2 2
#> 4 5 5 4H = honesty/humility (“test”)
Sinc = sincerity (a “facet” of honesty/humility)
Sinc1 = first “item” of the sincerity facet
2. Generate model estimates
ipv_est() automatically determines if the data are in
wide or long format, which models to estimate, uses the lavaan package to estimate them, and
returns an object of class “IPV” with formatted results.
# nested case: honesty/humility and agreeableness as "tests" (= sub-pools)
# of an overarching "construct" (= item pool)
res_HA <- ipv_est(dat = HEXACO[ ,c(2:41, 122:161)], name = "HA")
# simple case: agreeableness only
res_A <- ipv_est(dat = HEXACO[ ,c(122:161)], name = "A")If any factor loading is below .1 or any center distance below 0, it is set to that value and a warning (or message) is displayed. IPV does not allow negative factor loadings, which is indicated by an error. In this case, check if you have properly recoded negatively keyed items. If there remain negative factor loadings, the data does not fulfill the requirements of IPV (Dantlgraber et al., 2019).
Results are provided as an object of the class “IPV”, which is a list containing (some of) the following elements:
“lav”: the lavaan object for each estimated model (optional)
“est_raw”: estimates (factor loadings, latent correlations) structured based on the item pools, (optional)
“est”: pre-formatted list of center distances and latent correlations for IPV chart creation
You should always inspect the estimated models (“lav”) to understand
what is going on with your data. Use the lavaan functions
(e.g. lavaan::fitmeasures, lavaan::summary,
lavaan::lavInspect) for this purpose.
A more thorough introduction to the formatting of the objects representing model estimates can be found in the section on the alternative workflow in the Appendix.
3. Create and save IPV charts
Use the chart functions (item_chart,
facet_chart, nested_chart) to create an IPV
chart from your data.
All three IPV chart types can be created by specifying
data = only:
mychart <- item_chart(data = self_confidence)
mychart
If the test = argument is unspecified, the first test
will automatically be chosen.
It is advisable to use vector-based .pdf graphics output using the
file_name = argument:
mychart <- item_chart(data = self_confidence, test = "DSSEI", file_name = "DSSEI_item_chart.pdf").pdf files can be zoomed and scaled indefinitely without loss of
quality. If you need .png or .jpeg graphics output, use the
dpi = argument to find a balance between quality and file
size. The file format provided to file_name = will be used.
By default, no file is saved. Saving manually is not recommended.
It is advisable to inspect the graphics file itself. If you inspect your results within RStudio, always use the zoom pop-out of the Plots window, otherwise charts may be heavily distorted.
4. Customize IPV charts
Although some graphical options are automatically optimized based on the data, there are many ways to optimize the charts’ appearance (e.g. for print). For example you may use a different colour to guide attention, or re-size elements of the chart for readability.
4.1 center distance method
The parameter cd_method = allows to switch between
aggregation methods for center distances in facet charts and nested
charts. There are two options:
"aggregate" computes the sum of the squared loadings of
all items first and in a second step computes the center distance based
on the aggregated values. This is the recommended option and the
default. It is more meaningful in cases with heterogeneous factor
loadings across items.
"mean" first computes the center distance of each item
and in a second step computes the mean of these center distances. This
is the originally proposed option (Dantlgraber et al., 2019). It can be
intuitively derived from item charts.
4.2. Variable labels
The function relabel() can be used to change any item,
facet, test, or construct name, using a before-after syntax (see
documentation).
4.3. Size of chart elements
Most graphical parameters are size parameters for single elements of
the chart, all named size_... =, width_... =,
or length_... =. Those are pretty straightforward: linear
scaling parameters defaulting to 1. That means, .5 will half the size
and 2 will double it. For all chart types, there is also a global
size = parameter, scaling all elements of the chart at
once. Use this parameter first, before you fine tune single
elements.
4.4 Output file properties
The parameters file_width = and
file_height = determine, how large the .pdf file will be,
measured in inches (1 in = 2.54 cm). The size of .png or .jpeg files in
pixels is determined by multiplying the size in inches with the dots per
inch parameter value (dpi =).
4.5 Showing sections of the chart (“Screenshots”)
In some cases, it may be desirable to cut the chart to the
informative area for better readability, or to zoom in on a certain
section of the chart. It is possible to create vector-based PDF versions
of sections of the chart. The parameters zoom_x = and
zoom_y = can be used to crop the chart to a certain area by
providing lower and upper limits on both dimensions. The aspect ratio is
automatically retained if both parameters are used. This method is
superior to a manual screenshot, because it retains maximum graphics
quality and is exactly reproducible.
4.6. Rotation and order
For all chart types, it is possible to rotate the whole chart, using
rotate_radians = (use fractions of \(2\pi\)) or rotate_degrees =
(use 0-360). In all charts, the parameter facet_order =
enables you to set the (counter-clockwise) order of facets. For
example:
item_chart(self_confidence, test = "DSSEI", facet_order = c("Ab", "So", "Ph", "Pb"))In nested charts, test_order = and
subrotate_degrees =/subrotate_radians = will
function likewise. Several rotate_... = parameters can be
used to re-position single elements of the chart relative to the
origin.
4.7. Font
The font can be changed using the font = parameter. The
package extrafont allows
access to many more fonts. For changes to the font size, see section 4.3.
4.8. Structural elements
To reduce the visibility of structural elements, the
fade_... = parameters can be used (0 = “black”, 100 =
“white”).
4.9. Colour
For the use of colours and gray tones, see this guide. All charts functions have at least one colour parameter to increase visual contrast.
4.10 Additional plot layers
The chart functions return a ggplot2 object, which can easily be combined with other geoms or entire plots. The following example uses this to show two facet charts side by side at the same scale:
library(ggplot2)
library(cowplot)
x <- facet_chart(self_confidence) +
coord_fixed(
ratio = 1,
ylim = c(-3, 3),
xlim = c(-3, 3))
#> Axis tick set to 0.1 based on the data.
#> Facet circle radius set to 0.31 based on the data.
#> Coordinate system already present. Adding new coordinate system, which will replace the existing one.
y <- facet_chart(self_confidence, test = "RSES") +
coord_fixed(
ratio = 1,
ylim = c(-3, 3),
xlim = c(-3, 3))
#> Axis tick set to 0.05 based on the data.
#> Facet circle radius set to 0.211 based on the data.
#> Coordinate system already present. Adding new coordinate system, which will replace the existing one.# Save just as any other ggplot
ggsave(filename = "test.pdf",
plot = plot_grid(plotlist = list(x, y), align = "h"),
width = 20, height = 10) # defaults are optimized for 10x10 inches per chart4.11. Special options for item charts
You can use different colors for every second item to increase readability of item charts:
mychart <- item_chart(
data = self_confidence, test = "DSSEI",
color = "darkblue", color2 = "darkred")
mychartThe dodge = parameter allows long facet labels to dodge
the rest of the chart horizontally:
x <- self_confidence
x <- relabel(x, "So", "verylongname")
mychart1 <- item_chart(data = x, test = "DSSEI")
mychart2 <- item_chart(data = x, test = "DSSEI", dodge = 7)
mychart1
mychart2
This works simultaneously for all labels. Labels at the top and bottom
do not move, labels on the right and left move the most.
4.12. Special options for facet charts
mychart <- facet_chart(data = self_confidence, test = "DSSEI")
#> Axis tick set to 0.1 based on the data.
#> Facet circle radius set to 0.31 based on the data.
mychart
As you can see in the output (and the message in the console), two
parameter values (subradius = , and tick = )
have been generated automatically. These can be used to improve
readability. subradius = sets the size of the facet circles
and tick = sets the value at which a tick mark should be
displayed.
For a simplistic version of the chart, the correlations can be
omitted, by setting cor_labels = FALSE. It is also possible
to omit the tick marks emphasizing the center distances by setting
size_marker = 0.
mychart <- facet_chart(
data = self_confidence,
test = "DSSEI",
cor_labels = FALSE,
size_marker = 0)
#> Axis tick set to 0.1 based on the data.
#> Facet circle radius set to 0.31 based on the data.
mychart
4.13. Special options for nested charts
Due to the complexity one should not rely on default values too much:
mychart <- nested_chart(data = self_confidence)
#> Facet circle radius set to 0.211 based on the data.
#> cor_spacing set to 0.193 based on the data.
#> Relative scaling set to 3.78 based on the data.
#> Axis tick set to 0.1 based on the data.
#> dist_construct_label set to 0.5 based on the data.
mychart
There are four important options specific to nested charts:
relative_scaling =, xarrows =,
subrotate_... =, and cor_spacing =
The axis scaling within the nested facet charts is potentially
different to the global axis scaling, by exactly the factor of
relative_scaling =. This can be seen from the axis tick
marks (small dotted circles), which always indicate the same value.
relative_scaling = 1 is desirable for intuitive
understanding. Nevertheless, relative_scaling = should be
large enough to avoid circle overlap.
# all axes have the same scaling
nested_chart(self_confidence, relative_scaling = 1, tick = 0.2, rotate_tick_label = -.2)
#> Facet circle radius set to 0.211 based on the data.
#> cor_spacing set to 0.193 based on the data.
#> dist_construct_label set to 0.5 based on the data.
# the global axis is twice as large (see dotted circles)
nested_chart(self_confidence, relative_scaling = 2, tick = 0.2, rotate_tick_label = -.2)
#> Facet circle radius set to 0.211 based on the data.
#> cor_spacing set to 0.193 based on the data.
#> dist_construct_label set to 0.5 based on the data.
In this particular case, the facet circles could be larger, including the font sizes within:
mychart <- nested_chart(
data = self_confidence,
subradius = .5,
size_facet_labels = 2,
size_cor_labels_inner = 1.5)
#> cor_spacing set to 0.28 based on the data.
#> Relative scaling set to 5.97 based on the data.
#> Axis tick set to 0.1 based on the data.
#> dist_construct_label set to 0.5 based on the data.
mychart
Note how the dynamic default for relative_scaling = adapted
to the changes, because the test circles became larger, due to the
changes to subradius = .
The addition of correlation arrows between facets of different tests is indicated by the IPV authors as sensible, when the correlation between these facets exceed the correlation between the respective tests. The three arrows in the current example can also be omitted in the display:
mychart <- nested_chart(
data = self_confidence,
subradius = .5,
size_facet_labels = 2,
size_cor_labels_inner = 1.5,
xarrows = FALSE)
#> cor_spacing set to 0.28 based on the data.
#> Relative scaling set to 5.97 based on the data.
#> Axis tick set to 0.1 based on the data.
#> dist_construct_label set to 0.5 based on the data.
mychart
The column names of the data frame providing the data for the arrows need to match the example.
Note that ipv_est() generates the data frame for these
arrows automatically.
The arrows create a lot of overlap and make the chart look messy. This problem can be solved by rotating each of the nested facet charts, so the facets connected by arrows are oriented towards the center. Furthermore, the construct label should be moved out of harms way, as well as the test label of the SMTQ.
mychart <- nested_chart(
data = self_confidence,
subradius = .5,
size_facet_labels = 2,
size_cor_labels_inner = 1.5,
subrotate_degrees = c(180, 270, 90),
dist_construct_label = .7,
rotate_test_labels_degrees = c(0, 120, 0))
#> cor_spacing set to 0.28 based on the data.
#> Relative scaling set to 5.97 based on the data.
#> Axis tick set to 0.1 based on the data.
mychart
The cor_spacing = refers to the ring around the nested
facet charts for each test, in which the correlations between the tests
are displayed. It should be large enough for the correlation labels, but
not too large to skew proportions. If the correlations are omitted
(cor_labels_tests = FALSE), this ring is also omitted:
mychart <- nested_chart(
data = self_confidence,
subradius = .5,
size_facet_labels = 2,
size_cor_labels_inner = 1.5,
subrotate_degrees = c(180, 270, 90),
dist_construct_label = .7,
rotate_test_labels_degrees = c(0, 120, 0),
cor_labels_tests = FALSE)
#> Relative scaling set to 5.05 based on the data.
#> Axis tick set to 0.1 based on the data.
mychart
Color can be chosen for the global and the nested level independently. Increasing the line thickness makes the colors more visible.
mychart <- nested_chart(
data = self_confidence,
subradius = .5,
size_facet_labels = 2,
size_cor_labels_inner = 1.5,
subrotate_degrees = c(180, 270, 90),
dist_construct_label = .7,
rotate_construct_label_degrees = -15,
rotate_test_labels_degrees = c(0, 120, 0),
size_construct_label = 1.3,
size_test_labels = 1.2,
width_circles_inner = 1.2,
width_circles = 1.2,
width_axes_inner = 1.2,
width_axes = 1.2)
#> cor_spacing set to 0.28 based on the data.
#> Relative scaling set to 5.97 based on the data.
#> Axis tick set to 0.1 based on the data.
mychart