cmtzlib.h File Reference

C-level library for input, output and manipulation of MTZ files. More...

#include "ccp4_utils.h"
#include "mtzdata.h"

Go to the source code of this file.

Functions

MTZMtzGet (const char *logname, int read_refs)
MTZMtzGetUserCellTolerance (const char *logname, int read_refs, const double cell_tolerance)
int MtzRrefl (CCP4File *filein, int ncol, float *refldata)
int MtzPut (MTZ *mtz, const char *logname)
CCP4FileMtzOpenForWrite (const char *logname)
int MtzWhdrLine (CCP4File *fileout, int nitems, char buffer[])
int MtzWrefl (CCP4File *fileout, int ncol, float *refldata)
int MtzDeleteRefl (MTZ *mtz, int iref)
MTZMtzMalloc (int nxtal, int nset[])
int MtzFree (MTZ *mtz)
MTZCOLMtzMallocCol (MTZ *mtz, int nref)
int MtzFreeCol (MTZCOL *col)
MTZBATMtzMallocBatch (void)
int MtzFreeBatch (MTZBAT *batch)
char * MtzCallocHist (int nhist)
int MtzFreeHist (char *hist)
void MtzMemTidy (void)
int MtzNbat (const MTZ *mtz)
int MtzNref (const MTZ *mtz)
int MtzSpacegroupNumber (const MTZ *mtz)
int MtzResLimits (const MTZ *mtz, float *minres, float *maxres)
int MtzNxtal (const MTZ *mtz)
int MtzNumActiveXtal (const MTZ *mtz)
MTZXTAL ** MtzXtals (MTZ *mtz)
MTZXTALMtzIxtal (const MTZ *mtz, const int ixtal)
char * MtzXtalPath (const MTZXTAL *xtal)
MTZXTALMtzXtalLookup (const MTZ *mtz, const char *label)
MTZXTALMtzAddXtal (MTZ *mtz, const char *xname, const char *pname, const float cell[6])
int MtzNsetsInXtal (const MTZXTAL *xtal)
int MtzNumActiveSetsInXtal (const MTZ *mtz, const MTZXTAL *xtal)
MTZSET ** MtzSetsInXtal (MTZXTAL *xtal)
MTZSETMtzIsetInXtal (const MTZXTAL *xtal, const int iset)
int MtzNset (const MTZ *mtz)
int MtzNumActiveSet (const MTZ *mtz)
MTZXTALMtzSetXtal (const MTZ *mtz, const MTZSET *set)
char * MtzSetPath (const MTZ *mtz, const MTZSET *set)
MTZSETMtzSetLookup (const MTZ *mtz, const char *label)
MTZSETMtzAddDataset (MTZ *mtz, MTZXTAL *xtl, const char *dname, const float wavelength)
int MtzNcolsInSet (const MTZSET *set)
int MtzNumActiveColsInSet (const MTZSET *set)
int MtzNumSourceColsInSet (const MTZSET *set)
int MtzNbatchesInSet (const MTZ *mtz, const MTZSET *set)
MTZCOL ** MtzColsInSet (MTZSET *set)
MTZCOLMtzIcolInSet (const MTZSET *set, const int icol)
MTZCOLMtzAddColumn (MTZ *mtz, MTZSET *set, const char *label, const char *type)
int MtzAssignHKLtoBase (MTZ *mtz)
int MtzAssignColumn (MTZ *mtz, MTZCOL *col, const char crystal_name[], const char dataset_name[])
int MtzToggleColumn (MTZCOL *col)
MTZSETMtzColSet (const MTZ *mtz, const MTZCOL *col)
int MtzNcol (const MTZ *mtz)
int MtzNumActiveCol (const MTZ *mtz)
int MtzNumSourceCol (const MTZ *mtz)
char * MtzColPath (const MTZ *mtz, const MTZCOL *col)
int MtzRJustPath (char *path, const char *partial, const int njust)
int MtzPathMatch (const char *path1, const char *path2)
MTZCOLMtzColLookup (const MTZ *mtz, const char *label)
char * MtzColType (MTZCOL *col)
void MtzDebugHierarchy (const MTZ *mtz)
int MtzListColumn (const MTZ *mtz, char clabs[][31], char ctyps[][3], int csetid[])
int MtzListInputColumn (const MTZ *mtz, char clabs[][31], char ctyps[][3], int csetid[])
int MtzFindInd (const MTZ *mtz, int *ind_xtal, int *ind_set, int ind_col[3])
float MtzInd2reso (const int in[3], const double coefhkl[6])
int MtzHklcoeffs (const float cell[6], double coefhkl[6])
int MtzArrayToBatch (const int *intbuf, const float *fltbuf, MTZBAT *batch)
int MtzBatchToArray (MTZBAT *batch, int *intbuf, float *fltbuf)
MTZBATsort_batches (MTZBAT *batch, int numbat)
int ccp4_lrtitl (const MTZ *mtz, char *title)
int ccp4_lrhist (const MTZ *mtz, char history[][MTZRECORDLENGTH], int nlines)
int ccp4_lrsort (const MTZ *mtz, int isort[5])
int ccp4_lrbats (const MTZ *mtz, int *nbatx, int batchx[])
int ccp4_lrcell (const MTZXTAL *xtl, float cell[])
int ccp4_lrsymi (const MTZ *mtz, int *nsympx, char *ltypex, int *nspgrx, char *spgrnx, char *pgnamx)
int ccp4_lrsymm (const MTZ *mtz, int *nsymx, float rsymx[192][4][4])
int MtzParseLabin (char *labin_line, const char prog_labels[][31], const int nlprgi, char user_labels[][2][31])
MTZCOL ** ccp4_lrassn (const MTZ *mtz, const char labels[][31], const int nlabels, char types[][3])
int ccp4_lridx (const MTZ *mtz, const MTZSET *set, char crystal_name[64], char dataset_name[64], char project_name[64], int *isets, float datcell[6], float *datwave)
int ccp4_lrrefl (const MTZ *mtz, float *resol, float adata[], int logmss[], int iref)
int ccp4_lrreff (const MTZ *mtz, float *resol, float adata[], int logmss[], const MTZCOL *lookup[], const int ncols, const int iref)
int ccp4_ismnf (const MTZ *mtz, const float datum)
int ccp4_lhprt (const MTZ *mtz, int iprint)
int ccp4_lhprt_adv (const MTZ *mtz, int iprint)
int ccp4_lrbat (MTZBAT *batch, float *buf, char *charbuf, int iprint)
int MtzPrintBatchHeader (const MTZBAT *batch)
int ccp4_lwtitl (MTZ *mtz, const char *ftitle, int flag)
int MtzSetSortOrder (MTZ *mtz, MTZCOL *colsort[5])
int MtzAddHistory (MTZ *mtz, const char history[][MTZRECORDLENGTH], const int nlines)
int ccp4_lwsymm (MTZ *mtz, int nsymx, int nsympx, float rsymx[192][4][4], char ltypex[], int nspgrx, char spgrnx[], char pgnamx[])
MTZCOL ** ccp4_lwassn (MTZ *mtz, const char labels[][31], const int nlabels, const char types[][3], const int iappnd)
int ccp4_lwidx (MTZ *mtz, const char crystal_name[], const char dataset_name[], const char project_name[], const float datcell[6], const float *datwave)
int ccp4_lwrefl (MTZ *mtz, const float adata[], MTZCOL *lookup[], const int ncol, const int iref)
int ccp4_lwbat (MTZ *mtz, MTZBAT *batch, const int batno, const float *buf, const char *charbuf)
int ccp4_lwbsetid (MTZ *mtz, MTZBAT *batch, const char xname[], const char dname[])


