10.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)[source]
Base class for auxiliary timesteps.
Stores the auxiliary data for the current auxiliary step. On creation,
step
is set to -1.- 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 validtime_selector
must be provided.
- 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 asstep * dt + initial_time
.
- class MDAnalysis.auxiliary.base.AuxReader(represent_ts_as='closest', auxname=None, cutoff=- 1, **kwargs)[source]
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.
- 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
orts.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 -1 (default), all auxiliary steps assigned to that timestep will be used.
**kwargs – Options to be passed to
AuxStep
- 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
- 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.
- calc_representative()[source]
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 inauxstep
)
- 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 toNone
.See each individual auxiliary reader.
- property dt
Change in time between auxiliary steps (as stored in
auxstep
; in ps)
- get_description()[source]
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
- property initial_time
Time of first auxiliary step (as stored in
auxstep
; in ps)
- move_to_ts(ts)[source]
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_nonempty_frame(ts)[source]
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
Note
The returned index may be out of range for the trajectory.
- read_ts(ts)[source]
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
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.
- property step
Number of the current auxiliary step (as stored in
auxstep
; 0-based).
- step_to_frame(step, ts, return_time_diff=False)[source]
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)[source]
Return time of auxiliary step i.
Calculated using
dt
andinitial_time
ifconstant_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
- 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 toNone
.See each individual auxiliary reader.
- update_ts(ts)[source]
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 asts.aux.auxname
orts.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
- Raises
ValueError – If
auxname
is not set.
See also
- class MDAnalysis.auxiliary.base.AuxFileReader(filename, **kwargs)[source]
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
- auxfile
File object for the auxiliary file.