jcc.plot {jrt}

Plot the category curves for a judge.

Description

This function returns the Judge Category Curves (JCC) plot from a jrt object and the judge number. This is a wrapper function and adaptation of the itemplot function in the package mirt (Chalmers, 2012). It also uses the plotting functions of the packages directlabels and ggplot2.

Usage

jcc.plot(
  jrt.object,
  judge = "all",
  labelled = T,
  greyscale = F,
  vertical.labels = F,
  title = "auto",
  column.names = "auto",
  manual.facet.names = "auto",
  manual.line.names = "auto",
  overlay.reliability = F,
  color.palette = "D3",
  category.name.for.legend = "",
  name.for.reliability = "auto",
  theta.span = 3.5,
  line.width = 0.8,
  line.opacity = 1,
  key.width = 3,
  legend.position = "right",
  legend.columns = "",
  theme = "bw",
  text.size = 10,
  title.size = text.size + 4,
  font.family = "sans",
  remove.gridlines = T,
  facet.rows = NULL,
  facet.cols = NULL,
  facet.title.position = "top",
  precision = 20,
  debug = F,
  mirt.object.input = F,
  item = NULL
)

Arguments

jrt.object

A object of the jrt class (created by the function jrt).

judge

A numerical to indicate which judge(s) to plot. Default is all which plots all category curves of all judges. Alternatively, a single integer may be used to plot the JCC for one judge, or a vector of integers to plot multiple judges in a faceted plot. Note that, if a (Generalized) Rating Scale Model was used, then judges may have been removed for the model to be fitted.

labelled

A logical to indicate whether the curves should be labelled with boxed labels (TRUE, default) or whether a legend should be used instead (FALSE). This uses the package directlabels. Note that the rendering is slower (and may take more time to show in GUI) when the plot is labelled.

greyscale

A logical to indicate whether to plot in greyscale (TRUE, default) as opposed to color (FALSE).

vertical.labels

A logical to indicate whether the labels should be vertically oriented (TRUE), as opposed to oriented inthe angle of the trace curve (FALSE, the default).

title

A character title for the plot. By default it is created automatically based on the judge number.

column.names

A character to indicate what a column corresponds to (Defaults to "auto", which uses what was set in the estimation function jrt, whose default is "judge", but you may use "Rater", "Expert", "Item", etc.). This is used to create automatic titles.

manual.facet.names

A vector to indicate the names to give to the different facets. Defaults to "auto", which will automatically name them. If not using "auto", the vector length should be equal to the total number of items/judges (not the total in the plot but the total in the dataset).

manual.line.names

A vector to indicate the individual names to give to the different response categories (or different category curves). Defaults to "auto", which names categories from 1 to the number of categories. If not using "auto", the vector supplied should be of the same length as the number of response categories (use the name.for.reliability argument to change it for reliability).

overlay.reliability

A logical to indicate whether to overlay the reliability function of the item (default is FALSE). If overlayed (TRUE), the reliability function will be contrast with the category curves by being in color if the category curves are in blackandwhite, and in black dashed if the category curves are in color.

color.palette

A character value to indicate the colour palette to use. Defaults to "D3" from "ggsci". Use "" for the default of ggplot2. The palettes are supplied as arguments to ggplot2. See here for a list of palettes. In addition, most palettes from the package ggsci are available (e.g., "npg", "aas", "nejm", "lancet", "jama", "d3"). Use vignette("ggsci") for details. Make sure there are enough colors in the palette. Alternatively, you can pass a vector of colors.

category.name.for.legend

A character to indicate how to call categories in the legend. Default to "Category" but for example you may try "Cat." or even "" to save space.

name.for.reliability

A character to indicate a preferred name for reliability in the legend or labels. Defaults to "auto", which adapts to whether labels are used.

theta.span

A numeric indicating the maximum \theta.

line.width

A numeric indicating the width of the trace lines (default is 2.5).

line.opacity

A numeric vector to indicate opacities for the different category lines. Defaults to 1. Must be of length equal to the number of categories + 1 (for the reliability line, even if not plotted). For example if there are 5 response categories this vector should be of length 6.

key.width

A numeric to indicate the width of the legend key (default is 3).

legend.position

A character string or vector of coordinates to position the legend key. Defaults to "right". Other possibilities include notably "bottom".

legend.columns

A numeric to indicate after how many legend key elements to add a line break. Especially useful if using legend.position = "bottom" if you want line breaks between each key. Defaults to "", which automatically saves space based on the legend position (line breaks are used if the legend in positioned on the side of the graph).

theme

A character value to indicate the background color theme used by ggplot2. Defaults to "bw". Can be "light", "dark", "minimal", "classic", "gray", "bw" or "linedraw".

text.size

A numeric value to control the size of the text on the plot.

title.size

A numeric value to control the size of the plot title (defaults to text.size+4).

font.family

A character value to control the font family used on the graph. Defaults to "sans". Other possible values include "serif" or "mono".

remove.gridlines

A logical value to remove the gridlines (default is TRUE).

facet.rows

A numeric to change the number of rows for faceted plots. Use this one or facet.cols, not both. Defaults to NULL, which uses ggplot2's automatic layout.

facet.cols

A numeric to change the number of columns for faceted plots. Use this one or facet.row, not both. Defaults to NULL, which uses ggplot2's automatic layout.

facet.title.position

A character string to indicate the position of the facet titles for faceted plts. Defaults to "top", but can be "bottom", "left", or "right".

precision

A numeric to indicate the degree of precision used to plot the category curves. Higher values will increase the accuracy of the graph and make the curves look smoother, but the data generated to plot the graph will be bigger, which will slow down the function. Lower values will do the opposite. Values between 10 and 100 are recommended, 20 is the default and sufficient for most uses.

debug

A logical to report debug messages (used in development). Defaults to FALSE.

mirt.object.input

A logical allowing to input directly an mirt object as a jrt.object argument, even though this should be detected automatically. See mirt package documentation, and note that this is a secondary use that may lead to inconsistent results at this point.

item

For convenience, this argument, more standard to IRT packages, can be used instead of the judge argument.

Value

A plot of the category curves.

References

Chalmers, R., P. (2012). mirt: A Multidimensional Item Response Theory Package for the R Environment. Journal of Statistical Software, 48(6), 1-29. doi:10.18637/jss.v048.i06

Myszkowski, N., & Storme, M. (2019). Judge Response Theory? A call to upgrade our psychometrical account of creativity judgments. Psychology of Aesthetics, Creativity and the Arts, 13(2), 167-175. doi:10.1037/aca0000225

Myszkowski, N. (2021). Development of the R library “jrt”: Automated item response theory procedures for judgment data and their application with the consensual assessment techniques. Psychology of Aesthetics, Creativity and the Arts, 15(3), 426-438. doi:10.1037/aca0000287

Examples

# Load dataset
data <- jrt::ratings

# Fit model
fit <- jrt(data, irt.model = "PCM")

# JCC of the first judge
jcc.plot(fit, 1)

# See vignette for more options