# kivancbayraktar/enhancing-ddi-classification-via-textual-arguments architecture

> Architecture diagram of the GitHub repository kivancbayraktar/enhancing-ddi-classification-via-textual-arguments, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kivancbayraktar/enhancing-ddi-classification-via-textual-arguments
- Repository: https://github.com/kivancbayraktar/enhancing-ddi-classification-via-textual-arguments

## Overview

##### Project type and purpose
- This is a machine-learning research pipeline (full-stack data-processing + modeling) for Drug-Drug Interaction (DDI) classification that leverages textual arguments from DrugBank, UMLS, and NER outputs. It orchestrates data ingestion, feature extraction (embeddings, similarity matrices), dataset preparation, and runs a sequence of deep‐neural‐network experiments, logging results via MLflow.

##### File structure
- colab_notebooks/: Jupyter notebooks that orchestrate each major step (data prep, embedding gen, experiments).
- drugbank/: Parser + processor modules for ingesting the DrugBank XML and building a local SQLite DB.
- ner/: Named-entity-recognition pipeline using cTAKES, producing .pkl outputs.
- embedding_configurations/: JSON defining embedding sources/parameters.
- experiment_configurations/: JSON configs for each experimental scenario, plus a models.py helper.
- research_datasets/: Modules and raw/index files for constructing train/validation/test splits for two datasets (DDI-MDL, MDF-SA-DDI).
- results/: Excel outputs for each experiment.
- name_rxcui.json: UMLS ID mapping for drugs.
- Configuration & dependency files: .gitignore, LICENSE, README.md.

##### README for additional insights
- Four major steps: build drugbank.db, run NER, generate embeddings, run experiments.
- Dependencies: Python, TensorFlow, Apache cTAKES, Transformers, SentenceTransformers, MLflow.
- Experiments driven by changing `experiment_configuration_file` in the notebook.

