11.2. Auxiliary Readers — MDAnalysis.auxiliary.base

Base classes for deriving all auxiliary data readers. See the API in MDAnalysis.auxiliary.__init__.

class MDAnalysis.auxiliary.base.AuxStep(dt=1, initial_time=0, time_selector=None, data_selector=None, constant_dt=True, memory_limit=None)

Base class for auxiliary timesteps.

Stores the auxiliary data for the current auxiliary step. On creation, step is set to -1.

Changed in version 2.4.0: Added memory_limit parameter to control raising memory usage warnings.

Parameters:

• dt (float, optional) – Change in time between auxiliary steps (in ps). If not specified, will attempt to determine from auxiliary data; otherwise defaults to 1 ps. Ignored if constant_dt is False.

• initial_time (float, optional) – Time of first auxiliary step (in ps). If not specified, will attempt to determine from auxiliary data; otherwise defaults to 0 ps. Ignored if constant_dt is False.

• time_selector (optional) – Key to select ‘time’ value from the full set of data read for each step, if time selection is enabled; type will vary depending on the auxiliary data format (see individual AuxReader documentation). If None (default value), time is instead calculated as: time = step * dt + initial_time

• data_selector (optional) – Key(s) to select auxiliary data values of interest from the full set of data read for each step, if data selection is enabled by the reader; type will vary depending on the auxiliary data format (see individual AuxReader documentation). If None (default value), the full set of data is returned.

• constant_dt (bool, optional) – (Default: True) Set to False if dt is not constant throughout the auxiliary data set, in which case a valid time_selector must be provided.

• memory_limit (float, optional) – Sets the threshold of memory usage by auxiliary data (in GB) at which to issue a warning. Default: 1 GB.

step

Number of the current auxiliary step (0-based).

Type:

int

property data

Auxiliary values of interest for the current step (as ndarray).

Read from the full set of data read for each step if data selection is enabled and a valid data_selector is specified; otherwise defaults to the full set of data.

property time

Time in ps of current auxiliary step (as float).

Read from the set of auxiliary data read each step if time selection is enabled and a valid time_selector is specified; otherwise calculated as step * dt + initial_time.

class MDAnalysis.auxiliary.base.AuxReader(represent_ts_as='closest', auxname=None, cutoff=None, **kwargs)

Base class for auxiliary readers.

Allows iteration over a set of data from a trajectory, additional (‘auxiliary’) to the regular positions/velocities/etc. This auxiliary data may be stored in e.g. an array or a separate file.

See the Auxiliary API for more on use.

Changed in version 2.4.0: Behaviour of cutoff changed, default parameter which specifies not cutoff is set is now None, not -1.

Changed in version 2.4.0: AuxReader instances now have a copy() method which creates a deep copy of the instance.

Parameters:

• auxname (str, optional) – Name for auxiliary data. When added to a trajectory, the representative auxiliary value(s) for the timestep may be accessed as ts.aux.auxname or ts.aux['auxname'].

• represent_ts_as (str) – Method to use to calculate representative value of auxiliary data for a trajectory timestep. See calc_representative() for valid options.

• cutoff (float, optional) – Auxiliary steps further from the trajectory timestep than cutoff (in ps) will be ignored when calculating representative values. If None (default), all auxiliary steps assigned to that timestep will be used.

• **kwargs – Options to be passed to AuxStep

auxstep

AuxStep object containing data for current step.

frame_data

Dictionary containing data from each auxiliary step assigned to the current trajectory timestep, indexed by the difference in time between the step and trajectory timestep (i.e. auxstep.time - ts.time; in ps)

Type:

dict

frame_rep

Representative value(s) of auxiliary data for current trajectory timestep.

Type:

ndarray

Note

Auxiliary data are assumed to be time ordered and contain no duplicates.

attach_auxiliary(coord_parent, aux_spec: str | Dict[str, str] | None = None, format: str | None = None, **kwargs) → None

Attaches the data specified in aux_spec to the coord_parent

This method is called from within MDAnalysis.coordinates.base.ReaderBase.add_auxiliary(). add_auxiliary should be agnostic to the type of AuxReader, so the method call leads here instead. First, some checks are done on the arguments to make sure the input is treated properly. Then, the AuxReader(s) with appropriate data_selector are associated with the coord_parent from which add_auxiliary was called.

Parameters:

• coord_parent (MDAnalysis.coordinates.base.ReaderBase) – Reader object to which to attach the auxiliary data.

• aux_spec (str, Dict[str, str], None) – Specifies which data to add to coord_parent. String types are for MDAnalysis.auxiliary.XVG.XVGReader only. Dictionaries are the standard way of providing aux_spec information (see also: MDAnalysis.auxiliary.EDR). Passing None causes all data to be added.

Return type:

None

Raises:

ValueError – If trying to add data under an aux_spec key that is already assigned.

calc_representative()

Calculate representative auxiliary value(s) from the data in frame_data.

Currently implemented options for calculating representative value are:

• closest: default; the value(s) from the step closest to in time to the trajectory timestep

• average: average of the value(s) from steps ‘assigned’ to the trajectory timestep.

Additionally, if cutoff is specified, only steps within this time of the trajectory timestep are considered in calculating the representative.

If no auxiliary steps were assigned to the timestep, or none fall within the cutoff, representative values are set to np.nan.

Returns:

Array of auxiliary value(s) ‘representative’ for the timestep.

Return type:

ndarray

property constant_dt

True if dt is constant throughout the auxiliary (as stored in auxstep)

copy()

Returns a deep copy of the AuxReader

property data_selector

Key(s) to select auxiliary data values of interest from the full set of data read for each step (as stored in auxstep).

