Representative Text Units for Every Topic

Selects, for each fitted topic, the text units (documents, sentences, or clause segments) that best evidence it. The default ranking is by distinctiveness margin — the unit's cosine distance to its second-best centroid minus the distance to its own — rather than by raw closeness. Raw closeness systematically favors long units, because topic centroids are averages of whole-document embeddings and long units resemble whole documents; the margin instead rewards units that are unambiguously about one topic and no other, which are naturally short and pointed. Ties break toward the shorter unit, then alphabetically, so the selection is fully deterministic.

Usage

representatives(
  object,
  text = NULL,
  model = NULL,
  embeddings = NULL,
  n = 3L,
  rank = c("margin", "distance"),
  batch_size = 32L
)

Arguments

object

A fitted topics() model.

text

Character vector of candidate units, for example the text column of segment(). NULL (the default) ranks the units the model was fitted on — its documents, or its segments for a model fitted with segment = — from their stored embeddings, with no encoding.

model

A loaded sbert_model, a pinned model name, or NULL for the default model; ignored when embeddings are supplied.

embeddings

Optional numeric matrix with one row per unit.

n

Number of units returned per topic.

rank

"margin" (default) or "distance" (raw closeness to the topic centroid).

batch_size

Batch size passed to encode() when model is used.

Value

A base data frame with columns topic, rank, text, distance (to the unit's own centroid), and margin, ordered by topic and rank. When the fitted units are ranked (text = NULL), document_id — and segment, for a segmented model — sit between rank and text so every example can be traced to its source. Topics to which no unit is assigned contribute no rows.

Examples

text <- c(
  "Cats chase mice", "Dogs chase balls",
  "Stocks and bonds trade", "Markets price shares"
)
embeddings <- rbind(c(1, 0), c(0.9, 0.1), c(0, 1), c(0.1, 0.9))
fitted <- topics(text, 2, embeddings = embeddings)
representatives(
  fitted,
  c("kittens pounce", "bond yields", "pets and prices"),
  embeddings = rbind(c(1, 0.1), c(0.1, 1), c(0.7, 0.7)),
  n = 1
)
#>   topic rank           text     distance    margin
#> 1     1    1 kittens pounce 0.0009828586 0.8446397
#> 2     2    1    bond yields 0.0009828586 0.8446397