Detailed Description

C-level library for input, output and manipulation of MTZ files.

Functions defining the C-level API for accessing MTZ files. MtzGet and MtzPut read and write MTZ files to/from a data structure defined in mtzdata.h Other functions allow one to access data structure members, and to manipulate the structure and the values of structure members. Functions with names beginning ccp4_lr or ccp4_lw are primarily to support the Fortran API.

Author:
Martyn Winn

Function Documentation

int ccp4_ismnf ( const MTZ mtz,
const float  datum 
)

Checks whether a particular reflection value represents missing data.

Parameters:
mtz Pointer to the MTZ struct, which holds the value representing missing data (the Missing Number Flag) against which the input datum is compared.
datum Reflection value to be checked.
Returns:
Returns 1 is datum is the MNF, and 0 otherwise.

References MNF::amnf, ccp4_utils_isnan(), MNF::fmnf, and MTZ::mnf.

int ccp4_lhprt ( const MTZ mtz,
int  iprint 
)

int ccp4_lhprt_adv ( const MTZ mtz,
int  iprint 
)

Function to print header information in format appropriate to data structure hierarchy.

Parameters:
mtz Pointer to MTZ struct
iprint Print level
Returns:
1 on success, 0 on failure

References MNF::amnf, MTZXTAL::cell, MTZSET::col, MTZSET::dname, MNF::fmnf, MTZ::hist, MTZ::histlines, float_uint_uchar::i, MTZCOL::label, MTZ::mnf, MTZRECORDLENGTH, MTZ::mtzsymm, MTZSET::ncol, MTZ::nref, MTZXTAL::nset, MTZ::nxtal, MTZXTAL::pname, MTZXTAL::set, SYMGRP::spcgrp, MTZ::title, MTZCOL::type, MTZSET::wavelength, MTZXTAL::xname, and MTZ::xtal.

MTZCOL** ccp4_lrassn ( const MTZ mtz,
const char  labels[][31],
const int  nlabels,
char  types[][3] 
)

Finds columns in an MTZ struct according to column labels. Column types are checked for agreement between requested type (in argument 'types') and file type. If requested type is blank, file type is returned in argument 'types'. Note, this function is different from Fortranic LRASSN, in that any conversion from program labels to user labels should have been done previously.

Parameters:
mtz Pointer to MTZ struct.
labels Input array of column labels to be found in MTZ struct.
nlabels Number of columns to be found.
types Input array of column types of columns to be found.
Returns:
Array of pointers to columns in MTZ struct. Array element is NULL if column not found.

References ccp4_utils_malloc(), MTZCOL::label, and MTZCOL::type.

int ccp4_lrbat ( MTZBAT batch,
float *  buf,
char *  charbuf,
int  iprint 
)

Function to return batch header data for a specified batch.

Parameters:
batch Pointer to requested batch.
buf On return, real and integer batch data.
charbuf On return, character batch data (title and axes names).
iprint =0 no printing, =1 print title only, >1 print full header.
Returns:
1 on success, 0 on failure

References bathead::gonlab, NBATCHINTEGERS, NBATCHREALS, NBATCHWORDS, bathead::num, and bathead::title.

int ccp4_lrbats ( const MTZ mtz,
int *  nbatx,
int  batchx[] 
)

Get batch numbers from MTZ structure.

Parameters:
mtz Pointer to MTZ struct.
nbatx Number of batches in input file.
batchx Returned array of batch numbers.
Returns:
Number of batches.

References MTZ::batch, MTZ::n_orig_bat, bathead::next, and bathead::num.

int ccp4_lrcell ( const MTZXTAL xtl,
float  cell[] 
)

Get cell dimensions for a particular crystal.

Parameters:
xtl Pointer to crystal.
cell Output cell dimensions.
Returns:
1 on success, 0 on failure.

References MTZXTAL::cell.

int ccp4_lrhist ( const MTZ mtz,
char  history[][MTZRECORDLENGTH],
int  nlines 
)

Get history lines from MTZ structure.

Parameters:
mtz Pointer to MTZ struct.
history Returned history lines.
nlines Requested number of history lines.
Returns:
Actual number of history lines returned.

References MTZ::hist, and MTZ::histlines.

int ccp4_lridx ( const MTZ mtz,
const MTZSET set,
char  crystal_name[64],
char  dataset_name[64],
char  project_name[64],
int *  isets,
float  datcell[6],
float *  datwave 
)

