# topics

## Overview

An R-package for analyzing natural language implementing Differential
Language Analysis using words, phrases and topics.  
  
Check out our tutorial paper: [Multiple Methods for Visualizing Human
Language: A Tutorial for Social and Behavioural
Scientists](https://osf.io/preprints/psyarxiv/nxfvr_v1/). If you use the
topics package, please cite this tutorial in your work.  
  
The `topics` package is part of the *R Language Analysis Suite*,
including `talk`, `text` and `topics`.

- [`talk`](https://www.r-talk.org/) transforms voice recordings into
  text, audio features, or embeddings.  
    
- [`text`](https://www.r-text.org/) provides many language tasks such as
  converting digital text into word embeddings.  
    
  `talk` and `text` offer access to Large Language Models from Hugging
  Face.  
    
- [`topics`](https://www.r-topics.org/) visualizes language patterns
  into words, phrases or topics to generate psychological insights.  
  The `topics` package supports the `text` package in analysing and
  visualizing topics from BERTtopics.  
    

![](reference/figures/talk_text_topics.svg)

  
When using the `topics` package, please cite:

Ackermann L., Zhuojun G. & Kjell O.N.E. (2024). An R-package for
visualizing text in topics. <https://github.com/theharmonylab/topics>.
`DOI:zenodo.org/records/11165378`.

> ### 📣 Online Workshop: *Analysing Human Language using R*
>
> **August 11–13, 2026** — three half-day sessions (2:00–5:00 pm CEST /
> 8:00–11:00 am ET)
>
> Learn the full *R Language Analysis Suite* —
> [`talk`](https://www.r-talk.org/), [`text`](https://www.r-text.org/),
> and [`topics`](https://www.r-topics.org/) — with Oscar Kjell.
>
> **[Read more & register →](https://smart-workshops.com/lang-r-info)**

## Differential Language Analysis with Topics and N-grams

The `topics` pipeline is designed for a seamless transition from raw
text to statistically grounded visualizations. It is composed of the
following steps:

**1. Data Preprocessing** Transform raw text into a Document-Term Matrix
(DTM) or extract n-grams. This step handles cleaning, including the
removal of stopwords and punctuation, to prepare data for modeling or
frequency analysis.

**2. Model Training** For topic modeling, an LDA (Latent Dirichlet
Allocation) model is trained on the DTM. Users can specify the number of
topics and iterations to optimize the thematic representation of the
corpus.

**3. Model Inference** The model inference step uses the trained LDA
model to infer the topic-term distribution across documents, converting
qualitative text into quantitative topic loadings.

**4. Statistical Analysis** Perform Differential Language Analysis (DLA)
using [`topicsTest()`](https://r-topics.org/reference/topicsTest.md).
The analysis now supports: \* **Automatic Detection:** Intelligent
per-variable method detection (e.g., automatically applying logistic
regression for binary factors and linear regression for continuous
data). \* **Multi-Element Analysis:** Statistically test both LDA topics
and n-grams. \* **Rigorous Controls:** Support for control variables and
various p-value adjustment methods for multiple comparisons (e.g., FDR,
Bonferroni, Holm).

**5. Visualization** Generate publication-ready visualizations of your
results: \* **Wordclouds:** Create clouds of significant topics where
word size reflects the contribution to the theme. \* **N-gram Plots:**
Directly visualize the relationship between specific phrases and your
variables of interest.

![One-dimensional plots based on words and phrases (top) and LDA topics
(bottom).](reference/figures/one_dim.png)  
  
  

![A two-dimensional plot showing topics related to depression versus
worry responses (x-axis) and low versus high depression severity
(y-axis).](reference/figures/two_dim.png)  
  

# Package index

## Transform text to ngrams

- [`topicsGrams()`](https://r-topics.org/reference/topicsGrams.md) :
  N-grams

## Transform text to topics

- [`topicsDtm()`](https://r-topics.org/reference/topicsDtm.md) :
  Document Term Matrix
- [`topicsDtmEval()`](https://r-topics.org/reference/topicsDtmEval.md) :
  Summarize and Visualize your Document Term Matrix
- [`topicsModel()`](https://r-topics.org/reference/topicsModel.md) :
  Topic modelling

## Predict topic distribution from text

- [`topicsPredict()`](https://r-topics.org/reference/topicsPredict.md)
  [`topicsAssess()`](https://r-topics.org/reference/topicsPredict.md)
  [`topicsClassify()`](https://r-topics.org/reference/topicsPredict.md)
  [`topicsPreds()`](https://r-topics.org/reference/topicsPredict.md) :
  topicsPredict, topicsPreds, topicsAssess and topicsClassify

## Differential language analysis

- [`topicsTest()`](https://r-topics.org/reference/topicsTest.md) : Test
  topics or n-grams

## Plotting word topics

- [`topicsPlot()`](https://r-topics.org/reference/topicsPlot.md) : Plot
  word clouds
- [`topicsPlotOverview()`](https://r-topics.org/reference/topicsPlotOverview.md)
  : Combine topics and distribution legend into an overview figure
  (experimental)

## Example Data

- [`dep_wor_data`](https://r-topics.org/reference/dep_wor_data.md) :
  Example data about mental health descirptions .

## Help functions

- [`topicsScatterLegend()`](https://r-topics.org/reference/topicsScatterLegend.md)
  : Plot a distribution plot (available for the text-package)
- [`topicsGridLegend()`](https://r-topics.org/reference/topicsGridLegend.md)
  : Plot a grid (matrix) legend (available for the text-package)
- [`topicsTutorialData()`](https://r-topics.org/reference/topicsTutorialData.md)
  : Download and Prepare Tutorial Data

# Articles

### Resources

- [Resources](https://r-topics.org/articles/resources.md):

### Set-up

- [Installation](https://r-topics.org/articles/extended_installation_guide.md):