How to Use mk_prepare_receptor for AutoDock Vina: Inputs, Output Files, and Reproducibility
Use mk_prepare_receptor to create AutoDock Vina receptor PDBQT and box files while documenting parsers, residue decisions, outputs, validation, and provenance.
Receptor preparation often appears to be a short conversion step between downloading a structure and running Vina. In practice, it is where the biological receptor hypothesis becomes executable input. The same coordinate file can produce different docking receptors depending on the selected assembly, chains, alternate locations, incomplete residues, hydrogens, cofactors, waters, metals, and flexible sidechains.
Meeko provides mk_prepare_receptor.py as its
command-line receptor-preparation interface. The official examples
show how to write a rigid receptor PDBQT and, optionally, the Vina
box files used by the next stage of the workflow [1,2]. This guide
focuses on what each input and output means, which decisions still
belong to the researcher, and what to retain so another person can
reproduce the preparation.
What mk_prepare_receptor does and does not do
The boundary between preparation and scientific judgment
| Task | What the command can provide | What the user must decide or verify |
|---|---|---|
| Read a structure | Parse PDB coordinates with RDKit or read PDB/mmCIF through ProDy | Correct biological assembly, model, chains, state, and source version |
| Parameterize the receptor | Assign an AutoDock-compatible receptor representation | Protonation assumptions, missing atoms, templates, nonstandard chemistry, and retained components |
| Write docking input | Generate rigid and, when requested, flexible receptor PDBQT files | Whether the represented atoms and flexible residues match the experiment |
| Define a search region | Write Vina box coordinates and a PDB visualization of the box | Whether the center and dimensions cover the intended site without unnecessary search volume |
| Report success | Return files, warnings, or errors | Scientific review of the resulting receptor and its suitability for the planned study |
Freeze the receptor hypothesis before running the command
Receptor preflight decisions
| Decision | Question to answer | Evidence to retain |
|---|---|---|
| Structure and assembly | Which experimental or predicted structure and biological assembly represent the target state? | Stable identifier, source URL, retrieval date, model, and assembly |
| Chains and residues | Which chains belong in the receptor, and are binding-site residues complete? | Included chains, construct boundaries, mutations, missing segments, and repairs |
| Alternate locations | Which conformer is supported at each relevant alternate location? | Selected altloc identifiers and rationale |
| Waters, metals, and cofactors | Which non-protein components are part of the binding hypothesis and compatible with the method? | Component-by-component retention or removal record |
| Hydrogens and state | Are hydrogen placement and residue states appropriate for the modeled conditions? | Preparation method, pH assumption, manual decisions, and exceptions |
| Search site | Is the box based on a reference ligand, known residues, or another declared source? | Center, size, padding, and the evidence used to define them |
Choose the input parser deliberately
RDKit and ProDy input routes
| Option | Documented behavior | Use it when |
|---|---|---|
--read_pdb receptor.pdb | Reads a PDB file with the RDKit PDB parser | The selected input is PDB and this parsing route is part of the recorded protocol |
-i receptor.pdb or --read_with_prody receptor.pdb | Reads PDB or mmCIF through ProDy | The workflow requires ProDy parsing or starts from mmCIF |
The two options are input routes, not interchangeable spellings. Meeko documents them separately [2,3]. Record the selected parser because parser behavior can affect how structural records become the molecular object that is subsequently parameterized.
mk_prepare_receptor.py \
--read_pdb receptor.pdb \
-o receptor \
-pIn the official basic-docking example, -o supplies
the output basename and -p requests PDBQT output [1].
The explicit alternative shown in the command reference is
-i examples/system.pdb --write_pdbqt prepared.pdbqt
[2]. Use one documented form consistently, preserve the complete
command, and do not rely on a filename alone to describe how the
receptor was created.
Generate the receptor and Vina box files together
mk_prepare_receptor.py \
--read_pdb receptor.pdb \
-o receptor \
-p -v \
--box_enveloping reference_ligand.sdf \
--padding 5Files that may be produced
| Output | Requested by | Role |
|---|---|---|
receptor.pdbqt | -p or --write_pdbqt | Rigid receptor input for a standard Vina run; flexible preparation can add separate rigid and flexible files |
receptor.box.txt | -v with box settings | Vina configuration containing the search-box center and size |
receptor.box.pdb | Box generation | PDB representation for visually checking the box in a molecular viewer |
| Parameterized receptor JSON | -j or --write_json | Meeko receptor representation useful for retaining preparation data and advanced workflows |
| AutoGrid GPF | -g or --write_gpf | Grid parameter file for workflows that require AutoGrid maps; standard Vina scoring does not require precomputed maps [3,4] |
Treat residue, template, and altloc options as scientific decisions
Consequential receptor-preparation options
| Option family | What it changes | Review requirement |
|---|---|---|
--set_template | Assigns a specific residue template to a selected residue | Confirm that the template represents the intended residue state and atom connectivity |
--delete_residues | Removes explicitly selected residues | List every deletion and verify that it does not remove required pocket chemistry |
--delete_bad_res | Deletes residues that fail template matching in current documentation | Inspect each omitted residue; command completion does not justify silent deletion |
--default_altloc and --wanted_altloc | Select alternate atom locations globally or for named residues | Preserve the selected conformers and the evidence behind them |
| Flexible-residue options | Move selected sidechains into a separate flexible receptor representation | Justify residue selection and account for the larger search problem |
Validate the generated receptor before running Vina
Output validation checklist
| Check | What to inspect | Failure signal |
|---|---|---|
| Execution record | Exit status, standard output, warnings, command, environment, and version | Ignored warnings, undocumented defaults, or an unrecoverable template mismatch |
| File set | Every expected PDBQT, JSON, box, or GPF file exists and is nonempty | Missing companion file or output basename collision |
| Receptor composition | Expected chains, residues, cofactors, metals, waters, and no unintended ligand remain | Unexpected atom-count change or missing binding-site component |
| Local geometry | Binding-site residues, hydrogens, alternate locations, missing atoms, and clashes | Broken residue, implausible placement, or unresolved alternate conformer |
| PDBQT representation | Atom types, charges, preserved coordinates, and rigid/flexible partition | Unrecognized chemistry or movable atoms duplicated in the rigid file |
| Search box | Visualize .box.pdb and compare center and size with the intended pocket | Reference ligand or critical pocket region lies outside the box |
| Traceability | Hashes or stable identifiers connect source, command, outputs, and downstream Vina job | The receptor cannot be linked unambiguously to its preparation record |
Start with the broader protein and ligand preparation guide, then use the PDBQT format guide to inspect the executable representation. If the receptor contains water, metal, or cofactor decisions, apply the receptor-component decision framework. Define and document the search region with the Vina grid-box guide.
Keep a re-executable preparation record
receptor_source:
identifier: PDB_ID_AND_ASSEMBLY
file: receptor.pdb
sha256: RECORD_THE_INPUT_HASH
preparation:
meeko_version: RECORD_EXACT_VERSION
parser: rdkit_pdb
command: mk_prepare_receptor.py --read_pdb receptor.pdb -o receptor -p -v --box_enveloping reference_ligand.sdf --padding 5
chains: [A]
altloc_decisions: RECORD_EXPLICIT_SELECTIONS
deleted_residues: []
retained_components: RECORD_WATERS_METALS_COFACTORS
outputs:
receptor_pdbqt_sha256: RECORD_HASH
box_txt_sha256: RECORD_HASH
box_pdb_sha256: RECORD_HASH
validation:
warnings_reviewed: true
receptor_visually_inspected: true
search_box_visually_inspected: trueA manifest turns receptor preparation from an undocumented file conversion into a reviewable method step. For an individual researcher, it reduces the chance of losing the command and box behind a result. For a laboratory, it creates a minimum handoff record that can be reviewed before screening resources are committed. The broader re-executable Vina reporting checklist carries that record through the rest of the study.
MolNexus 0.1.1 connects visible standard receptor and ligand preparation review, interaction-box setup, AutoDock Vina 1.2.7 execution with Vina or Vinardo, pose inspection, local history, and exports in one Windows workspace. It does not select the biologically correct receptor or prove that a prepared input is scientifically valid. Its value is making a standard workflow easier to inspect and retain when that scope fits the project.
References
- Meeko developers, Forli Lab at Scripps Research. Basic Docking Official Meeko documentation Official receptor-preparation examples, box generation, output files, and flexible-receptor workflow.
- Meeko developers, Forli Lab at Scripps Research. mk_prepare_receptor.py Official Meeko command-line documentation Official command syntax, PDBQT writing, input modes, and residue-selection examples.
- Meeko developers, Forli Lab at Scripps Research. Options of mk_prepare_receptor.py Official Meeko option reference Official parser, output, template, deletion, alternate-location, charge, and box option reference.
- AutoDock Vina developers, Forli Lab at Scripps Research. Basic Docking Official AutoDock Vina documentation Official receptor preparation, Vina configuration, search-box, and docking execution guidance.
- AutoDock Vina developers, Forli Lab at Scripps Research. Frequently Asked Questions Official AutoDock Vina documentation Official guidance on input preparation, hydrogens, file paths, and reproducibility considerations.