Module relax_io

Module containing advanced IO functions for relax.

This includes IO redirection, automatic loading and writing of compressed files (both Gzip and BZ2 compression), reading and writing of files, processing of the contents of files, etc.

Classes

DummyFileObject

SplitIO

Functions

delete(file_name, dir=None, fail=True)
Deleting the given file, taking into account missing compression extensions.

(int, str) determine_compression(file_path)
Function for determining the compression type, and for also testing if the file exists.

list of lists of str extract_data(file=None, dir=None, file_data=None, sep=None)
Return all data in the file as a list of lines where each line is a list of line elements.

str file_root(file_path)
Return the root file name, striped of path and extension details.

str get_file_path(file_name=None, dir=None)
Generate and expand the full file path.

io_streams_restore(verbosity=1)
Restore all IO streams to the Python defaults.

io_streams_log(file_name=None, dir=None, verbosity=1)
Turn on logging, sending both STDOUT and STDERR streams to a file.

io_streams_tee(file_name=None, dir=None, compress_type=0, verbosity=1)
Turn on teeing to split both STDOUT and STDERR streams and sending second part to a file.

mkdir_nofail(dir=None, verbosity=1)
Create the given directory, or exit without raising an error if the directory exists.

file object open_read_file(file_name=None, dir=None, verbosity=1)
Open the file 'file' and return all the data.

writable file object (if return_path, then a tuple of the writable file and the full file path) open_write_file(file_name=None, dir=None, force=False, compress_type=0, verbosity=1, return_path=False)
Function for opening a file for writing and creating directories if necessary.

str, list of [str, float], or list of [str, float, float] read_spin_data(file=None, dir=None, file_data=None, spin_id_col=None, mol_name_col=None, res_num_col=None, res_name_col=None, spin_num_col=None, spin_name_col=None, data_col=None, error_col=None, sep=None, spin_id=None)
Generator function for reading the spin specific data from file.

list of lists of str strip(data, comments=True)
Remove all comment and empty lines from the file data structure.

test_binary(binary)
Function for testing that the binary string corresponds to a valid executable file.

write_spin_data(file, dir=None, sep=None, spin_ids=None, mol_names=None, res_nums=None, res_names=None, spin_nums=None, spin_names=None, force=False, data=None, data_name=None, data_length=20, data_format=None, error=None, error_name=None, error_length=20, error_format=None)
Generator function for reading the spin specific data from file.

Variables

__package__ = None
hash(x)

Imports: dep_check, BZ2File, GzipFile, devnull, F_OK, X_OK, access, altsep, getenv, makedirs, pathsep, remove, sep, expanduser, basename, splitext, match, search, split, sys, stdin, stdout, stderr, warn, generic_fns, generate_spin_id_data_array, RelaxError, RelaxFileError, RelaxFileOverwriteError, RelaxInvalidSeqError, RelaxMissingBinaryError, RelaxNoInPathError, RelaxNonExecError, RelaxWarning, RelaxFileEmptyWarning

Function Details

delete(file_name, dir=None, fail=True)

Deleting the given file, taking into account missing compression extensions.

Parameters:

• file_name (str) - The name of the file to delete.
• dir (None or str) - The directory containing the file.
• fail (bool) - A flag which if True will cause RelaxFileError to be raised.

Raises:

• RelaxFileError - If the file does not exist, and fail is set to true.

determine_compression(file_path)

Function for determining the compression type, and for also testing if the file exists.

Parameters:

• file_path (str) - The full file path of the file.

Returns: (int, str)

A tuple of the compression type and full path of the file (including its extension). A value of 0 corresponds to no compression. Bzip2 compression corresponds to a value of 1. Gzip compression corresponds to a value of 2.

extract_data(file=None, dir=None, file_data=None, sep=None)

Return all data in the file as a list of lines where each line is a list of line elements.

Parameters:

• file (str or file object) - The file to extract the data from.
• dir (str or None) - The path where the file is located. If None and the file argument is a string, then the current directory is assumed.
• file_data (list of str) - If the file data has already been extracted from the file, it can be passed into this function using this argument. If data is supplied here, then the file_name and dir args are ignored.
• sep (str) - The character separating the columns in the file data. If None, then whitespace is assumed.

Returns: list of lists of str

The file data.

file_root(file_path)

Return the root file name, striped of path and extension details.

Parameters:

• file_path (str) - The full path to the file.

Returns: str

The file root (with all directories and the extension stripped away).

get_file_path(file_name=None, dir=None)

Generate and expand the full file path.

Parameters:

• file_name (str) - The name of the file to extract the data from.
• dir (str) - The path where the file is located. If None, then the current directory is assumed.

Returns: str

The full file path.

io_streams_restore(verbosity=1)

Restore all IO streams to the Python defaults.

Parameters:

• verbosity (int) - The verbosity level.

io_streams_log(file_name=None, dir=None, verbosity=1)

Turn on logging, sending both STDOUT and STDERR streams to a file.

Parameters:

• file_name (str) - The name of the file.
• dir (str) - The path where the file is located. If None, then the current directory is assumed.
• verbosity (int) - The verbosity level.

io_streams_tee(file_name=None, dir=None, compress_type=0, verbosity=1)

Turn on teeing to split both STDOUT and STDERR streams and sending second part to a file.

Parameters:

• file_name (str) - The name of the file.
• dir (str) - The path where the file is located. If None, then the current directory is assumed.
• compress_type (int) - The compression type. The integer values correspond to the compression type: 0, no compression; 1, Bzip2 compression; 2, Gzip compression.
• verbosity (int) - The verbosity level.

mkdir_nofail(dir=None, verbosity=1)

Create the given directory, or exit without raising an error if the directory exists.