##### Detail
- Experimental scenario JSON appears as an input to the Experiment Runner.
- Optional paths (e.g., precomputed vs. regenerate embeddings, use existing NER output vs. rerun).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Data Sources
    DrugBankXML["DrugBank XML"]:::external
    RawText["Raw Biomedical Text"]:::external
    PreEmb["Precomputed Embeddings"]:::external
    nameMapping["name_rxcui.json"]:::external
    GitMeta[".gitignore<br/>LICENSE<br/>README.md"]:::external

    %% Data Ingestion
    Parser["drugbank_parser.py"]:::processing
    Processor["drugbank_processor.py"]:::processing
    EventExtractor["event_extractor.py"]:::processing
    DB["drugbank.db"]:::storage

    %% NER Pipeline
    CTakes["cTAKES Engine"]:::external
    NerModule["ner.py"]:::processing
    RunNER["run_ner.py"]:::processing
    NEROutput["ctakes_ner.pkl"]:::storage

    %% Feature Extraction
    EmbNotebook["embedding_generation.ipynb"]:::orchestrator
    EmbConfig["embeddings_config.json"]:::config
    FeatureMat["Feature Matrices"]:::storage

    %% Research Datasets
    subgraph "Research Datasets"
        subgraph "DDI-MDL"
            DDIBase["base.py"]:::processing
            DDIDataDB["event.db"]:::storage
            DDIIndexes["indexes/*.txt"]:::storage
        end
        subgraph "MDF-SA-DDI"
            MDFBase["base.py"]:::processing
            MDFCSV1["df_extraction_cleanxiaoyu50.csv"]:::storage
            MDFCSV2["drug_information_del_noDDIxiaoyu50.csv"]:::storage
            MDFIndexes["indexes/*.txt"]:::storage
        end
    end

    %% Experiment Runner
    ExpNotebook["experiments.ipynb"]:::orchestrator
    ExpCfg1["ddi-mdl/*.json"]:::config
    ExpCfg2["mdf-sa-ddi/*.json"]:::config
    ModelsHelper["models.py"]:::config

    %% Results
    ResultsDDI["results/DDIMDL/*.xlsx"]:::storage
    ResultsMDF["results/MDF-SA-DDI/*.xlsx"]:::storage

    %% Data Flow
    DrugBankXML --> Parser --> Processor --> EventExtractor --> DB
    RawText --> CTakes --> RunNER --> NEROutput
    DB --> EmbNotebook
    NEROutput --> EmbNotebook
    PreEmb --> EmbNotebook
    EmbConfig --> EmbNotebook
    EmbNotebook --> FeatureMat

    FeatureMat --> DDIBase
    FeatureMat --> MDFBase
    DB --> DDIBase
    DB --> MDFBase
    NEROutput --> DDIBase
    NEROutput --> MDFBase

    DDIBase --> ExpNotebook
    MDFBase --> ExpNotebook
    DDIDataDB --> DDIBase
    DDIIndexes --> DDIBase
    MDFCSV1 --> MDFBase
    MDFCSV2 --> MDFBase
    MDFIndexes --> MDFBase

    ExpCfg1 --> ExpNotebook
    ExpCfg2 --> ExpNotebook
    ModelsHelper --> ExpNotebook
    ExpNotebook --> ResultsDDI
    ExpNotebook --> ResultsMDF

    GitMeta

    %% Click Events
    click Parser "https://github.com/kivancbayraktar/enhancing-ddi-classification-via-textual-arguments/blob/main/drugbank/drugbank_parser.py"
    click Processor "https://github.com/kivancbayraktar/enhancing-ddi-classification-via-textual-arguments/blob/main/drugbank/drugbank_processor.py"
    click EventExtractor "https://github.com/kivancbayraktar/enhancing-ddi-classification-via-textual-arguments/blob/main/drugbank/event_extractor.py"
    click nameMapping "https://github.com/kivancbayraktar/enhancing-ddi-classification-via-textual-arguments/blob/main/name_rxcui.json"
    click NerModule "https://github.com/kivancbayraktar/enhancing-ddi-classification-via-textual-arguments/blob/main/ner/ner.py"
    click RunNER "https://github.com/kivancbayraktar/enhancing-ddi-classification-via-textual-arguments/blob/main/ner/run_ner.py"
    click NEROutput "https://github.com/kivancbayraktar/enhancing-ddi-classification-via-textual-arguments/blob/main/ner/output/ctakes/ctakes_ner.pkl"
    click EmbNotebook "https://github.com/kivancbayraktar/enhancing-ddi-classification-via-textual-arguments/blob/main/colab_notebooks/embedding_generation.ipynb"
    click EmbConfig "https://github.com/kivancbayraktar/enhancing-ddi-classification-via-textual-arguments/blob/main/embedding_configurations/embeddings_config.json"
    click DDIBase "https://github.com/kivancbayraktar/enhancing-ddi-classification-via-textual-arguments/blob/main/research_datasets/ddi_mdl/base.py"
    click DDIDataDB "https://github.com/kivancbayraktar/enhancing-ddi-classification-via-textual-arguments/blob/main/research_datasets/ddi_mdl/data/event.db"
    click DDIIndexes "https://github.com/kivancbayraktar/enhancing-ddi-classification-via-textual-arguments/blob/main/research_datasets/ddi_mdl/indexes/*.txt"
    click MDFBase "https://github.com/kivancbayraktar/enhancing-ddi-classification-via-textual-arguments/blob/main/research_datasets/mdf_sa_ddi/base.py"
    click ExpNotebook "https://github.com/kivancbayraktar/enhancing-ddi-classification-via-textual-arguments/blob/main/colab_notebooks/experiments.ipynb"
    click ExpCfg1 "https://github.com/kivancbayraktar/enhancing-ddi-classification-via-textual-arguments/blob/main/experiment_configurations/ddi-mdl/experiment_*.json"
    click ExpCfg2 "https://github.com/kivancbayraktar/enhancing-ddi-classification-via-textual-arguments/blob/main/experiment_configurations/mdf-sa-ddi/*.json"
    click ModelsHelper "https://github.com/kivancbayraktar/enhancing-ddi-classification-via-textual-arguments/blob/main/experiment_configurations/models.py"

    %% Styles
    classDef storage fill:#cce5ff,stroke:#0062cc,color:#004085;
    classDef processing fill:#d4edda,stroke:#155724,color:#155724;
    classDef orchestrator fill:#fff3cd,stroke:#856404,color:#856404;
    classDef config fill:#f5c6cb,stroke:#721c24,color:#721c24;
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
```