Report information on a particular dataset. This represents the collection of data held in one series of dataset records in the MTZ header. It is mainly useful for supporting old Fortran calls.

Parameters:
mtz pointer to MTZ struct
set pointer to dataset
crystal_name Crystal name
dataset_name Dataset name
project_name Project name
isets Dataset ID.
datcell Cell dimensions of crystal that dataset belongs to.
datwave X-ray wavelength associated with dataset.
Returns:
1 on success, 0 on failure

References MTZXTAL::cell, MTZXTAL::pname, and MTZXTAL::xname.

int ccp4_lrreff ( const MTZ mtz,
float *  resol,
float  adata[],
int  logmss[],
const MTZCOL lookup[],
const int  ncols,
const int  iref 
)

Returns iref'th reflection from file held in MTZ struct mtz. Returns data for certain columns held in input file, as specified by the column pointers held in lookup. In "in-memory" mode, reflection data is taken from arrays held in memory. In the traditional file-based mode, a reflection record is read from the input file.

Parameters:
mtz pointer to MTZ struct
resol resolution of reflection (output).
adata array of requested values (output).
logmss array of flags for missing data (output). A value of 1 indicates a Missing Number Flag, and a value of 0 indicates usable data.
lookup array of pointers to requested columns
ncols number of requested columns
iref index of requested reflection (starting at 1).
Returns:
1 if past last reflection, else 0

References MNF::amnf, ccp4_nan(), ccp4_utils_malloc(), MTZXTAL::cell, MTZSET::col, float_uint_uchar::f, MTZ::filein, MNF::fmnf, MTZ::mnf, MTZ::ncol_read, MTZ::nref_filein, MTZ::nxtal, MTZCOL::ref, MTZ::refs_in_memory, MTZXTAL::resmax, MTZXTAL::resmin, MTZXTAL::set, and MTZ::xtal.

int ccp4_lrrefl ( const MTZ mtz,
float *  resol,
float  adata[],
int  logmss[],
int  iref 
)

Returns iref'th reflection from file held in MTZ struct mtz. Returns data for all columns held in input file, in the order that they are held in the source file. The value of col->source can be used to find particular columns. In "in-memory" mode, reflection data is taken from arrays held in memory. In the traditional file-based mode, a reflection record is read from the input file.

Parameters:
mtz pointer to MTZ struct
resol resolution of reflection (output).
adata array of requested values (output).
logmss array of flags for missing data (output). A value of 1 indicates a Missing Number Flag, and a value of 0 indicates usable data.
iref index of requested reflection (starting at 1).
Returns:
1 if past last reflection, else 0

References ccp4_utils_malloc(), MTZXTAL::cell, MTZSET::col, MTZ::filein, MTZCOL::label, MTZSET::ncol, MTZ::ncol_read, MTZ::nref_filein, MTZXTAL::nset, MTZ::nxtal, MTZCOL::ref, MTZ::refs_in_memory, MTZXTAL::resmax, MTZXTAL::resmin, MTZXTAL::set, MTZCOL::source, MTZCOL::type, and MTZ::xtal.

int ccp4_lrsort ( const MTZ mtz,
int  isort[5] 
)

Get sort order from MTZ structure.

Parameters:
mtz Pointer to MTZ struct.
isort Returned sort order.
Returns:
1 on success, 0 on failure

References MTZSET::col, MTZSET::ncol, MTZXTAL::nset, MTZ::nxtal, MTZ::order, MTZXTAL::set, and MTZ::xtal.

int ccp4_lrsymi ( const MTZ mtz,
int *  nsympx,
char *  ltypex,
int *  nspgrx,
char *  spgrnx,
char *  pgnamx 
)

Get spacegroup information as held in MTZ header.

Parameters:
mtz Pointer to MTZ struct.
nsympx Number of primitive symmetry operators.
ltypex Lattice type (P,A,B,C,I,F,R).
nspgrx Spacegroup number.
spgrnx Spacegroup name.
pgnamx Pointgroup name.
Returns:
Spacegroup number.

References MTZ::mtzsymm, SYMGRP::nsymp, SYMGRP::pgname, SYMGRP::spcgrp, SYMGRP::spcgrpname, and SYMGRP::symtyp.

int ccp4_lrsymm ( const MTZ mtz,
int *  nsymx,
float  rsymx[192][4][4] 
)

Get symmetry matrices from MTZ structure. Note: ordering of matrices in rsymx was changed in April 2004.

Parameters:
mtz Pointer to MTZ struct.
nsymx Number of symmetry operators held in MTZ header.
rsymx Symmetry operators as 4 x 4 matrices, in the order they are held in the MTZ header. Each matrix has translations in elements [*][3].
Returns:
Number of symmetry operators.

References MTZ::mtzsymm, SYMGRP::nsym, and SYMGRP::sym.

int ccp4_lrtitl ( const MTZ mtz,
char *  title 
)

Returns title of MTZ structure 'mtz'

Parameters:
mtz pointer to MTZ struct
title MTZ title as character string
Returns:
length of title excluding trailing blanks and terminating null character.

References MTZ::title.

MTZCOL** ccp4_lwassn ( MTZ mtz,
const char  labels[][31],
const int  nlabels,
const char  types[][3],
const int  iappnd 
)

Assign columns for writing. Check to see if columns already exist, else create them. New columns are assigned to the base dataset if it exists, else the first dataset.

Parameters:
mtz pointer to MTZ struct
labels Input array of column labels to be assigned.
nlabels Number of columns.
types Input array of column types of columns.
iappnd If iappnd = 0, then deactivate columns which are not selected (allows one to write out a subset of columns). Else if iappnd = 1, append these columns to existing ones.
Returns:
Array of pointers to columns in MTZ struct.

References MTZCOL::active, ccp4_utils_malloc(), MTZSET::col, float_uint_uchar::i, MTZSET::ncol, MTZXTAL::nset, MTZ::nxtal, MTZXTAL::set, and MTZ::xtal.

