Type:	Package
Title:	Visualization of 'exametrika' Output Using 'ggplot2'
Version:	1.0.0
Description:	Provides 'ggplot2'-based visualization functions for output objects from the 'exametrika' package, which implements test data engineering methods described in Shojima (2022, ISBN:978-981-16-9547-1). Supports a wide range of psychometric models including Item Response Theory, Latent Class Analysis, Latent Rank Analysis, Biclustering (binary, ordinal, and nominal), Bayesian Network Models, and related network models. All plot functions return 'ggplot2' objects that can be further customized by the user.
URL:	https://kosugitti.github.io/ggExametrika/, https://github.com/kosugitti/ggExametrika
BugReports:	https://github.com/kosugitti/ggExametrika/issues
License:	MIT + file LICENSE
Encoding:	UTF-8
Depends:	R (≥ 4.1.0), ggplot2
Imports:	ggraph, ggrepel, gridExtra, igraph, tidyr
RoxygenNote:	7.3.3
Suggests:	exametrika, testthat (≥ 3.0.0)
Config/testthat/edition:	3
NeedsCompilation:	no
Packaged:	2026-03-25 00:04:06 UTC; newton
Author:	Koji Kosugi [aut, cre], Daichi Kamimura [aut]
Maintainer:	Koji Kosugi <kosugitti@gmail.com>
Repository:	CRAN
Date/Publication:	2026-03-29 16:20:03 UTC

Return the first non-NULL value from arguments

Description

Internal utility for fallback chains (e.g., new naming -> deprecated naming).

Usage

.first_non_null(...)

Arguments

Value

The first non-NULL value, or NULL if all are NULL.

Default color palette for ggExametrika

Description

Returns the package default color palette (ColorBrewer Dark2). Colorblind-friendly and high-contrast for both screen and print.

Usage

.gg_exametrika_palette(n = 8)

Arguments

Value

A character vector of hex color codes.

Item Information Function for 4PLM

Description

Computes the Item Information Function (IIF) for the four-parameter logistic model in Item Response Theory. The information function indicates how precisely an item measures ability at different theta levels.

Usage

ItemInformationFunc(x, a = 1, b, c = 0, d = 1)

Arguments

Details

Higher discrimination (a) parameters result in higher information. Items provide maximum information near their difficulty (b) parameter. The guessing (c) and upper asymptote (d) parameters reduce the maximum information an item can provide.

Value

A numeric value representing the item information at the given ability level.

See Also

LogisticModel

Examples

# Information at ability = 0 for an item with b = 0
ItemInformationFunc(x = 0, a = 1.5, b = 0, c = 0, d = 1)

# Compare information at different ability levels
sapply(seq(-3, 3, 0.5), function(x) ItemInformationFunc(x, a = 1, b = 0))

GRM Item Information Function

Description

Computes the Item Information Function (IIF) for the Graded Response Model. The information function indicates how precisely an item measures ability at different theta levels.

Usage

ItemInformationFunc_GRM(theta, a, b)

Arguments

Details

For GRM, the Item Information Function is computed as:

I(\theta) = a^2 \sum_{k=1}^{K-1} P_k^*(\theta) [1 - P_k^*(\theta)]

where P_k^*(\theta) is the cumulative probability of scoring in category k or above.

Value

A numeric value representing the item information at the given ability level.

See Also

plotICRF_gg

Examples

# Information at ability = 0 for a 5-category item
ItemInformationFunc_GRM(theta = 0, a = 1.5, b = c(-1, -0.5, 0.5, 1))

Four-Parameter Logistic Model

Description

Computes the probability of a correct response using the four-parameter logistic model (4PLM) in Item Response Theory.

Usage

LogisticModel(x, a = 1, b, c = 0, d = 1)

Arguments

Details

The four-parameter logistic model extends the 3PLM by adding an upper asymptote parameter d, which accounts for careless errors by high-ability examinees.

The model formula is:

P(\theta) = c + \frac{d - c}{1 + \exp(-a(\theta - b))}

Special cases:

• 1PLM: a = 1, c = 0, d = 1

• 2PLM: c = 0, d = 1

• 3PLM: d = 1

Value

A numeric value representing the probability of a correct response.

See Also

ItemInformationFunc

Examples

# Compute probability for ability = 0, difficulty = 0
LogisticModel(x = 0, a = 1, b = 0, c = 0, d = 1) # Returns 0.5

# 3PLM with guessing parameter
LogisticModel(x = -3, a = 1.5, b = 0, c = 0.2, d = 1)

Display Multiple Plots Simultaneously from ggExametrika Output

Description

This function arranges multiple ggplot objects from ggExametrika functions into a single display using a grid layout. Useful for comparing plots across items or students.

Usage

combinePlots_gg(plots, selectPlots = c(1:6))

Arguments

Details

This function uses gridExtra::grid.arrange to combine multiple plots. The number of rows and columns is automatically determined. For more control over layout, consider using gridExtra::grid.arrange directly with the nrow and ncol arguments.

Value

A gtable object containing the arranged plots, displayed as a side effect.

Examples

library(exametrika)
result <- IRT(J15S500, model = 3)
plots <- plotICC_gg(result)
combinePlots_gg(plots, selectPlots = 1:6) # Show first 6 items
combinePlots_gg(plots, selectPlots = c(1, 5, 10)) # Show specific items

Plot Array from exametrika

Description

This function takes exametrika output as input and generates array plots using ggplot2. Array plots visualize the response patterns of students (rows) across items (columns), showing both the original data and the clustered/reordered data.

Supports both binary (0/1) and multi-valued (ordinal/nominal) data.

Usage

