# neulab/reviewadvisor architecture

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

- Interactive diagram: https://gitdiagram.com/neulab/reviewadvisor
- Repository: https://github.com/neulab/reviewadvisor

## Overview

##### Project type and purpose
- This is an open-source NLP research toolkit (“ReviewAdvisor”) that automates scientific peer review by applying an “extract-then-generate” pipeline. It consists of two main processing modules—an extractor and a tagger—plus supporting scripts for data retrieval, preprocessing, and post-processing.

##### File structure
- Top-level:
- download_dataset.sh & download_tagger.sh – data/model acquisition scripts
- extractor/ – section-based and statistical extraction implementation
- tagger/ – sequence labeling (“tagging”) pipeline with helper utilities, config, and scripts
- scripts/ – generic download helper (gdown.pl)
- fig/ & materials/ – documentation, figures, annotation guidelines, sample JSON
- Orchestration point: the shell scripts call Python modules in extractor/ and tagger/ in sequence.

##### Essential components
a. Data Acquisition
- download_dataset.sh → populates dataset/; download_tagger.sh → retrieves pretrained model into tagger/seqlab_final/
b. Extraction Module (extractor/)
- extractor.py, extractor_utils.py read raw papers & parameters.txt → produce extracted snippets or selection indices
- example.ipynb demonstrates usage interactively
c. Tagging Module (tagger/)
- run_tagger.py or tasks.py orchestrates:
- prepare.sh → splits data (split.py), jsonlize outputs (jsonlize.py)
- annotator.py & heuristics.py → rule–based tagging for certain labels
- utils_batch.py & post_process.sh → batch inference using pretrained seqlab_final model
- config.json and labels.txt govern model behavior
d. (Optional) Generation / Evaluation / Visualization
- Evaluation and bias-analysis figures (in fig/) can be represented as “Metrics & Visualization” component.

##### Relationships & data flow
- Scripts (download_*.sh, prepare.sh, post_process.sh) surround and trigger each major module

##### Architectural patterns & design principles
- Modular pipeline: clear separation of concerns (data download, extraction logic, tagging logic, post-processing)
- Script-driven orchestration (shell scripts invoking Python modules)
- Configuration-driven components (config.json, parameters.txt) for flexibility
- Helper utilities extracted into a “helper/” package within tagger

##### Technologies & frameworks
- Python + standard libraries (os, json, argparse)
- Shell scripting (bash) for orchestration
- Jupyter notebook for interactive demos (extractor/example.ipynb)
- External pretrained sequence labeling model (loaded via tagger/run_tagger.py)

