Skip to Content
Getting Started

Getting Started

This guide covers installation, running your first pipeline, and understanding the output.

Prerequisites

  • Python 3.10+ — HEDGEHOG requires Python 3.10 or later.
  • uv — used for dependency management and running the CLI. Install from astral.sh/uv .

For the retrosynthesis (AiZynthFinder) part of the synthesis stage, you need the upstream aizynthfinder package and its public data. Use the built-in CLI setup command to install the optional dependency into the project environment and download the data into modules/aizynthfinder/.

Installation

Recommended: install from a source checkout.

# Clone the repository
git clone https://github.com/LigandPro/hedgehog.git
cd hedgehog
 
# Install HEDGEHOG and Python dependencies
uv sync

This is the supported path for the default sample configs, the setup helpers, and the TUI. The repository checkout includes the editable config files, bundled examples, and the modules/ workspace used by optional tool data installers.

Advanced: install from PyPI only if you plan to supply your own config and input paths instead of relying on the repository layout:

python -m pip install hedgehog
hedgehog --help

For full retrosynthesis runs, install AiZynthFinder after the base environment is working:

uv run hedgehog setup aizynthfinder

If you prefer on-demand installation of optional tools during a full pipeline run, use:

uv run hedgehog --auto-install

Legacy and manual fallback:

./modules/install_aizynthfinder.sh

First Safe Run

From a source checkout, start with the descriptor and structural filters smoke run. Use --force_new to write resilts to a new numbered output folder:

uv run hedgehog --stage descriptors --stage struct_filters --force-new

Or using the short alias:

uv run hedge --stage descriptors --stage struct_filters --force-new

This uses the default configuration at src/hedgehog/configs/config.yml and the test molecules in src/hedgehog/configs/examples/, but it avoids docking and retrosynthesis.

Full Pipeline Run

After the smoke run passes and optional tools are configured, run the full pipeline:

uv run hedgehog setup aizynthfinder
uv run hedgehog --auto-install

Full pipeline execution may require AiZynthFinder, GNINA, SMINA, and Matcha, valid receptor structures, reference ligands, and enough CPU and GPU resources.

If you installed from PyPI instead of cloning the repository, do not rely on this default sample workflow. Pass your own --config and input paths, or use a source checkout.

Note: the default config.yml contains absolute paths for optional external preparation tools for proteins and ligands. If you do not have these tools, set ligand_preparation_tool and/or protein_preparation_tool to empty values before your first run.

Input Data Contract

The recommended input format is a CSV or TSV file with a smiles header:

smiles,model_name
CCO,baseline
CCN,baseline
c1ccccc1,baseline

For multi-model comparisons, keep one row per molecule/model pair:

smiles,model_name
CCO,model_a
CCO,model_b
CCN,model_a
CCN,model_b

Required:

  • smiles

Optional:

  • model_name or name
  • mol_idx

Generated:

  • mol_idx is assigned automatically if missing.

Headerless .smi files are supported by extension for simple one-SMILES-per-line inputs, with an optional second whitespace token used as model_name. CSV/TSV with a smiles header remains the most explicit format for production runs.

Output structure

Results are saved to an auto-numbered directory under the configured output path (default: results/run_N/). Each run creates a new numbered folder unless you use the --reuse flag. Each stage directory contains a filtered_molecules.csv file with the molecules that passed that stage, along with any stage-specific outputs (plots, intermediate files).

The output directory structure:

results/run_N/
┌── configs/                        # Configuration snapshots
│   ├── master_config_resolved.yml
│   ├── config_*.yml
│   └── run_models_mapping.csv
├── input/
│   └── sampled_molecules.csv       # Input molecules (sampled)
├── output/
│   └── final_molecules.csv         # Final filtered molecules
├── stages/
│   ├── 01_mol_prep/                # Datamol-based standardization + strict filtering
│   ├── 02_descriptors_initial/     # Physicochemical descriptors
│   ├── 03_structural_filters_post/ # Post-descriptors structural filters
│   ├── 04_synthesis/               # Retrosynthesis analysis
│   ├── 05_docking/                 # Molecular docking (SMINA/GNINA/Matcha)
│   ├── 06_docking_filters/         # Post-docking pose & interaction filters
│   └── 07_descriptors_final/       # Final descriptor recalculation
├── report_data.json                # Report data
├── report.html                     # Interactive HTML report.
│                                     Primary deliverable for a browser-based overview
├── run_YYYYMMDD_HHMMSS.log         # Run logger
├── RUN_INFO.md                     # Run summary with MolEval metrics table
└── stage_filter_audit.ipynb        # Jupyter notebook for stage-by-stage molecule audit.
                                      Inspect passed or dropped molecules per stage in `mols2grid` and compare them 
                                      durig stages
Last updated on
IntroductionCLI Reference