Package 'facetsviz'

Parse and visualize FACETS output files

Description

The facetsviz package parses FACETS .out files and renders common multi-facet Rasch measurement plots, including Wright maps, severity distributions, criterion diagnostics, rating-scale diagnostics, and unexpected response summaries.

Core functions

• read_facets()

• render_facets_plots()

• render_facets_batch()

• run_app()

---

Facets plotting theme

Description

Facets plotting theme

Usage

facets_theme(base_size = 11, base_family = "Helvetica")

Arguments

base_size	Base text size.
base_family	Base font family.

Value

A ggplot2 theme object.

---

Plot the distribution of measures for a facet

Description

Plot the distribution of measures for a facet

Usage

plot_distribution(x, facet_index = 2L, binwidth = 0.75)

Arguments

x	A 'facets_out' object or path to a FACETS '.out' file.
facet_index	Which measurement report to plot (default '2L').
binwidth	Histogram bin width in logits.

Value

A ggplot object.

---

Plot measure estimates with standard errors for a facet

Description

Plot measure estimates with standard errors for a facet

Usage

plot_estimates(x, facet_index = 3L)

Arguments

x	A 'facets_out' object or path to a FACETS '.out' file.
facet_index	Which measurement report to plot (default '3L').

Value

A ggplot object.

---

Plot representative observed versus fair averages for a facet

Description

Plot representative observed versus fair averages for a facet

Usage

plot_fairness(x, facet_index = 1L, n = 8L)

Arguments

x	A 'facets_out' object or path to a FACETS '.out' file.
facet_index	Which measurement report to plot (default '1L').
n	Number of representative elements to show.

Value

A ggplot object.

---

Plot the expected-score ogive implied by Table 8.1 thresholds

Description

Plot the expected-score ogive implied by Table 8.1 thresholds

Usage

plot_ogive(x, theta = NULL)

Arguments

x	A 'facets_out' object or path to a FACETS '.out' file.
theta	Optional vector of theta values.

Value

A ggplot object.

---

Plot rating-scale category probability curves

Description

Plot rating-scale category probability curves

Usage

plot_probability(x, theta = NULL)

Arguments

x	A 'facets_out' object or path to a FACETS '.out' file.
theta	Optional vector of theta values.

Value

A ggplot object.

---

Plot mode, median, and mean category regions from rating-scale thresholds

Description

Plot mode, median, and mean category regions from rating-scale thresholds

Usage

plot_structure(x, theta = NULL)

Arguments

x	A 'facets_out' object or path to a FACETS '.out' file.
theta	Optional vector of theta values.

Value

A ggplot object.

---

Plot the strongest unexpected responses from Table 4.1

Description

Plot the strongest unexpected responses from Table 4.1

Usage

plot_unexpected(x, top_n = 20L)

Arguments

x	A 'facets_out' object or path to a FACETS '.out' file.
top_n	Number of rows to show.

Value

A ggplot object.

---

Plot rating-scale category usage frequencies

Description

Plot rating-scale category usage frequencies

Usage

plot_usage(x)

Arguments

x	A 'facets_out' object or path to a FACETS '.out' file.

Value

A ggplot object.

---

Plot a compact Wright map across available facets

Description

Plot a compact Wright map across available facets

Usage

plot_wright(x)

Arguments

x	A 'facets_out' object or path to a FACETS '.out' file.

Value

A ggplot object.

---

Read a FACETS output file

Description

Reads a FACETS '.out' file and parses the main FACETS tables used by the package.

Usage

read_facets(path, encoding = "UTF-8")

Arguments

path	Path to a FACETS '.out' file.
encoding	Text encoding used when reading the file.

Value

An object of class 'facets_out'.

---

Render FACETS plots for multiple output files

Description

Render FACETS plots for multiple output files

Usage

render_batch(
  paths = ".",
  output_root,
  recursive = TRUE,
  include = c("wright_map", "observed_vs_fair", "measure_distribution", "estimates",
    "category_usage", "probability_curves", "expected_score_ogive", "scale_structure",
    "unexpected_responses"),
  formats = c("png", "tiff"),
  dpi = 600,
  top_n_unexpected = 20L
)

Arguments

paths	One or more FACETS '.out' or '.txt' files or directories containing them.
output_root	Root directory for rendered plot folders.
recursive	Whether to search directories recursively.
include	Plot names passed to [render_plots()].
formats	File formats passed to [render_plots()].
dpi	Image resolution.
top_n_unexpected	Number of unexpected responses to show.

Value

A tibble describing rendered outputs.

---

Render a standard set of FACETS visualizations to disk

Description

Render a standard set of FACETS visualizations to disk

Usage

render_plots(
  x,
  output_dir,
  include = c("wright_map", "observed_vs_fair", "measure_distribution", "estimates",
    "category_usage", "probability_curves", "expected_score_ogive", "scale_structure",
    "unexpected_responses"),
  formats = c("png", "tiff"),
  dpi = 600,
  top_n_unexpected = 20L
)

Arguments

x	A 'facets_out' object or path to a FACETS '.out' file.
output_dir	Output directory for image files.
include	Character vector of plot names to render.
formats	File formats to write, such as '"png"' or '"tiff"'.
dpi	Image resolution.
top_n_unexpected	Number of unexpected responses to show when rendering that plot.

Value

Invisibly, a named list of generated file paths.

---

Launch the facetsviz Shiny app

Description

Launch the facetsviz Shiny app

Usage

run_app(launch = TRUE, host = "127.0.0.1", port = NULL)

Arguments

launch	If 'TRUE', run the app immediately. If 'FALSE', return the app object.
host	Host passed to [shiny::runApp()] when launching.
port	Port passed to [shiny::runApp()] when launching.

Value

A shiny app object when 'launch = FALSE', otherwise the result of [shiny::runApp()].

---