plotArray_gg(
  data,
  Original = TRUE,
  Clusterd = TRUE,
  Clusterd_lines = TRUE,
  Clusterd_lines_color = NULL,
  title = TRUE,
  colors = NULL,
  show_legend = NULL,
  legend_position = "right"
)

Arguments

Details

The array plot provides a visual representation of the biclustering result. For binary data, black cells indicate correct responses (1) and white cells indicate incorrect responses (0). For multi-valued data, different colors represent different response categories.

In a well-fitted model, the clustered plot should show a clear block diagonal pattern where high-ability students (bottom rows) answer difficult items (right columns) correctly.

Value

A ggplot object or a grid arrangement of two ggplot objects (original and clustered plots side by side).

See Also

plotFRP_gg, plotTRP_gg

Examples

library(exametrika)
result <- Biclustering(J35S515, nfld = 5, ncls = 6)

# Basic usage
plotArray_gg(result)

# Custom boundary line color
plotArray_gg(result, Clusterd_lines_color = "blue")

# Multi-valued data with custom colors
synthetic_data <- matrix(sample(0:3, 50 * 20, replace = TRUE), nrow = 50, ncol = 20)
result_multi <- Biclustering(synthetic_data, nfld = 4, ncls = 5)
plotArray_gg(result_multi, show_legend = TRUE, Clusterd_lines_color = "darkgreen")

Plot Class Membership Profile (CMP) from exametrika

Description

This function takes exametrika output as input and generates Class Membership Profile (CMP) plots using ggplot2. CMP shows each student's membership probability across all latent classes.

Usage

plotCMP_gg(
  data,
  title = TRUE,
  colors = NULL,
  linetype = "dashed",
  show_legend = FALSE,
  legend_position = "right"
)

Arguments

Details

The Class Membership Profile visualizes how strongly each student belongs to each latent class. Students with high membership probability in a single class are well-classified, while students with similar probabilities across classes may be ambiguous cases.

Value

A list of ggplot objects, one for each student. Each plot shows the membership probability across all latent classes.

See Also

plotRMP_gg, plotLCD_gg

Examples

library(exametrika)

result <- LCA(J15S500, ncls = 5)
plots <- plotCMP_gg(result)
plots[[1]] # Show CMP for the first student

Plot Class Reference Vector (CRV) from exametrika

Description

This function takes exametrika Biclustering output as input and generates a Class Reference Vector (CRV) plot using ggplot2. CRV shows how each latent class performs across fields, with one line per class.

Supports both binary (2-valued) and polytomous (multi-valued) biclustering models. For polytomous data, the stat parameter controls how expected scores are calculated from category probabilities.

Usage

plotCRV_gg(
  data,
  title = TRUE,
  colors = NULL,
  linetype = "solid",
  show_legend = TRUE,
  legend_position = "right",
  stat = "mean",
  show_labels = NULL
)

Arguments

Details

The Class Reference Vector is the transpose of the Field Reference Profile (FRP). While FRP shows one plot per field, CRV displays all classes in a single plot with fields on the x-axis. Each line represents a latent class, showing its correct response rate pattern across fields.

Binary Data (2 categories):

• Y-axis shows "Correct Response Rate" (0.0 to 1.0)

• Values represent the probability of correct response

Polytomous Data (3+ categories):

• Y-axis shows "Expected Score" (1 to max category)

• Values are calculated using the stat parameter

• Higher scores indicate better performance

CRV is used when latent classes are nominal (unordered). For ordered latent ranks, use plotRRV_gg instead.

Value

A single ggplot object showing the Class Reference Vector.

See Also

plotRRV_gg, plotFRP_gg, plotScoreField_gg

Examples

# Binary biclustering
library(exametrika)
result <- Biclustering(J35S515, nfld = 5, ncls = 6)
plotCRV_gg(result)


# Ordinal biclustering (polytomous)
data(J35S500)
result_ord <- Biclustering(J35S500, ncls = 5, nfld = 5, method = "R")
plotCRV_gg(result_ord) # Default: mean
plotCRV_gg(result_ord, stat = "median")
plotCRV_gg(result_ord, stat = "mode")

Plot Field Cumulative Boundary Reference from exametrika

Description

This function takes exametrika ordinalBiclustering output as input and generates a Field Cumulative Boundary Reference (FCBR) plot using ggplot2. The plot shows cumulative probability curves for each category boundary across latent classes or ranks. For each field, multiple lines represent the probability of scoring at or above each category boundary.

Usage

plotFCBR_gg(
  data,
  fields = NULL,
  title = TRUE,
  colors = NULL,
  linetype = NULL,
  show_legend = TRUE,
  legend_position = "right"
)

Arguments

Details

The Field Cumulative Boundary Reference (FCBR) visualizes how the probability of reaching each category boundary changes across latent classes or ranks in ordinal biclustering. This is particularly useful for understanding the difficulty of each response category threshold across different ability levels.

For a field with K categories (1, 2, ..., K), the FCBR shows:

• Line 1: P(response >= 1 | class/rank) = 1.0 (always)

• Line 2: P(response >= 2 | class/rank)

• Line 3: P(response >= 3 | class/rank)

• ...

• Line K: P(response >= K | class/rank)

The boundary probabilities are calculated by summing the probabilities of all categories at or above the boundary threshold. P(Q>=1) is always 1.0 and appears as a horizontal line at the top. Higher classes/ranks (higher ability) typically show higher probabilities for higher boundaries.

Value

A single ggplot object with faceted subplots for each field.

See Also

plotFCRP_gg, plotScoreField_gg, plotArray_gg

Examples

library(exametrika)
# Ordinal biclustering example with polytomous data
result <- Biclustering(J35S500, ncls = 4, nfld = 5)

