CCP4i Documentation for Programmers: Core Documentation

Contents

Handling CCP4-Specific File Formats

InitialiseProject The place for CCP4 specific initialisation

Argument list: None

InitialiseProject Load data from file CCP4/lib/data/symop.lib & CCP4/ccp4i/etc/crystal.lib

Argument list: None

Loaded into crystal_data array

ReadCrystalData Read etc/crystal.lib file and extract crystallographic info

Argument list: <file>

Save to array crystal_data

There are crystal_data(N_LAUE) laue groups stored as list of space groups in crystal_data(LAUE,$spgp)

The patterson info for space group spgp is stored in crystal_data(PATTERSON,$spgp) and is a list consisting of: patterson_spsgp_number, number of harker planes, definition of planes

file Full path name of crystal.lib file

MTZ Column Selection

MTZ Column Selection

CreateLabinLine and CreateLaboutLine are the APIs with a lot of support procedures. There is also CreateCadLabinLine which is for the customised labin lines used in the CAD interface.

CreateLabinLine Draw task interface line for selecting input MTZ column labels

Argument list: <linein> <message> <filein> <label1> <name1> <\>

This is a version of CreateLabinLine that can accommodate up to four MTZ labels in a single group.

The MTZ label line can allow the user to select up to four MTZ labels. The second and subsequent labels are expected to be associated with the first (such as a sigma or a Freidel mate) and when the user selects the first label then the second and subsequent labels are automatically updated to be the appropriate related column in the MTZ file. The label types are defined in CCP4I_TOP/etc/types.def

This procedure sets up commands so that when the user selects an input MTZ file the column names in the file are automatically read by the procedure ExtractMTZData and the menu(s) for users to select the column labels is updated by SetLabin

linein Output Tk frame id for the line

message Message line which appears if cursor over this line

filein Name of element in the task interface array which contains the name of the input MTZ file

label1 Text to appear in the task interface line

name1 Name of the element in the task interface array which contains the name of the input label

priority_name_list1 A list of possible column label names - if one of these appears in the MTZ file then it is set as the default.

-sigma labeln namen priority_name_listn

The label, element name and priority labels for an additional MTZ label

-dependent labeln namen priority_name_listn

Equivalent to the -sigma option

-toggle_display toggle_var toggle_state toggle_hitlist

Display this line in the task window dependent on the value of toggle_var. If it takes any of the values in the list toggle_hitlist then set the display status to toggle_state. toggle_state can be 'open', the line is displayed, or 'hide', the line is not displayed.

-command command_string

Associate a command to be invoked when the user clicks on any of the labels in the grouping.

CreateLabinLine4 Draw task interface line for selecting input MTZ column labels

Argument list: <linein> <message> <filein> <label1> <name1> <\>

This command is now just a wrapper to CreateLabinLine, and so supports all the same options as that command.

add_labinline_command Internal function used in CreateLabinLine

Argument list: <command> <arrayname> <var>

This adds a command callback to a label variable.

command The command to be invoked

arrayname The name of the parameter array

var The parameter name associated with the label

invoke_labinline_command Internal function used in CreateLabinLine

Argument list: <command> <args>

Invoke a user-defined callback when labels are changed

command The command to be invoked when the labels are updated

SetLabin An updated version of SetLabin ...

Argument list: <arrayname> <filename> <args>

SetLabin Handler to update Labin menu after user has selected MTZ file

Argument list: <arrayname> <filename> <args>

arrayname Name of data array

filename Element of array which contains the MTZ file name

labin_element1...labin_elementn Any number of elements of the array which are the input column labels which map onto the labin menu widgets

-setallelements

Flag that the labin elements are part of extending frames and have multiple instances with names element,n. Update the menus for all instances of the element

add_label_menu_extras Internal procedure called from SetLabin

Argument list: <menu> <arrayname> <ele> <file> <countVar>

Append the "ListAllLabels" and "EnterLabel" options to the labin menus set up in SetLabin.

extract_label_data Internal procedure called from SetLabin

Argument list: <arrayname> <\>

Set up the variables needed to define the label widgets in SetLabin.

SetLabinUnassigned Set labin menu to 'Unassigned' if the user has deselected an MTZ file

