wordorientation

Detect attraction and repulsion between words in text.

What it does

For every pair of words that co-occur often enough to analyze, wordorientation computes the phi coefficient (a correlation measure for binary co-occurrence data), tests it for significance, and classifies the pair as:

• attraction — the words co-occur significantly more than chance would predict
• repulsion — the words co-occur significantly less than chance would predict
• neutral — no significant relationship at the chosen threshold

Installation

# once on CRAN
install.packages("wordorientation")

# development version
# devtools::install_github("yourusername/wordorientation")

Usage

library(wordorientation)

result <- analyze_word_orientation(
  example_social_posts(),
  text_col = "text", doc_col = "id",
  min_count = 2
)

head(result$scored)
plot_orientation_network(result$scored)

Or step by step:

tokens <- tokenize_posts(my_data, text_col = "text")
cooc   <- cooccurrence_counts(tokens, min_count = 5)
scored <- word_orientation(cooc, alpha = 0.05)

How it differs from related packages

• widyr::pairwise_cor() computes the same underlying phi-style correlation but is a general tidy-correlation tool, not text-specific: it has no built-in tokenization, no significance-based classification, and no network plotting.
• collostructions measures the attraction/repulsion of words to grammatical constructions, not to each other.
• MadanTextNetwork provides a co-occurrence network Shiny app but is built specifically for Persian text and does not classify pairs by statistical significance.

wordorientation combines tokenization, co-occurrence counting, significance-tested classification, and network visualization into a single general-language pipeline.

Multiple comparisons

By default, word_orientation() applies a Benjamini-Hochberg correction across all tested word pairs (p_adjust_method = "BH"). On small corpora with few documents, this can mean no pair survives correction even when raw phi values look large — this is intentional, not a bug: it guards against over-interpreting spurious associations from sparse data.