diaad 0.3.0

Database-native infrastructure for reproducible discourse analysis workflows

DIAAD - Database-oriented, Integrative Architecture for Analyzing Discourse

DIAAD is open-source Python infrastructure for reproducible discourse analysis workflows. It helps organize CHAT transcripts, transcript-derived tables, metadata, manual coding files, reliability checks, blinding, rate calculations, target vocabulary analysis, generated examples, and run artifacts across repeated analyses.

DIAAD is under active development. Output formats, command behavior, and documentation may continue to change before a stable 1.0 release.

Core Capabilities

• Convert CHAT .cha files into sample- and utterance-level transcript tables.
• Generate coding and reliability workbooks for Complete Utterances, word counts, POWERS, Digital Conversation Turns, and custom templates.
• Select, evaluate, and reselect reliability samples.
• Analyze completed coding files and calculate per-minute rates from speaking-time tables.
• Analyze target vocabulary coverage using built-in or custom resources.
• Encode and decode configured identifier columns for blinding workflows.
• Generate runnable synthetic example projects and generated Example I/O documentation.
• Record resolved configuration, logs, manifests, and other run artifacts for reproducibility.

Installation

DIAAD requires Python >=3.12,<3.13. A fresh virtual environment is recommended.

python -m venv .venv
.venv\Scripts\activate
pip install diaad

On macOS or Linux, activate the environment with:

source .venv/bin/activate

Optional dependency groups:

pip install "diaad[web]"      # local Streamlit web app
pip install "diaad[nlp]"      # spaCy support for NLP-backed workflows
pip install "diaad[web,nlp]"  # both

If you install the nlp extra and use the default POWERS automation model, also install the spaCy model:

python -m spacy download en_core_web_sm

For development from a local checkout:

git clone https://github.com/nmccloskey/DIAAD.git
cd DIAAD
pip install -e ".[dev,web,nlp]"

Quick Start

Check the command-line interface:

diaad --help

Generate a full synthetic example dataset:

diaad examples

Generate examples for one command:

diaad examples --for-command "transcripts tabularize"

Run a basic transcript tabularization command:

diaad transcripts tabularize

Run multiple commands in sequence:

diaad "transcripts tabularize, cus files, words files"

Launch the local web app after installing diaad[web]:

diaad streamlit

The legacy streamlit_diaad launcher is also available.

Project Configuration

For real projects, use a project folder with split configuration files:

your_project/
  config/
    project.yaml
    advanced.yaml
  diaad_data/
    input/
    output/

When run from your_project/, the CLI uses ./config automatically. You can also pass a config source explicitly:

diaad transcripts tabularize --config config

Use a dry run to inspect the resolved configuration before processing data:

diaad transcripts tabularize --dry-run-config --dry-run-config-format yaml

See the manual for the current configuration model and settings.

Documentation

The authored manual is in docs/manual.

Useful entry points:

• Installation
• Command-line operation
• Web app operation
• Configuration
• Functional overview
• Generated Example I/O view

Generated Example I/O pages are built from packaged example specs and should be regenerated rather than edited by hand.

Development and Tests

Install development dependencies:

pip install -e ".[dev,web,nlp]"

Run the test suite:

pytest

Run a specific test file:

pytest tests/test_examples/test_examples.py

Data Privacy

DIAAD can support blinding and organized handling of discourse data, but it is not a de-identification guarantee. For identifiable, sensitive, or difficult-to-deidentify data, prefer local CLI processing and follow the privacy requirements of the project, institution, and data source.

Acknowledgments

DIAAD builds on the broader open-source language-analysis ecosystem and is designed to work downstream of CHAT/TalkBank-oriented workflows. Fuller methodological context and acknowledgments are maintained in the manual.

License

DIAAD is distributed under the MIT License. License metadata is declared in pyproject.toml.

Contact

Please use GitHub Issues for bug reports, feature requests, and documentation problems.