Argument list: <arrayname> <element> <args>

arrayname Name of data array

element Name of labin element in array

-setallelements

Flag that the labin element is part of extending frames and has multiple instances with name element,n. Update the menus for all instances of the element

UpdateDependentLabin Update the second labin column in a line when user selects the first labin#d_desc This procedure is called when the user selects a new item from the labin menu

Argument list: <selection> <arrayname> <param0> <args>

selection The selected value for the first labin

arrayname Name of data array

param0 The name of the array element which contains the first labin on the CreatelabinLine

param1...paramn A list of the dependent labin elements. There is usually just one for the second labin in the CreateLabin line

SetLabelList Save a list of allowed column labels and types a labin array element

Argument list: <arrayname> <element> <name_list> <type_list> <mode> <>

This list corresponds to the list of values presented in the menu

arrayname Name of data array

element The name of the array element which contains the labin

name_list List of valid column names for this labin

type_list List of the column types for these column names

mode Optional 'append' to append to existing list, otherwise overwrite

GetLabelList Return the list of allowed column labels and types for a labin array element

Argument list: <arrayname> <element> <name_listVar> <type_listVar>

This list corresponds to the list of values presented in the menu

arrayname Name of data array

element The name of the array element which contains the labin

name_listVar Output. List of valid column names for this labin

type_listVar Output. List of the column types for these column names

ListAllLabels List all column labels in MTZ file to support the 'List all Labels' option on column label menu

Argument list: <arrayname> <element> <file>

arrayname Name of data array

element The name of the array element which contains the labin

file The full path name for the MTZ file

handle_list_labels handler to update column label when it is selected from 'List all Columns'

Argument list: <w> <arrayname> <element>

w The Tk id of the listbox which listed all column labels

arrayname name of data array

element Name of element in array containing the selected column name

EnterLabel Window for user to type column label to support 'Enter Label' option on columns menu

Argument list: <arrayname> <ele>

arrayname Name of data array

ele The array element for the column label

CreateCadLabinLine Display the MTZ label selection line used in the Cad task interface

Argument list: <linein> <message> <filein> <label1> <name1> <label2>

See the Cad task interface for normal usage

linein Output Tk frame id for the line

message Message line which appears if cursor over this line

filein Name of element in the task interface array which contains the name of the input MTZ file

label1 Text to appear in the task interface line

name1 Name of the element in the task interface array which contains the name of the input label

label2 Text to appear in the task interface line

name2 Name of the element in the task interface array which contains the name of the output label

label3 Text to appear in the task interface line

type The MTZ column type for the output column

cad_update_labin Handler for CreateCadLabinLine to create menu of input column names

Argument list: <arrayname> <index> <name1> <name2> <type>

This procedure is invoked when an input MTZ column is selected from menu. The default values of the output column name and type are set to be the same as those of the input column. This procedure has an input 'index' which indicates which of the multiple column selection lines has been changed by the user. The procedure is complicated by the fact that the Cad task may have more than one input MTZ file and with multiple MTZ files then the 'index' parameter is 2-dimensional. The procedure GetLabelList is called to get a list of the column names and types associated with this column selection line and the list of names is searched to find the index in the list of the column selected by user. This index is then used to extract the correct column type from the list of columns.

arrayname Name of task interface array

index The number of the column selection line that is been updated

name1 Name of the element in the task interface array which contains the name of the input label

name2 Name of the element in the task interface array which contains the name of the output label

type The MTZ column type for the output column

CreateLaboutLine Draw a task interface line for user to specify output MTZ column name

Argument list: <linein> <message> <fileout> <label1> <name1> <args>

linein Output Tk frame id for the line

message Message line which appears if cursor over this line

fileout Name of element in the task interface array which contains the name of the output MTZ file

label1 Text to appear in the task interface line

name1 Name of the element in the task interface array which contains the name of the output labelpvar {$linein} line

CheckLabout Procedure to be called before running a task to check uniqueness of output MTZ column names

Argument list: <arrayname> <labout> <hklin>

Not currently used - code may not be reliable

arrayname Name of task interface array

