XTCFile#

class biotite.structure.io.xtc.XTCFile[source]#

Bases: TrajectoryFile

This file class represents a XTC trajectory file.

copy()#

This operation is not implemented for trajectory files.

Raises:
NotImplementedError
get_box()#

Get the box vectors for each frame.

Returns:
boxndarray, dtype=float, shape=(m,3,3)

An array containing the box dimensions for the frames, that were read from the file.

get_coord()#

Extract only the atom coordinates from the trajectory file.

Returns:
coordndarray, dtype=float, shape=(m,n,3)

The coordinates stored in the trajectory file.

get_structure(template)#

Convert the trajectory file content into an AtomArrayStack.

Since trajectory files usually only contain atom coordinate information and no topology information, this method requires a template atom array or stack. This template can be acquired for example from a PDB file, which is associated with the trajectory file.

Parameters:
templateAtomArray or AtomArrayStack

The template array or stack, where the atom annotation data is taken from.

Returns:
array_stackAtomArrayStack

A stack containing the annontation arrays from template but the coordinates and the simulation boxes from the trajectory file.

get_time()#

Get the simlation time in ps values for each frame.

Returns:
timendarray, dtype=float, shape=(m,)

A one dimensional array containing the time values for the frames, that were read from the file.

classmethod prepare_write_values(coord, box, time)#

Convert the coord, box and time attribute into a dictionary that is given as kwargs to the respective biotraj.TrajectoryFile.write() method.

PROTECTED: Override when inheriting.

Parameters:
coordndarray, dtype=float, shape=(m,n,3)

The atom coordinates in Å for each frame.

boxndarray, dtype=float, shape=(m,3,3)

The box vectors in Å for each frame.

timendarray, dtype=float, shape=(m,)

The simulation time in ps for each frame.

Returns:
parametersdict

This dictionary is given as kwargs parameter to the respective biotraj.TrajectoryFile.write() method.

classmethod process_read_values(read_values)#

Convert the return value of the read() method of the respective biotraj.TrajectoryFile into coordinates, simulation box and simulation time.

PROTECTED: Override when inheriting.

Parameters:
read_valuestuple

The return value of the respective biotraj.TrajectoryFile.read() method.

Returns:
coordndarray, dtype=float, shape=(m,n,3)

The atom coordinates in Å for each frame.

boxndarray, dtype=float, shape=(m,3,3) or None

The box vectors in Å for each frame.

timendarray, dtype=float, shape=(m,) or None

The simulation time in ps for each frame.

classmethod read(file_name, start=None, stop=None, step=None, atom_i=None, chunk_size=None)#

Read a trajectory file.

A trajectory file can be seen as a file representation of an AtomArrayStack. Therefore, start, stop and step represent slice parameters of the index of the first dimension and atom_i represents an index array for the second dimension.

Parameters:
file_namestr

The path of the file to be read. A file-like-object cannot be used.

startint, optional

The frame index, where file parsing is started. If no value is given, parsing starts at the first frame. The index starts at 0.

stopint, optional

The exclusive frame index, where file parsing ends. If no value is given, parsing stops after the last frame. The index starts at 0.

stepint, optional

If this value is set, the function reads only every n-th frame from the file.

atom_indarray, dtype=int, optional

If this parameter is set, only the atoms at the given indices are read from each frame.

chunk_sizeint, optional

If this parameter is set, the trajectory is read in chunks: Only the number of frames specified by this parameter are read at once. The resulting chunks of frames are automatically concatenated, after all chunks are collected. Use this parameter, if a MemoryError is raised when a trajectory file is read. Although lower values can decrease the memory consumption of reading trajectories, they also increase the computation time.

Returns:
file_objectTrajectoryFile

The parsed trajectory file.

classmethod read_iter(file_name, start=None, stop=None, step=None, atom_i=None, stack_size=None)#

Create an iterator over each frame of the given trajectory file in the selected range.

Parameters:
file_namestr

The path of the file to be read. A file-like-object cannot be used.

startint, optional

The frame index, where file parsing is started. If no value is given, parsing starts at the first frame. The index starts at 0.

stopint, optional

The exclusive frame index, where file parsing ends. If no value is given, parsing stops at the end of file. The index starts at 0.

stepint, optional

If this value is set, the function reads only every n-th frame from the file.