# Plot first 4 fields
plot <- plotFCBR_gg(result, fields = 1:4)
plot

# Custom colors and title (5 colors needed for 5-category ordinal data)
plot <- plotFCBR_gg(result,
  fields = 1:5,
  title = "Field Cumulative Boundary Reference",
  colors = c("red", "blue", "green", "purple", "orange")
)
plot

Plot Field Category Response Profile (FCRP) for Polytomous Biclustering

Description

Creates a Field Category Response Profile (FCRP) plot for polytomous (ordinal or nominal) Biclustering results. FCRP displays the probability of each response category for each latent class/rank within each field.

Usage

plotFCRP_gg(
  data,
  style = c("line", "bar"),
  title = TRUE,
  colors = NULL,
  linetype = NULL,
  show_legend = TRUE,
  legend_position = "right"
)

Arguments

Details

FCRP (Field Category Response Profile) visualizes how response category probabilities change across latent classes or ranks within each field. For each field, the plot shows P(response = k | class/rank) for all categories k. Probabilities sum to 1.0 for each class/rank.

This plot is only available for polytomous Biclustering models (ordinalBiclustering or nominalBiclustering) that have 3 or more response categories.

The style parameter allows two visualizations:

• "line": Shows category probability curves as lines with points

• "bar": Shows stacked bar chart with category proportions

Value

A ggplot object showing category response probabilities for each field and latent class/rank.

See Also

plotFCBR_gg, plotScoreField_gg

Examples

library(exametrika)
# Ordinal Biclustering with 5 categories
result <- Biclustering(J35S500, ncls = 5, nfld = 5, method = "R")

# Line plot (default)
plotFCRP_gg(result, style = "line")

# Stacked bar chart
plotFCRP_gg(result, style = "bar")

# Custom styling
plotFCRP_gg(result,
  style = "line",
  title = "Category Response Patterns",
  colors = c("#E69F00", "#56B4E9", "#009E73", "#F0E442", "#CC79A7")
)

Plot Field Reference Profile (FRP) from exametrika

Description

This function takes exametrika output as input and generates a Field Reference Profile (FRP) plot using ggplot2. For binary data, it displays correct response rates. For polytomous data, it shows expected scores calculated using the specified statistic.

Usage

plotFRP_gg(
  data,
  stat = "mean",
  fields = NULL,
  title = TRUE,
  colors = NULL,
  linetype = "solid",
  show_legend = TRUE,
  legend_position = "right"
)

Arguments

Details

The Field Reference Profile shows how response patterns vary across latent classes/ranks for each field (cluster of items).

For binary data (Biclustering, IRM, LDB, BINET):

• Y-axis: Correct Response Rate (0-1)

• Each line represents one field

For polytomous data (nominalBiclustering, ordinalBiclustering):

• Y-axis: Expected Score (calculated using stat parameter)

• stat = "mean": Weighted average across categories (default)

• stat = "median": Median category value

• stat = "mode": Most probable category

Value

A single ggplot object with all selected fields.

See Also

plotIRP_gg, plotTRP_gg, plotCRV_gg, plotRRV_gg

Examples

library(exametrika)

# Binary biclustering
result_bin <- Biclustering(J35S515, ncls = 4, nfld = 3)
plot <- plotFRP_gg(result_bin)


# Ordinal biclustering with mean (default)
result_ord <- Biclustering(J35S500, ncls = 4, nfld = 3)
plot_mean <- plotFRP_gg(result_ord, stat = "mean")

# Using mode for polytomous data
plot_mode <- plotFRP_gg(result_ord,
  stat = "mode",
  title = "Field Reference Profile (Mode)",
  colors = c("red", "blue", "green")
)

Plot Field PIRP (Parent Item Reference Profile) from exametrika

Description

This function takes exametrika LDB output as input and generates Field PIRP (Parent Item Reference Profile) plots using ggplot2. Field PIRP shows the correct response rate for each field as a function of the number-right score in parent fields.

Usage

plotFieldPIRP_gg(
  data,
  title = TRUE,
  colors = NULL,
  linetype = "solid",
  show_legend = FALSE,
  legend_position = "right"
)

Arguments

Details

In Local Dependence Biclustering (LDB), items in a field may depend on performance in parent fields. The Field PIRP visualizes this dependency by showing how the correct response rate in each field changes based on the number of correct responses in parent fields.

Note: Warning messages about NA values may appear during plotting but the behavior is normal.

Value

A list of ggplot objects, one for each rank. Each plot shows the correct response rate curves for all fields at that rank level.

See Also

plotFRP_gg, plotArray_gg

Examples

library(exametrika)
# LDB requires field configuration and edge structure
conf <- c(
  1, 6, 6, 8, 9, 9, 4, 7, 7, 7, 5, 8, 9, 10, 10, 9, 9,
  10, 10, 10, 2, 2, 3, 3, 5, 5, 6, 9, 9, 10, 1, 1, 7, 9, 10
)
edges_data <- data.frame(
  "From Field (Parent) >>>" = c(6, 4, 5, 1, 1, 4, 3, 4, 6, 2, 4, 4, 3, 6, 4, 1, 7, 9, 6, 7),
  ">>> To Field (Child)" = c(8, 7, 8, 7, 2, 5, 5, 8, 8, 4, 6, 7, 5, 8, 5, 8, 10, 10, 8, 9),
  "At Class/Rank (Locus)" = c(2, 2, 2, 2, 2, 2, 3, 3, 3, 3, 3, 3, 4, 4, 4, 4, 5, 5, 5, 5)
)
tmp_file <- tempfile(fileext = ".csv")
write.csv(edges_data, file = tmp_file, row.names = FALSE)
result <- LDB(J35S515, ncls = 5, conf = conf, adj_file = tmp_file)
unlink(tmp_file)
plots <- plotFieldPIRP_gg(result)
plots[[1]] # Show Field PIRP for rank 1

