10.1. Auxiliary Readers —
The auxiliary submodule contains code for reading ‘auxiliary’ data from a
trajectory and allowing alignment with trajectory timesteps. Additional
MDAnalysis.coordinates.base.ProtoReader allow auxiliary data
to be added and read alongside a trajectory.
Auxiliary data are timeseries accompanying a trajectory not stored in the regular trajectory file to be read by the trajectory Reader. They may be stored internally (e.g. in an array) or read from a file. In general, auxiliary data is assumed to be time ordered and contain no duplicates.
10.1.1. Supported formats
Currently supported formats:
Extension (if file)
Produced by Gromacs during simulation or analysis. Reads full file on initialisation.
Alternate xvg file reader, reading each step from the file in turn for a lower memory footprint.
XVGReaderis the default reader for .xvg files.
Produced by Gromacs during simulation. Reads full file on initialisation
10.1.2. Auxiliary API
Auxiliary readers inherit from the base
AuxReader. In stand-alone use they
allow iteration over each step in a set of auxiliary data:
aux = MDAnalysis.auxiliary.XVG.XVGReader('auxdata.xvg') for auxstep in aux: print(auxstep)
To iterate over only certain sections of the auxiliary:
for auxstep in aux[100:200]: # only steps 100-200 do_something(auxstep)
Or to skip steps:
for auxstep in aux[100::10]: # every 10th step starting at 100 do_something(auxstep)
AuxFileReader is also provided,
AuxReader with attributes/methods
for when auxiliary data is to be read from a file by keeping the file open and
reading steps one-at-time as needed.
get_auxreader_for() function is available to
return an appropriate
AuxReader class for
a supplied format or set of auxiliary data, guessing the format from the
auxreader = MDAnalysis.auxiliary.core.get_auxreader_for('auxdata.xvg') # will return the default XVGReader class auxreader = MDAnalysis.auxiliary.core.get_auxreader_for(format='XVG-F') # will return the XVGFileReader class
To directly load an instance of the guessed auxiliary reader class given the
supplied auxdata and any additional auxiliary reader options, the
auxreader() can be used:
aux = MDAnalysis.auxiliary.auxreader('auxdata.xvg', dt=2) for auxstep in aux: do_something(auxstep)
10.1.2.1. Auxiliaries and trajectories
For alignment with trajectory data, auxiliary readers provide methods to assign each auxiliary step to the nearest trajectory timestep, read all steps assigned to a trajectory timestep and calculate ‘representative’ value(s) of the auxiliary data for that timestep.
‘Assignment’ of auxiliary steps to trajectory timesteps is determined from the time
of the auxiliary step,
dt of the trajectory and time at the first frame of the
trajectory (obtained through a
instance from the trajectory), as:
frame = floor((time_at_step - time_at_frame_0 + dt/2)/dt)
If there are no auxiliary steps assigned to a given timestep (or none within
cutoff, if set), the representative value(s) are set to
10.1.2.1.1. Adding an auxiliary to a trajectory
Auxiliary data may be added to a trajectory Reader through the
add_auxiliary() method. Auxiliary data
may be passed in as a AuxReader instance, or directly as e.g. a filename, in
get_auxreader_for() is used to
guess an appropriate reader. e.g.:
u = MDAnalysis.Universe(PDB, XTC) u.trajectory.add_auxiliary('pullforce', './pull_force.xvg')
As the trajectory frame is updated, the auxiliary data will be read
updated, and the representative auxiliary value(s) will be available as e.g.
10.1.2.1.2. Iterating by an auxiliary
iter_as_aux() allow for movement
through only trajectory timesteps to which one or more steps that fall within
cutoff from a given auxiliary have been assigned. This may be used to
avoid representative values set to
np.nan, particularly when auxiliary data
is less frequent:
u.trajectory.add_auxiliary('low_f', 'low_freq_aux_data.xvg') for ts in u.trajectory.iter_as_aux('low_f'): do_something(ts.aux.low_f) # do something with 'low_f' auxiliary data without # worrying about having to deal with np.nan
If the auxiliary data are more frequent and the cutoff (if set) is
iter_as_aux() behave the same
In order to access auxiliary values at every individual step, including those
outside the time range of the trajectory,
iter_auxiliary() allows iteration
over the auxiliary independent of the trajectory:
for auxstep in u.trajectory.iter_auxiliary('pullforce'): do_something(auxstep)
To iterate over only a certain section of the auxiliary:
for auxstep in u.trajectory.iter_auxiliary('pullforce', start=100, step=10): # every 10th step from 100 do_something(auxstep)
The trajectory remains unchanged, and the auxiliary will be returned to the current timestep after iteration is complete.
10.1.2.1.3. Accessing auxiliary attributes
To check the values of attributes of an added auxiliary, use
pullf_dt = u.trajectory.get_aux_attribute('pullforce', 'dt')
If attributes are settable, they can be changed using
u.trajectory.set_aux_attribute('pullforce', 'data_selector', )
The auxiliary may be renamed using
set_aux_attribute with ‘auxname’, or more
directly by using
10.1.2.2. Recreating auxiliaries
To recreate an auxiliary, the set of attributes necessary to replicate it can
first be obtained with
The returned dictionary can then be passed to
auxreader() to load a new copy of the
original auxiliary reader:
description = aux.get_description() del(aux) reload_aux = MDAnalysis.auxiliary.auxreader(**description)
The ‘description’ of any or all the auxiliaries added to a trajectory can be
descriptions = u.trajectory.get_aux_descriptions()
Get descriptions for selected auxiliaries only:
descriptions = u.trajectory.get_aux_descriptions(['pullf', 'pullx'])
And to reload:
for descr in descriptions: new_u.new_trajectory.add_auxiliary(**descr)
10.1.2.3. AuxStep class
An AuxStep instance holds the auxiliary data for the current step. It is updated whenever a new auxiliary step is read.
AuxStep classes are derived from the base class
AuxStep. The appropriate AuxStep class for
a given auxiliary reader is identified in the reader by the _Auxstep attribute.
The following are inherited from
Current auxiliary step (0-based).
All recorded data for the current step, as a numpy array.
Time of current auxiliary step, as a float (in ps). Determined from the
_dataif time selection is enabled and a valid
time_selectorprovided; otherwise calculated using
Auxiliary values of interest for the current step, as a numpy array. Determined from
_dataid data selection is enabled at a valid
data_selectoris provided; otherwise set to
The following are stored in AuxStep. The parent auxiliary reader has the equivalent attributes, though non-private (no _) (see AuxReader class below).
Change in time between auxiliary steps (in ps). If not specified, will attempt to determine from auxiliary data; otherwise defaults to 1 ps.
Time of first auxiliary step (in ps). If not specified, will attempt to determine from auxiliary data; otherwise defaults to 0 ps.
Selection key to get time from full set of auxiliary data read with each step(
_data) (ignored if time selection is not enabled by the reader). Type depends on the auxiliary format - e.g. where data is stored in columns, time_selector may be an index of ‘time’ column. Default value is
None, in which case step time is calculated from
Selection key(s) to get data of interest from full set of auxiliary data read with each step (
_data) (ignored if data selection is not enabled by the reader). As for
time_selector, type depends on the auxiliary format. If
Boolean of whether dt is constant throughout auxiliary data. Default is
The following methods are inherited from
Setup appropriate attributes based on kwargs.
To enabled time/data selection in a particular AusStep, the following must be provided:
Return, as a float, the time value indicated by key from
_data(the full set of data read in from the current step). Raise
ValueErrorif key is not a valid time selector for the auxiliary format.
Return, as a ndarray, the value(s) indicated by key (may be e.g. a list of multiple individual ‘keys’) from
ValueErrorif key is not a valid data selector for the auxiliary format.
Depending on the format of the auxiliary and hence the format of
may be necessary to overload the following for a particular AuxStep:
Return a np.array in the same format as
datawith all values set to
np.nan. Used as the representative auxiliary value for a trajectory when no auxiliary steps are assigned to the current frame.
10.1.2.4. AuxReader class
In order to facilitate guessing of appropriate AuxReaders, all AuxReaders should set as appropriate format attribute. For files, this will be the expected file extension (in all caps).
10.1.2.4.2. Replicating auxiliaries
The names of the necessary attributes for replicating an auxiliary are stored in required_attrs, initially set in the base AuxReader. If a particular AuxReader introduces additional attributes required to reload an auxiliary, these should be added.
The following attributes are inherited from
Name under which auxiliary data will be stored in trajectory.
Method to use in calculating representative auxiliary value for a timestep. Default is ‘closest’.
Cutoff (in ps) for ignoring auxiliary steps when calculating representative value(s) for a timestep.
AuxStepobject to store data for the current step. The particular AuxStep used will depend on the auxiliary format.
Total number of auxiliary steps.
data from each auxiliary step assigned to the last-read trajectory timestep.
Representative value(s) of auxiliary data for last-read trajectory timestep.
The following are stored in
auxstep as private attributes (with _)
but may be accessed from the auxiliary reader; see the AuxStep class above.
File object for the auxiliary file.
Each auxiliary reader subclass will additionally set:
Value of ‘auxdata’ used to load the auxiliary - e.g. path to the file containing the auxiliary data. Will be used when getting the ‘description’ of the auxiliary for recreating.
Each auxiliary reader class must also identify an appropriate
AuxStep with the _Auxstep class attribute
The following methods are inherited from
Setup appropriate attributes based on kwargs.
Number of steps in auxiliary data.
Advance to next step.
Allow iteration through each auxiliary step.
If step is a single index, move to that step and return the
AuxStep; if a list or slice, return an iterator over the specified auxiliary steps. See examples in Auxiliary API above.
Reposition to first step.
Read auxiliary steps assigned to trajectory step ts, calculate and update the representative value in ts. Return ts.
Read auxiliary steps assigned to trajectory step ts and calculate representative value.
Move to the auxiliary step before the trajectory timestep ts, such that calling
_read_next_stepreads the first step assigned to ts or, when auxiliary data are less frequent and no steps are assigned to ts, the first step following ts.
step_to_frame(step, ts, return_time_diff=False)
Return the frame number of the trajectory described by ts to which the auxiliary step step is assigned. Optionally also return the difference it time between the step and the returned frame.
Return the time of the auxiliary step step.
Return the frame number of the next trajectory frame (after the current auxiliary time) for which a representative auxiliary value can be calculated (i.e., there is at least one assigned auxiliary step within
Return the representative value calculated from
datafollowing the method specified by
Entry method for Context Manager (returns self).
Exit method for Context Manager (calls
Get the values of the attributes required for replicating an auxiliary (as listed in
required_attrs) and return as a dictionary.
Check for equality by checking each of the attributes required for replicating an auxiliary (as listed in
required_attrs) are equal.
Each AuxReader must subclass
and addionally define:
Additional processing of kwargs and any necessary initial processing of auxdata. Must
Read the data from the next auxiliary step and update
auxstepas appropriate. Raise StopIteration when attempting to read past last step.
Move to and read step i (0-based) from the auxiliary data. Raise ValueError when i is out of range. Update the
Depending on the format of the auxiliary data, it may also be necessary to define/overwrite the following:
Return the list of times for each step (only required if
constant_dtmay be false).
Return the total number of steps (only required if _n_steps not otherwise set during __init__).
Reposition before the first step
For convenience, when reading auxiliary data from an open file, one step at a
AuxReader by providing the
following (these may be overwritten by subclasses as appropriate):
Open auxfile and any additional processing of kwargs.
Seek to the start of
Iterate through all steps until step i is reached.