writeAlizer: Getting Started

Optional model dependencies

Some scoring models need additional R packages. Run the following to see which optional packages are missing:

md <- model_deps()
md$missing

If packages are missing, model_deps() prints a command you can copy into R to install them. It does not install anything itself. md$required lists all optional packages from writeAlizer’s Suggests field, including documentation and testing tools; it does not mean those packages are already installed. Availability is checked, but version requirements are not.

Development version

For most users, the CRAN installation above is the best starting point. To install the development version from GitHub instead:

# install.packages("pak")  # If needed
pak::pak("shmercer/writeAlizer")

Try the workflow without downloads

If you want to check that the package is working without downloading models, run this small demonstration. It creates a temporary example model and restores your settings afterwards. Every score is 1.5: these are demonstration values, not assessments of writing quality.

local({
  old <- options(writeAlizer.mock_dir = NULL, writeAlizer.offline = TRUE)
  on.exit(options(old))
  example_parent <- tempfile("wa-example-")
  wa_seed_example_models(dir = example_parent)
  on.exit(unlink(example_parent, recursive = TRUE), add = TRUE)
  demo <- predict_quality("example", rb)
  head(demo)
})
#>   ID pred_example
#> 1  7          1.5
#> 2  8          1.5
#> 3  9          1.5

How text IDs are handled

Each imported table has an ID column. IDs are stored as text, preserving leading zeros such as 001, and rows are sorted by ID. Missing, blank, and duplicate IDs cause an error so that scores can be matched unambiguously to texts.

• ReaderBench: File.name is renamed to ID; the value itself is kept. An export that already has only an ID column is also accepted.
• Coh-Metrix and GAMET: directory paths and a trailing .txt extension are removed. For example, C:/Essays/001.txt becomes 001.
• Combining ReaderBench and GAMET: import_merge_gamet_rb(rb_path, gamet_path) keeps only IDs present in both files. Check that the IDs match before merging; unmatched texts are left out. Shared feature names receive .x (GAMET) and .y (ReaderBench) suffixes.

ReaderBench imports retain the features used by the supported models, using the packaged sample header as a reference. GAMET imports also calculate grammar and spelling error proportions. Those proportions are missing (NA) when the word count is zero.

ReaderBench and Coh-Metrix results

The recommended all-genre models each return three genre predictions (narrative, expository, and persuasive) and their mean. For ReaderBench, the overall score is pred_rb_mod3all_mean; for Coh-Metrix, it is pred_coh_mod3all_mean.

Single-genre models return just their prediction and ID, without a mean column. Models 1 and 2 return six and three component predictions, respectively, plus their mean. When some component scores are missing, the mean uses the available scores; if all are missing, the mean is NaN.

GAMET results

There is no overall mean for GAMET: these columns measure different aspects of writing. CWS and CIWS are model predictions and may be fractional; the package does not round or clip them.

Comparing scores across groups of texts

For ReaderBench and Coh-Metrix Models 2 and 3, writeAlizer standardizes predictors using the group of texts supplied to each call. In practical terms, the same text can receive a different score if you change the other texts in its scoring group. Use a consistent group when making comparisons. A single text, a feature with no variation, or missing measurements can lead to missing predictions or a model error.

This describes the existing scoring method. Scores are not percentages or universal proficiency cutoffs. See the model-development guide for the training samples and research context.

Save your results

write.csv(rb_quality, "writing_scores.csv", row.names = FALSE)
getwd()  # Show the folder where the file was saved

You can open the CSV in a spreadsheet program. If IDs include leading zeros, import the ID column as text in that program too.

ReaderBench

ReaderBench Model 3 keys also accept an explicit _v2 suffix; the output column names remain the same. Model 2 simplifies Model 1 and handles multi-paragraph compositions. Published applications include (Keller-Margulis et al., 2021; Matta et al., 2022; Mercer & Cannon, 2022) for Model 1 and (Matta et al., 2023) for Model 2.

Coh-Metrix

Model 2 is a simplified version of Model 1. Published Model 1 applications include (Keller-Margulis et al., 2021; Matta et al., 2022).

GAMET and the offline demonstration

gamet_cws1 returns the four GAMET columns described above. Published applications include (Matta et al., 2025; Mercer et al., 2021). The example model returns only pred_example, after it has been created with wa_seed_example_models().

File format and Windows encodings

To avoid encoding issues in R and other programs, always save text files as UTF-8. Text files created on Windows systems may sometimes use legacy encodings such as Windows-1252 (also known as CP1252) rather than UTF-8.

These encodings include typographic punctuation and symbols that are not part of standard ASCII and can cause problems when read on macOS or Linux systems, or by R functions that assume UTF-8 input.

Typical problematic characters include:

Programs expecting UTF-8 may display these characters incorrectly (as “garbled” symbols) or fail to read the file entirely.

# install.packages("readr")  # If needed
library(readr)

# Detect the likely encoding of a text file
guess_encoding("example.txt")

  encoding     confidence
1 UTF-8              0.95
2 windows-1252       0.05

txt <- readLines("example.txt")
txt_utf8 <- iconv(txt, from = "Windows-1252", to = "UTF-8")
stopifnot(!anyNA(txt_utf8))  # Stop if any text could not be converted
writeLines(txt_utf8, "example_utf8.txt", useBytes = TRUE)

Setting the Java Path in Windows

1. Open File Explorer and navigate to (or the directory Java is installed in):

C:\Program Files\Java\

2. Inside, locate your Java folder — for example:

C:\Program Files\Java\jre1.8.0_451

Copy this full path. You’ll need it in the next step.

3. Set JAVA_HOME (via Windows Settings)

• Press Windows + R, type sysdm.cpl, and press Enter.
  
• Go to the Advanced tab → click Environment Variables.
  
• Under System variables, click New…
  • Variable name: JAVA_HOME
  • Variable value: paste your Java path (e.g., C:\Program Files\Java\jre1.8.0_451)
• Click OK to save.

4. Add Java to your system Path

• In the same Environment Variables window, find and select the variable named Path, then click Edit.
  
• Click New, and add the following entry: %JAVA_HOME%\bin

5. In Command Prompt, check the Java version with this command:

java -version

Also check your environment variable. It should print your Java installation directory.

echo %JAVA_HOME%