PsychiatryNLPKit

A scientific Python package for computational linguistics analysis of clinical data in psychiatry. It is developed in the CEYMH / Douglas Research Group at McGill University and provides a curated set of linguistic metrics across seven analytical categories, each grounded in peer-reviewed research on psychosis risk assessment and thought disorder characterization.

Overview

PsychiatryNLPKit is designed for researchers and clinicians who need to extract validated computational linguistics features from spoken or written clinical text. The package implements analysis functions derived from the scientific literature on language markers of psychosis, including formal thought disorder, disorganization, and cognitive impairment.

The toolkit supports English and French text and provides metrics spanning:

Each function accepts pre-computed linguistic data from the TextData container and returns a dictionary mapping section names to numeric metric values. This modular design lets you compose analyses flexibly or run them all at once via the batch API.

Design principles

• Scientific grounding -- analysis functions are based on the psychiatry research literature. This package implements speech metrics that have been shown to correlate with clinical rating scales (PANSS, TLC, TLI).
• Batch efficiency -- expensive computations (tokenization, embedding, constituency parsing) are lazy-loaded and cached on the TextData container. Running multiple analyses over the same text incurs no redundant work.
• Hardware acceleration -- all deep learning pipelines run on CUDA, MPS (Apple Silicon), or Intel XPU when available, with automatic fallback to CPU.
• Composable architecture -- individual analysis functions can be called standalone, or orchestrated together via BatchAnalyzer. The same TextData object serves all analyses.

Quick Start

Batch API (recommended for most use cases)

The high-level batch API processes an entire corpus in a few lines:

import logging
import PsychiatryNLPKit as pnlp
from PsychiatryNLPKit.data import Section, TextData
from PsychiatryNLPKit.model import HFEmbeddingLLM, HFGenerativeLLM

# 1. Configure logging (optional but recommended)
pnlp.configure_logging(level=logging.INFO)

# 2. Load your text data from a file or database. Organize the dataset into different sections for separate analysis.
sections = [
    Section(text="I work in a factory that produces humanoid robots. The assembly line runs all day.", name="Paragraph 1"),
    Section(text="I just came back from a vacation in the mountains. The weather was calm and cool.", name="Paragraph 2"),
]
data = TextData(sections=sections, lang="en")

# 3. Attach models (lazy-loaded on first use)
data.embedding_model = HFEmbeddingLLM("unsloth/embeddinggemma-300m")
data.generative_model = HFGenerativeLLM("unsloth/Llama-3.2-1B")

# 4. Run analyses (exclude analyses that require additional models)
result = pnlp.BatchAnalyzer(
    data,
    excluded_analyses=[
        "paragraph_level_pseudo_perplexity",  # requires mask-filling model
        "sentence_level_pseudo_perplexity",
        "structural_graph",  # requires networkx extra
        "image_text_similarity",  # requires pillow extra and image paths
    ],
).run()

# 5. Inspect results
print(result.sections)          # ['Paragraph 1', 'Paragraph 2']
print(result.analyses_run)      # list of successfully executed function names
print(result.results["Paragraph 1"])     # {'sentence_length': 12.5, 'adverb_ratio': 0.08, ...}

# 6. Export to CSV for downstream statistical analysis
import csv
with open("results.csv", "w", newline="") as f:
    writer = csv.writer(f)
    writer.writerow(["section"] + list(result.results["Paragraph 1"].keys()))
    for section in result.sections:
        writer.writerow([section] + [result.results[section].get(k, float("nan"))
                                     for k in result.results["Paragraph 1"].keys()])

Single analyses (TextData.compute)

For targeted analysis or custom pipelines, run individual analyses by name. Each call resolves the required TextData property, language, and models automatically from the analysis registry:

from PsychiatryNLPKit.data import Section, TextData
from PsychiatryNLPKit.model import HFEmbeddingLLM, HFGenerativeLLM

sections = [Section(text="The quick brown fox jumps over the lazy dog. Birds watch from the fence.", name="Paragraph 1")]
data = TextData(sections=sections, lang="en")

# Attach models (lazy-loaded on first use)
data.embedding_model = HFEmbeddingLLM("unsloth/embeddinggemma-300m")
data.generative_model = HFGenerativeLLM("unsloth/Llama-3.2-1B")

