CMTZMAN (CCP4: Supported Program)

NAME

cmtzman - manipulate MTZ header information (crystal, dataset and column associations and data)

SYNOPSIS

cmtzman hklin foo_in.mtz hklout foo_out.mtz
[Keyworded input]

DESCRIPTION

CMTZMAN performs certain manipulations of the header information in an MTZ file, specifically to do with the MTZ crystal/dataset/column hierarchy. The available operations include:

Renaming of existing crystals and datasets, and associated projects (RENAME command)
Making new crystals and datasets (NEW command)
Reassignment of columns between datasets, and of datasets between crystals (MOVE command)
Delete crystals, datasets and columns (DELETE command)
Set attributes such as project name, cell, wavelength and column types (SET command)
Combining several MTZ files into one file (IMPORT command)

While these functions are also present in the CAD program, CMTZMAN aims to provide a more intuitive interface to the operations which reflects the MTZ crystal/dataset/column structure - for example, reassigning a dataset to a new crystal also reassigns the "child" columns to that crystal automatically.

KEYWORDED INPUT

The allowed keywords are:

DELETE, END, IMPORT, MOVE, NEW, RENAME, SET, SHOW, VALIDATE

DELETE

DELETE XTAL <xname>

DELETE DATASET [<xname>/]<dname>

DELETE COLUMN [[<xname>/]<dname>/]<label>

Removes an existing crystal, dataset or column from the MTZ hierarchy. Any datasets (for crystals) and columns under the specified element are also deleted automatically.

END

End input.

IMPORT <filename>

Import an MTZ file into the program and merge the contents with those already held in memory. All crystals, datasets and columns (except for HKL_base and the H K and L columns) in the named file will be added to those from HKLIN. Where names are duplicated between the two files, MTZMAN appends a digit from 0 to 9 in order to generate unique names.

If the imported file contains reflection records referenced by Miller indices which do not appear in HKLIN then the new records will be appended (with missing number flags inserted for existing columns), and it is likely that the final file HKLOUT will need to be resorted on H K and L.

Note that the spacegroups of the files being merged must be identical. No checks are made on the compatibility of other attributes, for example cell parameters.

MOVE

MOVE DATASET [<xname>/]<dname>

MOVE COLUMN [[<xname>/]<dname>/]<label>

Move an existing dataset (or column) to a different crystal (or dataset). For datasets, all columns inside the dataset are also moved.

NEW

NEW XTAL <xname> CELL <a> <b> <c> [<alpha> <beta> <gamma>]

NEW DATASET <xname> <dname> [WAVELENGTH <lambda>]

Make a new crystal with name <xname> and the given cell, or a new dataset with name <dname> in the crystal <xname>. For crystals, if cell angles <alpha> <beta> <gamma> are not supplied then these default to 90 degrees; if a wavelength <lambda> is not supplied then it defaults to 0.0.

RENAME

RENAME XTAL <xname> <xname_new>

RENAME DATASET [<xname>/]<dname> <dname_new>

RENAME COLUMN [[<xname>/]<dname>/]<label> <label_new>

RENAME PROJECT <pname1> [IN <xname>] [TO] <pname2>

Change the name of an existing crystal, dataset, or project. The new name must be unambiguous across the MTZ header.

SET

SET XTAL <xname> CELL <a> <b> <c> [<alpha> <beta> <gamma>]

SET XTAL <xname> PROJECT <pname>

SET DATASET [<xname>/]<dname> WAVELENGTH <lambda>

SET COLUMN [[<xname>/]<dname>/]<label> TYPE <ctype>

Allows the value of the relevant attributes (cell parameters and project name for crystals, wavelength for datasets, and types for columns).

SHOW

Prints the current hierarchy to screen (useful for seeing the results of the previous operations).

VALIDATE

NOT IMPLEMENTED IN THIS VERSION

Check the crystal, project and dataset names in the MTZ file, and enforce correctness, i.e. each name should be a single word containing alphanumeric characters and underscores only.

Notes on HKLOUT

Although it is possible to create "empty" crystals and datasets (i.e. crystals with no child datasets, or datasets with no child columns) and have these appear when using the SHOW command, note that the MTZ libraries automatically "prune" these when writing to HKLOUT. Thus no empty crystals or datasets will be written to output.

Notes on crystal, dataset and column names

Background information on the MTZ header hierarchy can be found as part of the MTZ file format documentation, in the Data Model section.

Uniqueness of dataset names and column labels

Although there is no explicit requirement for names of datasets or columns to be unique across the whole MTZ file, for historical reasons it is necessary that column labels at least be unique across each file (this is to avoid upsetting Fortran programs).

Referencing datasets and columns

The commands in MTZMAN give a number of different ways of referencing datasets and columns which has yet to be standardised in the program.

A "path-like" notation allows referencing of elements by using the / character to separate the components of the full name, for example:

crystal/dataset

crystal/dataset/column

KNOWN BUGS/FEATURES

These are not necessarily bugs but are missing functionality:

The program doesn't write any history record to HKLOUT.
MOVE could reassign multiple columns or datasets, and/or use wildcards.
When setting names or parameters there is limited checking of validity or consistency.
The program doesn't deal with batches (this aspect hasn't been properly considered yet)
The "validate" function is not interfaced in this version. Some function for "fixing" badly assigned names should be implemented.
Only spacegroups are checked on IMPORT
Output MTZ files are not sorted.

EXAMPLES

AUTHOR

Peter Briggs, CCLRC Daresbury