Getting Started

This guide will help you install PsychiatryNLPKit and run your first analysis. The package is developed in the CEYMH / Douglas Research Group at McGill University.

Installation

Prerequisites

Install from PyPI

pip install PsychiatryNLPKit

Optional dependencies

Some analyses require additional packages:

Extra

Description

graph

Graph-based network metrics (requires networkx>=3.0)

image

Image-text cross-modal similarity (requires pillow>=10.0.0)

Install with extras:

pip install "PsychiatryNLPKit[graph,image]"

Install from source

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

Hugging Face Token

Some models (e.g., Benepar constituency parsers) require authentication. Set the HF_TOKEN environment variable:

export HF_TOKEN="your_token_here"  # Linux / macOS
setx HF_TOKEN "your_token_here"    # Windows

Or in Python before importing:

import os
os.environ["HF_TOKEN"] = "your_token_here"

First Analysis

The fastest way to analyze text is with the Batch API, which runs all available analyses on your data in a single call.

Step 1: Prepare your text

Organize text into named sections (e.g., paragraphs, utterances, interview segments, or participant responses). The section name becomes the key in the analysis outputs.

from PsychiatryNLPKit.data import Section, TextData

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")

If your source data is a CSV file with one row per participant, build the sections from each row and name them Paragraph 1, Paragraph 2, and so on. If your source data is a folder of text files, create one section per file in the same way.

import csv
from pathlib import Path

from PsychiatryNLPKit.data import Section, TextData

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")

# Folder of text files with one file per participant
sections = []
for index, path in enumerate(Path("transcripts").glob("*.txt"), start=1):
    sections.append(Section(text=path.read_text(encoding="utf-8"), name=f"Paragraph {index}"))

Step 2: Attach models

Analysis functions use pre-computed linguistic features (POS tags, embeddings, constituency parses). Attach models to the TextData object — they are lazy-loaded on first access and cached:

from PsychiatryNLPKit.model import HFEmbeddingLLM, HFGenerativeLLM

data.embedding_model = HFEmbeddingLLM("unsloth/embeddinggemma-300m")
data.generative_model = HFGenerativeLLM("unsloth/Llama-3.2-1B")

Step 3: Run analyses

Use BatchAnalyzer to run a subset of analyses that match the models you’ve attached:

import PsychiatryNLPKit as pnlp
from PsychiatryNLPKit.analysis import BatchAnalyzer

# Optional: enable logging
pnlp.configure_logging()

analyzer = BatchAnalyzer(
    data,
    included_analyses=[
        "sentence_length", "adverb_ratio", "syntax_depth",
        "word_level_cosine_similarity", "sentence_level_cosine_similarity",
        "paragraph_level_perplexity", "sentence_level_perplexity",
        "pca_density_metrics", "intrinsic_dimensionality_density",
        "filler_words_count",
    ]
)
result = analyzer.run()

You can also start from the full analysis set and remove functions you do not want to run with excluded_analyses:

analyzer = BatchAnalyzer(
   data,
   included_analyses="all",
   excluded_analyses=[
      "paragraph_level_pseudo_perplexity",
      "sentence_level_pseudo_perplexity",
      "structural_graph",
      "image_text_similarity",
   ],
)
result = analyzer.run()

To run all analyses (including pseudo-perplexity and image-text similarity), attach the additional required models to the data object:

from PsychiatryNLPKit.model import HFMaskFillingModel, HFMultimodalEmbeddingModel

data.mask_filling_model = HFMaskFillingModel("LiquidAI/LFM2.5-Encoder-350M")
data.vit_model = HFMultimodalEmbeddingModel("Qwen/Qwen3-VL-Embedding-2B")

analyzer = BatchAnalyzer(
   data,
   image_paths={"Paragraph 1": "image1.jpg", "Paragraph 2": "image2.jpg"},
)
result = analyzer.run()

Step 4: Inspect results

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

Running Specific Analyses

To run only a subset of analyses (e.g., for faster iteration or to avoid certain models):

from PsychiatryNLPKit.analysis import BatchAnalyzer

analyzer = BatchAnalyzer(
    data,
    included_analyses=["sentence_length", "adverb_ratio", "syntax_depth"]
)
result = analyzer.run()

Individual Analysis Functions

For fine-grained control, run single analyses by name through TextData.compute. Each call resolves the required TextData property, language, and models automatically from the analysis registry:

# Syntax metrics use POS tags and syntax trees
lengths = data.compute("sentence_length")
depth = data.compute("syntax_depth")

# Similarity metrics use embedding vectors
coherence = data.compute("sentence_level_cosine_similarity")

Each function returns a dictionary keyed by section name with numeric metric values. See PsychiatryNLPKit.analysis.ALL_ANALYSES for the full list of analysis names.

Next Steps