Getting Started
===============

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

Installation
------------

.. rubric:: Prerequisites

- **Python 3.11+**
- A `Hugging Face account <https://huggingface.co/join>`_ (some models require authentication)

.. rubric:: Install from PyPI

.. code-block:: bash

   pip install PsychiatryNLPKit

.. rubric:: Optional dependencies

Some analyses require additional packages:

.. list-table::
   :widths: 25 75
   :header-rows: 1

   * - 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:

.. code-block:: bash

   pip install "PsychiatryNLPKit[graph,image]"

.. rubric:: Install from source

.. code-block:: bash

   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:

.. code-block:: bash

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

Or in Python before importing:

.. code-block:: python

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

.. code-block:: python

   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:

.. code-block:: python

   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:

.. code-block:: python

   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``:

.. code-block:: python

   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
~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: python

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

.. code-block:: python

   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``:

.. code-block:: python

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

- See :doc:`concepts` for an overview of the architecture and design principles
- Browse the :doc:`api/data`, :doc:`api/analysis`, and :doc:`api/model` reference pages
- Consult the `README <https://github.com/rukun-dou/PsychiatryNLPKit/blob/main/README.md>`_ for scientific background