Main Page   Data Structures   File List   Data Fields   Globals  

mmtzlib.h File Reference

The mini-mtz user-level library. More...

#include "umtzlib.h"

Go to the source code of this file.

Data Structures

struct  mmtz_column_
struct  mmtz_crystal_
struct  mmtz_dataset_

Typedefs

typedef umtzfile* mmtzfile
typedef struct mmtz_column_  mmtz_column
typedef struct mmtz_dataset_  mmtz_dataset
typedef struct mmtz_crystal_  mmtz_crystal

Functions

mmtzfile mmtz_open (const char *filename, const char *mode)
void mmtz_close (mmtzfile file)
void mmtz_copy_headers (mmtzfile dest, const mmtzfile src)
int mmtz_num_rows (const mmtzfile file)
int mmtz_num_cols (const mmtzfile file)
int mmtz_num_datasets (const mmtzfile file)
int mmtz_get_num_symops (const mmtzfile file)
char* mmtz_get_symop (const mmtzfile file, const int isym, char *symop)
float* mmtz_get_cell (const mmtzfile file, float *cell)
void mmtz_get_setxtl (const mmtzfile file, const int icol, mmtz_dataset *set, mmtz_crystal *xtl)
int mmtz_get_column (const mmtzfile file, const int icol, mmtz_column *col, mmtz_dataset *set, mmtz_crystal *xtl)
int mmtz_add_column (mmtzfile file, const mmtz_column *col, const mmtz_dataset *set, const mmtz_crystal *xtl)
void mmtz_init_headers (mmtzfile file, const char *title, const float cell[6])
void mmtz_add_sort_header (mmtzfile file, const char *sortorder)
void mmtz_add_syminf_header (mmtzfile file, const int nsym, const int nsymp, const char cellcode, const int ccp4_symbol, const char *hm_symbol, const char *pg_symbol)
void mmtz_add_symop_header (mmtzfile file, const char *symop)
void mmtz_get_row (const mmtzfile file, float *fdata, int *flags)
void mmtz_add_row (mmtzfile file, float *fdata, const int *flags)
void mmtz_seek_row (const mmtzfile file, const int n)

Detailed Description

The mini-mtz user-level library.

This is a simple lightweight library which can be used by application developers to access MTZ files from C, and other languages which can access C APIs.

Accessing a file is achieved by use of an mmtzfile structure. This structure is allocated by calling the mmtz_open() function with a filename and either "r" or "w" for read or write access. Closing the file frees the structure.

When reading a file, this structure is the queried to obtain information from the MTZ headers. The actual data in the file may be accessed by using the mmtz_get_row() function to access the data for each reflection in turn.

When writing a file, the file is opened, and the headers must be constructed using the 'init' and 'add' functions. Only once construction of the headers is complete may any actual data be written to the file. Once all the data is written, the file must be closed to force the headers to be written.

