Phenix Tools Reference
If Phenix is available, prefer run_phenix_tool over execute_code for structural biology tasks like validation, superposition, refinement, and map analysis. Phenix is the gold standard for these tasks.
Call run_phenix_tool(tool_name="phenix.<command>", input_files=["file.pdb"], description="..."). This reference lists the most useful commands grouped by task. Most commands accept PDB or mmCIF files, but some take map files, reflection data, sequences, or other formats — check each tool's --help if you are unsure.
Validation and Quality Assessment
| Command | Purpose | |
|---|
phenix.molprobity | Comprehensive validation: Ramachandran, rotamers, clashes, C-beta deviations; the single best overall quality check | |
phenix.clashscore | All-atom steric clash analysis | |
phenix.ramalyze | Ramachandran backbone analysis | |
phenix.rotalyze | Side-chain rotamer analysis | |
phenix.cablam | C-alpha based backbone validation | |
phenix.cbetadev | C-beta deviation analysis | |
phenix.omegalyze | Cis/trans peptide bond validation | |
phenix.model_vs_data | Model versus diffraction data statistics | |
phenix.model_statistics | Summary geometry statistics for a model | |
phenix.emringer | Map-model validation for cryo-EM structures | |
phenix.validation_cryoem | Comprehensive cryo-EM validation | |
phenix.undowser_validation | Check waters for clashes and poor contacts | |
phenix.clashscore2 | Updated all-atom clash score (prefer over clashscore when available; slightly different scoring) | |
phenix.undowser2_validation | Updated water validation (same relationship to undowser_validation as above) | |
phenix.holton_geometry_validation | Holton-method geometry validation — complementary signal to molprobity; useful for second-opinion checks | |
Example: Full validation
python
run_phenix_tool(
tool_name="phenix.molprobity",
input_files=["structure.pdb"],
description="Comprehensive structure quality check",
)
Structure Comparison and Superposition
| Command | Purpose | |
|---|
phenix.superpose_pdbs | Superpose two structures and report RMSD | |
phenix.chain_comparison | Chain-level comparison between structures | |
phenix.structure_comparison | Broader structural comparison | |
phenix.model_model_distances | Per-residue distance between two models | |
phenix.superpose_and_morph | Superpose and morph one structure onto another | |
phenix.superpose_models | Superpose with optional morphing and trimming (more flexible variant of superpose_and_morph) | |
phenix.find_reference | Find reference models (e.g., homologs in the PDB) for a supplied model | |
Example: Per-residue distances
python
run_phenix_tool(
tool_name="phenix.model_model_distances",
input_files=["experimental.pdb", "predicted.pdb"],
description="Per-residue distances between experimental and predicted",
)
AlphaFold and Predicted Models
| Command | Purpose | |
|---|
phenix.process_predicted_model | Process AlphaFold or predicted structures | |
phenix.dock_predicted_model | Dock a predicted model into a cryo-EM map | |
Example: Process AlphaFold model
python
run_phenix_tool(
tool_name="phenix.process_predicted_model",
input_files=["alphafold_model.pdb"],
arguments={"pae_json_file_name": "alphafold_pae.json"},
description="Process AlphaFold model and trim low-confidence regions",
)
Refinement
| Command | Purpose | |
|---|
phenix.refine | Reciprocal-space refinement against diffraction data | |
phenix.real_space_refine | Real-space refinement, primarily for cryo-EM | |
phenix.geometry_minimization | Energy minimization without data | |
phenix.dynamics | Molecular dynamics refinement | |
phenix.fit_h | Fit hydrogen positions with rotational DOF into a map (use after phenix.reduce when H positions matter for interpretation) | |
phenix.rocket | Wrapper for ROCKET refinement (external tool — see rocket-9.gitbook.io for docs) | |
phenix.aquaref | Quantum-mechanical (QM) refinement via qr.refine — specialized; only use when QM restraints are specifically required | |
phenix.mopac | Semiempirical QM refinement via MOPAC — specialized. Prefer phenix.refine (X-ray) or phenix.real_space_refine (cryo-EM) unless the task explicitly asks for QM | |
phenix.magref | Magnetic / spin-dependent refinement — specialized; only for data with magnetic scattering | |
phenix.TAAM_minus_IAM | Difference between Transferable Aspherical Atom Model and Independent Atom Model refinements — specialized, for ultra-high-resolution data only | |
Refinement commands are compute-intensive and may approach the 5-minute timeout. Use targeted refinement when possible. The last four rows above are narrow-use — do not invoke unless the task explicitly calls for QM/magnetic/aspherical refinement.
Map Operations
| Command | Purpose | |
|---|
phenix.maps | Compute electron density map coefficients | |
phenix.map_box | Extract map region around a model | |
phenix.map_model_cc | Map-model correlation coefficient | |
phenix.map_correlations | Correlation between two maps, or map vs model (use when comparing maps to each other — map_model_cc is map-vs-model only) | |
phenix.map_sharpening | Map sharpening via scale-factor optimization (newer, more flexible than auto_sharpen; supports half-maps and model-guided modes) | |
phenix.reduce_cryoem_resolution | Artificially limit cryo-EM half-maps to a target resolution (for testing resolution dependence) | |
phenix.mtriage | Cryo-EM map analysis | |
phenix.local_resolution | Local resolution estimation | |
phenix.auto_sharpen | Map sharpening | |
phenix.map_to_model | Build atomic model from a cryo-EM map | |
phenix.dock_in_map | Dock a model into a map | |
phenix.segment_and_split_map | Segment map into domains | |
Model Building and Manipulation
| Command | Purpose | |
|---|
phenix.autobuild | Automated model building into density | |
phenix.fit_loops | Fit or rebuild loop regions | |
phenix.pdbtools | PDB manipulation, including selections and B-factor edits | |
phenix.reduce | Add hydrogens to a structure | |
phenix.ready_set | Add hydrogens and generate ligand restraints | |
phenix.find_helices_strands | Identify secondary structure elements | |
phenix.analyze_alt_conf | Analyze alternate conformations in a model; can compare against another model | |
phenix.create_alt_conf | Generate alternate conformations from a single-conformation starting model and data | |
phenix.merge_models_as_alt_conf | Combine several models with identical hierarchies into one multi-conformer model | |
Example: Extract a single chain
python
run_phenix_tool(
tool_name="phenix.pdbtools",
input_files=["multimer.pdb"],
arguments={"selection": '"chain A"', "output.file_name": "chain_A.pdb"},
description="Extract chain A from multimer",
)
Ligand Tools
| Command | Purpose | |
|---|
phenix.elbow | Generate ligand geometry and restraints | |
phenix.ligandfit | Fit a ligand into electron density | |
phenix.ligand_identification | Identify unknown ligand density | |
phenix.find_all_ligands | Find all ligand binding sites | |
Data Analysis
| Command | Purpose | |
|---|
phenix.xtriage | Diffraction data analysis | |
phenix.merging_statistics | Data merging statistics | |
phenix.french_wilson | French-Wilson scaling | |
phenix.cif_as_mtz / phenix.mtz_as_cif | Reflection file format conversion | |
phenix.pdb_as_cif / phenix.cif_as_pdb | Model file format conversion | |
Molecular Replacement
| Command | Purpose | |
|---|
phenix.phaser | Molecular replacement | |
phenix.ensembler | Prepare search ensembles for molecular replacement | |
phenix.sculptor | Edit search models for molecular replacement | |
phenix.mr_model_preparation | Prepare molecular replacement search models | |
Sequence and Annotation
| Command | Purpose | |
|---|
phenix.print_sequence | Extract sequence from PDB | |
phenix.assign_sequence | Assign a sequence to a model using a map and sequence file | |
phenix.fetch_pdb | Download PDB entries by ID | |
Useful Utilities
| Command | Purpose | |
|---|
phenix.b_factor_statistics | B-factor distribution analysis | |
phenix.find_ncs | Detect non-crystallographic symmetry | |
phenix.hbond | Hydrogen bond analysis | |
phenix.table_one | Generate publication-ready Table 1 statistics | |
Tips for Using run_phenix_tool
- Start with
phenix.molprobity for a quick quality overview. - Input files are relative to
data/. - Pass CLI arguments as
arguments={"flag": "value"}. - Avoid large refinement jobs that are likely to hit the 5-minute timeout.
- Check
phenix.pdbtools before writing custom PDB manipulation code. - Use
phenix.pdb_as_cif or phenix.cif_as_pdb for format conversion.