int ccp4_lwbat ( MTZ mtz,
MTZBAT batch,
const int  batno,
const float *  buf,
const char *  charbuf 
)

Write new batch information to 'batch' or if 'batch' is NULL create new batch header with batch number 'batno'. If you try to create more than one new batch header with the same batch number, the function will complain and return. It is OK to create a new batch with the same number as one read from file - this is the mechanism for changing batch headers.

Parameters:
mtz pointer to MTZ struct
batch pointer to batch
batno batch number
buf pointer to batch array
charbuf pointer to character batch array
Returns:
1 on success, 0 on failure

References MTZ::batch, bathead::gonlab, float_uint_uchar::i, MTZ::n_orig_bat, NBATCHINTEGERS, bathead::next, bathead::num, and bathead::title.

int ccp4_lwbsetid ( MTZ mtz,
MTZBAT batch,
const char  xname[],
const char  dname[] 
)

Parameters:
mtz pointer to MTZ struct
batch pointer to batch
xname Crystal name
dname Dataset name

References bathead::nbsetid, and MTZXTAL::xname.

int ccp4_lwidx ( MTZ mtz,
const char  crystal_name[],
const char  dataset_name[],
const char  project_name[],
const float  datcell[6],
const float *  datwave 
)

Add or update a dataset in the MTZ structure. If the crystal name is not recognised, then a new crystal is created containing a single dataset. If the crystal name is recognised, then the parameters of the crystal are updated. The child dataset is then created if necessary or an existing dataset updated. Note that this function is used to update crystal parameters, as well as add crystals. If a duplicate crystal name is used by mistake, then the old crystal parameters are lost.

Parameters:
mtz pointer to MTZ struct
crystal_name Crystal name
dataset_name Dataset name
project_name Project name
datcell Cell dimensions of crystal that dataset belongs to.
datwave X-ray wavelength associated with dataset.
Returns:
1 on success, 0 on failure

References MTZXTAL::cell, float_uint_uchar::i, MTZXTAL::pname, and MTZXTAL::xname.

int ccp4_lwrefl ( MTZ mtz,
const float  adata[],
MTZCOL lookup[],
const int  ncol,
const int  iref 
)

Function to output reflection values for iref'th reflection. In "in-memory" mode, values are added/updated for columns for which a column-pointer is given in lookup, up to a maximum of ncol columns. In the traditional file-based mode, a reflection record is written to file.

Parameters:
mtz pointer to MTZ struct
adata array of values.
lookup array of pointers to columns.
ncol number of columns.
iref Reflection number such that 1st reflection is iref=1.
Returns:
1 on success, 0 on failure

References MTZCOL::active, ccp4array_resize, ccp4array_size, MTZXTAL::cell, MTZSET::col, MTZ::fileout, float_uint_uchar::i, MTZCOL::max, MCOLUMNS, MTZCOL::min, MTZSET::ncol, MTZ::nref, MTZXTAL::nset, MTZ::nxtal, MTZCOL::ref, MTZ::refs_in_memory, MTZXTAL::resmax, MTZ::resmax_out, MTZXTAL::resmin, MTZ::resmin_out, MTZXTAL::set, and MTZ::xtal.

int ccp4_lwsymm ( MTZ mtz,
int  nsymx,
int  nsympx,
float  rsymx[192][4][4],
char  ltypex[],
int  nspgrx,
char  spgrnx[],
char  pgnamx[] 
)

Write or update symmetry information for MTZ header. This provides support for the Fortran API, and is not particularly convenient for C programs. Note: ordering of matrices in rsymx was changed in November 2003.

Parameters:
mtz pointer to MTZ struct
nsymx number of symmetry operators
nsympx number of primitive symmetry operators
rsymx array of symmetry operators (dimensions ordered in C convention, with translations in elements [*][3])
ltypex lattice type
nspgrx spacegroup number
spgrnx spacegroup name
pgnamx point group name
Returns:
1 on success, 0 on failure

References float_uint_uchar::i, MAXSPGNAMELENGTH, MTZ::mtzsymm, SYMGRP::nsym, SYMGRP::nsymp, SYMGRP::pgname, SYMGRP::spcgrp, SYMGRP::spcgrpname, SYMGRP::sym, and SYMGRP::symtyp.

int ccp4_lwtitl ( MTZ mtz,
const char *  ftitle,
int  flag 
)

Write header title for later output to file.

Parameters:
mtz Pointer to MTZ struct.
ftitle Title string.
flag If 0 overwrite existing title, else append to existing title.
Returns:
1 on success, 0 on failure

References float_uint_uchar::i, and MTZ::title.

MTZCOL* MtzAddColumn ( MTZ mtz,
MTZSET set,
const char *  label,
const char *  type 
)

Add a column to dataset set and create + fill with NAN

Parameters:
mtz pointer to MTZ struct
set pointer to dataset
label Column label
type Column type
Returns:
pointer to column

References MNF::amnf, ccp4_nan(), ccp4_signal(), ccp4array_resize, ccp4array_size, float_uint_uchar::f, MNF::fmnf, float_uint_uchar::i, MCOLUMNS, MTZ::mnf, MTZ::nref, and MTZ::refs_in_memory.

MTZSET* MtzAddDataset ( MTZ mtz,
MTZXTAL xtl,
const char *  dname,
const float  wavelength 
)

Add a dataset to crystal xtl

Parameters:
mtz pointer to MTZ struct.
xtl pointer to crystal struct.
dname Dataset name
wavelength X-ray wavelength of dataset
Returns:
pointer to set

References ccp4_signal(), ccp4_utils_malloc(), ccp4array_new_size, ccp4array_resize, ccp4array_size, float_uint_uchar::i, MTZXTAL::nset, MTZ::nxtal, MTZXTAL::set, MTZSET::setid, and MTZ::xtal.

int MtzAddHistory ( MTZ mtz,
const char  history[][MTZRECORDLENGTH],
const int  nlines 
)

