# nih-nei/ian architecture

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

- Interactive diagram: https://gitdiagram.com/nih-nei/ian
- Repository: https://github.com/nih-nei/ian

## Overview

##### Project type and purpose
- This is an R-package (named “IAN”) that implements a modular pipeline for integrated “omics” data analysis.
- It’s designed to take a list of differentially expressed genes (DEGs) as input, perform multiple enrichment and interaction analyses, leverage a multi-agent LLM system for interpretation, and produce interactive network visualizations and an HTML report.

##### File structure
Top-level files:
- DESCRIPTION, NAMESPACE: define the R package metadata and exports
- R/: contains the core R code, one .R file per logical module
- man/: auto-generated Rd documentation for every function and class
- inst/docs/: supplementary scripts (Python, grounding, evaluation), parameter guides, example data
- inst/rmd/: report template and styling (R Markdown)
Key patterns:
- Each R/IAN_*.R file represents a distinct processing stage (gene mapping, enrichment, prompt generation, network generation, visualization)
- There is a central orchestration module (IAN_multi_agent_system.R) that ties together sub-modules
- Deployment artifacts include rmarkdown templates and CSS for report generation

##### Extract architectural insights from the README
- Inputs: custom DEG lists or outputs from DESeq2/Seurat
- Enrichment backends: clusterProfiler (GO, Reactome, KEGG), enrichR (ChEA), STRINGdb for PPI
- Multi-agent LLM system: Google Gemini API with prompt generators and revision loops
- Outputs: visNetwork interactive graphs, HTML reports via rmarkdown

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Input Module
    subgraph "Input Module"
        InputDEG["User DEG File\n(inst/docs/uveitis-PIIS0002939421000271-deg.txt)"]:::processing
    end

    %% Pre-processing
    subgraph "Pre-processing"
        GeneMapper["IAN_gene_id_mapper.R"]:::processing
    end

    %% Enrichment Engines (Parallel)
    subgraph "Enrichment Engines"
        EnrichAnalysis["IAN_enrichment_analysis.R\n(GO, KEGG, Reactome, WP, ChEA, STRING)"]:::processing
        PathwayComp["IAN_pathway_comparison.R"]:::processing
    end

    %% Multi-Agent LLM Orchestrator
    subgraph "Multi-Agent LLM Orchestrator"
        Orchestrator["IAN_multi_agent_system.R"]:::llm
        LLMPrompts["IAN_llm_prompts.R"]:::llm
        SystemModelPrompt["IAN_system_model_prompt_generator.R"]:::llm
        NetworkPrompt["IAN_network_prompt_generator.R"]:::llm
        AgentClass["Agent (man/Agent.Rd)"]:::llm
        EnvClass["Environment (man/Environment.Rd)"]:::llm
        GoogleGemini["Google Gemini API"]:::external
    end

    %% Network Integration & Revision
    subgraph "Network Integration & Revision"
        CreateCombined["IAN_create_combined_prompt.R"]:::llm
        ReviseNetwork["IAN_network_prompt_generator.R"]:::llm
    end

    %% Visualization & Reporting
    subgraph "Visualization & Reporting"
        Visualize["IAN_visualize_system_model.R"]:::viz
        ReportTemplate["report_template.Rmd"]:::viz
        ReportStyle["styles.css"]:::viz
        FinalReport["HTML Report"]:::external
    end

    %% Supporting Scripts & Documentation
    subgraph "Supporting Scripts & Docs"
        Grounding["ground.R"]:::external
        EvalPlots["human-evaluation-plots.R"]:::external
        AnalysisGuide["analysis_instructions.md"]:::external
        AnalysisParams["analysis_parameters.md"]:::external
        ExamplePy["bert-similarity.py"]:::external
        GeneMapExample["gene-mapping-example.R"]:::external
    end

    %% Connections
    InputDEG -->|reads| GeneMapper
    GeneMapper -->|maps IDs| EnrichAnalysis
    GeneMapper -->|maps IDs| PathwayComp
    EnrichAnalysis -->|enrichment results| Orchestrator
    PathwayComp -->|comparison results| Orchestrator
    Orchestrator -->|generate prompts| LLMPrompts
    Orchestrator -->|system model prompt| SystemModelPrompt
    Orchestrator -->|network prompt| NetworkPrompt
    LLMPrompts --> AgentClass
    LLMPrompts --> EnvClass
    Orchestrator -->|API calls| GoogleGemini
    GoogleGemini -->|responses| Orchestrator
    Orchestrator -->|combine networks| CreateCombined
    CreateCombined --> ReviseNetwork
    ReviseNetwork --> Visualize
    Visualize -->|embeds| ReportTemplate
    ReportTemplate -->|uses| ReportStyle
    ReportTemplate --> FinalReport

    %% Click Events
    click InputDEG "https://github.com/nih-nei/ian/blob/main/inst/docs/uveitis-PIIS0002939421000271-deg.txt"
    click GeneMapper "https://github.com/nih-nei/ian/blob/main/R/IAN_gene_id_mapper.R"
    click EnrichAnalysis "https://github.com/nih-nei/ian/blob/main/R/IAN_enrichment_analysis.R"
    click PathwayComp "https://github.com/nih-nei/ian/blob/main/R/IAN_pathway_comparison.R"
    click Orchestrator "https://github.com/nih-nei/ian/blob/main/R/IAN_multi_agent_system.R"
    click LLMPrompts "https://github.com/nih-nei/ian/blob/main/R/IAN_llm_prompts.R"
    click SystemModelPrompt "https://github.com/nih-nei/ian/blob/main/R/IAN_system_model_prompt_generator.R"
    click NetworkPrompt "https://github.com/nih-nei/ian/blob/main/R/IAN_network_prompt_generator.R"
    click AgentClass "https://github.com/nih-nei/ian/blob/main/man/Agent.Rd"
    click EnvClass "https://github.com/nih-nei/ian/blob/main/man/Environment.Rd"
    click CreateCombined "https://github.com/nih-nei/ian/blob/main/R/IAN_create_combined_prompt.R"
    click ReviseNetwork "https://github.com/nih-nei/ian/blob/main/R/IAN_network_prompt_generator.R"
    click Visualize "https://github.com/nih-nei/ian/blob/main/R/IAN_visualize_system_model.R"
    click ReportTemplate "https://github.com/nih-nei/ian/blob/main/inst/rmd/report_template.Rmd"
    click ReportStyle "https://github.com/nih-nei/ian/blob/main/inst/rmd/styles.css"
    click Grounding "https://github.com/nih-nei/ian/blob/main/inst/docs/ground.R"
    click EvalPlots "https://github.com/nih-nei/ian/blob/main/inst/docs/human-evaluation-plots.R"
    click AnalysisGuide "https://github.com/nih-nei/ian/blob/main/inst/docs/analysis_instructions.md"
    click AnalysisParams "https://github.com/nih-nei/ian/blob/main/inst/docs/analysis_parameters.md"
    click ExamplePy "https://github.com/nih-nei/ian/blob/main/inst/docs/bert-similarity.py"
    click GeneMapExample "https://github.com/nih-nei/ian/blob/main/inst/docs/gene-mapping-example.R"

    %% Styles
    classDef processing fill:#9ad,stroke:#333,stroke-width:1px
    classDef llm fill:#9f9,stroke:#333,stroke-width:1px
    classDef viz fill:#ff9,stroke:#333,stroke-width:1px
    classDef external fill:#ccc,stroke:#333,stroke-width:1px
```
