# jiachengxiong/reactseq architecture

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

- Interactive diagram: https://gitdiagram.com/jiachengxiong/reactseq
- Repository: https://github.com/jiachengxiong/reactseq

## Overview

##### Project Type and Purpose
- ReactSeq is a machine‐learning pipeline for chemical retrosynthesis:
- It converts product SMILES into a “ReactSeq” representation via data preprocessing (RDKit/Indigo).
- It trains and runs a seq2seq model (OpenNMT-py) to predict ReactSeq strings.
- It transforms predicted ReactSeq back to reactant SMILES and evaluates top-k accuracy.
- Key use cases: data augmentation, training, inference, evaluation, and demo via Gradio.

##### File Structure Analysis
- Top‐level directories/files:
- config/ – YAML files for training/inference settings
- datasets/ – raw and processed data splits (50k_ReactSeq, with/without prompts)
- onmt/ – customized OpenNMT-py library (encoders, decoders, modules, training/inference scripts)
- checkpoints/ & trained_models/ – model checkpoint storage
- scripts: preprocess_data.py, transform.py, train.sh, inference.sh, demo_*.sh
- embedding/ – embedding extraction & analysis notebooks/scripts
- ELN/ – exploratory notebooks for condition/yield prediction
- output/ – inference outputs & evaluation templates
- Two conda environments:
- rdkit2019 for chemistry preprocessing
- opennmt3 for model training/inference

##### README Insights
- Describes dual‐environment setup, data preprocessing commands, training/inference workflows, transformation steps, and evaluation.
- Points to notebooks for usage examples and accuracy calculations.
- Mentions external demo service (Gradio on Hugging Face).

##### Main Components & Relationships

A. Data Layer
- Raw USPTO_50K CSVs (datasets/50k_raw)
- Vocabulary files (datasets/vocabs)

B. Preprocessing Layer (rdkit2019 env)
- preprocess_data.py & preprocess_prompt_data.ipynb
- RDKit/Indigo tokenization, reaction mapping
- Outputs: processed src/tgt files in datasets/50k_ReactSeq*

