clipper::CCP4MTZfile Class Reference

MTZ import/export parent class for clipper objects. More...

#include <ccp4_mtz_io.h>

Classes
struct	crystalinf
struct	datacolinf
struct	datasetinf
struct	hkldatacol
Public Types
enum	CCP4MTZcolumn_label_mode { Default, Normal, Legacy }
Public Member Functions
	CCP4MTZfile ()
	Constructor: does nothing.
	~CCP4MTZfile ()
	Destructor: close any file that was left open.
void	open_read (const String filename_in)
	Open a file for read access.
void	close_read ()
	Close a file after reading.
void	open_append (const String filename_in, const String filename_out)
	Open a file for read access.
void	close_append ()
	Close a file after reading.
void	open_write (const String filename_out)
	Open a file for read access.
void	close_write ()
	Close a file after reading.
const Spacegroup &	spacegroup () const
	get file spacegroup
const Cell &	cell () const
	get file cell
const Resolution &	resolution () const
	get file resolution
const HKL_sampling &	hkl_sampling () const
	get file HKL sampling
std::vector< String >	column_labels () const
	get column labels
void	import_hkl_list (HKL_info &target)
	read the reflection list from the MTZ
void	import_hkl_info (HKL_info &target, const bool generate=true)
	import parameters of HKL_info object from the MTZ
void	import_crystal (MTZcrystal &cxtl, const String mtzpath)
	import crystal info from the MTZ
void	import_dataset (MTZdataset &cset, const String mtzpath)
	import dataset info from the MTZ
void	import_hkl_data (HKL_data_base &cdata, const String mtzpath)
	mark a hkl_data for import from MTZ
void	export_hkl_info (const HKL_info &target)
	write the reflection list to the MTZ (along with cell, spacegroup)
void	export_crystal (const MTZcrystal &cxtl, const String mtzpath)
	export crystal info from the MTZ
void	export_dataset (const MTZdataset &cset, const String mtzpath)
	export dataset info from the MTZ
void	export_hkl_data (const HKL_data_base &cdata, const String mtzpath)
	mark a hkl_data for export to MTZ
void	import_chkl_data (Container &target, const String mtzpath, const String path="")
	mark a chkl_data container for import from MTZ
void	export_chkl_data (Container &target, const String mtzpath)
	mark a chkl_data container for export to MTZ
std::vector< String >	column_paths () const
	return a vector of strings of the file column names/path
const std::vector< String > &	assigned_paths () const
	return a vector of strings of column names/paths just allocated
String	title () const
	get title for MTZ file
void	set_title (const String &title)
	set title for MTZ file
std::vector< String >	history () const
	get history for MTZ file
void	set_history (const std::vector< String > &history)
	add to history for MTZ file
void	set_column_label_mode (CCP4MTZcolumn_label_mode mode)
	set default column label interpretation mode
void	import_hkl_data (HKL_data_base &cdata, MTZdataset &cset, MTZcrystal &cxtl, const String mtzpath)
void	export_hkl_data (const HKL_data_base &cdata, const MTZdataset &cset, const MTZcrystal &cxtl, const String mtzpath)

Detailed Description

MTZ import/export parent class for clipper objects.

This is the import/export class which can be linked to an mtz file and be used to transfer data into or out of a Clipper data structure.

Note that to access the MTZ file efficiently, data reads and writes are deferred until the file is closed.

MTZpaths: MTZ column specification

Note that the specification of the MTZ column names is quite versatile. The MTZ crystal and dataset must be specified, although the wildcard '*' may replace a complete name. Several MTZ columns will correspond to a single datalist. This may be handled in two ways:

A simple name. The corresponding MTZ columns will be named after the datalist name, a dot, the datalist type, a dot, and a type name for the indivudal column, i.e. /crystal/dataset/datalist.listtype.coltype This is the default Clipper naming convention for MTZ data.
A comma separated list of MTZ column names enclosed in square brackets. This allows MTZ data from legacy applications to be accessed.
Thus, for example, an MTZPATH of
```
    native/CuKa/fsigfdata
```
expands to MTZ column names of
```
    fsigfdata.F_sigF.F
    fsigfdata.F_sigF.sigF
```
with a crystal called native and a dataset called CuKa. An MTZPATH of
```
    native/CuKa/[FP,SIGFP]
```
expands to MTZ column names of
```
    FP
    SIGFP
```
with a crystal called native and a dataset called CuKa.

MTZ_iotypes

MTZ_iotypes: Import/export types

