Skip to content

quickstart.md

Latest commit

 

History

History
218 lines (154 loc) · 5.89 KB

quickstart.md

File metadata and controls

218 lines (154 loc) · 5.89 KB
Raw

Quickstart Guide

BioAgentFlow 快速入门指南

This guide walks you through installing BioAgentFlow, running your first virtual screening job, and interpreting the output.

Table of Contents

  1. Prerequisites
  2. Installation
  3. Your First Screen
  4. Understanding the Output
  5. Using the Web UI
  6. Next Steps

Prerequisites

Requirement Minimum Notes
Python 3.10+ 3.11 or 3.12 recommended
pip 22+ pip install --upgrade pip
OS Linux, macOS, Windows (WSL2) Native Windows support is experimental
RAM 8 GB 16 GB recommended for larger libraries
GPU Not required Optional; speeds up ESMFold and DiffDock
Docker 20.10+ Only if using Docker installation

Note: 基本虚拟筛选无需 GPU，普通笔记本即可运行。

Installation

Choose one of the three methods below.

Option A: pip (Recommended)

pip install bioagentflow

Verify the installation:

bioagentflow --version

Option B: Docker

docker pull bioagentflow/bioagentflow:latest
docker run --rm bioagentflow/bioagentflow:latest bioagentflow --version

Option C: From Source

git clone https://github.com/BioAgentFlow/BioAgentFlow.git
cd BioAgentFlow
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
bioagentflow --version

Your First Screen

We will screen the human carbonic anhydrase II protein (UniProt: P00918) against a small subset of ZINC15 compounds.

Step 1 -- Create a Configuration File

Create a file called quickstart.yaml:

# quickstart.yaml -- minimal BioAgentFlow configuration
target:
  source: uniprot
  id: P00918                    # Human carbonic anhydrase II

structure:
  method: alphafold             # Fetch from AlphaFold DB (no prediction needed)

ligands:
  source: zinc15
  subset: fda-approved          # Small set for a quick test
  max_compounds: 50

docking:
  engine: diffdock
  num_poses: 5

filtering:
  rules:
    - lipinski
    - veber

output:
  directory: ./results
  formats:
    - csv
    - html

Step 2 -- Run the Pipeline

bioagentflow screen --config quickstart.yaml

You will see progress output for each pipeline stage:

[1/6] Target Discovery    ... P00918 (Carbonic anhydrase 2) found     ✔
[2/6] Structure            ... fetched from AlphaFold DB               ✔
[3/6] Ligand Preparation   ... 50 compounds retrieved from ZINC15      ✔
[4/6] Docking              ... 250 poses generated (50 × 5)            ✔
[5/6] Scoring              ... ranked by DiffDock confidence            ✔
[6/6] Filtering            ... 12 compounds passed Lipinski + Veber    ✔

Report saved to ./results/

Step 3 -- Review Results

The results/ directory now contains:

results/
├── docking_scores.csv      # All 50 compounds with scores
├── filtered_hits.csv       # 12 compounds that passed ADMET filters
├── report.html             # Human-readable HTML report
├── structures/             # Docked pose PDB files
│   ├── ZINC000003986735_pose1.pdb
│   └── ...
└── metadata.json           # Run parameters and timing

Understanding the Output

docking_scores.csv

Column Description
compound_id ZINC or ChEMBL identifier (化合物编号)
smiles Canonical SMILES string
score DiffDock confidence score (higher is better)
pose_rank Rank of this pose among multiple poses for the same compound
mw Molecular weight (分子量)
logp Predicted octanol-water partition coefficient
hbd Hydrogen bond donors
hba Hydrogen bond acceptors
tpsa Topological polar surface area
rotatable_bonds Number of rotatable bonds (可旋转键数)

filtered_hits.csv

Same columns as above, but only rows that satisfy all active filter rules. An additional column pass_rules lists which rules each compound satisfied.

report.html

An interactive HTML page with:

  • Summary statistics for the run
  • Sortable table of top hits
  • 2D compound structure images
  • Filter rule pass/fail breakdown

metadata.json

Machine-readable record of all run parameters, software versions, data source timestamps, and wall-clock timing per stage. Useful for reproducibility.

Using the Web UI

For interactive exploration, launch the Streamlit dashboard:

bioagentflow ui

This opens a browser at http://localhost:8501 where you can:

  1. Configure a screening run using form inputs instead of YAML.
  2. Monitor pipeline progress in real time.
  3. Explore results with sortable tables and interactive charts.
  4. Adjust filter thresholds and see the hit list update immediately.
  5. Export filtered results to CSV or SDF.

To load previous results without re-running:

bioagentflow ui --results ./results

Next Steps

Now that you have completed your first screen, consider exploring:

  • Larger compound libraries -- remove the max_compounds limit or switch to the full zinc15 or chembl source.
  • Structure prediction -- set structure.method: esmfold to predict a structure from sequence when no experimental or AlphaFold structure is available.
  • Custom filters -- add your own ADMET rules by writing a filter plugin (see Architecture).
  • Batch screening -- pass a CSV of multiple target IDs with bioagentflow screen --targets targets.csv.
  • Python API -- integrate BioAgentFlow into your own scripts for programmatic access (see examples in the README).

For deeper technical details, see the Architecture Document.

如有问题，请在 GitHub 上提交 Issue 或参与 Discussion。祝筛选顺利！