Plot DAG (Directed Acyclic Graph) from exametrika

Description

Creates a ggplot2-based visualization of DAG structures from exametrika Bayesian network models. Supports BNM, LDLRA, LDB, and BINET models. Design based on TDE figures with items as rounded rectangles and fields as diamonds.

Usage

plotGraph_gg(
  data,
  layout = "sugiyama",
  direction = "BT",
  node_size = 12,
  label_size = 4,
  arrow_size = 3,
  title = TRUE,
  colors = NULL,
  show_legend = FALSE,
  legend_position = "right"
)

Arguments

Details

Design follows TDE figure specifications:

• BNM: Items shown as purple circles with numbers inside

• LDLRA: Items as circles per rank/class, one plot per rank. Isolated nodes auto-removed

• LDB: Fields shown as green diamonds, one plot per rank. Isolated nodes auto-removed

• BINET: Integrated graph with Class nodes (blue squares) and Field nodes (green diamonds) as intermediates. Field nodes are smaller and placed between the Class nodes they connect

Direction Guidelines:

Choose the direction that best represents your data structure:

• Use BT (default) for learning progression, skill development, or upward growth

• Use TB for traditional hierarchies or causal flows

• Use LR/RL for temporal sequences or wide-format displays

Auto-Scaling:

The function automatically scales node and arrow sizes based on graph complexity:

• 1-5 nodes: 100\

• 6-10 nodes: 80\

• 11-20 nodes: 60\

• 21+ nodes: 50\

Arrows maintain a minimum size of 2mm to ensure visibility.

Value

A list of ggplot objects. For BNM, a single-element list. For LDLRA/LDB, one plot per rank/class. For BINET, the integrated graph.

Note

The linetype common option is not applicable to DAG visualization, as edges are drawn as directed arrows rather than standard lines.

Examples

library(exametrika)
library(ggExametrika)

# BNM example
DAG <- matrix(c(
  "Item01", "Item02", "Item02", "Item03",
  "Item02", "Item04", "Item03", "Item05",
  "Item04", "Item05"
), ncol = 2, byrow = TRUE)
g <- igraph::graph_from_data_frame(DAG)
result <- BNM(J5S10, g = g)

# Default: Bottom-to-Top (arrows point upward)
plots <- plotGraph_gg(result)
plots[[1]]

# Alternative directions
plotGraph_gg(result, direction = "TB")[[1]] # Top-to-Bottom
plotGraph_gg(result, direction = "LR")[[1]] # Left-to-Right
plotGraph_gg(result, direction = "RL")[[1]] # Right-to-Left

# Force-directed layout (no direction parameter)
plotGraph_gg(result, layout = "fr")[[1]]

# Custom title
plotGraph_gg(result, title = "My Network Model")[[1]]

Plot Item Category Boundary Response from exametrika

Description

This function takes exametrika LRAordinal output as input and generates an Item Category Boundary Response (ICBR) plot using ggplot2. The plot shows cumulative probability curves for each category boundary across latent ranks. For each item, multiple lines represent the probability of scoring at or above each category boundary.

Usage

plotICBR_gg(
  data,
  items = NULL,
  title = TRUE,
  colors = NULL,
  linetype = NULL,
  show_legend = TRUE,
  legend_position = "right"
)

Arguments

Details

The Item Category Boundary Response (ICBR) visualizes how the probability of reaching each category boundary changes across latent ranks. This is particularly useful for understanding the difficulty of each response category in ordinal items.

For an item with K categories (0, 1, ..., K-1), the ICBR shows:

• Line 1: P(response >= 1 | rank)

• Line 2: P(response >= 2 | rank)

• ...

• Line K: P(response >= K | rank) (always 1.0 for category 0)

Higher ranks typically show lower probabilities for higher categories, indicating lower ability levels.

Value

A single ggplot object with faceted subplots for each item, or a combined plot using gridExtra if faceting is not suitable.

See Also

plotScoreFreq_gg, plotLRD_gg, plotRMP_gg

Examples

library(exametrika)

result <- LRA(J15S3810, nrank = 4, dataType = "ordinal")

# Plot first 4 items
plot <- plotICBR_gg(result, items = 1:4)
plot

# Custom colors and title
plot <- plotICBR_gg(result,
  items = 1:6,
  title = "Item Category Boundary Response",
  colors = c("red", "blue", "green", "purple")
)
plot

Plot Item Characteristic Curves (ICC) from exametrika

Description

This function takes exametrika IRT output as input and generates Item Characteristic Curves (ICC) using ggplot2. ICC shows the probability of a correct response as a function of ability (theta).

Usage

plotICC_gg(
  data,
  items = NULL,
  xvariable = c(-4, 4),
  title = TRUE,
  colors = NULL,
  linetype = "solid",
  show_legend = FALSE,
  legend_position = "right"
)

Arguments

Details

The function supports 2PL, 3PL, and 4PL IRT models:

• 2PL: slope (a) and location (b) parameters

• 3PL: adds lower asymptote (c) parameter

• 4PL: adds upper asymptote (d) parameter

The ICC is computed using the four-parameter logistic model:

P(\theta) = c + \frac{d - c}{1 + \exp(-a(\theta - b))}

Value

A list of ggplot objects, one for each item. Each plot shows the Item Characteristic Curve for that item.

See Also

plotIIC_gg, plotTIC_gg

Examples

