DOCSEARCHbyAlgolia
Submit Docs

PoseBusters Documentation

repository·main·Indexed 18 days ago

https://github.com/maabuu/posebusters

PoseBusters is a tool for performing plausibility checks on generated molecule poses to ensure they are physically valid. It identifies common failure modes in molecular modeling, including geometric validity (bond lengths, angles, steric clashes), stereochemistry preservation, receptor interaction (volume overlap), and chemical validity using RDKit and InChI. The library provides a Python API via the PoseBusters and DockBuster classes, as well as a CLI with the `bust` command for processing .sdf and .pdb files.

Tokens
6.2K
Snippets
21
Records
29
Agent score
61%

What's inside PoseBusters

  1. Overview of PoseBusters plausibility checks

    main

    PoseBusters evaluates the physical validity of 3D molecular poses. It identifies common failures in molecular conformation generators and docking programs, such as:

    • Steric clash: Detecting when a molecule is intertwined or atoms are clashing internally.
    • Aromatic rings flatness: Ensuring conjugated pi bond systems maintain appropriate flatness.
    • Volume overlap: Identifying clashes between the ligand and the receptor.
    • Other checks: Includes bond lengths, bond angles, tetrahedral stereochemistry, double bond stereochemistry, and energy ratios.

  2. How PoseBusters modules work

    main

    A PoseBusters module is a functional unit used to validate molecule poses.

    Inputs

    Modules accept one or more of the following as RDKit molecules:

    • mol_pred: The predicted molecule pose.
    • mol_true: The ground truth molecule pose.
    • mol_cond: The condition molecule (e.g., the protein/condensed phase).

    Any additional inputs must be parameters for which default values are specified.

    Outputs

    A module must return a dictionary containing:

    • A results key: This must be a dictionary where keys are test names and values are the test outcomes.
    • Other keys: Optional entries for additional data, such as bond lengths or bounds for all bonds in the ligand.

  3. Understand PoseBusters failure modes and geometric checks

    main

    PoseBusters evaluates the physical validity of molecular conformations, docking, and de-novo generation. It checks for several common failure modes in molecular modeling:

    Geometric Validity

    • Bond lengths: Ensures atoms are not too close or too far apart (e.g., preventing carbon-oxygen bonds from being too short).
    • Bond angles: Checks that bond angles are reasonable and atoms are not clashing.
    • Steric clash: Detects if a molecule is intertwined or if atoms are clashing internally.
    • High energy conformation: Identifies energetically unfavorable states, such as twisted rings.
    • Aromatic rings not flat: Ensures conjugated pi bond systems maintain a flat geometry.

    Stereochemistry Preservation

    • Tetrahedral stereochemistry: Verifies that chiral centers (e.g., oxygen orientation) are preserved.
    • Double bond stereochemistry: Ensures the correct cis/trans configuration of double bonds.

    Receptor Interaction

    • Volume overlap: Detects steric clashes between the ligand and the receptor binding pocket.

    Chemical Validity

    • RDKit Sanitisation: Molecules must pass standard RDKit chemical sanitisation checks.
    • InChI Interconvertibility: Molecules should be interconvertible with InChI strings.

  4. Quick start with the bust CLI

    main

    Use the bust command to perform plausibility checks on molecular poses. You can check individual molecules, docked ligands, or generated molecules conditioned on a protein.

    Common usage involves providing a target pose, a reference ligand (for re-docking checks), and a protein structure. You can control the verbosity of the output using the --outfmt flag.

    # Check a redocked ligand with short output format
bust redocked_ligand.sdf -l crystal_ligand.sdf -p protein.pdb --outfmt short

# Check a redocked ligand with long output format
bust redocked_ligand.sdf -l crystal_ligand.sdf -p protein.pdb --outfmt long