##### Detail to capture
- Shell scripts as the “glue” that invoke each stage
- The contents of tagger/helper (split, heuristics, jsonlize) as sub-components of the Tagging Module
- The role of config.json and labels.txt in controlling tagging behavior
- Interactive/demo components (notebook, fig/) as auxiliary outputs

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Acquisition Scripts
    subgraph "Data Acquisition" 
        direction TB
        DScripts["download_dataset.sh"]:::script
        DTScripts["download_tagger.sh"]:::script
        GDown["gdown.pl"]:::script
    end
    DScripts -->|populates dataset/| RawData["Raw Dataset (JSON, PDF)"]:::dataStore
    DTScripts -->|retrieves model| PreModel["Pretrained Model Store"]:::external
    GDown --> DScripts
    GDown --> DTScripts

    %% Extraction Module
    subgraph "Extraction Module" 
        direction TB
        EM_py["extractor.py"]:::processing
        EM_utils["extractor_utils.py"]:::processing
        Keywords["keywords.txt"]:::dataStore
        Params["parameters.txt"]:::dataStore
        ExampleNB["example.ipynb"]:::external
    end
    RawData --> EM_py
    Params --> EM_py
    Keywords --> EM_py
    EM_py --> Extracted["Extracted Snippets"]:::dataStore

    %% Tagging Module
    subgraph "Tagging Module"
        direction TB
        Prepare["prepare.sh"]:::script
        subgraph "Helper Utilities"
            direction TB
            Split["split.py"]:::processing
            Jsonl["jsonlize.py"]:::processing
            AnnUtils["annotator_utils.py"]:::processing
            Heuristics["heuristics.py"]:::processing
            Utils["utils.py"]:::processing
            UtilsBatch["utils_batch.py"]:::processing
        end
        Tasks["tasks.py"]:::processing
        Annotator["annotator.py"]:::processing
        RunTagger["run_tagger.py"]:::processing
        Config["config.json"]:::dataStore
        Labels["labels.txt"]:::dataStore
        PostProc["post_process.sh"]:::script
    end
    Extracted --> Prepare
    Prepare --> Split
    Split --> Jsonl
    Jsonl --> Tasks
    Tasks --> Annotator
    Annotator --> RunTagger
    RunTagger --> PostProc
    Config --> RunTagger
    Labels --> RunTagger
    PreModel --> RunTagger
    PostProc --> TagOutputs["Tagging Outputs (JSONL, labels)"]:::dataStore

    %% Review Generation and Evaluation
    RG["Review Generation"]:::processing
    TagOutputs --> RG
    MVis["Metrics & Visualization"]:::external
    RG --> MVis

    %% Documentation & Materials
    Mat["Documentation & Sample Materials"]:::external

    %% Layout: place Materials to left
    Mat -.-> RawData

    %% Click Events
    click DScripts "https://github.com/neulab/reviewadvisor/blob/main/download_dataset.sh"
    click DTScripts "https://github.com/neulab/reviewadvisor/blob/main/download_tagger.sh"
    click GDown "https://github.com/neulab/reviewadvisor/blob/main/scripts/gdown.pl"
    click EM_py "https://github.com/neulab/reviewadvisor/blob/main/extractor/extractor.py"
    click EM_utils "https://github.com/neulab/reviewadvisor/blob/main/extractor/extractor_utils.py"
    click Keywords "https://github.com/neulab/reviewadvisor/blob/main/extractor/keywords.txt"
    click Params "https://github.com/neulab/reviewadvisor/blob/main/extractor/parameters.txt"
    click ExampleNB "https://github.com/neulab/reviewadvisor/blob/main/extractor/example.ipynb"
    click Prepare "https://github.com/neulab/reviewadvisor/blob/main/tagger/prepare.sh"
    click Split "https://github.com/neulab/reviewadvisor/blob/main/tagger/helper/split.py"
    click Jsonl "https://github.com/neulab/reviewadvisor/blob/main/tagger/helper/jsonlize.py"
    click AnnUtils "https://github.com/neulab/reviewadvisor/blob/main/tagger/helper/annotator_utils.py"
    click Heuristics "https://github.com/neulab/reviewadvisor/blob/main/tagger/helper/heuristics.py"
    click Utils "https://github.com/neulab/reviewadvisor/blob/main/tagger/helper/utils.py"
    click UtilsBatch "https://github.com/neulab/reviewadvisor/blob/main/tagger/helper/utils_batch.py"
    click Tasks "https://github.com/neulab/reviewadvisor/blob/main/tagger/tasks.py"
    click Annotator "https://github.com/neulab/reviewadvisor/blob/main/tagger/annotator.py"
    click RunTagger "https://github.com/neulab/reviewadvisor/blob/main/tagger/run_tagger.py"
    click Config "https://github.com/neulab/reviewadvisor/blob/main/tagger/config.json"
    click Labels "https://github.com/neulab/reviewadvisor/blob/main/tagger/labels.txt"
    click PostProc "https://github.com/neulab/reviewadvisor/blob/main/tagger/post_process.sh"
    click MVis "https://github.com/neulab/reviewadvisor/tree/main/fig/"
    click Mat "https://github.com/neulab/reviewadvisor/tree/main/materials/"

    %% Styles
    classDef dataStore fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef processing fill:#98FB98,stroke:#333,stroke-width:1px
    classDef script fill:#FFA500,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
```