library(exametrika)
result <- IRT(J15S500, model = 3)
plots <- plotICC_gg(result)
plots[[1]] # Show ICC for the first item
combinePlots_gg(plots, selectPlots = 1:6) # Show first 6 items

Plot All Item Characteristic Curves Overlaid from exametrika

Description

This function takes exametrika IRT output as input and generates an overlay plot of all Item Characteristic Curves (ICC) using ggplot2. All item curves are displayed on a single graph for easy comparison.

Usage

plotICC_overlay_gg(
  data,
  items = NULL,
  xvariable = c(-4, 4),
  title = TRUE,
  colors = NULL,
  linetype = "solid",
  show_legend = TRUE,
  legend_position = "right"
)

Arguments

Details

This function is similar to calling plot(IRT_result, type = "IRF", overlay = TRUE) in the exametrika package, but returns a ggplot2 object that can be further customized.

The ICC is computed using the four-parameter logistic model:

P(\theta) = c + \frac{d - c}{1 + \exp(-a(\theta - b))}

Value

A single ggplot object showing all Item Characteristic Curves overlaid on one graph.

See Also

plotICC_gg, plotIIC_gg

Examples

library(exametrika)
result <- IRT(J15S500, model = 3)
plotICC_overlay_gg(result) # All items
plotICC_overlay_gg(result, items = 1:5) # First 5 items only
plotICC_overlay_gg(result, title = "My Custom Title", show_legend = TRUE)

Plot Item Category Response Function (ICRF) for GRM from exametrika

Description

This function takes exametrika GRM output as input and generates Item Category Response Function (ICRF) plots using ggplot2. Each plot shows the probability of selecting each response category as a function of ability (theta).

Usage

plotICRF_gg(
  data,
  items = NULL,
  xvariable = c(-4, 4),
  title = TRUE,
  colors = NULL,
  linetype = "solid",
  show_legend = TRUE,
  legend_position = "right"
)

Arguments

Details

The Graded Response Model (GRM) estimates the probability of selecting each ordered response category. For an item with K categories, the ICRF shows K curves, one for each category. At any given ability level, the probabilities across all categories sum to 1.

The category probabilities are derived from cumulative probabilities:

P_k^*(\theta) = \frac{1}{1 + \exp(-a(\theta - b_k))}

P_k(\theta) = P_k^*(\theta) - P_{k+1}^*(\theta)

Value

A list of ggplot objects, one for each item. Each plot shows the Item Category Response Function for that item.

See Also

plotICC_gg

Examples

library(exametrika)

result <- GRM(J5S1000)
plots <- plotICRF_gg(result)
plots[[1]] # Show ICRF for the first item
combinePlots_gg(plots, selectPlots = 1:5)

Plot Item Category Reference Profile from exametrika

Description

This function takes exametrika LRAordinal or LRArated output as input and generates an Item Category Reference Profile (ICRP) plot using ggplot2. The plot shows response probability curves for each category across latent ranks. For each item, multiple lines represent the probability of selecting each response category.

Usage

plotICRP_gg(
  data,
  items = NULL,
  title = TRUE,
  colors = NULL,
  linetype = NULL,
  show_legend = TRUE,
  legend_position = "right"
)

Arguments

Details

The Item Category Reference Profile (ICRP) visualizes how the response probability for each category changes across latent ranks. Unlike ICBR which shows cumulative probabilities, ICRP shows the raw probability of selecting each specific category.

For an item with K categories (0, 1, ..., K-1), the ICRP shows:

• Line for Cat0: P(response = 0 | rank)

• Line for Cat1: P(response = 1 | rank)

• ...

• Line for CatK: P(response = K | rank)

The sum of all probabilities at each rank equals 1.0, as they represent mutually exclusive response options.

Typically, higher ranks (higher ability) show higher probabilities for higher categories and lower probabilities for lower categories.

Value

A single ggplot object with faceted subplots for each item.

See Also

plotICBR_gg, plotScoreFreq_gg, plotLRD_gg

Examples

library(exametrika)

result <- LRA(J15S3810, nrank = 4, dataType = "ordinal")

# Plot first 4 items
plot <- plotICRP_gg(result, items = 1:4)
plot

# Custom colors and title
plot <- plotICRP_gg(result,
  items = 1:6,
  title = "Item Category Reference Profile",
  colors = c("red", "blue", "green", "purple")
)
plot

Plot Item Information Curves (IIC) from exametrika

Description

This function takes exametrika IRT or GRM output as input and generates Item Information Curves (IIC) using ggplot2. IIC shows how much information each item provides at different ability levels.

Usage

plotIIC_gg(
  data,
  items = NULL,
  xvariable = c(-4, 4),
  title = TRUE,
  colors = NULL,
  linetype = "solid",
  show_legend = FALSE,
  legend_position = "right"
)

Arguments

Details

The Item Information Function indicates how precisely an item measures ability at each point on the theta scale. Items with higher discrimination parameters provide more information. The peak of the information curve occurs near the item's difficulty parameter.

For IRT models (2PL, 3PL, 4PL), the function uses the standard IRT information function. For GRM, the information is computed as:

I(\theta) = a^2 \sum_{k=1}^{K-1} P_k^*(\theta) [1 - P_k^*(\theta)]

Value

A list of ggplot objects, one for each item. Each plot shows the Item Information Curve for that item.

See Also

plotICC_gg, plotTIC_gg, plotICRF_gg

Examples

library(exametrika)

# IRT example
result_irt <- IRT(J15S500, model = 3)
plots_irt <- plotIIC_gg(result_irt)
plots_irt[[1]] # Show IIC for the first item

# GRM example
result_grm <- GRM(J5S1000)
plots_grm <- plotIIC_gg(result_grm)
plots_grm[[1]] # Show IIC for the first item