For an HKL_data object to be imported or exported, an MTZ_iotype for that datatype must exist in the MTZ_iotypes_registry. MTZ_iotypes are defined for all the built-in datatypes. If you need to store a user defined type in an MTZ file, then register that type with the MTZ_iotypes_registry.

Constructor & Destructor Documentation

clipper::CCP4MTZfile::CCP4MTZfile ( )

Constructor: does nothing.

Constructing an CCP4MTZfile does nothing except flag the object as not attached to any file for either input or output

clipper::CCP4MTZfile::~CCP4MTZfile ( )

Destructor: close any file that was left open.

Close any files which were left open. This is particularly important since to access the MTZ file efficiently, data reads and writes are deferred until the file is closed.

References close_append(), close_read(), and close_write().

Member Function Documentation

void clipper::CCP4MTZfile::open_read ( const String filename_in )

Open a file for read access.

The file is opened for reading. This CCP4MTZfile object will remain attached to this file until it is closed. Until that occurs, no other file may be opened with this object, however another CCP4MTZfile object could be used to access another file.

Parameters:

filename_in

The input filename or pathname.

References clipper::Resolution::init(), clipper::Util::max(), and clipper::message.

void clipper::CCP4MTZfile::close_read ( )

Close a file after reading.

Close the file after reading. This command also actually fills in the data in any HKL_data structures which have been marked for import.

References clipper::Util::intr(), clipper::message, clipper::Util::set_null(), and clipper::String::tail().

Referenced by ~CCP4MTZfile().

void clipper::CCP4MTZfile::open_append	(	const String	filename_in,
		const String	filename_out
	)

Open a file for read access.

A file is opened for appending. One file is opened for reading, and a second is opened for writing. The second file will contain all the information from the first, plus any additional columns exported from HKL_data objects.

Parameters:

	filename_in	The input filename or pathname.
	filename_out	The output filename or pathname.

References clipper::Resolution::init(), clipper::Util::max(), and clipper::message.

void clipper::CCP4MTZfile::close_append ( )

Close a file after reading.

Close the files after appending. This command actually copies the input file to the output file, adding data from any HKL_data objects which have been marked for import.

References clipper::Util::intr(), clipper::Util::is_nan(), clipper::Message::message(), clipper::message, and clipper::String::tail().

Referenced by ~CCP4MTZfile().

void clipper::CCP4MTZfile::open_write ( const String filename_out )

Open a file for read access.

The file is opened for writing. This will be a new file, created entirely from data from within the program, rather than by extending an existing file. Similar restrictions apply as for open_read().

In practice the open_append() method is usually preferred.

Parameters:

filename_out

The output filename or pathname.

References clipper::message.

void clipper::CCP4MTZfile::close_write ( )

Close a file after reading.

Close the file after writing. This command also actually writes the data reflection list from the HKL_info object and the data from any HKL_data objects which have been marked for import.

References clipper::HKL_info::cell(), clipper::HKL::h(), clipper::HKL_info::hkl_of(), clipper::Util::is_nan(), clipper::HKL::k(), clipper::HKL::l(), clipper::message, clipper::HKL_info::num_reflections(), and spacegroup().

Referenced by ~CCP4MTZfile().

const Spacegroup & clipper::CCP4MTZfile::spacegroup ( ) const

get file spacegroup

Get the spacegroup from the MTZ file.

Returns:: The spacegroup.

Referenced by close_write().

const Cell & clipper::CCP4MTZfile::cell ( ) const

get file cell

Get the base cell from the MTZ file.

Returns:: The cell.

const Resolution & clipper::CCP4MTZfile::resolution ( ) const

get file resolution

Get the resolution limit from the MTZ file.

Returns:: The resolution.

const HKL_sampling & clipper::CCP4MTZfile::hkl_sampling ( ) const

get file HKL sampling

Get the HKL sampling from the MTZ file.

Returns:: The hkl_sampling.

std::vector< String > clipper::CCP4MTZfile::column_labels ( ) const

get column labels

Get the column labels from the MTZ file.

Returns:: Array of labels.

void clipper::CCP4MTZfile::import_hkl_list ( HKL_info & target )

read the reflection list from the MTZ

Import the list of reflection HKLs from an MTZ file into an HKL_info object. If the resolution limit of the HKL_info object is lower than the limit of the file, any excess reflections will be rejected, as will any systematic absences or duplicates.

Parameters:

target

The HKL_info object to be initialised.

