digital-trial/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What This Is

Digital Trials is a Nextflow pipeline that simulates drug-protein interactions for digital clinical trials. Given a drug (as SMILES), it predicts metabolites, screens the drug and its metabolites against a proteome, performs pathway enrichment, and maps tissue distribution of interacting proteins.

Running the Pipeline

# Local test run (uses params defined in main.nf)
nextflow run main.nf

# With parameter file for cluster runs
nextflow run main.nf -params-file params/input_to_run.json

# Kubernetes via Tower
export TOWER_ACCESS_TOKEN=68358d90995ae27fe78b4c1818f9f0097d834b00
nextflow run main.nf -profile k8s -with-tower https://tower.stg.cluster.omic.ai/api -params-file params/input_to_run.json

Building Containers

# Build and tag individual containers via docker-compose
docker-compose build tissue
docker-compose build chembl
docker-compose build network

# Images push to harbor.cluster.omic.ai/omic/digitaltrials/

Each pipeline step has its own Dockerfile: Dockerfile_biotransformer, Dockerfile_conplex, Dockerfile_tissue, Dockerfile_chembl, Dockerfile_network.

Pipeline Architecture

The pipeline is orchestrated in main.nf (entry point and parameter definitions) and composed from three module files:

Stage 1: Metabolite Prediction (main_biotransformer.nf)

• HUMAN_TRANSFORMER — Runs BioTransformer (Java) to predict human metabolites from input SMILES. Only HUMAN mode is fully implemented.
• GET_FINAL_METABOLITES_STATIC — Filters to terminal metabolites (not precursors), checks against local ChEMBL SQLite DB and PubChem, outputs canonical SMILES list.

Stage 2: Proteome Screening (main_conplex.nf)

• PREPROCESS_PROTEIN — Merges patient FASTA files and projects them into a Zarr vector store (GPU, uses /app/project.py inside container).
• CONPLEX — Screens drug + metabolite SMILES against protein Zarr DBs using ConPLex model. Runs /app/convert.py, /app/screen.py, /app/get_round_2.py inside the metabolite-screen container. Outputs drug scores and significant interactions TSVs.
• NETWORK_ENRICHMENT — Queries STRING DB API for pathway enrichment and protein-protein interactions from significant hits.

Stage 3: Tissue & Biological Properties (main_tissue.nf)

• TISSUE_DISTRIBUTION — Maps interacting proteins to tissue expression using HPA data (drug_tissue_distribution.py).
• BIO_METRICS — Aggregates biological properties across metabolites, drug scores, and interactions (digital_patient_extract_metrics.py).

Data Flow

Input CSVs (SMILES+TARGET) → HUMAN_TRANSFORMER → GET_FINAL_METABOLITES_STATIC
                                                          ↓
Patient FASTA → PREPROCESS_PROTEIN → Zarr ──→ CONPLEX (drug + metabolites vs proteome)
Pre-built Zarr ─────────────────────────↗        ↓                    ↓
                                    NETWORK_ENRICHMENT    TISSUE_DISTRIBUTION
                                                          ↓
                                                      BIO_METRICS

Channels are joined by ligand ID (CSV simpleName), ensuring each drug's metabolites are matched to the correct ConPLex screening run.

Key Parameters (in main.nf)

Parameter	Purpose	Default
params.mode	BioTransformer mode — use HUMAN only	HUMAN
params.threshold	ConPLex binding score cutoff for significant interactions	0.65
params.protein_network_threshold	STRING DB enrichment cutoff	0.65
params.keep_enst	Keep per-protein Zarr results from ConPLex	false
params.ligands	Input directory of per-compound CSV files	—
params.mutated_protein_fasta	Directory of patient-specific FASTA files (or blank)	—
params.protein_zarr	Pre-built protein sequence Zarr DB	—
params.chembl_db	Path to ChEMBL SQLite database file	—
params.outdir	Output root directory	—
params.bt_initial_memory	Biotransformer starting memory (GB)	5
params.bt_growth_memory	Biotransformer additional memory per retry (GB)	15
params.bt_max_retries	Biotransformer max retry attempts	10
params.bt_fail_action	Biotransformer failure strategy: 'terminate' or 'ignore'	'terminate'
params.conplex_initial_memory	ConPLex starting memory (GB)	5
params.conplex_growth_memory	ConPLex additional memory per retry (GB)	15
params.conplex_max_retries	ConPLex max retry attempts	1
params.conplex_fail_action	ConPLex failure strategy: 'terminate' or 'ignore'	'ignore'

Nextflow Gotchas

• Params loaded from JSON are strings — use .toInteger() when used in resource directives (e.g., memory, maxRetries)
• main.nf defines all default param values; params files only need to override what they change

Sub-pipeline: Metabolite Screen Adaptive

nf_metabol_screen_adaptive/ is a standalone Nextflow pipeline for ConPLex-based metabolite screening. It has its own main.nf, test.nf, Dockerfile, and nextflow.config. Used for development/testing of the screening step independently.

Container Registry

All images are at harbor.cluster.omic.ai/omic/digitaltrials/. Container refs in main.nf use sha256 digests for reproducibility (except tissue which uses version tags). When updating containers, pin to a digest or explicit version tag.

Input Format

Per-compound .csv files named by identifier (e.g., InChIKey). 4-line key-value format:

SMILES
<SMILES string>
TARGET
<ENST transcript ID or empty>

Input directories are under /data/digital-trials-data/ (e.g., input_to_run/, input_knowen_target/, input_new/input/). See also /data/runs/docs/digital-trials-input-format.md for format details.

Output Structure

Results are organized under {outdir}/{project_name}/:

• 1_biotransformer/ — Raw metabolite predictions
• 1b_final_metabolites/ — Filtered terminal metabolites
• 2_conplex/ — Drug scores and significant interaction TSVs
• 3_string/ — Network enrichment and interaction TSVs
• 4_tissue_distribution/ — Tissue distribution and biological properties TSVs