Plot All Item Information Curves Overlaid from exametrika

Description

This function takes exametrika IRT or GRM output as input and generates an overlay plot of all Item Information Curves (IIC) using ggplot2. All item curves are displayed on a single graph for easy comparison.

Usage

plotIIC_overlay_gg(
  data,
  items = NULL,
  xvariable = c(-4, 4),
  title = TRUE,
  colors = NULL,
  linetype = "solid",
  show_legend = TRUE,
  legend_position = "right"
)

Arguments

Details

This function is similar to calling plot(IRT_result, type = "IIF", overlay = TRUE) or plot(GRM_result, type = "IIF", overlay = TRUE) in the exametrika package, but returns a ggplot2 object that can be further customized.

The Item Information Function indicates how precisely an item measures ability at each point on the theta scale. Items with higher discrimination parameters provide more information. The peak of the information curve occurs near the item's difficulty parameter.

Value

A single ggplot object showing all Item Information Curves overlaid on one graph.

See Also

plotIIC_gg, plotICC_gg

Examples

library(exametrika)

# IRT example
result_irt <- IRT(J15S500, model = 3)
plotIIC_overlay_gg(result_irt) # All items
plotIIC_overlay_gg(result_irt, items = 1:5) # First 5 items only

# GRM example
result_grm <- GRM(J5S1000)
plotIIC_overlay_gg(result_grm, show_legend = TRUE)

Plot Item Reference Profile (IRP) from exametrika

Description

This function takes exametrika output as input and generates Item Reference Profile (IRP) plots using ggplot2. IRP shows the probability of a correct response for each item at each latent class or rank level.

Usage

plotIRP_gg(
  data,
  title = TRUE,
  colors = NULL,
  linetype = "dashed",
  show_legend = FALSE,
  legend_position = "right"
)

Arguments

Details

The Item Reference Profile visualizes how item difficulty varies across latent classes (LCA) or ranks (LRA, LDLRA). Items with monotonically increasing profiles indicate good discrimination between classes/ranks.

Value

A list of ggplot objects, one for each item. Each plot shows the correct response rate across latent classes or ranks.

See Also

plotFRP_gg, plotTRP_gg

Examples

library(exametrika)
result <- LRA(J15S500, nrank = 5)
plots <- plotIRP_gg(result)
plots[[1]] # Show IRP for the first item

Plot Latent Class Distribution (LCD) from exametrika

Description

This function takes exametrika output as input and generates a Latent Class Distribution (LCD) plot using ggplot2. LCD shows the number of students in each latent class and the class membership distribution.

Usage

plotLCD_gg(
  data,
  Num_Students = TRUE,
  title = TRUE,
  colors = NULL,
  linetype = "dashed",
  show_legend = FALSE,
  legend_position = "right"
)

Arguments

Details

The Latent Class Distribution shows how students are distributed across latent classes. The bar graph shows the number of students assigned to each class, and the line graph shows the cumulative class membership distribution.

Value

A single ggplot object with dual y-axes showing both the student count and membership frequency.

See Also

plotLRD_gg, plotTRP_gg

Examples

library(exametrika)
result <- LCA(J15S500, ncls = 5)
plot <- plotLCD_gg(result)
plot

Plot LDPSR (Local Dependence Passing Student Rate) from exametrika

Description

This function takes exametrika BINET output as input and generates LDPSR (Local Dependence Passing Student Rate) plots using ggplot2. LDPSR visualizes the correct response rate for items within a field, comparing the parent class and child class at each DAG edge.

Each plot corresponds to one edge in the BINET DAG structure, showing how item-level performance differs between the parent class (lower ability) and the child class (higher ability) connected through a specific field.

Usage

plotLDPSR_gg(
  data,
  title = TRUE,
  colors = NULL,
  linetype = "solid",
  show_legend = TRUE,
  legend_position = "right"
)

Arguments

Details

In BINET (Bicluster Network Model), latent classes are connected by a directed acyclic graph (DAG), where edges pass through specific fields. LDPSR shows the item-level passing rate for each such edge: the parent class line represents the correct response rate of students in the originating class, and the child class line shows the rate for students in the destination class.

The gap between the two lines indicates how much students improve on each item when transitioning from the parent class to the child class via the specified field.

Value

A list of ggplot objects, one for each DAG edge. Each plot shows the correct response rate profiles for the parent class and child class on items belonging to the connecting field.

See Also

plotFRP_gg, plotArray_gg, plotGraph_gg, combinePlots_gg

Examples

library(exametrika)
# BINET requires field configuration and edge structure
conf <- c(
  1, 5, 5, 5, 9, 9, 6, 6, 6, 6, 2, 7, 7, 11, 11, 7, 7,
  12, 12, 12, 2, 2, 3, 3, 4, 4, 4, 8, 8, 12, 1, 1, 6, 10, 10
)
edges_data <- data.frame(
  "From Class (Parent) >>>" = c(1, 2, 3, 4, 5, 7, 2, 4, 6, 8, 10, 6, 6, 11, 8, 9, 12),
  ">>> To Class (Child)" = c(2, 4, 5, 5, 6, 11, 3, 7, 9, 12, 12, 10, 8, 12, 12, 11, 13),
  "At Field (Locus)" = c(1, 2, 2, 3, 4, 4, 5, 5, 5, 5, 5, 7, 8, 8, 9, 9, 12)
)
tmp_file <- tempfile(fileext = ".csv")
write.csv(edges_data, file = tmp_file, row.names = FALSE)
result <- BINET(J35S515, ncls = 13, nfld = 12, conf = conf, adj_file = tmp_file)
unlink(tmp_file)
plots <- plotLDPSR_gg(result)
plots[[1]] # Show LDPSR for the first edge