Parameters:

• dir (str) - The directory to create.
• verbosity (int) - The verbosity level.

open_read_file(file_name=None, dir=None, verbosity=1)

Open the file 'file' and return all the data.

Parameters:

• file_name (str) - The name of the file to extract the data from.
• dir (str) - The path where the file is located. If None, then the current directory is assumed.
• verbosity (int) - The verbosity level.

Returns: file object

The open file object.

open_write_file(file_name=None, dir=None, force=False, compress_type=0, verbosity=1, return_path=False)

Function for opening a file for writing and creating directories if necessary.

Parameters:

• file_name (str) - The name of the file to extract the data from.
• dir (str) - The path where the file is located. If None, then the current directory is assumed.
• force (bool) - Boolean argument which if True causes the file to be overwritten if it already exists.
• compress_type (int) - The compression type. The integer values correspond to the compression type: 0, no compression; 1, Bzip2 compression; 2, Gzip compression.
• verbosity (int) - The verbosity level.
• return_path (bool) - If True, the function will return a tuple of the file object and the full file path.

Returns: writable file object (if return_path, then a tuple of the writable file and the full file path)

The open, writable file object and, if the return_path is True, then the full file path is returned as well.

read_spin_data(file=None, dir=None, file_data=None, spin_id_col=None, mol_name_col=None, res_num_col=None, res_name_col=None, spin_num_col=None, spin_name_col=None, data_col=None, error_col=None, sep=None, spin_id=None)

Generator function for reading the spin specific data from file.

Description

This function reads a columnar formatted file where each line corresponds to a spin system. Spin identification is either through a spin ID string or through columns containing the molecule name, residue name and number, and/or spin name and number.

Parameters:

• file (str) - The name of the file to open.
• dir (str or None) - The directory containing the file (defaults to the current directory if None).
• file_data (list of lists) - An alternative to opening a file, if the data already exists in the correct format. The format is a list of lists where the first index corresponds to the row and the second the column.
• spin_id_col (int or None) - The column containing the spin ID strings. If supplied, the mol_name_col, res_name_col, res_num_col, spin_name_col, and spin_num_col arguments must be none.
• mol_name_col (int or None) - The column containing the molecule name information. If supplied, spin_id_col must be None.
• res_name_col (int or None) - The column containing the residue name information. If supplied, spin_id_col must be None.
• res_num_col (int or None) - The column containing the residue number information. If supplied, spin_id_col must be None.
• spin_name_col (int or None) - The column containing the spin name information. If supplied, spin_id_col must be None.
• spin_num_col (int or None) - The column containing the spin number information. If supplied, spin_id_col must be None.
• data_col (int or None) - The column containing the data.
• error_col (int or None) - The column containing the errors.
• sep (str or None) - The column separator which, if None, defaults to whitespace.
• spin_id (None or str) - The spin ID string used to restrict data loading to a subset of all spins.

Returns: str, list of [str, float], or list of [str, float, float]

A list of the spin specific data is yielded. The format is a list consisting of the spin ID string, the data value (if data_col is give), and the error value (if error_col is given). If both data_col and error_col are None, then the spin ID string is simply yielded.

strip(data, comments=True)

Remove all comment and empty lines from the file data structure.

Parameters:

• data (list of lists of str) - The file data to clean up.
• comments (bool) - A flag which if True will cause comments to be deleted.

Returns: list of lists of str

The input data with the empty and comment lines removed.

test_binary(binary)

Function for testing that the binary string corresponds to a valid executable file.

Parameters:

• binary (str) - The name or path of the binary executable file.

write_spin_data(file, dir=None, sep=None, spin_ids=None, mol_names=None, res_nums=None, res_names=None, spin_nums=None, spin_names=None, force=False, data=None, data_name=None, data_length=20, data_format=None, error=None, error_name=None, error_length=20, error_format=None)

Generator function for reading the spin specific data from file.

Description

This function writes a columnar formatted file where each line corresponds to a spin system. Spin identification is either through a spin ID string or through columns containing the molecule name, residue name and number, and/or spin name and number.

Parameters:

• file (str or file object) - The name of the file to write the data to (or alternatively an already opened file object).
• dir (str or None) - The directory to place the file into (defaults to the current directory if None and the file argument is not a file object).
• sep (str or None) - The column separator which, if None, defaults to whitespace.
• spin_ids (None or list of str) - The list of spin ID strings.
• mol_names (None or list of str) - The list of molecule names.
• res_nums (None or list of int) - The list of residue numbers.
• res_names (None or list of str) - The list of residue names.
• spin_nums (None or list of int) - The list of spin numbers.
• spin_names (None or list of str) - The list of spin names.
• force (bool) - A flag which if True will cause an existing file to be overwritten.
• data (list or list of lists) - A list of the data to write out. The first dimension corresponds to the spins. A second dimension can also be given if multiple data sets across multiple columns are desired.
• data_name (str or list of str) - A name corresponding to the data argument. If the data argument is a list of lists, then this must also be a list with the same length as the second dimension of the data arg.
• data_length (int) - The length of the data columns.
• data_format (None or str) - The optional python formatting string for the data columns, e.g. "%-30s".
• error (list or list of lists) - A list of the errors to write out. The first dimension corresponds to the spins. A second dimension can also be given if multiple data sets across multiple columns are desired. These will be inter-dispersed between the data columns, if the data is given. If the data arg is not None, then this must have the same dimensions as that object.
• error_name (str or list of str) - A name corresponding to the error argument. If the error argument is a list of lists, then this must also be a list with the same length at the second dimension of the error arg.
• error_length (int) - The length of the error columns.
• error_format (None or str) - The optional python formatting string for the error columns, e.g. "%-30s".