7.26. ChainReader — MDAnalysis.coordinates.chain

The ChainReader is used by MDAnalysis internally to represent multiple trajectories as one virtual trajectory. Users typically do not need to use the ChainReader explicitly and the following documentation is primarily of interest to developers.

class MDAnalysis.coordinates.chain.ChainReader(filenames, **kwargs)[source]

Reader that concatenates multiple trajectories on the fly.

The ChainReader is used by MDAnalysis internally to represent multiple trajectories as one virtual trajectory. Users typically do not need to use the ChainReader explicitly.

Notes

The trajectory API attributes exist but most of them only reflect the first trajectory in the list; ChainReader.n_frames, ChainReader.n_atoms, and ChainReader.fixed are properly set, though

Changed in version 0.11.0: Frames now 0-based instead of 1-based

Changed in version 0.13.0: time now reports the time summed over each trajectory’s frames and individual dt.

Set up the chain reader.

Parameters:
  • filenames (str or list or sequence) –

    file name or list of file names; the reader will open all file names and provide frames in the order of trajectories from the list. Each trajectory must contain the same number of atoms in the same order (i.e. they all must belong to the same topology). The trajectory format is deduced from the extension of each file name.

    Extension: filenames are either a single file name or list of file names in either plain file names format or (filename, format) tuple combination. This allows explicit setting of the format for each individual trajectory file.

  • skip (int (optional)) – skip step (also passed on to the individual trajectory readers); must be same for all trajectories
  • dt (float (optional)) – Passed to individual trajectory readers to enforce a common time difference between frames, in MDAnalysis time units. If not set, each reader’s dt will be used (either inferred from the trajectory files, or set to the reader’s default) when reporting frame times; note that this might lead an inconsistent time difference between frames.
  • **kwargs (dict (optional)) – all other keyword arguments are passed on to each trajectory reader unchanged

Changed in version 0.8: The delta keyword was added.

Changed in version 0.13: The delta keyword was deprecated in favor of using dt.

_get_local_frame(k)[source]

Find trajectory index and trajectory frame for chained frame k.

Parameters:k (int) –

Frame k in the chained trajectory can be found in the trajectory at index i and frame index f.

Frames are internally treated as 0-based indices into the trajectory.

Returns:(i, f)local frame tuple
Return type:tuple
Raises:IndexError for k<0 or i<0.

Note

Does not check if k is larger than the maximum number of frames in the chained trajectory.

_apply(method, **kwargs)[source]

Execute method with kwargs for all readers.

_get(attr)[source]

Get value of attr for all readers.

_get_same(attr)[source]

Verify that attr has the same value for all readers and return value.

Parameters:attr (str) – attribute name
Returns:value – common value of the attribute
Return type:int or float or str or object
Raises:ValueError if not all readers have the same value
_read_frame(frame)[source]

Position trajectory at frame index frame and return Timestep.

The frame is translated to the corresponding reader and local frame index and the Timestep instance in ChainReader.ts is updated.

Notes

frame is 0-based, i.e. the first frame in the trajectory is accessed with frame = 0.

_chained_iterator()[source]

Iterator that presents itself as a chained trajectory.

active_reader

Reader instance from which frames are currently being read.

close()[source]

Close the trajectory file.

compressed

compressed attribute of the currently read trajectory

convert_pos_from_native(x)[source]

Conversion of coordinate array x from native units to base units.

Parameters:
  • x (array_like) – Positions to transform
  • inplace (bool (optional)) – Whether to modify the array inplace, overwriting previous data

Note

By default, the input x is modified in place and also returned. In-place operations improve performance because allocating new arrays is avoided.

Changed in version 0.7.5: Keyword inplace can be set to False so that a modified copy is returned unless no conversion takes place, in which case the reference to the unmodified x is returned.

convert_pos_to_native(x)[source]

Conversion of coordinate array x from base units to native units.

Parameters:
  • x (array_like) – Positions to transform
  • inplace (bool (optional)) – Whether to modify the array inplace, overwriting previous data

Note

By default, the input x is modified in place and also returned. In-place operations improve performance because allocating new arrays is avoided.

Changed in version 0.7.5: Keyword inplace can be set to False so that a modified copy is returned unless no conversion takes place, in which case the reference to the unmodified x is returned.

convert_time_from_native(t)[source]

Convert time t from native units to base units.

Parameters:
  • t (array_like) – Time values to transform
  • inplace (bool (optional)) – Whether to modify the array inplace, overwriting previous data

Note

By default, the input t is modified in place and also returned (although note that scalar values t are passed by value in Python and hence an in-place modification has no effect on the caller.) In-place operations improve performance because allocating new arrays is avoided.

Changed in version 0.7.5: Keyword inplace can be set to False so that a modified copy is returned unless no conversion takes place, in which case the reference to the unmodified x is returned.

convert_time_to_native(t)[source]

Convert time t from base units to native units.

Parameters:
  • t (array_like) – Time values to transform
  • inplace (bool, optional) – Whether to modify the array inplace, overwriting previous data

Note

By default, the input t is modified in place and also returned. (Also note that scalar values t are passed by value in Python and hence an in-place modification has no effect on the caller.)

Changed in version 0.7.5: Keyword inplace can be set to False so that a modified copy is returned unless no conversion takes place, in which case the reference to the unmodified x is returned.

filename

Filename of the currently read trajectory

frame

Cumulative frame number of the current time step.

periodic

periodic attribute of the currently read trajectory

rewind()[source]

Set current frame to the beginning.

time

Cumulative time of the current frame in MDAnalysis time units (typically ps).

units

units attribute of the currently read trajectory