phenix_weight_scan.py Command Help

Command: $SCHRODINGER/run -FROM psp phenix_weight_scan.py

usage: $SCHRODINGER/run -FROM psp phenix_weight_scan.py <struct_file> <map_file> [options]

Perform a weight scan for Phenix/OPLS over given scan parameters.

Input structure and experimental map should be given. If experimental map is in MTZ, CIF and CV format phenix.refine is run and if experimental map is in CCP4, MAP and MRC phenix.real_space_refine is run with OPLS4 force field. Ligand ASL can be provided to calculate ligand correlation and ligand prime energy for the output, but does not affect the refinement.

Although this script can be performed to scan various multiple independent refinement options in a grid like fashion by taking their permutations, it is typically used to determine how heavily to weigh the experimental data versus the OPLS4 force field. Multiple weights are scanned and the best structure is chosen by looking at a number of validation metrics. If no scan options or weights are provided, 10 default weights are used. Default weights are: 0.01, 0.1, 0.5, 1, 2, 3, 4, 5, 10, 50. These weights set up -weight argument for phenix.real_space_refine and XYZ weights (-fix_wxc) for phenix.refine and will run 10 Phenix/OPLS jobs. These jobs can run in parallel if the number of cores are specified (e.g. -HOST localhost:10). If scan options or custom weights are provided, these default weights are ignored. When scan options are provided, the scan is performed over all permutations of the values.

The refinement options can be passed as -refine_options individually. These options can also be written to a file and this file can be passed to the script with -phenix_params_fn. If none of these options are provided, default refinement options are used. For default options and the parameters that can be passed phenix.[real_space_]refine --show_defaults can be used. Any of these options can be passed as -scan_options to perform a grid scan over them (when more than one value, seperated by comma, is given).

The output for each refinement job is written in the output directory as well as CSV file for refinement statistics for all runs. The best refinement run is picked by choosing the one with lowest Rfree by applying cut-offs to RamaZ, MolProbity and Rgap. The output structure from this run is saved with the extension of "optimal.mae". Correlation vs MolProbity and RamaZ plots are generated for the results. If ligand ASL is provided, Ligand Correlation vs Ligand Energy plot is also generated. For reciprocal space refinement, Rfree vs RamaZ, MolProbity, Rgap and Ligand correlation plots (if ligand ASL is given) are generated. The best refinement run is marked with red "x" in plots, whereas initial values are marked with green "+".

positional arguments:
  struct_fn             Structure file to refine.
  exp_data_fn           File containing experimental data to refine against.
                        Accepts mtz, cif and cv for phenix.refine and ccp4,
                        map and mrc for phenix.real_space_refine

options:
  -h, --help            show this help message and exit
  -v                    show program's version number and exit
  -jobname JOBNAME, -JOBNAME JOBNAME, -j JOBNAME
                        Set the base name of outputs

Phenix Refinement Options:
  -resolution RESOLUTION
                        Resolution of input CryoEM data. Only applicable for
                        real space refinement.
  -label LABEL          Label of reflection column in data file. Only
                        applicable for reciprocal space refinement. By default
                        several common values are searched for.
  -rfree_label RFREE_LABEL
                        Label of R-free column in data file. Only applicable
                        for reciprocal space refinement. By default several
                        common values are searched for.
  -prepwizard           Run prepwizard on input structure. Handy for large
                        scale testing.
  -refine_options REFINE_OPTIONS
                        Pass any keyword value pair to Phenix refine in the
                        form <keyword>=<value>.
  -phenix_params_fn PHENIX_PARAMS_FN
                        Parameter file containing Phenix options. Alternative
                        is giving key-value pairs using -refine_options.
  -remove_clashing_residues
                        Removes all residues (only side chains if sufficient
                        otherwise completely) that are near special positions
                        and are clashing with their crystal mates before
                        running phenix refine. Clashing waters are always
                        removed.

