tfep.utils.plumed.auxreader.PLUMEDAuxReader

class tfep.utils.plumed.auxreader.PLUMEDAuxReader(file_path, col_names=None, units=None, **kwargs)[source]

Bases: XVGReader

Auxiliary reader for PLUMED files.

The class extends the MDAnalysis.auxiliary.XVG.XVGReader class to allow filtering by column name, converting to MDAnalysis internal unit system, and solving a few recurring problems with the PLUMED output (e.g., when the record at time 0.0 is duplicated).

Parameters:

file_path (str) – The path to the PLUMED output file.
col_names (List[str], optional) – A list of column names to read. These names correspond to those provided in the initial ‘#! FIELDS …’ header record. If not given, the function reads all the columns. Time is always read and it will always be moved as the first column.
units (Dict[str, str]) – units[col_name] is the unit used by PLUMED (e.g. ‘fs’) to for values in column col_name. This information is used to convert the data into the internal unit system used by MDAnalysis. If not given, no conversion is performed, which is equivalent to assume that the PLUMED output is given in the MDAnalysis unit system. Note that the default unit for length is different in PLUMED (nm) and MDAnalysis (Angstrom).
**kwargs – Other keyword arguments for XVGReader.

Variables:

col_names (Tuple[str]) – The order of the columns in the auxiliary information. Depending on if and where the ‘time’ column was given on initialization, this can be different than the input parameter.

See also

MDAnalysis.auxiliary.XVG.XVGReader: All other parameters, methods, and attributes exposed by PLUMEDReader.

__init__(file_path, col_names=None, units=None, **kwargs)[source]

Methods

`__init__`(file_path[, col_names, units])
`attach_auxiliary`(coord_parent[, aux_spec, ...])	Attaches the data specified in aux_spec to the coord_parent
`calc_representative`()	Calculate representative auxiliary value(s) from the data in frame_data.
`close`()
`copy`()	Returns a deep copy of the AuxReader
`get_column_idx`(col_name)	Return the column index associated to the column name.
`get_description`()	Override MDAnalysis method to duplicate the reader.
`move_to_ts`(ts)	Position auxiliary reader just before trajectory timestep ts.
`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.
`read_all_times`()	Get NumPy array of time at each step.
`read_ts`(ts)	Read auxiliary steps corresponding to the trajectory timestep ts.
`rewind`()	Return to and read first step.
`step_to_frame`(step, ts[, return_time_diff])	Calculate closest trajectory frame for auxiliary step step.
`step_to_time`(i)	Return time of auxiliary step i.
`update_ts`(ts)	Read auxiliary steps corresponding to and update the trajectory timestep ts.

Attributes

`constant_dt`	True if `dt` is constant throughout the auxiliary (as stored in `auxstep`)
`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`).
`dt`	Change in time between auxiliary steps (as stored in `auxstep`; in ps)
`format`
`initial_time`	Time of first auxiliary step (as stored in `auxstep`; in ps)
`n_steps`	Total number of steps in the auxiliary data.
`represent_options`
`represent_ts_as`	Method by which 'representative' timestep values of auxiliary data will be calculated.
`required_attrs`
`step`	Number of the current auxiliary step (as stored in `auxstep`; 0-based).
`time`	Time of current auxiliary step (as stored in `auxstep`; in ps)
`time_selector`	Key to select 'time' value from the full set of data read for each step.

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_column_idx(col_name)[source]: Return the column index associated to the column name.

get_description()[source]: Override MDAnalysis method to duplicate the reader.

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_all_times()

Get NumPy array of time at each step.

Returns:: Time at each step.
Return type:: NumPy array of float

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.