Plot Latent Rank Distribution (LRD) from exametrika

Description

This function takes exametrika output as input and generates a Latent Rank Distribution (LRD) plot using ggplot2. LRD shows the number of students in each latent rank and the rank membership distribution.

Usage

plotLRD_gg(
  data,
  Num_Students = TRUE,
  title = TRUE,
  colors = NULL,
  linetype = "dashed",
  show_legend = FALSE,
  legend_position = "right"
)

Arguments

Details

The Latent Rank Distribution shows how students are distributed across latent ranks. Unlike latent classes, ranks have an ordinal interpretation where higher ranks indicate higher ability levels.

Value

A single ggplot object with dual y-axes showing both the student count and membership frequency.

See Also

plotLCD_gg, plotTRP_gg

Examples

library(exametrika)
result <- LRA(J15S500, nrank = 5)
plot <- plotLRD_gg(result)
plot

Plot Rank Membership Profile (RMP) from exametrika

Description

This function takes exametrika output as input and generates Rank Membership Profile (RMP) plots using ggplot2. RMP shows each student's membership probability across all latent ranks.

Usage

plotRMP_gg(
  data,
  title = TRUE,
  colors = NULL,
  linetype = "dashed",
  show_legend = FALSE,
  legend_position = "right"
)

Arguments

Details

The Rank Membership Profile visualizes how strongly each student belongs to each latent rank. Unlike class membership, rank membership has an ordinal interpretation. Students with unimodal profiles centered on a single rank are well-classified.

Value

A list of ggplot objects, one for each student. Each plot shows the membership probability across all latent ranks.

See Also

plotCMP_gg, plotLRD_gg

Examples

library(exametrika)

result <- LRA(J15S500, nrank = 5)
plots <- plotRMP_gg(result)
plots[[1]] # Show RMP for the first student

Plot Rank Reference Vector (RRV) from exametrika

Description

This function takes exametrika Biclustering output as input and generates a Rank Reference Vector (RRV) plot using ggplot2. RRV shows how each latent rank performs across fields, with one line per rank.

Supports both binary (2-valued) and polytomous (multi-valued) biclustering models. For polytomous data, the stat parameter controls how expected scores are calculated from category probabilities.

Usage

plotRRV_gg(
  data,
  title = TRUE,
  colors = NULL,
  linetype = "solid",
  show_legend = TRUE,
  legend_position = "right",
  stat = "mean",
  show_labels = NULL
)

Arguments

Details

The Rank Reference Vector is the transpose of the Field Reference Profile (FRP). While FRP shows one plot per field, RRV displays all ranks in a single plot with fields on the x-axis. Each line represents a latent rank, showing its performance pattern across fields.

Binary Data (2 categories):

• Y-axis shows "Correct Response Rate" (0.0 to 1.0)

• Values represent the probability of correct response

Polytomous Data (3+ categories):

• Y-axis shows "Expected Score" (1 to max category)

• Values are calculated using the stat parameter

• Higher scores indicate better performance

RRV is used when latent ranks are ordinal (ordered). For unordered latent classes, use plotCRV_gg instead.

Value

A single ggplot object showing the Rank Reference Vector.

See Also

plotCRV_gg, plotFRP_gg, plotScoreField_gg

Examples

# Binary biclustering
library(exametrika)
result <- Biclustering(J15S500, nfld = 3, ncls = 5)
plotRRV_gg(result)


# Ordinal biclustering (polytomous)
data(J35S500)
result_ord <- Biclustering(J35S500, ncls = 5, nfld = 5, method = "R")
plotRRV_gg(result_ord) # Default: mean
plotRRV_gg(result_ord, stat = "median")
plotRRV_gg(result_ord, stat = "mode")

# Custom styling
plotRRV_gg(result_ord,
  title = "Rank Performance Across Fields",
  colors = c("#1b9e77", "#d95f02", "#7570b3", "#e7298a", "#66a61e"),
  legend_position = "bottom"
)

Plot Score-Field Heatmap (ScoreField) for Polytomous Biclustering

Description

Creates a heatmap visualization showing the expected scores for each field across latent classes or ranks in polytomous biclustering models (nominalBiclustering, ordinalBiclustering).

The expected score for each field-class/rank combination is calculated as the sum of (category x probability) across all categories.

Usage

plotScoreField_gg(
  data,
  title = TRUE,
  colors = NULL,
  show_legend = TRUE,
  legend_position = "right",
  show_values = TRUE,
  text_size = 3.5
)

Arguments

Details

This function is designed for polytomous (multi-valued) biclustering models where items have more than two response categories. It displays the expected score (weighted sum of category probabilities) for each field across all latent classes or ranks.

The heatmap uses:

• Y-axis: Fields (F1, F2, ...)

• X-axis: Latent Classes (C1, C2, ...) or Ranks (R1, R2, ...)

• Color: Expected score magnitude (lighter = lower, darker/redder = higher)

• Text: Actual expected score values (optional, controlled by show_values)

Higher expected scores indicate that students in that class/rank are expected to achieve higher scores in that field.

Value

A ggplot2 object representing the Score-Field heatmap.

See Also

plotFCRP_gg for field category response profiles, plotFCBR_gg for field cumulative boundary reference, plotArray_gg for array plots, plotScoreRank_gg for score-rank heatmaps

Examples

library(exametrika)
# Ordinal Biclustering example
result <- Biclustering(J35S500, ncls = 5, nfld = 5, method = "R")

# Basic plot
plotScoreField_gg(result)

# Custom title and hide values
plotScoreField_gg(result,
  title = "Expected Scores by Field and Rank",
  show_values = FALSE
)