Type differs between auxiliary formats, depending how the data for each step is read in and stored - e.g. data from .xvg files is read in as a list and data_selector must be a list of valid indicies. If data selection is not enabled by the reader, data_selector will default to None.

See each individual auxiliary reader.

property dt

Change in time between auxiliary steps (as stored in auxstep; in ps)

get_description()

Get the values of the parameters necessary for replicating the AuxReader.

An AuxReader can be duplicated using auxreader():

description = original_aux.get_description()
new_aux = MDAnalysis.auxiliary.auxreader(**description)

The resulting dictionary may also be passed directly to add_auxiliary() to reload an auxiliary into a trajectory:

trajectory.add_auxiliary(**description)

Returns:

Key-word arguments and values that can be used to replicate the AuxReader.

Return type:

dict

property initial_time

Time of first auxiliary step (as stored in auxstep; in ps)

move_to_ts(ts)

Position auxiliary reader just before trajectory timestep ts.

Calling next() should read the first auxiliary step ‘assigned’ to the trajectory timestep ts or, if no auxiliary steps are assigned to that timestep (as in the case of less frequent auxiliary data), the first auxiliary step after ts.

Parameters:

ts (Timestep object) – The trajectory timestep before which the auxiliary reader is to be positioned.

property n_steps

Total number of steps in the auxiliary data.

next()

Move to next step of auxiliary data.

next_nonempty_frame(ts)

Find the next trajectory frame for which a representative auxiliary value can be calculated.

That is, the next trajectory frame to which one or more auxiliary steps are assigned and fall within the cutoff.

Starts looking from the current step time. If the end of the auxiliary data is reached before a trajectory frame is found, None is returned.

Parameters:

ts (Timestep object) – Any timestep from the trajectory for which the next ‘non-empty’ frame is to be found.

Returns:

Index of the next auxiliary-containing frame in the trajectory.

Return type:

int

Note

The returned index may be out of range for the trajectory.

read_ts(ts)

Read auxiliary steps corresponding to the trajectory timestep ts.

Read the auxiliary steps ‘assigned’ to ts (the steps that are within ts.dt/2 of of the trajectory timestep/frame - ie. closer to ts than either the preceding or following frame). Then calculate a ‘representative value’ for the timestep from the data in each of these auxiliary steps.

To update ts with the representative value, use update_ts instead.

Parameters:

ts (Timestep object) – The trajectory timestep for which corresponding auxiliary data is to be read.

See also

update_ts()

Note

The auxiliary reader will end up positioned at the last step assigned to the trajectory frame or, if the frame includes no auxiliary steps, (as when auxiliary data are less frequent), the most recent auxiliary step before the frame.

property represent_ts_as

Method by which ‘representative’ timestep values of auxiliary data will be calculated.

rewind()

Return to and read first step.

property step

Number of the current auxiliary step (as stored in auxstep; 0-based).

step_to_frame(step, ts, return_time_diff=False)

Calculate closest trajectory frame for auxiliary step step.

Calculated given dt, time and frame from ts:

time_frame_0 = ts.time - ts.frame*ts.dt   # time at frame 0

frame = floor((step_to_time(step) - time_frame_0 + ts.dt/2)/ts.dt))

The difference in time between the step and the calculated frame can also optionally be returned with return_time_diff.

Parameters:

• step (int) – Number of the auxiliary step to calculate closest trajectory frame for.

• ts (Timestep object) – (Any) timestep from the trajectory the calculated frame number is to correspond to.

• return_time_diff (bool, optional) – (Default: False) Additionally return the time difference between step and returned frame.

Returns:

• frame_index (int or None) – Number of the trajectory frame closest (in time) to the given auxiliary step. If the step index is out of range for the auxiliary data, None is returned instead.

• time_diff (float (optional)) – Difference in time between step and frame_index.

Note

Assumes trajectory dt is consant. The returned frame number may be out of range for the trajectory.

step_to_time(i)

Return time of auxiliary step i.

Calculated using dt and initial_time if constant_dt is True; otherwise from the list of times as read from the auxiliary data for each step.

Parameters:

i (int) – Index (0-based) of step to return time for

Returns:

time – Time (in ps) of step i

Return type:

float

Raises:

ValueError – When i not in valid range

property time

Time of current auxiliary step (as stored in auxstep; in ps)

property time_selector

Key to select ‘time’ value from the full set of data read for each step. As stored in austep.

Type differs between auxiliary formats, depending how the data for each step is read in and stored; e.g. data from .xvg files is read in as a list and time_selector must be a valid index. If time selection is not enabled by the reader, time_selector will default to None.

See each individual auxiliary reader.

update_ts(ts)

Read auxiliary steps corresponding to and update the trajectory timestep ts.

Calls read_ts(), then updates ts with the representative value. auxname must be set; the representative value will be accessible in ts as ts.aux.auxname or ts.aux['auxname'].

Parameters:

ts (Timestep object) – The trajectory timestep for which corresponding auxiliary data is to be read and updated.

Returns:

ts with the representative auxiliary value in ts.aux be updated appropriately.

Return type:

Timestep

Raises:

ValueError – If auxname is not set.

See also

read_ts()

class MDAnalysis.auxiliary.base.AuxFileReader(filename, **kwargs)

Base class for auxiliary readers that read from file.

Extends AuxReader with attributes and methods particular to reading auxiliary data from an open file, for use when auxiliary files may be too large to read in at once.

Parameters:

• filename (str) – Location of the file containing the auxiliary data.

• **kwargs – Other AuxReader options.

See also

AuxReader

auxfile

File object for the auxiliary file.

close()

Close auxfile.