| Type: | Package |
| Title: | Parse and Visualize Facets Output Files |
| Version: | 0.1.1 |
| Description: | Utilities to parse output files from 'Facets' (a software widely used for multi-facet Rasch measurement) and build accurate visualizations from the measurement reports. For more details on the underlying measurement framework, see Linacre (1994, ISBN:0-941938-02-6) and Linacre (2023) https://www.winsteps.com/a/Facets-Manual.pdf. |
| URL: | https://github.com/myprabowo/facetsviz |
| BugReports: | https://github.com/myprabowo/facetsviz/issues |
| License: | MIT + file LICENSE |
| Encoding: | UTF-8 |
| Depends: | R (≥ 4.1.0) |
| Imports: | ggrepel, ggplot2, rlang, scales, stats, tibble, tidyr, tools, utils |
| Suggests: | bslib, DT, knitr, rmarkdown, shiny, testthat |
| VignetteBuilder: | knitr |
| Config/testthat/edition: | 3 |
| RoxygenNote: | 7.3.3 |
| NeedsCompilation: | no |
| Packaged: | 2026-07-11 08:29:43 UTC; muhammadyogaprabowo |
| Author: | Muhammad Yoga Prabowo [aut, cre] |
| Maintainer: | Muhammad Yoga Prabowo <muhammadyogaprabowo@gmail.com> |
| Repository: | CRAN |
| Date/Publication: | 2026-07-21 09:20:02 UTC |
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()].