mmtbx.command_line package

The command_line directory contains many common utilities as well as several relatively complex applications, including Xtriage, the core of MolProbity, phenix.maps, and phenix.table_one. Many of these tools have in common the same basic inputs and setup procedures. These are encapsulated in the top-level mmtbx.command_line module, and simplify the process of loading models and data to just a few lines of code for each new application.

API documentation

Generic wrapper for bootstrapping high-level applications which rely on some combination of model and data, with special attention to geometry restraints interpretation and f_model setup. All of the bookkeeping required to disambiguate crystal symmetry and Miller array conventions is performed automatically. This is superficially similar to the setup for phenix.refine (and re-uses many of the methods in mmtbx.utils), but is somewhat simpler (single-dataset only) and more general-purpose.

mmtbx.command_line.check_files(phil_scope, file_type, error_message)
mmtbx.command_line.generate_master_phil_with_inputs(phil_string, enable_twin_law=True, enable_automatic_twin_detection=False, enable_experimental_phases=False, enable_pdb_interpretation_params=False, enable_stop_for_unknowns=None, enable_full_geometry_params=False, enable_unmerged_data=False, enable_cdl=None, as_phil_string=False)

Generate a complete PHIL parameter block with generic input parameters plus user-specified options. The result is suitable for input for the class load_model_and_data. Depending on the target application, the exact input options can be adjusted.

Parameters:

  • phil_string – application-specific parameters

  • enable_twin_law – allow twinned f_model calculation

  • enable_automatic_twin_detection – allow automatic detection of twinning and setup of the f_model object

  • enable_experimental_phases – use Hendrickson-Lattman coefficients

  • enable_pdb_interpretation_params – show options for modifying the behavior of mmtbx.monomer_library.pdb_interpretation

  • enable_stop_for_unknowns – modify behavior of restraint interpretation when unknown atoms are encountered. Default is None; if True, the program will not raise an error; if False, the program will raise an error which may be suppressed by the user

  • enable_full_geometry_params – include parameters for specifying custom geometry resraints

  • enable_unmerged_data – accept separate unmerged intensities

  • enable_cdl – change default setting for conformation-dependent library

  • as_phil_string – return parameter string instead of PHIL object

Returns:

PHIL object (unless as_phil_string=True)

mmtbx.command_line.generic_simple_input_phil()

Generate minimal PHIL input string with no additional parameters.

mmtbx.command_line.load_and_validate_unmerged_data(f_obs, file_name, data_labels, log=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

Read in (and verify) unmerged intensities, e.g. from scalepack or XDS.

class mmtbx.command_line.load_model_and_data(args, master_phil, out=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, process_pdb_file=True, require_data=True, create_fmodel=True, prefer_anomalous=None, force_non_anomalous=False, set_wavelength_from_model_header=False, set_inelastic_form_factors=None, usage_string=None, create_log_buffer=False, remove_unknown_scatterers=False, generate_input_phil=False)

Bases: object

Class for processing command-line input and creating necessary objects. The master_phil object should include cmdline_input_phil_str above, plus any application-specific parameters. Programs which use this can be invoked using simple file arguments or explicit parameters, e.g.

mmtbx.some_program model.pdb data.mtz

This class performs the following functions (mostly using other wrappers elsewhere in mmtbx.utils):

  1. Process all arguments and extract as Python parameters

  2. Read in data and R-free flags

  3. Filter data and flags to be consistent if necessary

  4. Read in PDB file, either using the iotbx.pdb API, or if process_pdb_file is True, mmtbx.monomer_library.pdb_interpretation (using any CIF files included in the inputs)

  5. Extract the pdb_hierarchy and xray_structure objects.

  6. Create an mmtbx.f_model.manager object using the data, flags, and xray_structure.

If at any point the inputs are ambiguous, hopefully the program will stop and raise an interpretable error.

Parameters:

  • args (list of command-line arguments)

  • master_phil (PHIL master (can optionally be an unparsed string))

  • out (filehandle-like object)

  • process_pdb_file (run full restraints generation)

  • require_data (raise error if no experimental data supplied)

  • create_fmodel (setup mmtbx.f_model.manager object)

  • prefer_anomalous (preferentially use anomalous data if present)

  • force_non_anomalous (merge anomalous data if present)

  • set_wavelength_from_model_header (interpret PDB or mmCIF header to set experimental wavelength)

  • set_inelastic_form_factors (table to use (if any) for setting anomalous scattering form factors)

  • usage_string (console output for no arguments or --help)

  • create_log_buffer (store log output for later output to file)

  • remove_unknown_scatterers (delete atoms with scattering type 'X' (only used when process_pdb_file=False))

  • generate_input_phil (specifies that the master_phil object is a string containing onky the app-specific options, and automatically add the standard input parameters)

args
Type:

list of str

cif_file_names
Type:

libtbx.phil.scope_extract_list

cif_objects
Type:

list of …

crystal_symmetry
Type:

cctbx.crystal.symmetry

f_obs
Type:

cctbx.miller.array

fmodel
Type:

mmtbx.f_model.manager

geometry
Type:

cctbx.geometry_restraints.manager.manager

hl_coeffs
Type:

…

intensity_flag
Type:

bool

log
Type:

file

master_phil
Type:

libtbx.phil.scope

miller_arrays
Type:

list of cctbx.miller.array

params
Type:

libtbx.phil.scope_extract

pdb_file_names
Type:

libtbx.phil.scope_extract_list

pdb_hierarchy
Type:

iotbx.pdb.hierarchy.root

pdb_inp
Type:

iotbx.pdb.input

processed_pdb_file
Type:

mmtbx.monomer_library.pdb_interpretation.process

r_free_flags
Type:

cctbx.miller.array

raw_data
Type:

cctbx.miller.array

raw_flags
Type:

cctbx.miller.array

sequence
Type:

…

test_flag_value
Type:

int

unknown_residues_flag
Type:

bool

unknown_residues_error_message
Type:

str

unmerged_i_obs
Type:

…

working_phil
Type:

libtbx.phil.scope

xray_structure
Type:

cctbx.xray.structure.structure

Examples

>>> from mmtbx.command_line import load_model_and_data
>>> cmdline = load_model_and_data(
...  args=["model.pdb", "data.mtz"],
...  master_phil=master_phil,
...  prefer_anomalous=True,
...  set_wavelength_from_model_header=True,
...  set_inelastic_form_factors="sasaki",
...  )
>>> assert cmdline.pdb_hierarchy is not None
>>> assert cmdline.fmodel is not None
>>> assert cmdline.params.input.wavelength is not None
create_model_manager(log=None)

Instantiate an mmtbx.model.manager object with the current pdb hierarchy, xray structure, and geometry restraints. deprecated

save_data_mtz(file_name)

Write the processed amplitudes, optional Hendrickson-Lattman coefficients, and R-free flags to the designated MTZ file.

start_log_file(file_name)

Open a log file and write out the existing output buffer, returning the multi_out pseudo-filehandle.

Parameters:

file_name – log file to create

Returns:

libtbx.utils.multi_out object

mmtbx.command_line.show_symmetry_error(file1, file2, symm1, symm2)
mmtbx.command_line.validate_input_params(params)

Check for completeness of mandatory input parameters

A more complex example, which identifies suspect ligands based on electron density:

>>> master_phil = mmtbx.command_line.generate_master_phil_with_inputs(
...   enable_twin_law=True,
...   phil_string="""
...     hetatms_only = True
...       .type = bool
...     skip_single_atoms = True
...       .type = bool
...     min_acceptable_cc = 0.8
...       .type = float""")
...
>>> cmdline = mmtbx.command_line.load_model_and_data(
...  args=sys.argv[1:],
...  master_phil=master_phil,
...  out=sys.stdout,
...  process_pdb_file=True,
...  create_fmodel=True,
...  prefer_anomalous=False)
...
>>> log = cmdline.start_log_file("bad_ligands.log")
>>> params = cmdline.params
>>> bad_ligands = mmtbx.real_space_correlation.find_suspicious_residues(
...   fmodel=fmodel,
...   pdb_hierarchy=pdb_hierarchy,
...   hetatms_only=params.hetatms_only,
...   skip_single_atoms=params.skip_single_atoms,
...   min_acceptable_cc=params.min_acceptable_cc,
...   log=log)
...