labout Name of element in array which contains a list of the array elements which are output column labels.#d_arg hklin Array element which contains the name of the input MTZ file

PackLabinLine Pack, i.e. set the layout, of the task interface line to select MTZ columns

Argument list: <line> <args>

This procedure is needed to complement CreateLabinLine. When CreateLabinLine calls CreateLine with the line format 'MTZlabel' line procedure is used to layout the line.

Tk frame id for the line

Extracting Data from Map Files

InitialiseMAPData Initialise the MAP_file_data array with header info from the last selected input CCP4 map file.

Argument list: None

ReadCCP4Map Read a CCP4 map file using mapdump and return program output

Argument list: <file> <ttVar>

file Input map file name

ttVar Returned text output by mapdump program

ExtractMAPData Read header info from a CCP4 map file and save to MAP_file_data array

Argument list: <file>

file Input map file name

Extracting Data from PDB Files

InitialisePDBData Initialise the PDB_file_data array which holds header parameters from the last selected input PDB file.

Argument list: None

ExtractPDBData Read header from PDB file and load params into global array PDB_file_data

Argument list: <file>

GetCCP4SpaceGroup Return space group in CCP4 format

Argument list: <spacegp>

Extracting Data from MTZ Files

SetMtzParamField Put data value from MTZ header into an array element

Argument list: <paramtype> <arrayname> <filename> <element>

paramtype Parameter type - must one of the names of elements in MTZ_file_data array

arrayname Name of data array

filename Name of array element containing MTZ file name

element Name of array element to receive data from MTZ

GetMtzParam Return a specified data item from specified MTZ file

Argument list: <file> <param> <dataVar>

file MTZ file name

param Parameter type - must be one of the names of elements in MTZ_file_data array

dataVar Variable with returned data value

GetMtzParamFromDataset Return a specified data item from specified MTZ file

Argument list: <file> <xtal> <dataset> <param> <dataVar>

A variation on GetMtzParam.

file MTZ file name

xtal A crystal in the MTZ file

dataset A dataset in the MTZ file

param Parameter type - must be one of the names of elements in MTZ_file_data array

dataVar Variable with returned data value

GetMtzColumnResolution Return the maximum and minimum resolution for an MTZ column.

Argument list: <file> <label> <maxresoVar> <minresoVar>

The resolution values are given in Angrstroms. Returns 1 on success, 0 on failure.

file MTZ file name

label MTZ column label

maxresoVar Variable returned with maximum resolution

minresoVar Variable returned with minimum resolution

GetMtzDatasetFromLabel Return the parent dataset for the specified label

Argument list: <file> <label> <xtalVar> <datasetVar>

The parent "dataset" consists of an MTZ crystal-dataset pair. This procedure returns 1 on success (the parent dataset is identified) and 0 on failure (no parent is identified).

file MTZ file name

label MTZ column label

xtalVar Variable returned with parent crystal name

datasetVar Variable returned with parent dataset name

GetMtzXtals Return list of crystal names in an MTZ file

Argument list: <file>

file MTZ file name

GetMtzDatasetsInXtal Return a list of the datasets associated with a crystal in an MTZ file

Argument list: <file> <xtal>

file MTZ file name

xtal Crystal name

GetMtzColsInDataset Return a list of the columns in a dataset in an MTZ file

Argument list: <file> <xtal> <dataset>

file MTZ file name

xtal Crystal name

dataset Dataset name

MtzColSameDataset Determine whether two columns belong to the same dataset

Argument list: <file> <col1> <col2>

Return 1 if the parent dataset and crystal names for each label match, and 0 if not.

file MTZ file

col1 Label of the first column in the comparison

col2 Label of the second column

GetMtzAllCols List all column labels in an MTZ file

Argument list: <file>

file MTZ file name

GetMtzColType Return MTZ column type corresponding to a specific label

Argument list: <file> <label>

Returns the column type taken from the file, or an empty string if no match to the supplied label is found in the file.

Required by GroupMtzCols.

file MTZ file

label MTZ column label

GroupMtzCols Group a list of MTZ columns by type

Argument list: <file> <col_list> <nlabels> <4>

This procedure is used to group the supplied list of MTZ columns according to their type.

