This Page

Quick search

The coordinates submodule contains code to read coordinates, either
single frames (e.g. the PDB module) or trajectories (such as the DCD
reader). All readers are supposed to expose a Reader object
that presents a common Trajectory API to other code.

that points to the actual Reader
object; all Readers are supposed to be accessible through this entry
point in the same manner (“duck typing”).

In order to write coordinates, a factory function is provided
(MDAnalysis.coordinates.core.writer()) which is made available
as MDAnalysis.Writer()) that returns a Writer appropriate for
the desired file format (as indicated by the filename
suffix). Furthermore, a trajectory
Reader can also have a method
Writer() that returns an
appropriate Writer for the file
format of the trajectory.

The table below lists the coordinate file formats understood by MDAnalysis. The
emphasis is on formats that are used in popular molecular dynamics
codes. MDAnalysis figures out formats by looking at the extension. Thus, a DCD
file always has to end with ”.dcd” to be recognized as such. (A number of files
are also recognized when they are compressed with gzip or
bzip2 such as ”.xyz.bz2”.)

(1, 2, 3, 4, 5) This format can also be used to provide basic topology
information (i.e. the list of atoms); it is possible to create a
full Universe by simply
providing a file of this format: u=Universe(filename)

The Trajectory API defines how classes have to be structured that allow
reading and writing of coordinate files. By following the API it is possible to
seamlessly enhance the I/O capabilities of MDAnalysis. The actual underlying
I/O code can be written in C or python or a mixture thereof.

Typically, each format resides in its own module, named by the format specifier
(and using upper case by convention).

In various places, MDAnalysis tries to automatically select appropriate formats
(e.g. by looking at file extensions). In order to allow it to choose the
correct format, all I/O classes must be registered in one of three dictionaries
with the format (typically the file extension in upper case):

Trajectory reader classes must be added to
MDAnalysis.coordinates._trajectory_readers.

Trajectory writer classes must be added to
MDAnalysis.coordinates._trajectory_writers.

Single-frame writer classes must be added to to
MDAnalysis.coordinates._frame_writers.

These attributes are set directly by the underlying trajectory
readers. Normally the user should not have to directly access those (although in
some cases it is convenient to directly use Timestep._pos).

open filename; other kwargs are processed as needed and the
Reader is free to ignore them. Typically, MDAnalysis supplies as
much information as possible to the Reader in kwargs; at the moment the
following data are supplied in keywords when a trajectory is loaded from
within MDAnalysis.Universe:

numatoms: the number of atoms (known from the topology)

__iter__()

allow iteration from beginning to end:

fortsintrajectory:printts.frame

close()

close the file and cease I/O

__del__()

ensure that the trajectory is closed

next()

advance to next time step or raise IOError when moving
past the last frame

rewind()

reposition to first frame

Optional methods

Not all trajectory formats support the following methods, either because the
data are not available or the methods have not been implemented. Code should
deal with missing methods gracefully.

__len__()

number of frames in trajectory

__getitem__(arg)

advance to time step arg = frame and return Timestep; or if arg is a
slice, then return an iterator over that part of the trajectory.

The first functionality allows one to randomly access frames in the
trajectory:

universe.trajectory[314]

would load frame 314 into the current Timestep.

Using slices allows iteration over parts of a trajectory

fortsinuniverse.trajectory[1000:2000]:process_frame(ts)# do something

or skipping frames

fortsinuniverse.trajectory[1000::100]:process_frame(ts)# do something

The last example starts reading the trajectory at frame 1000 and
reads every 100th frame until the end.

The performance of the __getitem__() method depends on the underlying
trajectory reader and if it can implement random access to frames. In many
cases this is not easily (or reliably) implementable and thus one is
restricted to sequential iteration.

Writer(filename,**kwargs)

returns a Writer which is set up with
the same parameters as the trajectory that is being read (e.g. time step,
length etc), which facilitates copying and simple on-the-fly manipulation.

If no Writer is defined then a NotImplementedError is raised.

The kwargs can be used to customize the Writer as they are typically
passed through to the init method of the Writer, with sensible defaults
filled in; the actual keyword arguments depend on the Writer.

Trajectory readers are derived from
MDAnalysis.coordinates.base.Writer. They are use to write
multiple frames to a trajectory file. Every time the
write() method is called,
another frame is appended to the trajectory.

A single frame writer is a special case of a trajectory writer in that it
writes only a single coordinate frame to a file, for instance, a pdb or gro
file. Unlike trajectory formats, which only contains coordinates, single
frame formats contain much more information (e.g. atom and residue names and
numbers) and hence it is possible to write selections of atoms in a meaningful
way.

Signature:

W=FrameWriter(filename,**kwargs)W.write(AtomGroup)W.write(Universe)

The blanket kwargs is required so that one can pass the same kind of
arguments (filename and numatoms) as for the Trajectory writers. In
this way, the simple writer()
factory function can be used for all writers.

The following data structures connect reader/writer classes to their
format identifiers. They are documented for programmers who want to
enhance MDAnalysis; the casual user is unlikely to access them
directly.