Adds history lines to the MTZ header in front of existing history lines.

Parameters:
mtz pointer to MTZ struct
history lines to be added
nlines number of lines to be added
Returns:
total number of history lines

References MTZ::hist, MTZ::histlines, and float_uint_uchar::i.

MTZXTAL* MtzAddXtal ( MTZ mtz,
const char *  xname,
const char *  pname,
const float  cell[6] 
)

Add a crystal to header mtz.

Parameters:
mtz pointer to MTZ struct
xname Crystal name.
pname Name of associated project.
cell Cell dimensions of crystal.
Returns:
Pointer to crystal.

References ccp4_signal(), ccp4_utils_malloc(), ccp4array_new_size, ccp4array_resize, ccp4array_size, MTZXTAL::cell, float_uint_uchar::i, MTZXTAL::nset, MTZ::nxtal, MTZXTAL::pname, MTZXTAL::resmax, MTZXTAL::resmin, MTZXTAL::set, MTZXTAL::xname, MTZ::xtal, and MTZXTAL::xtalid.

int MtzArrayToBatch ( const int *  intbuf,
const float *  fltbuf,
MTZBAT batch 
)

int MtzAssignColumn ( MTZ mtz,
MTZCOL col,
const char  crystal_name[],
const char  dataset_name[] 
)

Assigns a column to a dataset identified by crystal_name and dataset_name. First, the function checks whether the column already belongs to this dataset, in which case it does nothing. Then it checks if the requested dataset exists. If not, it is created, though it is better to explicitly create it beforehand. Finally, the column is assigned to the dataset.

Parameters:
mtz pointer to MTZ struct
col pointer to column
crystal_name name of crystal containing dataset
dataset_name name of dataset
Returns:
1 on success, 0 on failure

References ccp4_signal(), ccp4array_resize, ccp4array_size, MTZSET::col, float_uint_uchar::i, and MTZSET::ncol.

int MtzAssignHKLtoBase ( MTZ mtz  ) 

Assigns HKL columns to the base dataset.

Parameters:
mtz pointer to MTZ struct
Returns:
1 on success, 0 on failure

References MTZSET::col, float_uint_uchar::i, MTZSET::ncol, MTZXTAL::nset, MTZ::nxtal, MTZXTAL::set, MTZCOL::type, and MTZ::xtal.

int MtzBatchToArray ( MTZBAT batch,
int *  intbuf,
float *  fltbuf 
)

char* MtzCallocHist ( int  nhist  ) 

Allocates memory for the mtz history with 'nhist' lines.

Parameters:
nhist 
Returns:
pointer to history

References ccp4_utils_calloc(), and MTZRECORDLENGTH.

MTZCOL* MtzColLookup ( const MTZ mtz,
const char *  label 
)

Returns a pointer to the column of mtz with the given `label`, or NULL

Parameters:
mtz pointer to MTZ struct
label Column label.
Returns:
pointer to column

References float_uint_uchar::c, MTZSET::col, MTZSET::ncol, MTZXTAL::nset, MTZ::nxtal, MTZXTAL::set, and MTZ::xtal.

char* MtzColPath ( const MTZ mtz,
const MTZCOL col 
)

Return the full path name of a column as "/xname/dname/label" Memory for the path name is assigned with malloc, and can be free'd by the calling function.

Parameters:
mtz pointer to MTZ struct
col pointer to MTZ column.
Returns:
full path name of column

References ccp4_utils_malloc(), and MTZCOL::label.

MTZSET* MtzColSet ( const MTZ mtz,
const MTZCOL col 
)

Get the dataset associated with a column.

Parameters:
mtz pointer to MTZ struct
col pointer to column of interest
Returns:
pointer to set containing column of interest, or NULL if "col" is not contained in "mtz".

References float_uint_uchar::c, MTZSET::col, MTZSET::ncol, MTZXTAL::nset, MTZ::nxtal, MTZXTAL::set, and MTZ::xtal.

MTZCOL** MtzColsInSet ( MTZSET set  ) 

For a given dataset, return array of pointers to columns in that dataset.

Parameters:
set pointer to dataset
Returns:
array of pointers to columns

char* MtzColType ( MTZCOL col  ) 

Get the MTZ column type of a particular column.

Parameters:
col pointer to MTZ column.
Returns:
column type

References MTZCOL::type.

void MtzDebugHierarchy ( const MTZ mtz  ) 

Print summary of current crystal/dataset/column hierarchy. This is designed for debugging purposes rather than for the user.

Parameters:
mtz pointer to MTZ struct
Returns:
void

References MTZCOL::active, MTZXTAL::cell, MTZSET::col, MTZSET::dname, MTZ::filein, MTZ::fileout, MTZCOL::label, MTZSET::ncol, MTZXTAL::nset, MTZ::nxtal, MTZXTAL::set, MTZCOL::source, MTZXTAL::xname, and MTZ::xtal.

int MtzDeleteRefl ( MTZ mtz,
int  iref 
)

Delete a reflection from the data structure. Beware, there is no going back!

Parameters:
mtz pointer to MTZ struct.
iref index of reflection
Returns:
0 if successful, 1 otherwise

References ccp4array_delete_ordered, MTZSET::col, float_uint_uchar::i, MTZSET::ncol, MTZ::nref, MTZXTAL::nset, MTZ::nxtal, MTZCOL::ref, MTZ::refs_in_memory, MTZXTAL::set, and MTZ::xtal.

int MtzFindInd ( const MTZ mtz,
int *  ind_xtal,
int *  ind_set,
int  ind_col[3] 
)

Find where indices h, k, l are in MTZ structure. Usually, they will be first 3 columns of 1st dataset, but safest not to assume this.

Parameters:
mtz pointer to MTZ struct
ind_xtal crystal containing indices
ind_set dataset containing indices
ind_col 3 columns containing indices
Returns:
1 on success, 0 on failure

References MTZSET::col, MTZCOL::label, MTZSET::ncol, MTZXTAL::nset, MTZ::nxtal, MTZXTAL::set, MTZCOL::type, and MTZ::xtal.