References clipper::HKL_info::add_hkl_list(), clipper::HKL_info::cell(), clipper::Util::intr(), clipper::HKL::invresolsq(), clipper::Resolution::invresolsq_limit(), clipper::message, clipper::HKL_info::resolution(), and clipper::String::tail().

Referenced by import_hkl_info().

void clipper::CCP4MTZfile::import_hkl_info	(	HKL_info &	target,
		const bool	generate = `true`
	)

import parameters of HKL_info object from the MTZ

Import a complete HKL_info object. The supplied HKL_info object is examined, and if any of the parameters (spacegroup, cell, or resolution) are unset, then they will be set using values from the file. The reflections list will then be generated (the default), or imported from the file.

This method is a shortcut which can generally replace most common combinations of calls to import_spacegroup(), import_cell(), import_resolution() and import_hkl_list().

Parameters:

	target	The HKL_info object to be initialised.
	generate	Generate the list of HKLs rather than importing it from the file.

References clipper::HKL_info::cell(), clipper::HKL_info::generate_hkl_list(), import_hkl_list(), clipper::HKL_info::init(), clipper::Resolution::is_null(), clipper::Cell::is_null(), clipper::Spacegroup::is_null(), clipper::HKL_info::resolution(), and clipper::HKL_info::spacegroup().

void clipper::CCP4MTZfile::import_crystal	(	MTZcrystal &	cxtl,
		const String	mtzpath
	)

import crystal info from the MTZ

Parameters:

	cxtl	The crystal to import.
	mtzpath	The mtz path of the crystal.

References clipper::message, and clipper::String::split().

Referenced by import_chkl_data(), and import_hkl_data().

void clipper::CCP4MTZfile::import_dataset	(	MTZdataset &	cset,
		const String	mtzpath
	)

import dataset info from the MTZ

Parameters:

	cset	The dataset to import.
	mtzpath	The mtz path of the dataset.

References clipper::message, and clipper::String::split().

Referenced by import_chkl_data(), and import_hkl_data().

void clipper::CCP4MTZfile::import_hkl_data	(	HKL_data_base &	cdata,
		const String	mtzpath
	)

mark a hkl_data for import from MTZ

Import data from an MTZ file into an HKL_data object. The dataset and crystal information from the first corresponding MTZ column are also returned.

An MTZ column type must be present in the MTZ_type_registry for the HKL_data type element name concerned.

This routine does not actually read any data, but rather marks the data to be read when the file is closed.

For container objects import_chkl_data() is preferred.

Parameters:

	cdata	The HKL_data object into which data is to be imported.
	mtzpath	The MTZ column names, as a path. See MTZpaths for details.

References clipper::HKL_data_base::data_names(), clipper::HKL_data_base::data_size(), clipper::HKL_data_base::init(), clipper::HKL_data_base::is_null(), clipper::message, clipper::CCP4MTZ_type_registry::scale(), clipper::String::split(), clipper::CCP4MTZ_type_registry::type(), and clipper::HKL_data_base::type().

Referenced by import_chkl_data(), and import_hkl_data().

void clipper::CCP4MTZfile::export_hkl_info ( const HKL_info & target )

write the reflection list to the MTZ (along with cell, spacegroup)

Export a complete HKL_info object, including spacegroup, cell, and list of reflection HKLs from an HKL_info object to an MTZ file. This is compulsory when writing an MTZ file, but forbidden when appending, since the HKLs will then come from the input MTZ.

Parameters:

target

The HKL_info object to supply the parameters.

References clipper::HKL_info::cell(), clipper::message, clipper::HKL_info::resolution(), and clipper::HKL_info::spacegroup().

void clipper::CCP4MTZfile::export_hkl_data	(	const HKL_data_base &	cdata,
		const String	mtzpath
	)

mark a hkl_data for export to MTZ

Export data from an HKL_data object into an MTZ file. MTZdataset and crystal information must be supplied, and will be applied to all columns in the output MTZ.

An MTZ column type must be present in the MTZ_type_registry for the HKL_data type element name concerned.

This routine does not actually write any data, but rather marks the data to be written when the file is closed.

Normally export_chkl_data() is preferred.

Parameters:

	cdata	The HKL_data object from which data is to be exported.
	mtzpath	The MTZ column names, as a path. See MTZpaths for details.

References clipper::HKL_data_base::data_names(), clipper::HKL_data_base::data_size(), clipper::message, clipper::CCP4MTZ_type_registry::scale(), clipper::String::split(), clipper::String::tail(), clipper::CCP4MTZ_type_registry::type(), and clipper::HKL_data_base::type().

