set_factor_labels: Attach persistent factor labels to an ackwards object

In ackwards: Bass-Ackwards Hierarchical Structural Analysis

Attach persistent factor labels to an ackwards object

Description

Store substantive names for factors (e.g. "Neuroticism" for "m5f1") on the object itself, so that print(), summary(), tidy(), autoplot(), and top_items() display them without re-supplying the labels each time. This is the factor-label counterpart to item / variable labels (see top_items() and ?ackwards); the two are distinct and never interchanged.

Usage

set_factor_labels(x, labels)

Arguments

x	An ackwards object.
labels	A named character vector mapping factor IDs ("m{k}f{j}") to label strings, or NULL to clear all stored labels. Every name must match a factor ID in x (an unknown ID is an error, not a warning – the object's IDs are knowable up front; see factor_labels() to read the current set).

Details

Labels are display only – they never change a factor's stable ID (⁠m{k}f{j}⁠), and every lineage / edge / score column continues to key on the ID. A factor with no label falls back to its ID everywhere. The stored labels ride along through prune(), boot_edges(), augment(), and predict() unchanged.

Value

The ackwards object, with meta$factor_labels updated. Pipeable.

Updating and clearing

set_factor_labels() merges into any labels already stored, so you can build them up incrementally. Within a single call:

• a normal string sets (or overwrites) that factor's label;

• an NA or "" value removes just that factor's label;

• passing labels = NULL clears all labels at once.

The scaffold printed by label_template() is a convenient starting point: copy its c(...) literal, fill in the substantive names, and pass it here.

See Also

factor_labels() to read them back, label_template() for a ready-to-edit scaffold, autoplot.ackwards() (node_labels overrides a stored label per node).

Examples

x <- ackwards(sim16, k_max = 4, engine = "pca")

# Start from a scaffold, fill in names, attach them:
x <- set_factor_labels(x, c(m4f1 = "Alpha", m4f2 = "Beta"))
factor_labels(x)

# Merge in more; remove one; everything downstream now shows the labels:
x <- set_factor_labels(x, c(m2f1 = "Broad", m4f2 = NA))
summary(x)

ackwards documentation built on July 25, 2026, 1:08 a.m.