int MtzFree ( MTZ mtz  ) 

Frees the memory reserved for the MTZ header struct.

Parameters:
mtz pointer to MTZ header struct.
Returns:
1 on success, 0 on failure

References MTZ::batch, ccp4_file_close(), ccp4array_free, MTZSET::col, MTZ::filein, MTZ::fileout, MTZ::hist, float_uint_uchar::i, MTZ::n_orig_bat, MTZSET::ncol, MTZXTAL::nset, MTZ::nxtal, MTZXTAL::set, and MTZ::xtal.

int MtzFreeBatch ( MTZBAT batch  ) 

Frees the memory reserved for 'batch'.

Parameters:
batch 
Returns:
1 on success, 0 on failure

References bathead::next.

int MtzFreeCol ( MTZCOL col  ) 

Frees the memory reserved for 'col'

Parameters:
col pointer to MTZ column.
Returns:
1 on success, 0 on failure

References ccp4array_free, and MTZCOL::ref.

int MtzFreeHist ( char *  hist  ) 

Frees the memory reserved for 'hist'.

Parameters:
hist 
Returns:
1 on success, 0 on failure

MTZ* MtzGet ( const char *  logname,
int  read_refs 
)

MTZ* MtzGetUserCellTolerance ( const char *  logname,
int  read_refs,
const double  cell_tolerance 
)

For compatibility with main CCP4 version.

Parameters:
logname logical name of MTZ file
read_refs whether to read reflections into memory (non-zero) or to read later from file (zero)
cell_tolerance tolerance within unit cells are considered equal.

int MtzHklcoeffs ( const float  cell[6],
double  coefhkl[6] 
)

Generate coefhkl coefficients from given cell parameters.

Parameters:
cell cell dimensions to be used for resolution calculation.
coefhkl double array of 6 coefficients
Returns:
1 on success, 0 on failure

References ccp4_signal().

MTZCOL* MtzIcolInSet ( const MTZSET set,
const int  icol 
)

For a given dataset, return pointer to the icol'th column in that dataset.

Parameters:
set pointer to dataset
icol number of the particular column (icol = 0 ... MtzNcolsInSet(set) -1
Returns:
pointer to specified column

float MtzInd2reso ( const int  in[3],
const double  coefhkl[6] 
)

Calculate resolution from indices and coefhkl. coefhkl is obtained from MtzHklcoeffs.

Parameters:
in integer array of 3 indices
coefhkl double array of 6 coefficients
Returns:
resolution

MTZSET* MtzIsetInXtal ( const MTZXTAL xtal,
const int  iset 
)

For a given crystal, return pointer to the iset'th dataset in that crystal.

Parameters:
xtal pointer to the crystal struct
iset number of the particular dataset (iset = 0 ... MtzNsetsInXtal(xtal) -1
Returns:
pointer to specified dataset

References MTZXTAL::set.

MTZXTAL* MtzIxtal ( const MTZ mtz,
const int  ixtal 
)

Return pointer to the ixtal'th crystal.

Parameters:
mtz pointer to MTZ struct
ixtal number of the particular crystal (ixtal = 0 ... MtzNxtal(xtal) -1
Returns:
pointer to the specified crystal

References MTZ::xtal.

int MtzListColumn ( const MTZ mtz,
char  clabs[][31],
char  ctyps[][3],
int  csetid[] 
)

List of column information: label, type, dataset.

Parameters:
mtz pointer to MTZ struct
clabs List of labels (output).
ctyps List of column types (output).
csetid List of dataset IDs (output).
Returns:
number of columns in current structure.

References MTZSET::col, MTZCOL::label, MTZSET::ncol, MTZXTAL::nset, MTZ::nxtal, MTZXTAL::set, MTZSET::setid, MTZCOL::type, and MTZ::xtal.

int MtzListInputColumn ( const MTZ mtz,
char  clabs[][31],
char  ctyps[][3],
int  csetid[] 
)

List of column information from input file: label, type, dataset.

Parameters:
mtz pointer to MTZ struct
clabs List of labels (output).
ctyps List of column types (output).
csetid List of dataset IDs (output).
Returns:
number of columns in input file.

References MTZSET::col, MTZCOL::label, MTZSET::ncol, MTZXTAL::nset, MTZ::nxtal, MTZXTAL::set, MTZSET::setid, MTZCOL::source, MTZCOL::type, and MTZ::xtal.

MTZ* MtzMalloc ( int  nxtal,
int  nset[] 
)

Allocates memory for an MTZ header structure. The structure can contain 0, 1 or more crystals, and for each crystal 0, 1 or more datasets. Crystals have a name based on the time "NULL_xnameHHMMSS" to ensure uniqueness (compared to crystals defined elsewhere - all new crystals created here will (probably) have the same name). Crystals have the project name "NULL_pname", and datasets have the name "NULL_dname".

Parameters:
nxtal Number of crystals to allocate.
nset Number of datasets for each crystal to allocate.
Returns:
pointer to MTZ header struct

References MNF::amnf, MTZ::batch, ccp4_signal(), ccp4_utils_itime(), ccp4_utils_malloc(), ccp4array_new_size, MTZ::filein, MTZ::fileout, MTZ::hist, MTZ::histlines, float_uint_uchar::i, MTZ::mnf, MTZ::mtzsymm, MTZ::n_orig_bat, MTZ::ncol_read, MTZ::nref, MTZ::nref_filein, MTZXTAL::nset, SYMGRP::nsym, SYMGRP::nsymp, MTZ::nxtal, MTZ::order, SYMGRP::pgname, MTZ::refs_in_memory, MTZ::resmax_out, MTZ::resmin_out, SYMGRP::spcgrp, SYMGRP::spcgrpname, SYMGRP::symtyp, MTZ::title, and MTZ::xtal.

MTZBAT* MtzMallocBatch ( void   ) 

Allocates memory for a single batch header.

Returns:
pointer to batch

References ccp4_signal(), ccp4_utils_malloc(), and bathead::next.

MTZCOL* MtzMallocCol ( MTZ mtz,
int  nref 
)

Allocates memory for an MTZ column. Space is allocated for the reflection data if and only if mtz->refs_in_memory is set.

Parameters:
mtz pointer to MTZ header struct.
nref number of reflections in column.
Returns:
pointer to MTZ column.

References ccp4_signal(), ccp4_utils_malloc(), ccp4array_new_size, MTZCOL::ref, and MTZ::refs_in_memory.

void MtzMemTidy ( void   ) 

Free all memory malloc'd from static pointers. To be called before program exit. The function can be registered with atexit.

Returns:
void

int MtzNbat ( const MTZ mtz  ) 

Get the number of batches in the mtz.

Parameters:
mtz pointer to MTZ struct
Returns:
Number of batches.

References MTZ::batch, and bathead::next.

int MtzNbatchesInSet ( const MTZ mtz,
const MTZSET set 
)

For a given dataset, return number of batches in that dataset.

Parameters:
mtz pointer to MTZ struct
set pointer to dataset
Returns:
number of batches

References MTZ::batch, float_uint_uchar::i, MTZ::n_orig_bat, bathead::nbsetid, and bathead::next.

int MtzNcol ( const MTZ mtz  ) 

Get the number of columns in the MTZ data structure.

Parameters:
mtz pointer to MTZ struct
Returns:
number of columns

References MTZXTAL::nset, MTZ::nxtal, MTZXTAL::set, and MTZ::xtal.

int MtzNcolsInSet ( const MTZSET set  ) 

For a given dataset, return number of columns in that dataset. This is simply set->ncol and so includes all columns irrespective of col->active

Parameters:
set pointer to dataset
Returns:
number of columns

int MtzNref ( const MTZ mtz  ) 

Get the number of reflections in the mtz.

Parameters:
mtz pointer to MTZ struct
Returns:
Number of reflections.

References MTZ::nref.

int MtzNset ( const MTZ mtz  ) 

Get the number of datasets in the MTZ structure

Parameters:
mtz pointer to MTZ struct
Returns:
total number of datasets

References MTZ::nxtal, and MTZ::xtal.

int MtzNsetsInXtal ( const MTZXTAL xtal  ) 

For a given crystal, return number of datasets in that crystal.

Parameters:
xtal pointer to the crystal struct
Returns:
number of datasets

References MTZXTAL::nset.

int MtzNumActiveCol ( const MTZ mtz  ) 

Get the number of active columns in the MTZ data structure.

Parameters:
mtz pointer to MTZ struct
Returns:
number of columns

References MTZXTAL::nset, MTZ::nxtal, MTZXTAL::set, and MTZ::xtal.

int MtzNumActiveColsInSet ( const MTZSET set  ) 

For a given dataset, return number of active columns in that dataset.

Parameters:
set pointer to dataset
Returns:
number of active columns

int MtzNumActiveSet ( const MTZ mtz  ) 

Get the number of active datasets in the MTZ structure

Parameters:
mtz pointer to MTZ struct
Returns:
total number of datasets

References MTZ::nxtal, and MTZ::xtal.

int MtzNumActiveSetsInXtal ( const MTZ mtz,
const MTZXTAL xtal 
)

For a given crystal, return number of active datasets in that crystal.

Parameters:
mtz pointer to MTZ struct
xtal pointer to the crystal struct
Returns:
number of datasets

References MTZXTAL::nset, and MTZXTAL::set.

int MtzNumActiveXtal ( const MTZ mtz  ) 

Get the number of active crystals in the MTZ structure

Parameters:
mtz pointer to MTZ struct
Returns:
number of active crystals

References MTZ::nxtal, and MTZ::xtal.

int MtzNumSourceCol ( const MTZ mtz  ) 

Get the number of columns in the MTZ data structure which have a source in an input file (i.e. non-zero source attribute).

Parameters:
mtz pointer to MTZ struct
Returns:
number of columns

References MTZXTAL::nset, MTZ::nxtal, MTZXTAL::set, and MTZ::xtal.

int MtzNumSourceColsInSet ( const MTZSET set  ) 

For a given dataset, return number of columns in that dataset which have a source in an input file (i.e. non-zero source attribute).

Parameters:
set pointer to dataset
Returns:
number of source columns

int MtzNxtal ( const MTZ mtz  ) 

Get the total number of crystals in the MTZ structure

Parameters:
mtz pointer to MTZ struct
Returns:
number of active crystals

References MTZ::nxtal.

CCP4File* MtzOpenForWrite ( const char *  logname  ) 

Opens a new MTZ file for writing.

Parameters:
logname logical name for output file.
Returns:
pointer to file or NULL on failure

References ccp4_file_open(), ccp4_file_seek(), ccp4_file_setmode(), ccp4_file_setstamp(), ccp4_file_warch(), ccp4_file_write(), ccp4_file_writechar(), ccp4_signal(), and SIZE1.

int MtzParseLabin ( char *  labin_line,
const char  prog_labels[][31],
const int  nlprgi,
char  user_labels[][2][31] 
)

Uses LABIN or LABOUT line to convert program labels to user labels. This is a helper function, but does not access reflection structure at all.

Parameters:
labin_line (I) LABIN/LABOUT line from Parser.
prog_labels (I) Progam labels.
nlprgi (I) Number of program labels.
user_labels (O) On output, user-supplied file labels in corresponding positions. For unassigned program labels, user_labels is empty string.
Returns:
Number of program labels matched, or -1 if there was an error.

References ccp4_keymatch(), ccp4_parse_end(), ccp4_parse_start(), ccp4_parser(), ccp4_signal(), CCP4PARSERARRAY::keyword, and CCP4PARSERARRAY::token.

int MtzPathMatch ( const char *  path1,
const char *  path2 
)

Test for match between two paths, including wildcards

Parameters:
path1 First path
path2 Second path
Returns:
1 if paths match, else 0.

int MtzPrintBatchHeader ( const MTZBAT batch  ) 

int MtzPut ( MTZ mtz,
const char *  logname 
)

int MtzResLimits ( const MTZ mtz,
float *  minres,
float *  maxres 
)

Return the overall resolution limits of the MTZ structure. These are the widest limits over all crystals present.

Parameters:
mtz pointer to MTZ struct
minres minimum resolution
maxres maximum resolution
Returns:
1 on success, 0 on failure

References MTZ::nxtal, MTZXTAL::resmax, MTZXTAL::resmin, and MTZ::xtal.

int MtzRJustPath ( char *  path,
const char *  partial,
const int  njust 
)

Complete a right-justified path by prefixing with wildcards

Parameters:
path Completed path.
partial Partial right-justified path
njust 
Returns:
1 on success, 0 on failure.

References float_uint_uchar::i.

int MtzRrefl ( CCP4File filein,
int  ncol,
float *  refldata 
)

Reads reflection data from MTZ file.

Parameters:
filein pointer to input file
ncol number of columns to read
refldata array of reflection data
Returns:
istat from ccp4_file_read

References ccp4_file_read(), and ccp4_file_setmode().

MTZSET* MtzSetLookup ( const MTZ mtz,
const char *  label 
)

Returns a pointer to the dataset of MTZ with the given label.

Parameters:
mtz pointer to MTZ struct.
label Label of desired set. This could be dname or xname/dname.
Returns:
pointer to set or NULL if not found

References MTZXTAL::nset, MTZ::nxtal, MTZXTAL::set, and MTZ::xtal.

char* MtzSetPath ( const MTZ mtz,
const MTZSET set 
)

Return the full path name of a dataset as "/xname/dname" The pointer to MTZ is required to do reverse lookup of xname. Memory for the path name is assigned with malloc, and can be free'd by the calling function.

Parameters:
mtz pointer to MTZ struct
set pointer to dataset
Returns:
pointer to string containing path name

References ccp4_utils_malloc().

MTZSET** MtzSetsInXtal ( MTZXTAL xtal  ) 

For a given crystal, return array of pointers to datasets in that crystal.

Parameters:
xtal pointer to the crystal struct
Returns:
array of pointers to datasets

References MTZXTAL::set.

int MtzSetSortOrder ( MTZ mtz,
MTZCOL colsort[5] 
)

Sets the sort order in the MTZ header. The sort order is a list of columns to be used for sorting, to be applied in the order they appear in the list, i.e. sort first on colsort[0], then on colsort[1], etc. If there are less than 5 columns to be used for sorting, some of colsort[] may be NULL.

Parameters:
mtz Pointer to MTZ struct
colsort Array of pointers to columns.
Returns:
1 on success, 0 on failure

References float_uint_uchar::i, and MTZ::order.

MTZXTAL* MtzSetXtal ( const MTZ mtz,
const MTZSET set 
)

Get the crystal associated with a dataset The pointer to MTZ is required to do reverse lookup of xname.

Parameters:
mtz pointer to MTZ struct
set pointer to dataset
Returns:
pointer to parent crystal, or NULL if "set" is not present in "mtz".

References MTZXTAL::nset, MTZ::nxtal, MTZXTAL::set, and MTZ::xtal.

int MtzSpacegroupNumber ( const MTZ mtz  ) 

Get the spacegroup number (likely CCP4 convention).

Parameters:
mtz pointer to MTZ struct
Returns:
Spacegroup number.

References MTZ::mtzsymm, and SYMGRP::spcgrp.

int MtzToggleColumn ( MTZCOL col  ) 

Toggle active flag of column. A value of 0 means inactive and will not be written out, whereas a value of 1 means active and will be written out.

Parameters:
col pointer to column
Returns:
New value of col->active.

References MTZCOL::active.

int MtzWhdrLine ( CCP4File fileout,
int  nitems,
char  buffer[] 
)

Write header record to fileout. Record is filled from buffer and padded by blanks to a total length of MTZRECORDLENGTH.

Parameters:
fileout Pointer to output file.
nitems Number of characters in buffer.
buffer Character buffer containing MTZ header line.
Returns:
Number of bytes written on success, EOF on failure.

References ccp4_file_writechar(), float_uint_uchar::i, and MTZRECORDLENGTH.

int MtzWrefl ( CCP4File fileout,
int  ncol,
float *  refldata 
)

Write ncol column entries to fileout from refldata.

Parameters:
fileout pointer to output MTZ file.
ncol number of reflection data items to write.
refldata array of reflection data items.
Returns:
Number of items written. If this is less than ncol, then that indicates a write error.

References ccp4_file_write(), and ccp4_signal().

MTZXTAL* MtzXtalLookup ( const MTZ mtz,
const char *  label 
)

Returns a pointer to the crystal of mtz with the given `label`, or NULL.

Parameters:
mtz pointer to MTZ struct
label 
Returns:
pointer to crystal

References MTZ::nxtal, and MTZ::xtal.

char* MtzXtalPath ( const MTZXTAL xtal  ) 

Return the full path name of a crystal as "/xname" Memory for the path name is assigned with malloc, and can be free'd by the calling function.

Parameters:
xtal pointer to the crystal struct
Returns:
pointer to string containing path name

References ccp4_utils_malloc(), and MTZXTAL::xname.

MTZXTAL** MtzXtals ( MTZ mtz  ) 

Return array of pointers to crystals.

Parameters:
mtz pointer to MTZ struct
Returns:
array of pointers to crystals

References MTZ::xtal.

MTZBAT* sort_batches ( MTZBAT batch,
int  numbat 
)

Sort a linked list of batches on batch number. The function first checks whether batches are already in order, as they will usually be.

Parameters:
batch pointer to beginning of batch list
numbat number of batches to be sorted
Returns:
Sorted list if batches sorted, original list if batches already in order

References ccp4_liberr_verbosity(), float_uint_uchar::i, bathead::next, and bathead::num.


Generated on Wed Oct 29 21:05:09 2008 for gpp4 by  doxygen 1.5.6