biotite.structure.io.TrajectoryFile

class biotite.structure.io.TrajectoryFile[source]

Bases: File

This file class represents a trajectory file interfacing a trajectory file class from MDtraj.

A trajectory file stores atom coordinates over multiple (time) frames. The file formats are usually binary and involve sometimes heavy compression, so that a large number of frames can be stored in relatively small space. Since all TrajectoryFile subclasses interface MDtraj trajectory file classes, MDtraj must be installed to use any of them.

Notes

When extracting data from the file, only a reference to the data arrays stored in this file are created. The same is true, when setting data in the file. Therefore, it is strongly recommended to make a copy of the respective array, if the array is modified.

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.

abstract 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 mdtraj.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 mdtraj.TrajectoryFile.write() method.

abstract classmethod process_read_values(read_values)

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

PROTECTED: Override when inheriting.

Parameters
read_valuestuple

The return value of the respective mdtraj.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.

abstract classmethod traj_type()

The MDtraj files class to be used.

PROTECTED: Override when inheriting.

Returns
class

An MDtraj 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 TNG and DCD files.