It returns a list of lists, each sublist containing a group of labels. For mean structure factor amplitudes (type F), mean intensities (type J), E-values (type E) and anomalous differences (type D), the groupings returned will be pairs based on value-sigma. For phases (type P) the groupings will be pairs based on phases-weight.

For F(+)/F(-) and I(+)/I(-) the groupings will sets of four columns.

For Hendrickson-Lattman coefficients the grouping will also be a set of four columns.

For situations where there are F/Phi pairings, additional "groups" (consisting of the single F and the single Phi) may also appear.

This procedure assumes strict typing. Columns for which no matching sigma etc is expected or found, will be returned in the list as a single item.

The heuristic algorithm is as follows:

1. Go through the column list once, attempting to group columns that appear in sequence in the list (for example, "F SIGF" or "I(+) SIGI(+) I(-) SIGI(-)"). This results in a list of groups, with "ungrouped" labels assigned to "groups" of one.

2. Check the groups for those containing either single F-type or single P-type columns, and try to merge them into F-P pairs.

3. Look for mistyped Freidel pairs of amplitudes (e.g. F(+) which is typed as "F" instead of "G") and try to assemble these into groups of four labels. (The identification is based on the names having either "(+)" or "(-)" components.)

4. Look for anomalous differences (type "D") that should be matched with labels of type "F".

file MTZ file

col_list List of column names (MTZ labels)

nlabels Maximum number of labels in a group (default is 4)

InitialiseMTZData Initialise the MTZ_file_data array with header info from the last selected input MTZ file

Argument list: None

ReadMTZ Read an MTZ file using mtzdump and return program output

Argument list: <file> <ttVar> <mtzdmp_args> <HEADER>

file Input MTZ file name

ttVar Returned text output by mtzdump program

mtzdmp_args (Optional, default=HEADER) Arguments to the mtzdump program.

ExtractMTZData Read header info from an MTZ file and save to MTZ_file_data array

Argument list: <file>

First, checks to see if file exists. Then checks to see if

data has already been loaded. If the data has not been loaded,

or the file has been changed on disk since loading, then the

global array MTZ_file_data is initialised, and filled again

from the file.

file Name of MTZ file

InitialiseParamFromFile Initialise the *_file_data arrays containing data from map/pdb/mtz file headers

Argument list: <format>

This is called when user loads a new def file into task and (possibly) changes the selected files from which header data has been loaded

format pdb, mtz or map or 'all' for all three

GetMtzColumnList Return the labelled columns of a specified type and one default

Argument list: <file> <name_listin> <type_listin> <default_name_in>

This procedure calls GetMtzGroupByType to recover groups of columns from the file, then searches the list for matching column groupings by type before looking for any column name which matches any of the priority name list input to CreateLabinLine. This procedure, itself, is just setting the default selected column that the user sees immediately after selecting an MTZ file.

Although priority names can be specified for up to four columns, in practice due to the grouping mechanism it is likely that only the first will have any practical effect.

This function returns the number of columns in name_listin on output, or zero if there was a problem.

See also the docs for GetMtzColumnByType and GetMtzGroupByType.

file Name of MTZ file for which info required

name_listin Output. List of selected column names

type_listin Output. List of the types of the selected columns

default_name_in Output. The name of one default column

select_type A list of one or more required column types

priority_name_list A list of the preferred column names for the default

name_listin2 Output. List of selected column names

type_listin2 Output. List of the required column types

default_name2_in Output. The name of one default column

select_type2 Optional. A list of one or more required column types

priority_name_list2 A list of the preferred column names for the default

name_listin3 Output. List of selected column names

type_listin3 Output. List of the required column types

default_name3_in Output. The name of one default column

select_type3 Optional. A list of one or more required column types

priority_name_list3 A list of the preferred column names for the default

name_listin4 Output. List of selected column names

type_listin4 Output. List of the required column types

default_name4_in Output. The name of one default column

select_type4 Optional. A list of one or more required column types

priority_name_list4 A list of the preferred column names for the default

GetMtzColumnByType Return the labelled columns of a specified type found in an MTZ file

Argument list: <file> <select_type> <name_listin> <type_listin>

