Main Page   Compound List   File List   Compound Members   File Members   Related Pages  

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

MTZ * MtzGet (const char *logname, int read_refs)
MTZ * MtzGetUserCellTolerance (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)
CCP4File * MtzOpenForWrite (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)
MTZ * MtzMalloc (int nxtal, int nset[])
int MtzFree (MTZ *mtz)
MTZCOL * MtzMallocCol (MTZ *mtz, int nref)
int MtzFreeCol (MTZCOL *col)
MTZBAT * MtzMallocBatch (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)
MTZXTAL * MtzIxtal (const MTZ *mtz, const int ixtal)
char * MtzXtalPath (const MTZXTAL *xtal)
MTZXTAL * MtzXtalLookup (const MTZ *mtz, const char *label)
MTZXTAL * MtzAddXtal (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)
MTZSET * MtzIsetInXtal (const MTZXTAL *xtal, const int iset)
int MtzNset (const MTZ *mtz)
int MtzNumActiveSet (const MTZ *mtz)
MTZXTAL * MtzSetXtal (const MTZ *mtz, const MTZSET *set)
char * MtzSetPath (const MTZ *mtz, const MTZSET *set)
MTZSET * MtzSetLookup (const MTZ *mtz, const char *label)
MTZSET * MtzAddDataset (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)
MTZCOL * MtzIcolInSet (const MTZSET *set, const int icol)
MTZCOL * MtzAddColumn (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)
MTZSET * MtzColSet (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)
MTZCOL * MtzColLookup (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)
MTZBAT * sort_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.

int ccp4_lhprt (  const MTZ *    mtz,
int    iprint
) 
 

Function to print header information in traditional format.

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

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

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.

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

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.

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.

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.

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

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

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

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

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.

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.

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.

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

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. The reflection values are provided in an array "adata". The value in adata[i] will be assigned to the MTZ column pointed to by lookup[i]. Typically, lookup[i] is a pointer returned from an earlier call to MtzAddColumn(). In "in-memory" mode, values are added/updated to column data held in memory. In the traditional file-based mode, a reflection record is written to file. This function will also update the column ranges and the crystal/file resolution limits.

Parameters:
mtz  pointer to MTZ struct
adata  array of reflection column 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

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

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

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

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

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

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.

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

Reads batch arrays into data structure.

Parameters:
intbuf  pointer to integer batch array
fltbuf  pointer to float batch array
batch  pointer to batch structure
Returns:
1 on success, 0 on failure

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

int MtzAssignHKLtoBase (  MTZ *    mtz ) 
 

Assigns HKL columns to the base dataset.

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

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

Writes data structure to batch arrays.

Parameters:
batch  pointer to batch structure
intbuf  pointer to integer batch array
fltbuf  pointer to float batch array
Returns:
1 on success, 0 on failure

char* MtzCallocHist (  int    nhist ) 
 

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

Parameters:
nhist 
Returns:
pointer to history

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

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

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".

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

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

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

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

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

int MtzFreeBatch (  MTZBAT *    batch ) 
 

Frees the memory reserved for 'batch'.

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

int MtzFreeCol (  MTZCOL *    col ) 
 

Frees the memory reserved for 'col'

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

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
) 
 

Reads the contents of the MTZ file into an MTZ structure.

Parameters:
logname  (I) Logical name of MTZ file
read_refs  (I) Whether to read reflections into memory (non-zero) or to read later from file (zero)
Returns:
Pointer to MTZ struct

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

Reads the contents of the MTZ file into an MTZ structure. As for function MtzGet except for extra argument cell_tolerance.

Parameters:
logname  (I) Logical name of MTZ file
read_refs  (I) Whether to read reflections into memory (non-zero) or to read later from file (zero)
cell_tolerance  (I) User-defined tolerance for ccp4uc_cells_differ. Setting this to zero means that a new crystal is generated whenever dataset cell dimensions are different. MtzGet allows for a certain variation within a single crystal.
Returns:
Pointer to MTZ struct

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

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

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

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.

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.

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

MTZBAT* MtzMallocBatch (  void    ) 
 

Allocates memory for a single batch header.

Returns:
pointer to batch

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.

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.

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

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

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.

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

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

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

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

int MtzNumActiveSetsInXtal (  const MTZ *    mtz,
const MTZXTAL *    xtal
) 
 

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

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

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

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

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

CCP4File* MtzOpenForWrite (  const char *    logname ) 
 

Opens a new MTZ file for writing. The output file can be specified either with a true filename, or more likely as a logical name corresponding to an environment variable or a CCP4 command line argument such as HKLOUT.

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

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.

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 ) 
 

Function to print batch header data for a specified batch to stdout.

Parameters:
batch  Pointer to requested batch.
Returns:
1 on success, 0 on failure

int MtzPut (  MTZ *    mtz,
const char *    logname
) 
 

Writes an MTZ data structure to disk. If file is already open, MtzPut uses file pointer in mtz struct, else uses logical name of file.

Parameters:
mtz  pointer to MTZ struct.
logname  logical name for output file or blank.
Returns:
1 on success, 0 on failure

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

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.

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

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

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

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

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

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".

int MtzSpacegroupNumber (  const MTZ *    mtz ) 
 

Get the spacegroup number (likely CCP4 convention).

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

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.

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.

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.

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

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

MTZXTAL** MtzXtals (  MTZ *    mtz ) 
 

Return array of pointers to crystals.

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

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