tebuffer/ian-container repository overview

This container provides a self-contained, reproducible environment to execute the IAN R package, designed for systems-level interpretation of high-throughput omics data using a multi-agent Artificial Intelligence (AI) architecture. IAN integrates standard enrichment analyses (KEGG, WikiPathways, Reactome, GO, ChEA) and network data (STRING) to guide a Large Language Model (LLM) in generating insightful biological explanations, identifying key regulatory networks, and formulating novel hypotheses. This image abstracts away complex R package dependencies and LLM API configuration, allowing researchers to process Differential Gene Expression (DEG) lists quickly to produce comprehensive, grounded analysis reports, minimizing the risk of hallucination through a novel augmented prompt generation strategy.

Source Code & Detailed Documentation: https://github.com/NIH-NEI/IAN⁠

Preprint Publication: IAN: An Intelligent System for Omics Data Analysis and Discovery. https://www.biorxiv.org/content/10.1101/2025.03.06.640921v1.full.pdf⁠

⁠IAN: Intelligent System for Omics Analysis and Discovery (Containerized)

Image Tag: tebuffer/ian-container:v1.0

⁠🔬 Overview

IAN is a cutting-edge R package that harnesses the power of Multi-Agent Artificial Intelligence (AI) and Large Language Models (LLMs) to transform complex, high-throughput omics data into actionable biological insights.

This container provides a reproducible, dependency-free environment to run the complete IAN pipeline, simplifying the analysis workflow for researchers dealing with thousands of Differentially Expressed Genes (DEGs).

⁠Key Capabilities:

• Integrated Enrichment: Analyzes DEGs against KEGG, WikiPathways, Reactome, GO, ChEA, and STRING databases simultaneously.
• LLM Reasoning: Uses an LLM (defaulting to Google Gemini) via Augmented Prompt Generation (APG) to synthesize results, identify key regulators, and minimize hallucination.
• System Modeling: Generates a mechanistic system model and a comprehensive HTML report summarizing the findings.
• Reproducibility: Consistent results regardless of the host operating system environment.

⁠🚀 Quick Start Guide

This container is configured to run the input_type = "custom" workflow, requiring a single-column list of gene identifiers.

⁠⚠️ Important Note on Environment

This documentation and workflow have been tested specifically on macOS. Usage on Windows or Linux may require minor adjustments to path formats (e.g., using forward slashes instead of backslashes, or adjusting the home directory syntax).

⁠1. Prerequisites

Before starting, ensure you have the following on your local macOS machine:

1. Install & Start Docker Desktop:
   • Download and install Docker Desktop from the official website⁠.
   • Crucially, ensure Docker Desktop is running and active (the whale icon should be stable in your menu bar) before proceeding to the terminal. If you encounter rights issues, consult your IT department.
2. Create Workspace: Create a dedicated folder on your local machine that will serve as the workspace for all inputs and outputs. For these instructions, we refer to this folder as ~/ian-analysis.
3. Prepare Input Files: Place the following two required items inside your local ~/ian-analysis folder:
   • Your single-column DEG list (e.g., my_degs.txt) must be in your local workspace. Download example data: List of 180 genes significantly differentially expressed in Uveitis⁠. Original Publication: [Rosenbaum et al., 2021] (https://pmc.ncbi.nlm.nih.gov/articles/PMC8286715/⁠). This file MUST contain only one gene ID or symbol per line.
   • Your Google Gemini API Key file. The Google Gemini API Key must be saved in a file named api_keys.txt inside your local workspace. Obtain api-key following the instructions here: https://ai.google.dev/gemini-api/docs/api-key⁠ .

Note on Input Type: This container is configured to run using the input_type = "custom" mode. If your source data comes from DESeq2 or Seurat, you must first extract only the list of relevant gene IDs/symbols into the single-column file mentioned above.

⁠2. Pulling the Image

Open your Terminal application and use the following command to download the pre-built IAN container image:

docker pull tebuffer/ian-container:v1.0

⁠3. Running the Container

Use the following command in your Terminal to start the container. This command links your local workspace folder (~/ian-analysis) to the container's working space (/app) and starts an interactive BASH shell session inside the running container:

docker run -it --rm \
  -v ~/ian-analysis:/app \
  tebuffer/ian-container:v1.0 /bin/bash

⁠4. Execution Inside the Container (R Session)

After the previous command runs, your terminal prompt will change, indicating you are now inside the Docker container's terminal environment. Now, first start the R program in your containers terminal by simply typing the command R and hitting the return/enter key. When you are inside the R environment, run the following R commands sequentially within the R environment, which your just started in the container terminal:

# --- Setup ---
# Load the IAN package and enrichR library (R libraries are pre-installed)
library(IAN)
library(enrichR)

# Define paths relative to the container's /app directory (your mounted folder)
api_key_file <- "api_keys.txt"
deg_file_path <- "uveitis-PIIS0002939421000271-deg.txt" # Use the exact filename of your input file

# Define output directory (this folder will be created inside /app)
output_dir <- "IAN_results"

# Define the experimental design
experimental_design = "RNA-Seq data generated from peripheral, whole blood was used to identify differentially expressed genes between Uveitis patients and healthy controls."

# Call the main IAN function (must use input_type = "custom")
IAN(
  experimental_design = experimental_design,
  deg_file = deg_file_path, 
  gene_type = "ENSEMBL",  # IMPORTANT: Must match the ID type in your custom input file
  organism = "human",
  input_type = "custom",
  output_dir = output_dir,
  api_key_file = api_key_file,
  model = "gemini-2.5-flash-lite"
)

# Wait for the analysis to complete (this takes several minutes due to LLM calls).
# Once complete, your will see the R prompt back in your screen. Now can exit the R environment by running the quit() command and once you quit the R environment, exit the container by typing 'exit' and pressing Enter.

⁠5. Retrieving Results

All generated files, including the final HTML report, will be available in the IAN_results subdirectory within your original local folder (e.g., ~/ian-analysis/IAN_results/).

⁠📚 Resources & Attribution

This project is based on the IAN R Package.

• Source Code & Detailed Documentation: https://github.com/NIH-NEI/IAN⁠
• Preprint Publication: *IAN: An Intelligent System for Omics Data Analysis and Discovery https://www.biorxiv.org/content/10.1101/2025.03.06.640921v1.full.pdf⁠

Built by Vijayaraj Nagarajan PhD and collaborators at NEI/NIH.