This procedure calls ExtractMTZData which loads the MTZ header info into the MTZ_file_data array if that array does not already hold data for the specified file. This procedure can output either one or two sets of selected columns. The second set of columns is expected to be something like a sigma or a weight and a column in this set is expected to appear in the MTZ file immediately after a column from the first set. If a column from the first selected set is followed in the MTZ file by a column of type unsuitable for the second set then the value 'Unassigned' is appended to the second set.

file Name of MTZ file for which info required

select_type A list of one or more column types which the selected columns may have.

name_listin Output. List of selected column names

type_listin Output. List of the types of the selected columns

select_type2 Optional. A list of one or more column types which the selected columns may have.

name_listin2 Output. List of selected column names

type_listin2 Output. List of the types of the selected columns

GetMtzGroupByType Return groups of MTZ columns based on the requested types

Argument list: <file> <select_type> <\>

Given a set of input column types this procedure tries to match them to the groups of columns that are returned from GroupMtzCols.

The procedure returns a list of lists: two lists, the first of which is a list of groups and the second of which is a list of the corresponding types.

This procedure is called from GetMtzColumnList.

file Name of the MTZ file

select_type MTZ column type for first column

select_type2 MTZ column type for second column

select_type3 MTZ column type for third column

select_type4 MTZ column type for fourth column

Accessing Standard Crystallographic Data

GetSpaceGroupNumber Return space group number from input space group code

Argument list: <code>

code space group code (or number will be handled OK)

GetSpaceGroupCode Return CCP4 space group code from input space group number

Argument list: <number>

number space group number (or code will be handled OK)

GetSpaceGroupStdCode Return PDB standard space group code from input space group number

Argument list: <number>

number space group number (or CCP4 code will be handled OK)

GetSpaceGroupNops Return the number of symmetry ops for a space group

Argument list: <number>

number space group number (or CCP4/PDB code will be handled OK)

GetSpaceGroupLattice Return the crystal lattice for a space group

Argument list: <number>

number space group number (or CCP4/PDB code will be handled OK)

GetSpaceGroupSymops Return the symmetry ops for a space group as a list

Argument list: <number>

number space group number (or CCP4/PDB code will be handled OK)

GetAsymUnit Return the CCP4 standard asymmetric unit

Argument list: <spgp_code>

spgp_code Space group code (CCP4 or PDB) or space group number

GetLaueGroupNumber Return an identifier for the laue group

Argument list: <spgp_code>

Will return 0 if not in the LAUE list from etc/crystal.lib file

spgp_code Space group code (CCP4 or PDB) or space group number

GetLaueGroup Return a list of space groups in given Laue group

Argument list: <laue_no>

laue_no Laue group number

GetPattersonSpaceGroup Return the Patterson space group for given space group

Argument list: <spgp_code>

spgp_code Space group code (CCP4 or PDB) or space group number

GetHarkerSections Return the Harker sections for given space group (as Tcl list)

Argument list: <spgp_code> <modein> <2>

spgp_code Space group code (CCP4 or PDB) or space group number

modein Maximum number of sections returned (or all). Optional, default 2

GetFFTSpaceGroups Get a list of space groups supported by FFT program

Argument list: <spgpVar>

spgpVar Returned list of space groups

GetChangeHandData Get resultant space group and transformations fro changing hand of data

Argument list: <spgp_code> <space_groupVar> <cxVar>

spgp_code Space group code (CCP4 or PDB) or space group number

space_groupVar Returned. Space group for data on changed hand

cxVar Returned. Tcl list of cx,xy,cz where change of hand transforms x,y,z to cx-x,cy-y,cz-z

GetTwinData Get the transformation(s) for twinned data

Argument list: <spgp_code> <cxVar>

spgp_code Space group code (CCP4 or PDB) or space group number

cxVar Returned. A Tcl list of transformations of form -h,-k,l

GetLatticeFromSpaceGp Return the lattice type from space group name ('cos shelx can not!)

Argument list: <spacegp> <args>

shelx number code: P = -1 I = -2 F = -4 A = -5 B = -6 C = -7

spgp_code Space group code (CCP4 or PDB) or space group number

-shelx

Return the Shelx numbering code