Referenced by export_chkl_data(), and export_hkl_data().

void clipper::CCP4MTZfile::import_chkl_data	(	Container &	target,
		const String	mtzpath,
		const String	path = `""`
	)

mark a chkl_data container for import from MTZ

Import data from an MTZ into a CHKL_data object. If they don't already exist, then CMTZcrystal and CMTZdataset objects will be created to match the MTZ crystal and dataset information for the first MTZ column used. These new objects will be children of the parent CHKL_info object, and this CHKL_data will be moved to become a child of the CMTZdataset object.

Thus, to import data into a CHKL_data, you must first create a CHKL_data anywhere below a parent HKL_info. Then call this method, and the object will be moved to a position below the HKL_info corresponding to its position in the data hierarchy in the MTZ file. The following code imports data, dataset, and crystal from an MTZ file:

  CHKL_info myhkl; // must be given cell, spacegroup, and HKL list.
  ...
  CHKL_data<F_sigF> mydata
  CCP4MTZfile file = open_read("in.mtz");
  file.import_chkl_data( mydata, "native/CuKa/[FP,SIGFP]" );
  file.close_read();

An MTZ column type must be present in the MTZ_type_registry for the HKL_data type element name concerned.

This routine does not actually read any data, but rather marks the data to be read when the file is closed.

Parameters:

	target	The HKL_data object into which data is to be imported.
	mtzpath	The MTZ column names, as a path. See MTZpaths for details.
	path	Where to put this in the data hierarchy, overriding the MTZ crystal and dataset.

References clipper::MTZcrystal::crystal_name(), clipper::Container::find_path_ptr(), import_crystal(), import_dataset(), import_hkl_data(), clipper::message, clipper::Container::move(), clipper::String::notail(), clipper::Container::parent_of_type_ptr(), clipper::Container::path(), clipper::Container::set_destroyed_with_parent(), and clipper::String::tail().

void clipper::CCP4MTZfile::export_chkl_data	(	Container &	target,
		const String	mtzpath
	)

mark a chkl_data container for export to MTZ

Export data from a CHKL_data object to an MTZ. The object must have a parent Cdataset and CMTZcrystal to provide the MTZ crystal and dataset information. The MTZ file will be checked for names matching the names of these objects, and the new MTZ columns will be added to the corresponding dataset if it exists, otherwise it will be created.

An MTZ column type must be present in the MTZ_type_registry for the HKL_data type element name concerned.

This routine does not actually write any data, but rather marks the data to be written when the file is closed.

Parameters:

	target	The HKL_data object from which data is to be exported.
	mtzpath	The MTZ column names, as a path. See MTZpaths for details.

References export_crystal(), export_dataset(), export_hkl_data(), clipper::message, and clipper::Container::parent_of_type_ptr().

std::vector< String > clipper::CCP4MTZfile::column_paths ( ) const

return a vector of strings of the file column names/path

Return a vector of all the columns in the MTZ file, including crystal, dataset and type information. The result is a vector of Strings. Each String contains text of the form '/CrystalName/DatasetName/ColumnName Type'.

const std::vector< String > & clipper::CCP4MTZfile::assigned_paths ( ) const

return a vector of strings of column names/paths just allocated

Return a vector of all the columns in the MTZ file used for the previous call to import_hkl_data or export_hkl_data. The result is a vector of Strings. Each String contains text of the form '/CrystalName/DatasetName/ColumnName Type'.

This function is commonly used to add an output column to the same crystal and dataset as a particular input column. e.g.

  String opcol = mtzfile.assigned_paths()[0].notail() + "/[FWT,PHIWT]";

void clipper::CCP4MTZfile::import_hkl_data	(	HKL_data_base &	cdata,
		MTZdataset &	cset,
		MTZcrystal &	cxtl,
		const String	mtzpath
	)

Deprecated:

References import_crystal(), import_dataset(), and import_hkl_data().

void clipper::CCP4MTZfile::export_hkl_data	(	const HKL_data_base &	cdata,
		const MTZdataset &	cset,
		const MTZcrystal &	cxtl,
		const String	mtzpath
	)

Deprecated:

References export_crystal(), export_dataset(), and export_hkl_data().

The documentation for this class was generated from the following files:

ccp4_mtz_io.h
ccp4_mtz_io.cpp

clipper::CCP4MTZfile Class Reference

Classes

Public Types

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation