Function Reference

Conversions

Functions used during data preparation to convert phase information which is collected from experiments to maps which can then be sliced into 2d images for training.

High Level Functions

topaz3.conversions.files_to_map(phase_filename: str, cell_info_filename: str, space_group_filename: str, xyz_limits: Tuple[int, int, int], output_filename: str)

Extract information from files before running the phase to map conversion.

Checks phase file provided for bad values and amends if necesary with phase_remove_bad_values

Parameters:
  • phase_filename – phase file to convert to map
  • cell_info_filename – file with cell info, normally .mtz
  • space_group_filename – file with space group information, can be .mtz or other (.log, .txt, etc)
  • xyz_limits – x, y, z, size of the map output
  • output_filename – absolute path for the map output file. This will be used to generate temporary file names for the intermediate files
Returns:

True
topaz3.conversions.phase_to_map()

Convert a phase file to a regularised map file with dimensions x, y, z using the space group and cell info provided.

Parameters:
  • phase_filename – input phase file to check for bad values
  • cell_info – list of 6 floating point values with cell information
  • space_group – space group for structure, e.g “P212121”
  • xyz_limits – x, y, z, size of the map output
  • output_filename – absolute path for the map output file
Returns:

True
topaz3.conversions.phase_remove_bad_values(phase_filename: str, output_filename: str) → str

Inspects a phase file looking for lines with **** values which represent bad data. If these lines are found, remove and write a temporary phase file out. Returns the filepath of the temporary file created, otherwise returns the original filepath

Parameters:
  • phase_filename – input phase file to check for bad values
  • output_filename – file to store filtered output in if necessary
Returns:

path of file with good values in

Train Test Split Tool

This is a helpful tool to randomly select a number of files or subdirectories as test objects and remove them from your main directory.

Get help with the command line interface by using:

topaz3.train_test_split.test_split_directory()

Move files or directories from input dir to output dir to separate training and test information.

Looks for all files in the input directory, checks they are all of the same type. This means either all directories, or all files with the same file extension. Randomly selects split_percent % of them to be moved to the output directory. Random number generator is seeded so this is a deterministic translation.

Copies selected files to output directory then deletes. This ensures that all copying is completed before any deletion takes place. If there is an error during copying then function can be ran again with same parameters (once error is fixed).

If the input directory contains subdirectories, they will be moved recursively.

Returns a tuple of the new file locations.

Parameters:
  • input_directory – directory to randomly select from
  • split_percent – percentage (0-100) of files to move
  • output_directory – new location for selected files
Returns:

tuple of new file locations

Low Level Functions

The processing of the phase file is broken up into 3 sections:

  • transforming the phase file to an mtz file
  • transforming the mtz file to a map file
  • transforming the map to a map which is equal in x, y, z dimensions

The api for these functions is listed below, please note that they all use the Shell Scripts.

topaz3.conversions.phs_to_mtz()
Use the CCP4 f2mtz utility to convert a phase file into a .mtz file
and return the mtz file location.
Parameters:
  • phase_filename – input phase file to be transformed
  • cell_info – list of 6 floating point values with cell information
  • space_group – space group for structure, e.g “P212121”
  • output_filename – absolute path for the mtz output file
Returns:

location of the mtz file
topaz3.conversions.mtz_to_map(mtz_filename, output_filename)

Convert .mtz file to map using CCP4 cfft utility and return the new output map location.

Parameters:
  • mtz_filename – input mtz file
  • output_filename – absolute path for the mtz output file
Returns:

location of the mtz file
topaz3.conversions.map_to_map(map_filename: str, xyz_limits: Tuple[int, int, int], space_group: str, output_filename: str)

Converts a map file to a map file with specific xyz dimensions and returns the output file location

Parameters:
  • phase_filename – input phase file to check for bad values
  • space_group – space group for structure, e.g “P212121”
  • xyz_limits – size limits for the x, y, z axes of the output map
  • output_filename – absolute path for the map output file
Returns:

location of output map