# Syntax: sentence length
lengths = data.compute("sentence_length")
# → {"Paragraph 1": {"sentence_length": 10.0}}

# Semantic coherence: adjacent sentence similarity
coherence = data.compute("sentence_level_cosine_similarity")
# → {"Paragraph 1": {"sentence_level_cosine_similarity": 0.73}}

# Perplexity: generative model on paragraphs
perplexity = data.compute("paragraph_level_perplexity")
# → {"Paragraph 1": {"paragraph_level_perplexity": 42.5}}

# Graph: structural word-transition network metrics (requires [graph] extra)
graph_metrics = data.compute("structural_graph")
# → {"Paragraph 1": {"nodes_count": 8.0, "edges_count": 9.0, ...}}

# Density: PCA-based semantic space compression (uses token-level embeddings)
density = data.compute("pca_density_metrics")
# → {"Paragraph 1": {"Ncomp_90": 3.0, "Pcomp_90": 0.375, "ExVar_2": 0.45}}

# Density: propositional idea density (POS-based, no model required)
pid = data.compute("propositional_idea_density")
# → {"Paragraph 1": {"propositional_idea_density": 42.7, "proposition_count": 34.0, "word_count": 80.0}}

# Lexicon: filler word disfluency count
fillers = data.compute("filler_words_count")
# → {"Paragraph 1": {"filler_words_count": 0, "filler_words_ratio": 0.0}}

See PsychiatryNLPKit.analysis.ALL_ANALYSES for the full list of registered analysis names.

Installation

From PyPI

pip install PsychiatryNLPKit              # core package
pip install PsychiatryNLPKit[graph]       # + networkx (for structural_graph)
pip install PsychiatryNLPKit[image]       # + pillow, torchvision (for image_text_similarity)
pip install PsychiatryNLPKit[dev]         # + pytest, pyright, sphinx (for development)

# All extras at once:
pip install PsychiatryNLPKit[graph,image,dev]

From source

git clone https://github.com/rukun-dou/PsychiatryNLPKit.git
cd PsychiatryNLPKit
pip install -e ".[graph,image,dev]"

Requirements: Python 3.11+, Hugging Face token (for gated models). Set the HF_TOKEN environment variable before loading any model that requires authentication.

Configuration

Device detection

PsychiatryNLPKit automatically detects and uses the fastest available hardware:

CUDA (NVIDIA) → MPS (Apple Silicon) → Intel XPU → CPU

from PsychiatryNLPKit import device, hf_token

print(device)        # torch.device('cuda') or 'mps' or 'cpu'
print(hf_token)      # str | None  (read from HF_TOKEN env var)

Models are loaded with bfloat16 precision on GPUs for memory efficiency and faster inference. All deep learning computations (tokenization, embedding generation, perplexity scoring, image-text similarity) run on the detected device.

Logging

import logging
import PsychiatryNLPKit as pnlp

pnlp.configure_logging(level=logging.DEBUG)  # default is INFO

The package uses a dedicated logger (PsychiatryNLPKit) with propagate=False, so messages won't interfere with your application's root logger. Calling configure_logging multiple times is safe (duplicate handlers are guarded against).

Data Model

TextData

The central container for all analysis. It holds raw text sections and computes linguistic properties lazily on first access, caching results to avoid redundant computation:

from PsychiatryNLPKit.data import Section, TextData

sections = [
    Section(text="First paragraph contains two sentences. It is long enough for analysis.", name="Paragraph 1"),
    Section(text="Second paragraph also has two sentences. It gives the model more context.", name="Paragraph 2"),
]
data = TextData(sections=sections, lang="en")

Section

A named text segment:

from PsychiatryNLPKit.data import Section

section = Section(
    text="Clinical interview transcript begins here. The participant describes recent stressors.",
    name="Paragraph 1",
)

Each section has a text attribute (the raw string) and an optional name used as the dictionary key in all analysis outputs. If no name is provided, sections are auto-named section_0, section_1, etc.

ImageData

For image-text similarity analysis:

from PsychiatryNLPKit.data import ImageData

image = ImageData(path="patient_response.jpg", name="Paragraph 1")
# Access via image.image → PIL.Image.Image (lazy-loaded)

ImageData is a convenience container for single-image use. The batch API takes a plain {section_name: path} dict via image_paths instead (see above).

Batch Analysis