Weight Scan Options:
  -ligand_asl LIGAND_ASL
                        Ligand ASL. If given, correlation and energies are
                        also provided for ligand.
  -weights WEIGHTS      Weights to try during scan. Weights should be given as
                        comma-separated values,e.g. 1.0,2.0,3.0. For real
                        space refinement this sets the weight parameter, for
                        reciprocal space it sets the fix_wxc parameter:
                        default weights = [0.01, 0.1, 0.5, 1, 2, 3, 4, 5, 10,
                        50]
  -scan_options SCAN_OPTIONS
                        Pass any keyword value pair to Phenix to perform grid
                        scan over. Add additional options to scan over all
                        permutations. Values need to be comma separated, e.g.
                        -scan_options fix_wxc=1.0,2.0-scan_options strategy="i
                        ndividual_sites+individual_adp,individual_sites+tls."
  -noplot               Do not generate plot figures.
  -RESTART              Restart weight scan job from previously completed
                        refinement runs.
  -ignore_failures      Run analysis even if some refinement jobs fail.

Job Control Options:
  -HOST <hostname>      Run job remotely on the indicated host entry.
  -WAIT                 Do not return a prompt until the job completes.
  -D, -DEBUG            Show details of Job Control operation.
  -NOJOBID              Run the job directly, without Job Control layer.

Standard Options:
  -NJOBS NJOBS          Divide the overall job into NJOBS subjobs.
  -RETRIES RETRIES      If a subjob fails for any reason, it will be retried
                        RETRIES times. (Default: 2)
  -NOLAUNCH             Set up subjob inputs, but don't run the jobs.

Examples:
Weight scan with default weights for real space refinement (will run 10 phenix jobs):
$SCHRODINGER/run -FROM psp phenix_weight_scan.py structure.mae map.mrc -resolution 3.0

Weight scan with default weights for real space refinement (will run 10 phenix jobs in parallel)
$SCHRODINGER/run -FROM psp phenix_weight_scan.py structure.mae map.mrc -resolution 3.0 -HOST localhost:10

Weight scan with default weights for reciprocal space refinement (only xyz weights, will run 10 phenix jobs):
$SCHRODINGER/run -FROM psp phenix_weight_scan.py structure.mae map.mtz

Weight scan with ligand correlation and ligand energy calculation for real space refinement (will run 10 phenix jobs with default weights):
$SCHRODINGER/run -FROM psp phenix_weight_scan.py structure.mae map.mrc -resolution 3.0 -ligand_asl "res. LIG"

Weight scan with custom weights for real space refinement (will run 3 phenix jobs):
$SCHRODINGER/run -FROM psp phenix_weight_scan.py structure.mae map.mrc -resolution 3.0 -weights 0.1,0.5,1.0

Weight scan with custom weights for XYZ (fix_wxc) and ADP weights (fix_wxu) for reciprocal space refinement (will run 9 phenix jobs):
$SCHRODINGER/run -FROM psp phenix_weight_scan.py structure.mae map.mtz -scan_options fix_wxc=0.1,0.5,1.0 -scan_options fix_wxu=0.1,0.5,1.0

Weight scan with additional scan and refine options for real space refinement (will run 8 phenix jobs):
$SCHRODINGER/run -FROM psp phenix_weight_scan.py structure.mae map.mrc -resolution 3.0
-refine_options refinement.macro_cycles=1 -scan_options weight="1,3" -scan_options gradients_method="fd,linear"
-scan_options refinement.run="minimization_global+adp,minimization_global+rigid_body+local_grid_search+adp"

Weight scan with additional scan and refine options for reciprocal space refinement (will run 8 phenix jobs):
$SCHRODINGER/run -FROM psp phenix_weight_scan.py structure.mae map.mtz -ligand_asl "res. LIG"
-refine_options main.number_of_macro_cycles=1 -scan_option fix_wxc=0.1,0.5
-scan_option fix_wxu=0.001,0.01 -scan_option strategy="individual_sites+individual_adp,individual_sites+tls"

Restart weight scan from previously completed refinement runs in the same directory
(need to use the same weights and options with original run and will run remaining phenix jobs):
$SCHRODINGER/run -FROM psp phenix_weight_scan.py structure.mae map.map -resolution 3.0 -weights 1,2 -ligand_asl "res. LIG" -RESTART