# contextlab/quail architecture

> Architecture diagram of the GitHub repository contextlab/quail, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/contextlab/quail
- Repository: https://github.com/contextlab/quail

## Overview

##### Project type and purpose
- This is an open-source Python toolbox (library) named “Quail” for analyzing and plotting free-recall behavioral data.
- It provides a programmatic API (classes & functions) for loading data, building “egg” data structures, running analyses (SPC, PFR, lag-CRP, clustering, fingerprint), and plotting results.

##### File structure
- Top-level folders:
- quail/          ← core library package
– data/         ← built-in example data files (.egg, CSV)
– analysis/     ← modules implementing each analysis metric
– decode_speech.py ← wrapper for Google Cloud Speech-to-Text
– egg.py        ← Egg class definition (core data structure)
– helpers.py, distance.py, fingerprint.py, load.py, plot.py, simulate.py
- docs/           ← Sphinx documentation sources & build outputs
- examples/       ← simple example scripts demonstrating API usage
- tests/          ← pytest test suite for each module
- data/           ← sample raw audio (.wav) for speech decoding tutorials
- setup.py, requirements.txt, README.md, Makefile…

##### README for additional insights
- The README describes the high-level API:
- quail.Egg → data container
- quail.load_example_data → data loader
- quail.analyze(egg, analysis=…) → returns pandas DataFrame of metrics
- quail.plot(dataframe) → uses matplotlib/seaborn to render figures
- Optional speech decoding via Google Cloud STT (requires ffmpeg).

##### Main components and interactions
a. Core components:
- Client code (users or examples/notebooks)
- API facade (quail/__init__.py exposing high-level functions: Egg, load, analyze, plot)
- Data layer (quail/data): built-in datasets, egg file I/O
- Analysis modules (quail/analysis/*.py): implement each metric → return pandas structures
- Speech decoding module (quail/decode_speech.py) → external Google Cloud STT service + ffmpeg
- Helpers & utilities (quail/helpers.py, distance.py, simulate.py)
- Tests (pytest suite verifying module behavior)
- Documentation (Sphinx, docs/conf.py → HTML/PDF output)

b. Relationships & Data Flow:
1. User invokes quail.Egg(...) or quail.load_example_data()
2. Egg object holds input lists (pres, rec) or loads from .egg files
3. quail.analyze(egg, analysis=… ) calls the appropriate module in quail/analysis → returns pandas DataFrame
4. quail.plot(dataframe, …) calls quail/plot.py → matplotlib/seaborn renders the figure
5. Optionally, quail.decode_speech(wav) sends audio to Google Cloud API → transcripts → Egg constructor

c. Architectural patterns & design principles:
- Facade pattern: quail/__init__.py exposes a simple, unified high-level API
- Modular separation: each analysis metric is its own module (single responsibility)
- Data-centric flow: Egg object → DataFrame → Visualization

d. Key technologies & dependencies:
- Python 3.6+
- pandas, numpy, scipy (data structures & numeric ops)
- matplotlib, seaborn (visualization)
- Google Cloud Speech-to-Text API (optional external service)
- ffmpeg (external binary for audio processing)
- pytest (testing)
- Sphinx (documentation generation)

##### Detailed capture of essential architectural elements
- Do not over-fragment; group related analysis functions under a single “Analysis” block but note submodules
- How documentation & tests integrate: docs are auto-built from code, tests verify core modules
- Facade: client code only needs to import quail.*

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Code
    Client["Client Code\n(examples/)"]:::user
    click Client "https://github.com/contextlab/quail/tree/master/examples/"

    %% Core Library
    subgraph "Core Library" 
        direction TB
        API["API Facade\nquail/__init__.py"]:::core
        click API "https://github.com/contextlab/quail/blob/master/quail/__init__.py"

        Egg["Egg Class\nquail/egg.py"]:::core
        click Egg "https://github.com/contextlab/quail/blob/master/quail/egg.py"

        DataLoader["Data Loader\nquail/load.py"]:::core
        click DataLoader "https://github.com/contextlab/quail/blob/master/quail/load.py"

        DataLayer["Data Layer\nquail/data/"]:::core
        click DataLayer "https://github.com/contextlab/quail/tree/master/quail/data/"

        Analysis["Analysis Modules\n(quail/analysis/)"]:::core
        click Analysis "https://github.com/contextlab/quail/blob/master/quail/analysis/analysis.py"

        Plot["Plot Module\nquail/plot.py"]:::core
        click Plot "https://github.com/contextlab/quail/blob/master/quail/plot.py"

        Speech["Speech Decoding\nquail/decode_speech.py"]:::core
        click Speech "https://github.com/contextlab/quail/blob/master/quail/decode_speech.py"

        Helpers["Helpers & Utilities\n(quail/helpers.py,\nquail/distance.py,\nquail/simulate.py,\nquail/fingerprint.py)"]:::core
        click Helpers "https://github.com/contextlab/quail/blob/master/quail/helpers.py"
    end

    %% Outputs
    Figure["Figure Output\n(Matplotlib Figure)"]:::core

    %% External Dependencies & Services
    subgraph "External Dependencies & Services"
        direction TB
        pandas["pandas, numpy, scipy"]:::external
        matplotlib["matplotlib, seaborn"]:::external
        STT["Google Cloud STT"]:::external
        ffmpeg["ffmpeg"]:::external
    end

    %% Tests & Documentation
    Tests["Tests\n(pytest suite)"]:::testdoc
    click Tests "https://github.com/contextlab/quail/tree/master/tests/"

    Docs["Documentation\n(Sphinx docs)"]:::testdoc
    click Docs "https://github.com/contextlab/quail/tree/master/docs/"

    %% Data Flow
    Client -->|"calls"| API
    API -->|"Egg() / load_example_data()"| Egg
    API -->|"load_example_data()"| DataLoader
    DataLoader -->|"reads files"| DataLayer
    API -->|"analyze(egg,analysis=)"| Analysis
    Analysis -->|"returns pandas DataFrame"| Plot
    Plot -->|"renders"| Figure

    %% Speech Decoding Flow
    API -->|"decode_speech(wav)"| Speech
    Speech -->|"sends audio"| STT
    STT -->|"returns JSON transcript"| Speech
    Speech -->|"constructs Egg"| Egg

    %% Dependency Links
    Analysis -->|"uses"| pandas
    Analysis -->|"uses"| numpy
    Analysis -->|"uses"| scipy
    Plot -->|"uses"| matplotlib
    Plot -->|"uses"| seaborn
    Speech -->|"requires"| ffmpeg

    %% Tests & Docs Relationships
    Tests -->|"verify core modules"| Egg
    Tests --> Egg
    Tests --> Analysis
    Tests --> Plot
    Docs -->|"builds from source"| API
    Docs -->|"includes tutorials for"| Speech

    classDef core fill:#cce5ff,stroke:#0066cc;
    classDef external fill:#ffe5cc,stroke:#cc6600;
    classDef user fill:#ccffcc,stroke:#339933;
    classDef testdoc fill:#e0e0e0,stroke:#666666;
```