BatchAnalyzer is the high-level orchestrator. It runs selected analyses on a TextData object and collects all results into a single structured container:

from PsychiatryNLPKit.analysis import BatchAnalyzer, AnalysisResult
from PsychiatryNLPKit.model import HFMaskFillingModel, HFMultimodalEmbeddingModel

# Attach the remaining models (lazy-loaded on first use)
data.mask_filling_model = HFMaskFillingModel("LiquidAI/LFM2.5-Encoder-350M")
data.vit_model = HFMultimodalEmbeddingModel("Qwen/Qwen3-VL-Embedding-2B")

# Run every analysis (requires all four models attached)
result = BatchAnalyzer(
    data,
    image_paths={"Paragraph 1": "img1.jpg", "Paragraph 2": "img2.jpg"},  # per-section images
).run()

# Run a subset
result = BatchAnalyzer(
    data,
    included_analyses=["sentence_length", "adverb_ratio", "filler_words_count"],
).run()

# Exclude specific analyses from the full set
result = BatchAnalyzer(
    data,
    included_analyses="all",
    excluded_analyses=[
        "paragraph_level_pseudo_perplexity",  # requires mask-filling model
        "sentence_level_pseudo_perplexity",
        "structural_graph",  # requires networkx extra
        "image_text_similarity",  # requires pillow extra and image paths
    ],
).run()

Note: included_analyses="all" requires all four models attached (embedding_model, generative_model, mask_filling_model, vit_model). Analyses whose models are missing raise an AssertionError at construction, so use excluded_analyses to skip them (as in the Quick Start example).

Parameters

Image-text similarity in batch mode

image_text_similarity needs the [image] extra, a multimodal embedding model, and one image path per section:

pip install "PsychiatryNLPKit[image]"

from PsychiatryNLPKit.data import Section, TextData
from PsychiatryNLPKit.model import HFMultimodalEmbeddingModel
from PsychiatryNLPKit.analysis import BatchAnalyzer

sections = [
    Section(text="The patient drew a house with a large sun.", name="Paragraph 1"),
    Section(text="The drawing shows a family in front of the house.", name="Paragraph 2"),
]
data = TextData(sections=sections, lang="en")
data.vit_model = HFMultimodalEmbeddingModel("Qwen/Qwen3-VL-Embedding-2B")

result = BatchAnalyzer(
    data,
    included_analyses=["image_text_similarity"],
    image_paths={
        "Paragraph 1": "drawing_1.jpg",  # keys must match section names exactly
        "Paragraph 2": "drawing_2.jpg",
    },
).run()

image_paths must contain an entry for every section in data.section_names; missing entries raise an AssertionError. Each value is a path to an image file (PIL image objects are also accepted).

AnalysisResult

Analysis Functions Reference

Every analysis below is invoked by name through TextData.compute(name), which resolves the required input automatically (see "Single analyses" above). The "Required input" column documents what each underlying function consumes.

All functions accept a sections parameter (list[str] \| None) to restrict processing to specific sections. When None, all available sections are processed. Empty or missing sections receive float("nan"). Language-dependent functions support "en" and "fr".

Syntax (pnlp.analysis.Syntax) — 13 functions

Measures of sentence structure, part-of-speech distributions, and syntax tree complexity derived from clinical research on thought disorder.

POS tag aliases support both Penn Treebank (JJ, NN, RB) and Universal Dependencies (ADJ, NOUN, ADV) schemes.

Similarity (pnlp.analysis.Similarity) — 2 functions

Cosine similarity between adjacent embeddings to quantify semantic coherence:

Perplexity (pnlp.analysis.Perplexity) — 4 functions

Language model perplexity at paragraph and sentence levels using both generative (causal LM) and masked language models:

Graph (pnlp.analysis.Graph) — 1 function

Constructs a directed, weighted word-transition graph from lemmatized content words and computes network metrics:

Parameters: directed=True, weighted=True, n_random_graphs=1000 (for z-score computation against a null distribution).

Density (pnlp.analysis.Density) — 4 functions

Measures of semantic space dimensionality derived from embeddings, plus propositional idea density:

PCA is applied in token space (features = tokens, i.e. X.T) so metrics reflect how many token directions are needed to explain semantic variance. Total paragraph length must be controlled during statistical analysis.