C. Model Training Layer (opennmt3 env)
- Config YAMLs (config/*.yml)
- onmt/bin/train.py wrapper (called by train.sh)
- onmt/core modules: encoders, decoders, training loops
- Checkpoint saving to checkpoints/

D. Inference Layer (opennmt3 env)
- onmt/bin/translate.py via inference.sh / inference_with_prompt.sh
- Generates ReactSeq predictions (output/tgt_*.txt)

E. Postprocessing Layer (rdkit2019 env)
- transform.py converts ReactSeq → SMILES of reactants
- Output: output/pred_reactants_*.txt

F. Evaluation & Analysis
- cal_top_k_accuracy.ipynb for metrics
- embedding/ scripts & notebooks for representation analysis
- ELN/ notebooks for auxiliary exploratory tasks

G. Demo Service
- demo_inference.sh + demo_transform.sh
- Gradio frontend hosted on Hugging Face

##### Architectural Patterns & Technologies
- Pipeline architecture with distinct environments for chemistry vs. ML
- Modular separation of concerns: data, preprocessing, modeling, postprocessing, evaluation
- Configuration-driven (YAML) orchestration of training/inference
- Reusable library (onmt/) alongside project-specific scripts
- Notebook-driven exploration & demos

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% RDKit Environment: Data & Preprocessing
    subgraph "RDKit Environment" 
        direction TB
        RawCSV("Raw USPTO_50K CSVs"):::data
        Vocab("Vocabulary Files"):::data
        Preprocess["Preprocess Data"]:::preproc
        PreprocessPrompt["Preprocess with Prompts"]:::preproc
        Processed("Processed src/tgt Files"):::data
    end

    %% OpenNMT-py Environment: Training & Inference
    subgraph "OpenNMT-py Environment"
        direction TB
        ConfigTrain("Train Config YAMLs"):::config
        TrainScript["train.sh / train_prompt.sh"]:::script
        TrainPy["onmt/bin/train.py"]:::script
        Checkpoints("Model Checkpoints"):::checkpoint
        TranslatePy["onmt/bin/translate.py"]:::script
        InferenceScript["inference.sh / inference_with_prompt.sh"]:::script
        Predictions("ReactSeq Predictions"):::data
    end

    %% Postprocessing & Evaluation
    subgraph "Postprocessing & Evaluation"
        direction TB
        Transform["transform.py"]:::post
        PostPred("Predicted Reactants SMILES"):::data
        EvalNotebook["cal_top_k_accuracy.ipynb"]:::eval
        Embedding("Embedding Analysis"):::eval
        ELN("ELN Notebooks"):::eval
    end

    %% Demo Service
    subgraph "Demo Service"
        direction TB
        DemoInfer["demo_inference.sh"]:::demo
        DemoTrans["demo_transform.sh"]:::demo
        DemoOutputSmiles("demo_output_smiles.txt"):::data
        DemoSrc("demo_src.txt"):::data
        DemoTgt("demo_tgt.txt"):::data
        DemoNotebook["Usage_Example_of_ReactSeq.ipynb"]:::demo
    end

    %% Connections
    RawCSV -->|raw_train.csv/raw_val.csv/raw_test.csv| Preprocess
    Vocab -->|whole_vocabs.src| Preprocess
    Preprocess --> Processed
    PreprocessPrompt --> Processed
    Processed -->|src/tgt files| TrainPy
    ConfigTrain --> TrainPy
    TrainScript --> TrainPy
    TrainPy --> Checkpoints
    Checkpoints --> TranslatePy
    Processed --> TranslatePy
    InferenceScript --> TranslatePy
    TranslatePy --> Predictions
    Predictions --> Transform
    Transform --> PostPred
    PostPred --> EvalNotebook
    PostPred --> Embedding
    PostPred --> ELN
    Predictions --> DemoInfer
    DemoInfer --> DemoTrans
    DemoTrans --> DemoOutputSmiles
    DemoTrans --> DemoSrc
    DemoTrans --> DemoTgt
    DemoNotebook --> DemoInfer

    %% Click Events
    click RawCSV "https://github.com/jiachengxiong/reactseq/blob/main/datasets/50k_raw/raw_train.csv"
    click Vocab "https://github.com/jiachengxiong/reactseq/blob/main/datasets/vocabs/whole_vocabs.src"
    click Preprocess "https://github.com/jiachengxiong/reactseq/blob/main/preprocess_data.py"
    click PreprocessPrompt "https://github.com/jiachengxiong/reactseq/blob/main/preprocess_prompt_data.ipynb"
    click Processed "https://github.com/jiachengxiong/reactseq/tree/main/datasets/50k_ReactSeq/"
    click Processed "https://github.com/jiachengxiong/reactseq/tree/main/datasets/50k_ReactSeq_with_prompt/"
    click ConfigTrain "https://github.com/jiachengxiong/reactseq/blob/main/config/50k_ReactSeq_train_from_scracth.yml"
    click ConfigTrain "https://github.com/jiachengxiong/reactseq/blob/main/config/50k_ReactSeq_finetune.yml"
    click ConfigTrain "https://github.com/jiachengxiong/reactseq/blob/main/config/50k_ReactSeq_finetune_with_prompt.yml"
    click TrainPy "https://github.com/jiachengxiong/reactseq/blob/main/onmt/bin/train.py"
    click TrainScript "https://github.com/jiachengxiong/reactseq/blob/main/train.sh"
    click TrainScript "https://github.com/jiachengxiong/reactseq/blob/main/train_prompt.sh"
    click Checkpoints "https://github.com/jiachengxiong/reactseq/tree/main/checkpoints/"
    click TranslatePy "https://github.com/jiachengxiong/reactseq/blob/main/onmt/bin/translate.py"
    click InferenceScript "https://github.com/jiachengxiong/reactseq/blob/main/inference.sh"
    click InferenceScript "https://github.com/jiachengxiong/reactseq/blob/main/inference_with_prompt.sh"
    click Predictions "https://github.com/jiachengxiong/reactseq/blob/main/output/tgt_50k_ReactSeq_*.txt"
    click Transform "https://github.com/jiachengxiong/reactseq/blob/main/transform.py"
    click DemoTrans "https://github.com/jiachengxiong/reactseq/blob/main/demo_transform.sh"
    click PostPred "https://github.com/jiachengxiong/reactseq/blob/main/output/pred_reactants_50k_ReactSeq_*.txt"
    click EvalNotebook "https://github.com/jiachengxiong/reactseq/blob/main/cal_top_k_accuracy.ipynb"
    click Embedding "https://github.com/jiachengxiong/reactseq/blob/main/embedding/1_extract_emebddings.py"
    click Embedding "https://github.com/jiachengxiong/reactseq/blob/main/embedding/2_extract_edit_tokens_embedding.ipynb"
    click Embedding "https://github.com/jiachengxiong/reactseq/blob/main/embedding/3_visualize_and_calculate_metrics.ipynb"
    click ELN "https://github.com/jiachengxiong/reactseq/blob/main/ELN/ELN_condition_prediction.ipynb"
    click ELN "https://github.com/jiachengxiong/reactseq/blob/main/ELN/ELN_yield_prediction.ipynb"
    click DemoInfer "https://github.com/jiachengxiong/reactseq/blob/main/demo_inference.sh"
    click DemoOutputSmiles "https://github.com/jiachengxiong/reactseq/blob/main/demo_output_smiles.txt"
    click DemoSrc "https://github.com/jiachengxiong/reactseq/blob/main/demo_src.txt"
    click DemoTgt "https://github.com/jiachengxiong/reactseq/blob/main/demo_tgt.txt"
    click DemoNotebook "https://github.com/jiachengxiong/reactseq/blob/main/Usage_Example_of_ReactSeq.ipynb"

    %% Styles
    classDef data fill:#ADD8E6,stroke:#1E90FF,color:#000;
    classDef preproc fill:#B0E0E6,stroke:#5F9EA0,color:#000;
    classDef config fill:#90EE90,stroke:#3CB371,color:#000;
    classDef script fill:#98FB98,stroke:#2E8B57,color:#000;
    classDef checkpoint fill:#FFD700,stroke:#DAA520,color:#000,shape:cylinder;
    classDef post fill:#FFA500,stroke:#FF8C00,color:#000;
    classDef eval fill:#D8BFD8,stroke:#9370DB,color:#000;
    classDef demo fill:#DDA0DD,stroke:#BA55D3,color:#000;
```