# Custom color gradient
plotScoreField_gg(result,
  colors = c("white", "blue", "darkblue"),
  legend_position = "bottom"
)

# Nominal Biclustering example
data(J20S600)
result_nom <- Biclustering(J20S600, ncls = 5, nfld = 4)
plotScoreField_gg(result_nom)

Plot Score Frequency Distribution from exametrika

Description

This function takes exametrika LRAordinal or LRArated output as input and generates a Score Frequency Distribution plot using ggplot2. The plot shows the density distribution of scores with vertical dashed lines indicating the thresholds between adjacent latent ranks.

Usage

plotScoreFreq_gg(
  data,
  title = TRUE,
  colors = NULL,
  linetype = c("solid", "dashed"),
  show_legend = FALSE,
  legend_position = "right"
)

Arguments

Details

The Score Frequency Distribution visualizes how student scores are distributed and where the boundaries between latent ranks fall. The threshold between rank i and rank i+1 is calculated as the midpoint between the maximum score in rank i and the minimum score in rank i+1.

This plot is useful for understanding how latent ranks correspond to observed score ranges.

Value

A single ggplot object showing the score frequency distribution with rank threshold lines.

See Also

plotLRD_gg, plotRMP_gg

Examples

library(exametrika)
result <- LRA(J15S3810, nrank = 4, dataType = "ordinal")
plot <- plotScoreFreq_gg(result)
plot

Plot Score-Rank Heatmap from exametrika

Description

This function takes exametrika LRAordinal or LRArated output as input and generates a Score-Rank heatmap using ggplot2. The heatmap shows the distribution of students across scores (y-axis) and latent ranks (x-axis), with darker cells indicating higher frequency.

Usage

plotScoreRank_gg(
  data,
  title = TRUE,
  colors = NULL,
  show_legend = TRUE,
  legend_position = "right"
)

Arguments

Details

The Score-Rank heatmap visualizes the joint distribution of observed scores and estimated latent ranks. Each cell represents the number of students with a given score assigned to a given rank. Darker cells indicate higher frequency.

The data is taken from data$ScoreRank, a matrix where rows represent scores and columns represent latent ranks.

Value

A single ggplot object showing the Score-Rank heatmap.

See Also

plotScoreFreq_gg, plotLRD_gg

Examples

library(exametrika)
result <- LRA(J15S3810, nrank = 4, dataType = "ordinal")
plot <- plotScoreRank_gg(result)
plot

Plot Test Information Curve (TIC) from exametrika

Description

This function takes exametrika IRT or GRM output as input and generates a Test Information Curve (TIC) using ggplot2. TIC shows the total information provided by all items at each ability level.

Usage

plotTIC_gg(
  data,
  xvariable = c(-4, 4),
  title = TRUE,
  colors = NULL,
  linetype = "solid",
  show_legend = FALSE,
  legend_position = "right"
)

Arguments

Details

The Test Information Function is the sum of all Item Information Functions. It indicates how precisely the test as a whole measures ability at each point on the theta scale. The reciprocal of test information is approximately equal to the squared standard error of measurement.

The function supports IRT models (2PL, 3PL, 4PL) and GRM.

Value

A single ggplot object showing the Test Information Curve.

See Also

plotICC_gg, plotIIC_gg, plotICRF_gg

Examples

library(exametrika)

# IRT example
result_irt <- IRT(J15S500, model = 3)
plot_irt <- plotTIC_gg(result_irt)
plot_irt # Show Test Information Curve

# GRM example
result_grm <- GRM(J5S1000)
plot_grm <- plotTIC_gg(result_grm)
plot_grm # Show Test Information Curve

Plot Test Response Function (TRF) from exametrika

Description

This function takes exametrika IRT output as input and generates a Test Response Function (TRF) using ggplot2. TRF shows the expected total score as a function of ability (theta).

Usage

plotTRF_gg(
  data,
  xvariable = c(-4, 4),
  title = TRUE,
  colors = NULL,
  linetype = "solid",
  show_legend = FALSE,
  legend_position = "right"
)

Arguments

Details

The Test Response Function is the sum of all Item Characteristic Curves (ICCs). At each ability level, TRF represents the expected number of correct responses across all items. For a test with J items:

TRF(\theta) = \sum_{j=1}^{J} P_j(\theta)

The y-axis ranges from 0 to the total number of items. The function supports 2PL, 3PL, and 4PL IRT models.

Value

A single ggplot object showing the Test Response Function.

See Also

plotICC_gg, plotTIC_gg

Examples

library(exametrika)
result <- IRT(J15S500, model = 3)
plot <- plotTRF_gg(result)
plot # Show Test Response Function

Plot Test Reference Profile (TRP) from exametrika

Description

This function takes exametrika output as input and generates a Test Reference Profile (TRP) plot using ggplot2. TRP shows the number of students in each latent class/rank (bar graph) and the expected test score for each class/rank (line graph).

Usage

plotTRP_gg(
  data,
  Num_Students = TRUE,
  title = TRUE,
  colors = NULL,
  linetype = "dashed",
  show_legend = FALSE,
  legend_position = "right"
)

Arguments

Details

The Test Reference Profile provides an overview of the latent structure. The bar graph shows how students are distributed across classes/ranks, while the line graph shows the expected test score for each class/rank. In well-fitted models, expected scores should increase monotonically with class/rank number.

Value

A single ggplot object with dual y-axes showing both the student distribution and expected scores.

See Also

plotIRP_gg, plotLCD_gg, plotLRD_gg

Examples

library(exametrika)
result <- LRA(J15S500, nrank = 5)
plot <- plotTRP_gg(result)
plot