vector_unpacking_density implements the vector unpacking algorithm: sentence vectors (normalized sums of content-word embeddings) are decomposed into a linear combination of their word embeddings by gradient descent, and the number of meaning components (high-weight embeddings, selected by F-ratio partitioning) divided by the number of content words gives the sentence density. Total paragraph length must be controlled during statistical analysis.

propositional_idea_density counts elementary predications following the CPIDR rule set (Brown et al., 2008): each verb (excluding copular and auxiliary "be" and modals), adjective, adverb, preposition, and conjunction contributes one proposition, and universal quantifiers contribute one as well. PID is reported per 100 words.

Lexicon (pnlp.analysis.Lexicon) — 2 functions

Filler word lists are loaded from the packaged resources/filler_words.json resource. The averaging_method parameter controls computation: "macro" averages per-sentence filler ratios, "micro" computes total fillers / total words across the section (default: "macro").

zipf_frequency looks up each word's lemma in the wordfreq database (English and French); unrecognized lemmas are excluded from the mean and standard deviation.

ImageSimilarity (pnlp.analysis.ImageSimilarity) — 1 function

The image argument accepts a PIL Image object or a file path. Text and images are encoded with a SentenceTransformer multimodal model, then compared with cosine similarity.

Model Wrappers

All models use lazy loading: the underlying Hugging Face model is downloaded and loaded only when first accessed. Models are unloaded after each compute() call (or at the end of a BatchAnalyzer run) to free GPU memory.

from PsychiatryNLPKit.model import HFEmbeddingLLM, HFGenerativeLLM, HFMaskFillingModel, HFMultimodalEmbeddingModel

embedding = HFEmbeddingLLM("unsloth/embeddinggemma-300m")
embedding.load()
# embedding.model.encode(...)  # use the underlying model directly
embedding.unload()  # frees GPU memory

vit_model = HFMultimodalEmbeddingModel("Qwen/Qwen3-VL-Embedding-2B")
vit_model.load()
# vit_model.model.encode([image, text], convert_to_tensor=True)
vit_model.unload()

Data Formats

Input: Text sections

The primary input is a list of Section objects, each containing raw text and an optional name. Sections can represent individual interview responses, paragraphs from clinical notes, or any other text unit.

For batch processing from files, a typical workflow looks like:

import csv
from PsychiatryNLPKit.data import Section, TextData

# Read from CSV: columns "id", "text"
sections = []
with open("clinical_corpus.csv", newline="") as f:
    reader = csv.DictReader(f)
    for index, row in enumerate(reader, start=1):
        sections.append(Section(text=row["text"], name=f"Paragraph {index}"))

data = TextData(sections=sections, lang="en")

Output: AnalysisResult

The AnalysisResult container provides three access patterns:

# By section → metric
result.results["Paragraph 1"]["sentence_length"]  # 12.5

# Export to pandas DataFrame for statistical analysis
import pandas as pd
records = []
for section in result.sections:
    record = {"section": section}
    record.update({k: v for k, v in result.results[section].items()})
    records.append(record)
df = pd.DataFrame(records)

# Check for failures
if result.errors:
    print("Failed analyses:", result.errors)

Project Structure

PsychiatryNLPKit/
├── src/
│    └── PsychiatryNLPKit/
│         ├── config.py                  # Device detection, logging setup, HF token
│         ├── data/
│         │    ├── Text.py                # Section, TextData (lazy-computed properties)
│         │    ├── Image.py               # ImageData container
│         │    ├── Audio.py               # Placeholder for future audio processing
│         │    └── _resources.py          # SQLite-backed WordEmbeddingStore, stopwords
│         ├── model/
│         │    ├── LLM.py                 # BaseLLM, HuggingFaceLLM, HFEmbeddingLLM, HFGenerativeLLM, HFMaskFillingModel
│         │    └── ViT.py                 # HuggingFaceViTModel, HFMultimodalEmbeddingModel
│         ├── analysis/
│         │    ├── Syntax.py              # 13 syntax functions
│         │    ├── Similarity.py          # 2 similarity functions
│         │    ├── Perplexity.py          # 4 perplexity functions
│         │    ├── Graph.py                # structural_graph (network metrics + z-scores)
│         │    ├── Density.py             # PCA density, intrinsic dimensionality, propositional idea density
│         │    ├── Lexicon.py             # Filler word disfluency analysis
│         │    ├── ImageSimilarity.py     # multimodal image-text similarity
│         │    └── batch.py               # BatchAnalyzer, AnalysisResult
│         └── resources/
│              ├── filler_words.json      # EN/FR filler word lists
│              └── word2vec.db            # SQLite database with Zstd-compressed embeddings
└── tests/                                # Unit and integration tests