atom_indarray, dtype=int, optional

If this parameter is set, only the atoms at the given indices are read from each frame.

stack_sizeint, optional

If this parameter is set, the given number of frames m are read at once. As result an additional dimension is added to the return values. If the number of frames is not a multiple of stack_size, the final stack is smaller than stack_size.

Yields:
coordndarray, dtype=float32, shape=(n,3) or shape=(m,n,3)

The atom coordinates in the current frame or stack.

boxndarray, dtype=float32, shape=(3,3) or shape=(m,3,3) or None

The box vectors of the current frame or stack.

timefloat or ndarray, dtype=float32, shape=(n,) or None

The simulation time of the current frame or stack in ps.

Notes

The step parameter does currently not work for DCD files.

classmethod read_iter_structure(file_name, template, start=None, stop=None, step=None, atom_i=None, stack_size=None)#

Create an iterator over each frame of the given trajectory file in the selected range.

In contrast to read_iter(), this function creates an iterator over the structure as AtomArray. Since trajectory files usually only contain atom coordinate information and no topology information, this method requires a template atom array or stack. This template can be acquired for example from a PDB file, which is associated with the trajectory file.

Parameters:
file_namestr

The path of the file to be read. A file-like-object cannot be used.

templateAtomArray or AtomArrayStack

The template array or stack, where the atom annotation data is taken from.

startint, optional

The frame index, where file parsing is started. If no value is given, parsing starts at the first frame. The index starts at 0.

stopint, optional

The exclusive frame index, where file parsing ends. If no value is given, parsing stops at the end of file. The index starts at 0.

stepint, optional

If this value is set, the function reads only every n-th frame from the file.

atom_indarray, dtype=int, optional

If this parameter is set, only the atoms at the given indices are read from each frame in the file.

stack_sizeint, optional

If this parameter is set, multiple frames are combined into an AtomArrayStack. The number of frames in the AtomArrayStack is determined by this parameter. If the number of frames is not a multiple of stack_size, the final stack is smaller than stack_size.

Yields:
structureAtomArray or AtomArrayStack

The structure of the current frame as AtomArray. If stack_size is set, multiple frames are returned as AtomArrayStack.

See also

read_iter

Notes

This iterator creates a new copy of the given template for every frame (or stack of frames, if stack_size is set). If a higher efficiency is required, please use the read_iter() function.

The step parameter does currently not work for DCD files.

set_box(box)#

Set the periodic box vectors of each frame in the trajectory file.

Parameters:
timendarray, dtype=float, shape=(m,3,3)

The box vectors to be set.

set_coord(coord)#

Set the atom coordinates in the trajectory file.

Parameters:
coordndarray, dtype=float, shape=(m,n,3)

The coordinates to be set.

set_structure(structure, time=None)#

Write an atom array (stack) into the trajectory file object.

The topology information (chain, residue, etc.) is not saved in the file.

Parameters:
structureAtomArray or AtomArrayStack

The structure to be put into the trajectory file.

timendarray, dtype=float, shape=(n,), optional

The simulation time for each frame in structure.

set_time(time)#

Set the simulation time of each frame in the trajectory file.

Parameters:
timendarray, dtype=float, shape=(m,)

The simulation time in ps to be set.

classmethod traj_type()#

The biotraj files class to be used.

PROTECTED: Override when inheriting.

Returns:
class

An biotraj subclass of TrajectoryFile.

write(file_name)#

Write the content into a trajectory file.

Parameters:
file_namestr

The path of the file to be written to. A file-like-object cannot be used.

classmethod write_iter(file_name, coord, box=None, time=None)#

Iterate over the given coord and write each item into the file specified by file_name.

In contrast to write(), the data is not stored in an intermediate TrajectoryFile, but is directly written to the file. Hence, this class method may save a large amount of memory if a large file should be written, if coord are provided as generator.

Parameters:
file_namestr

The path of the file to be written to. A file-like-object cannot be used.

coordgenerator or array-like of ndarray, shape=(n,3), dtype=float

The atom coordinates for each frame.

boxgenerator or array-like of ndarray, shape=(3,3), dtype=float, optional

The three box vectors for each frame.

timegenerator or array-like of float, optional

The simulation time in ps for each frame.

Notes

The time parameter has no effect for DCD files.