Getting Started

This guide will help you install PsychiatryNLPKit and run your first analysis.

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, or interview segments):

from PsychiatryNLPKit.data import Section, TextData

sections = [
    Section(text="I work in a factory that produces humanoid robots.", name="p1"),
    Section(text="I just came back from a vacation in the mountains.", name="p2"),
]
data = TextData(sections=sections, lang="en")

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

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

from PsychiatryNLPKit.model import HFMaskFillingModel, HFMultimodalEmbeddingModel

analyzer = BatchAnalyzer(
    data,
    mask_filling_model=HFMaskFillingModel("google-bert/bert-base-multilingual-uncased"),
    vit_model=HFMultimodalEmbeddingModel("openai/clip-vit-base-patch16"),
    image_paths={"p1": "image1.jpg", "p2": "image2.jpg"},
)
result = analyzer.run()

Step 4: Inspect results

print(result.sections)       # ['p1', 'p2']
print(result.analyses_run)   # list of successfully executed analysis names
print(result.results["p1"])  # {'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, call analysis functions directly with pre-computed features from TextData:

from PsychiatryNLPKit import analysis as pnlp_a

# Syntax metrics use POS tags and syntax trees
lengths = pnlp_a.sentence_length(data.pos_tags)
depth = pnlp_a.syntax_depth(data.syntax_trees)

# Similarity metrics use embedding vectors
coherence = pnlp_a.sentence_level_cosine_similarity(
    data.sentence_embedding_vectors
)

Each function returns a dictionary keyed by section name with numeric metric values.

Next Steps