BibTeX Citation

If you use PsychiatryNLPKit in your research, please cite:

@software{psychiatrynlpkit2026,
  author = {Dou, Rukun and Wei, Tiana and Voppel, Alban Elias and Palaniyappan, Lena},
  title = {PsychiatryNLPKit: Computational linguistics toolkit for psychosis risk assessment and thought disorder analysis},
  year = {2026},
  url = {https://github.com/rukun-dou/PsychiatryNLPKit},
  version = {0.1.7},
  license = {MIT}
}

References

All analysis functions include their theoretical basis and primary references in their docstrings. Key publications underpinning this toolkit:

• Alqahtani, A., Kayi, E. S., Hamidian, S., Compton, M., & Diab, M. (2022). A quantitative and qualitative analysis of schizophrenia language. Proceedings of the 13th International Workshop on Health Text Mining and Information Analysis (LOUHI), 173–183.
• Bilgrami, Z. R., et al. (2022). Construct validity for computational linguistic metrics in individuals at clinical risk for psychosis. Schizophrenia Research, 245, 90–96.
• Elvevåg, B., Foltz, P. W., Weinberger, D. R., & Goldberg, T. E. (2007). Quantifying incoherence in speech: An automated methodology and novel application to schizophrenia. Schizophrenia Research, 93(1-3), 304–316.
• Haas, S. S., Doucet, G. E., Garg, S., Herrera, S. N., Sarac, C., Bilgrami, Z. R., Shaik, R. B., & Corcoran, C. M. (2020). Linking language features to clinical symptoms and multimodal imaging in individuals at clinical high risk for psychosis. European Psychiatry, 63(1), e72.
• He, R., Palominos, C., Zhang, H., Alonso-Sánchez, M. F., Palaniyappan, L., & Hinzen, W. (2024). Navigating the semantic space: Unraveling the structure of meaning in psychosis using different computational language models. Psychiatry Research, 333, 115752.
• Hill, E., et al. (2021). Propositional idea density and cognitive decline.
• Liebenthal, E., et al. (2022). Linguistic and non-linguistic markers of disorganization in psychotic illness. Schizophrenia Research, 259, 111–120.
• Morice, R. D., & Ingram, J. C. (1983). Language complexity and age of onset of schizophrenia. Psychiatry Research, 9(3), 233–242.
• Nikzad, A. H., et al. (2022). Who does what to whom? graph representations of action-predication in speech relate to psychopathological dimensions of psychosis. Schizophrenia, 8(1), 58.
• Rezaii, N., Walker, E., & Wolff, P. (2019). A machine learning approach to predicting psychosis using semantic density and latent content analysis. npj Schizophrenia, 5, 9.
• Palominos, C., et al. (2025). Lexical meaning is lower dimensional in psychosis. Scientific Reports, 16(1), 859.
• Vail, A. K., Liebson, E., Baker, J. T., & Morency, L.-P. (2018). Toward objective, multifaceted characterization of psychotic disorders: Lexical, structural, and disfluency markers of spoken language. Proceedings of the 20th ACM International Conference on Multimodal Interaction, 170–178.

Funding

This work was supported by the FRQS Partenariat Innovation-Québec-Janssen (PIQ-J) initiative (#338282), the FRQS Alliance en santé mentale grant (#348797 to Douglas Research Centre), CIHR SPOR (PJK192157), CIHR Project Grant (PJT195903), Wellcome Trust Discretionary Grant (226168/Z/22/Z), and Wellcome Trust Mental Health Award for the DIALOG consortium (314138/Z/24/Z). L. Palaniyappan is supported by the Monique H. Bourgeois Chair in Developmental Disorders and the Graham Boeckh Foundation, and holds a salary award from the Fonds de recherche du Québec – Santé (366934), with additional support through a Research Centre Grant to Douglas Research Centre (5230).

License

MIT License -- Copyright (c) 2026 Rukun Dou, Tiana Wei, Alban Elias Voppel, Lena Palaniyappan