# Check a redocked ligand with CSV output format
bust redocked_ligand.sdf -l crystal_ligand.sdf -p protein.pdb --outfmt csv

  7. Configure PoseBusters via YAML files

    main

    PoseBusters searches for configuration parameters in posebusters.yml (or .cfg) files. Settings are merged based on a specific order of precedence, where higher-numbered items override lower-numbered ones.

    Search Order (Lowest to Highest Priority)

    1. System-wide: /etc/posebusters.cfg or c:\posebusters\posebusters.cfg
    2. User-wide: ~/.config/posebusters.cfg (via $XDG_CONFIG_HOME) or ~/.posebusters.cfg (via $HOME)
    3. Project-wide: posebusters.cfg located inside the current working directory.
    4. Explicit: A file path provided via the --config command line option.

    Note: User-defined values have higher priority than system-wide defaults, and project-wide settings (local directory) will override others when defined.

  8. How PoseBusters configuration and modules work

    main

    PoseBusters operates by iterating through a list of modules defined in your configuration. Each module entry in the config can specify:

    1. name: A custom name for the module's output columns.
    2. function: The name of the test function to execute (from the supported list).
    3. parameters: A dictionary of static parameters to pass to the function.
    4. rename_outputs: A mapping to rename specific output keys.
    5. rename_suffix: A suffix to append to output column names.
    6. chosen_binary_test_output: A list of specific output keys to include in the final report.

    Execution Flow:

    1. Initialization: PoseBusters loads the config and maps function names to actual Python callables using inspect.signature to determine which molecules (mol_pred, mol_true, mol_cond) are required for each test.
    2. Parallelization: Depending on max_workers and chunk_size, PoseBusters runs tests either in a single thread, parallelizing over files, or parallelizing over poses within files using a ProcessPoolExecutor.
    3. Module Execution: For each pose, the class loads the required molecules and calls the configured functions. If a required molecule for a specific test is missing (e.g., mol_true is required for rmsd but not provided), that test is skipped for that pose.
    4. Result Collection: Results are aggregated into a pandas.DataFrame where the index represents the file, molecule name, and pose position.

  10. Initialize the PoseBusters class

    main

    To use PoseBusters, instantiate the PoseBusters class. You can provide a configuration via a predefined mode string or a custom dictionary.

    Configuration Modes:

    • dock: Default configuration for docking tasks.
    • redock: Default configuration for re-docking tasks.
    • mol: Default configuration for molecule-only tasks.
    • gen: Default configuration for generation tasks.
    • regen: Default configuration for regeneration tasks.
    • *_fast variants: Faster versions of the above modes.

    Parallelization Settings:

    • top_n: Limits the number of poses processed. If None, all poses are processed.
    • max_workers: Controls parallelization. If None, all available cores are used. If 0 or negative, no parallelization is used.
    • chunk_size: Number of poses to process per process when using parallelization. Defaults to 100.
    from posebusters.posebusters import PoseBusters

# Using a predefined configuration mode
pb = PoseBusters(config="redock", top_n=10, max_workers=4)

# Or using a custom configuration dictionary
custom_config = {
    "modules": [
        {"name": "chemistry_check", "function": "sanity"}
    ]
}
pb = PoseBusters(config=custom_config)

  11. Use the PoseBusters class to run molecule tests

    main

    The PoseBusters class is the primary entry point for the library. It manages the collection of molecules to be tested, executes the selected validation modules, and aggregates the final test results.

    from posebusters import PoseBusters

# Initialize the PoseBusters runner
pb = PoseBusters()

# The class is used to collect molecules and run modules to report results

  12. Use the DockBuster Python API

    main

    The DockBuster class from the dockbusters module allows you to perform plausibility checks programmatically.

    • Re-docked ligand check: DockBuster().bust(ligand_pred_file, ligand_crystal_file, protein_crystal_file)
    • Docked ligand check: DockBuster().bust(ligand_pred_file, protein_crystal_file)
    • Molecule check: DockBuster().bust(ligand_pred_file, protein_crystal_file)
    from dockbusters import DockBuster

# check re-docked ligand
DockBuster().bust(ligand_pred_file, ligand_crystal_file, protein_crystal_file)

# check docked ligand
DockBuster().bust(ligand_pred_file, protein_crystal_file)

# check molecule
DockBuster().bust(ligand_pred_file, protein_crystal_file)