Parameter Reference

Complete reference for every parameter in Hedgehog’s YAML configuration files.

config.yml

The main configuration file. Controls input/output paths, parallelism, and references to all stage-specific configs.

Target-based alignment is controlled directly by the master config:

target_mols_path: data/reference_molecules.csv
alignment:
  enabled: true
  target_coverage_percent: 95
  # descriptor_bounds_mode: expand  # keep source borders; widen only where targets need it
  # descriptor_bounds_mode: target  # replace each border with the target-derived value
  descriptor_bounds_mode: expand

When enabled, HEDGEHOG calculates numeric thresholds with respect to the target molecules before evaluating generated_mols_path. Structural hard filters are not percentile-calibrated. Descriptor alignment supports descriptor_bounds_mode: target, which replaces each configured descriptor border with the target-derived border, and descriptor_bounds_mode: expand, which applies min(source_min, target_min) and max(source_max, target_max). In expand, generic ZINC+ChEMBL descriptor envelopes are preserved and can only become wider. If descriptor_bounds_mode is omitted, expand is used. The target structural probe evaluates every calculate_* filter and every common-alert ruleset without removing molecules. Synthesis is skipped during target calibration and does not participate in target-cohort selection; the candidate uses the source synthesis config unchanged, including SA/RA/SYBA thresholds and retrosynthesis settings. The calibration probe may calculate every structural method for diagnostics, but the generated candidate config copies the source filter_* flags, Common Alerts enforcement lists, and structural parameters unchanged. Structural pass masks do not participate in target-cohort selection or the target_coverage_percent guarantee. structural_filter_failures.csv records every measured failure. Set enabled: false to use the stage configs without recalculation. --align-config PERCENT enables alignment and overrides target_coverage_percent for one run. Generated aligned master configs set alignment.enabled: false to prevent recalibration when reused, and add the target-run and threshold-audit paths as provenance. Each aligned stage config is created immediately after its alignable stage completes. Continuous thresholds use outward rounding, while integer-valued thresholds are rounded up.

config_mol_prep.yml

Preprocessing. Standardizes molecules before any descriptor computation. This stage aims to produce “clean” molecules by:

• removing salts and solvents and keeping the largest fragment
• disconnecting metals and normalizing/reionizing structures
• preserving formal charge by default (steps.standardize_mol.uncharge: false)
• preserving stereochemistry by default (steps.remove_stereochemistry: false)
• applying atom, radical, and single-fragment filters while retaining isotope labels

General Settings

config_descriptors.yml

Descriptors. Controls descriptor calculation and filtering borders. Plot presentation has code defaults and only needs configuration for custom reports.

General Settings

The descriptors stage always computes the complete descriptor table. When filter_data is true, configured filters are applied as follows:

• borders define generic descriptor ranges such as molWt, logP, TPSA, hbd, hba, n_rings, and fsp3.
• structural_constraints are converted into additional upper bound checks on derived descriptor columns.

Use borders for the production filtering contract. The optional legacy-compatible structural_constraints block can add motif caps when its own enabled field is true.

Optional Plot Overrides

Normally these fields should be omitted: plotted columns are derived from borders, while discrete-column metadata and labels come from code defaults (DESCRIPTOR_DISPLAY_NAMES and related constants in src/hedgehog/descriptors/constants.py). There is no YAML renamer.

Default borders are the ZINC250k + ChEMBL34 calibration envelope (q0.29–q99.71). See Descriptors.

config_structFilters.yml

Structural Filters. Calculates structural alerts and medicinal-chemistry diagnostics. calculate_<name> controls diagnostics; filter_<name> independently controls Stage 3 survival.

General Settings

Target-aware runs keep the complete generic structural gate. Alignment audits cannot change explicit filter_<name> flags. Any future target-specific relaxation must be an explicit, separately justified exception for a concrete hard rule. Scheduler settings such as lilly_scheduler remain execution controls.

Structural Filter Profiles

Three shipped configs share the same diagnostic calculations. Hard gates differ. The former balanced profile is removed.

Smoke on 20 MOSES molecules (results/profile_smoke_struct_filters/summary.csv): default 15/20, exploration 18/20, strict 0/20.