To append columns to a file, open on file for reading and a second for writing. Use the mmtz_copy_headers() function to copy the headers from the first to the second. Then add any additional column headers using mmtz_add_column(). Finally read the data a reflection at a time, fill in the additional columns and write the data. The resulting code looks like this: 

  mmtzfile filein, fileout;
  mmtz_column col;
  mmtz_crystal xtl;
  mmtz_dataset set;
  int fcol, pcol;

  filein  = mmtz_open( "old.mtz", "r" );
  fileout = mmtz_open( "new.mtz", "w" );
  mmtz_copy_headers( fileout, filein );
  \/* get dataset and crystal for column 0 (i.e. H) *\/
  mmtz_get_column( filein, 1, &col, &set, &xtl );
  strcpy( col.label, "FCAL" );    \/* add an FCAL column *\/
  strcpy( col.type, "F" );
  fcol = mmtz_add_column( fileout, &col, &set, &xtl );
  strcpy( col.label, "PHICAL" );  \/* add an PHICAL column *\/
  strcpy( col.type, "P" );
  pcol = mmtz_add_column( fileout, &col, &set, &xtl );
  for (i = 0; i<mmtz_num_rows(filein); i++) {
    mmtz_get_row(filein, fdata, idata);
    fdata[ fcol ]   = 500.0;
    fdata[ pcol ] = 60.0;
    mmtz_add_row(fileout, fdata, idata);
  }
  mmtz_close( filein );
  mmtz_close( fileout );

Typedef Documentation

typedef struct mmtz_column_ mmtz_column
 

data structure describing an MTZ column

typedef struct mmtz_crystal_ mmtz_crystal
 

data structure describing an MTZ crystal

typedef struct mmtz_dataset_ mmtz_dataset
 

data structure describing an MTZ dataset

typedef umtzfile * mmtzfile
 

data structure for an MTZ file which is opened for input or output

Function Documentation

int mmtz_add_column ( mmtzfile file,
const mmtz_column * col,
const mmtz_dataset * set,
const mmtz_crystal * xtl )
 

add column: supply column, dataset, crystal. dataset and crystal have their names checked in turn, and if they already exist the existing copies are used.

Parameters:
file   The mmtzfile to modify
col   Pointer to the MTZ column structure to be used
set   Pointer to the MTZ dataset structure to be used
xtl   Pointer to the MTZ crystal structure to be used
Returns:
The new column number

void mmtz_add_row ( mmtzfile file,
float * fdata,
const int * flags )
 

write a new row of data to the file. Data will be marked as missing in the file if it has flags[col]=FALSE

Parameters:
file   The mmtzfile to modify
fdata   Array of floats holding a row of data
flags   Array of ints holding a row of 'missing' flags

void mmtz_add_sort_header ( mmtzfile file,
const char * sortorder )
 

write sort order header to a new mtz: Writing the sort order header is an assertion that reflections will be supplied in the given order. This is not checked. Failure will lead to an invalid mtz. sortorder contains 3 chars, H, K and L, giving the names of the slow, medium and fast columns in order. (usually "HKL")

Parameters:
file   The mmtzfile to modify
sortorder   A character array representing the sort order

void mmtz_add_syminf_header ( mmtzfile file,
const int nsym,
const int nsymp,
const char cellcode,
const int ccp4_symbol,
const char * hm_symbol,
const char * pg_symbol )
 

write spacegroup header to a new mtz file: Writing the syminf header is an assertion that you will later supply (nsym) symmetry operators to go with it. This is not checked. Failure will lead to an invalid mtz.

Parameters:
file   The mmtzfile to modify
nsym   The number of symmetry operators
nsymp   The number of primitive symmetry operators
cellcode   The cell centering code (P/A/B/C/F/I/R/H)
ccp4_symbol   The CCP4 spacegroup/setting number
hm_symbol   The Hermann--Maugnuin symbol for the spacegroup
pg_symbol   The point group symbol for the spacegroup

void mmtz_add_symop_header ( mmtzfile file,
const char * symop )
 

write a symop header to a new mtz file: Note you must supply the same number of symops as were specified in the syminf header. e.g. "X+1/2, Y+1/2, Z"

Parameters:
file   The mmtzfile to modify
symop   The character representation of the symop

void mmtz_close ( mmtzfile file )
 

close a file for read/write (and write header if necessary). When reading a file this frees the data structures. When writing this actually writes the new MTZ header to the output file, so failure to close the file will lead to an unreadable file.

Parameters:
file   The mmtzfile to close

void mmtz_copy_headers ( mmtzfile dest,
const mmtzfile src )
 

copy headers from one file to another (for append)

Parameters:
dest   The target mmtzfile
src   The source mmtzfile

float * mmtz_get_cell ( const mmtzfile file,
float * cell )
 

get base cell

Parameters:
file   The mmtzfile to query
cell   An array of at least 6 floats
Returns:
the float array containing the cell parameters

int mmtz_get_column ( const mmtzfile file,
const int icol,
mmtz_column * col,
mmtz_dataset * set,
mmtz_crystal * xtl )
 

get column: Get the n'th column from the file, along with the dataset and crystal which correspond to that column.

Parameters:
file   The mmtzfile to query
icol   The number of the MTZ column to be returned
col   Pointer to the MTZ column structure to be filled
set   Pointer to the MTZ dataset structure to be filled
xtl   Pointer to the MTZ crystal structure to be filled
Returns:
The column number (i.e. icol)

int mmtz_get_num_symops ( const mmtzfile file )
 

get number of symops

Parameters:
file   The mmtzfile to query
Returns:
The number of symmetry operators in the file

void mmtz_get_row ( const mmtzfile file,
float * fdata,
int * flags )
 

get the next row of data from the file. If data is present, it is marked with flags[col]=TRUE, if it is missing flags[col]=FALSE

Parameters:
file   The mmtzfile to query
fdata   Array of floats large enough to hold a row of data
flags   Array of ints large enough to hold a row of 'missing' flags

void mmtz_get_setxtl ( const mmtzfile file,
const int icol,
mmtz_dataset * set,
mmtz_crystal * xtl )
 

get dataset and crystal info

Parameters:
file   The mmtzfile to query
icol   The number of the dataset and crystal to be returned
set   Pointer to the MTZ dataset structure to be filled
xtl   Pointer to the MTZ crystal structure to be filled

char * mmtz_get_symop ( const mmtzfile file,
const int isym,
char * symop )
 

get n'th symops

Parameters:
file   The mmtzfile to query
isym   The number of the symmetry operator to be returned
symop   A character array or at least 72 characters
Returns:
the character string describing the isym'th symmetry operator

void mmtz_init_headers ( mmtzfile file,
const char * title,
const float cell[6] )
 

write the initial headers to a new MTZ

Parameters:
file   The mmtzfile to modify
title   The title for the new MTZ file
cell   An array of 6 floats containing the cell parameters

int mmtz_num_cols ( const mmtzfile file )
 

get number of columns

Parameters:
file   The mmtzfile to query
Returns:
The number of columns in the file (including H, K, L)

int mmtz_num_datasets ( const mmtzfile file )
 

get number of columns

Parameters:
file   The mmtzfile to query
Returns:
The number of datasets in the file

int mmtz_num_rows ( const mmtzfile file )
 

get number of reflections

Parameters:
file   The mmtzfile to query
Returns:
The number of rows (reflections) in the file

mmtzfile mmtz_open ( const char * filename,
const char * mode )
 

open a file for read/write (and read headers if necessary)

Parameters:
filename   The filename/path of the MTZ file
mode   "r" for read or "w" for write
Returns:
The mmtzfile object

void mmtz_seek_row ( const mmtzfile file,
const int n )
 

skip to the n'th row (reflection) in the file

Parameters:
file   The mmtzfile to query
n   The number of the row to go to

Generated at Fri Dec 14 11:37:56 2001 by doxygen1.2.8.1 written by Dimitri van Heesch, © 1997-2001