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.
See also
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 asAtomArray
. 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 theAtomArrayStack
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 asAtomArrayStack
.
See also
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 ofTrajectoryFile
.
- 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 intermediateTrajectoryFile
, 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.
Gallery#
Basic analysis of a MD simulation
BinaryCIF as trajectory format
Secondary structure during an MD simulation