Prevalence evidence: results/zinc250_thresholds/iteration_24_structural_ruleset_prevalence/REPORT.md.

config_synthesis.yml

Synthesis Feasibility. Controls the retrosynthesis feasibility stage, including synthesizability score thresholds.

config_docking.yml

Docking. Controls molecular docking using SMINA, GNINA, Matcha, or any explicit combination of them. Defines the receptor, search box, and engine-specific parameters.

General Settings

SMINA Configuration (smina_config)

GNINA Configuration (gnina_config)

Matcha Configuration (matcha_config)

Default path is the official Matcha CLI (LigandPro/Matcha), checked out under modules/matcha_remote. Hedgehog runs uv run --project <checkout> matcha ....

Optional Matcha CLI knobs also accepted when set: n_confs, docking_batch_limit, num_workers, prefetch_factor, persistent_workers, gnina_batch_mode, scorer_path, config, run_name, repo_url.

The optional backend: docking path needs checkpoint_root and checkpoint_run (training config is always <checkpoint_root>/<checkpoint_run>/config.yaml). Prefer $HEDGEHOG_MATCHA_CHECKPOINT_ROOT in YAML instead of host absolute paths. Sampling/GPU knobs for that backend come from the docking repo itself, not from Hedgehog YAML.

When prepare_ligands is true, one input molecule may produce several prepared ligands. This can change row counts and downstream mapping. Keep it false for the default 1:1-oriented docking path unless you explicitly need an external preparation workflow.

config_docking_filters.yml

Three-Dimensional Filters. Stage 6 evaluates model-provided SDF coordinates by default and can additionally evaluate docked coordinates. Five independent filters can be combined with all (every filter must pass) or any (at least one must pass) aggregation.

General Settings

Aggregation

Pose Quality (pose_quality)

posecheck-fast only. Legacy PoseCheck keys (strain_forcefield, clash_tolerance) are not used.

Interactions (interactions)

Shepherd Score (shepherd_score)

Conformer Deviation (conformer_deviation)

Deduplication

Docking can produce multiple poses per molecule. After filtering, the pipeline deduplicates to unique molecules:

1. All passing poses are saved to filtered_poses.csv
2. Poses are sorted by affinity (best first)
3. For each unique mol_idx, only the best-scoring pose is kept
4. Deduplicated molecules are saved to filtered_molecules.csv

SMILES for the output are taken from the original ligand table rather than regenerated from 3D coordinates.

config_weighted_score.yml

Controls the post-run Generator Reality Assessment used by HTML reporting and RUN_INFO.md.

The scorecard is explainable and intended to rank generator behavior, not to estimate hit probability. It also reports a secondary Final Candidate Pool Quality score for the survivor set.

General Settings

Component Weights (weights)

Weights are normalized over all configured components before scoring. When one component is unavailable, it is simply excluded, and the effective average is recomputed from the remaining available components.

physchem is measured from stages/02_descriptors_initial/filtered/pass_flags.csv as an all pass descriptor gate rate, so it reflects the early generated set rather than the final survivor pool. The mean flag pass rate is retained as evidence only. structural uses the stage survival rate from filtered and failed molecules, with the weakest structural filter as supporting evidence. Final descriptor files are used only as a fallback for older or partial runs. synthesis and docking_pose similarly prefer full stage evaluation artifacts before filtered or final survivor files.

Secondary Candidate Pool Weights (candidate_pool_weights)

candidate_pool_weights control the secondary Final Candidate Pool Quality score. It keeps the older survivor-pool interpretation: final-count yield saturation, mean descriptor flag pass rate, mean structural flag pass rate, and the same synthesis/docking/diversity formulas.

Yield and Structural Settings

Hard Caps (hard_caps)

Hard caps prevent a model from receiving a high generator score when an early AND-gate rejects most molecules.

Docking Thresholds (docking)

Increase strictness by moving bad_* upward and good_* downward, or relax by widening the interval.

Synthesis Thresholds (synthesis)

Raise or lower these to bias toward faster/easier synthetic routes.

config_moleval.yml

Controls generative evaluation metrics computed during report generation. These metrics assess diversity, scaffold coverage, and basic filter pass rates across pipeline stages.

General Settings

Metric Groups

Each flag enables or disables a group of related metrics.