phenix-tools-reference

name	phenix-tools-reference
description	Reference of available Phenix commands for structural biology analysis
category	domain

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

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

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

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

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

1. Start with phenix.molprobity for a quick quality overview.
2. Input files are relative to data/.
3. Pass CLI arguments as arguments={"flag": "value"}.
4. Avoid large refinement jobs that are likely to hit the 5-minute timeout.
5. Check phenix.pdbtools before writing custom PDB manipulation code.
6. Use phenix.pdb_as_cif or phenix.cif_as_pdb for format conversion.