Auxiliary files

Auxiliary readers allow you to read in timeseries data accompanying a trajectory, that is not stored in the regular trajectory file.

Supported formats

Reader	Format	Extension (if file)	Remarks
XVGReader	XVG	xvg (default)	Produced by Gromacs during simulation or analysis. Reads full file on initialisation.
XVGFileReader	XVG-F	xvg	Alternate xvg file reader, reading each step from the file in turn for a lower memory footprint. XVGReader is the default reader for .xvg files.

Reading data directly

In [1]: import MDAnalysis as mda

In [2]: from MDAnalysis.tests.datafiles import XVG_BZ2  # cobrotoxin protein forces
---------------------------------------------------------------------------
TypeError                                 Traceback (most recent call last)
<ipython-input-2-1ab82d15e01a> in <module>
----> 1 from MDAnalysis.tests.datafiles import XVG_BZ2  # cobrotoxin protein forces

~/checkouts/readthedocs.org/user_builds/mdauserguide/conda/rms-1.0/lib/python3.8/site-packages/MDAnalysis/tests/datafiles.py in <module>
     41 
     42 try:
---> 43     from MDAnalysisTests.datafiles import *
     44 except ImportError:
     45     print("*** ERROR ***")

~/checkouts/readthedocs.org/user_builds/mdauserguide/conda/rms-1.0/lib/python3.8/site-packages/MDAnalysisTests/__init__.py in <module>
    124 try:
    125     import matplotlib
--> 126     matplotlib.use('agg', warn=False)
    127 except ImportError:
    128     pass

TypeError: use() got an unexpected keyword argument 'warn'

In [3]: aux = mda.auxiliary.core.auxreader(XVG_BZ2)
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-3-0c6e0f31d0f8> in <module>
----> 1 aux = mda.auxiliary.core.auxreader(XVG_BZ2)

NameError: name 'XVG_BZ2' is not defined

In [4]: aux
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-4-c1d93f0ef0f3> in <module>
----> 1 aux

NameError: name 'aux' is not defined

In stand-alone use, an auxiliary reader allows you to iterate over each step in a set of auxiliary data.

In [5]: for step in aux:
   ...:     print(step.data)
   ...: 
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-5-2b2c8e575980> in <module>
----> 1 for step in aux:
      2     print(step.data)

NameError: name 'aux' is not defined

Use slicing to skip steps.

In [6]: for step in aux[1:2]:
   ...:     print(step.time)
   ...: 
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-6-4f8d5984773e> in <module>
----> 1 for step in aux[1:2]:
      2     print(step.time)

NameError: name 'aux' is not defined

The auxreader() function uses the get_auxreader_for() to return an appropriate class. This can guess the format either from a filename, ‘

In [7]: mda.auxiliary.core.get_auxreader_for(XVG_BZ2)
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-7-24dfee86a49a> in <module>
----> 1 mda.auxiliary.core.get_auxreader_for(XVG_BZ2)

NameError: name 'XVG_BZ2' is not defined

or return the reader for a specified format.

In [8]: mda.auxiliary.core.get_auxreader_for(format='XVG-F')
Out[8]: MDAnalysis.auxiliary.XVG.XVGFileReader

Loading data into a Universe

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 which case get_auxreader_for() is used to guess an appropriate reader.

In [9]: from MDAnalysis.tests.datafiles import PDB_xvf, TRR_xvf
---------------------------------------------------------------------------
TypeError                                 Traceback (most recent call last)
<ipython-input-9-6ccfd7da76ac> in <module>
----> 1 from MDAnalysis.tests.datafiles import PDB_xvf, TRR_xvf

~/checkouts/readthedocs.org/user_builds/mdauserguide/conda/rms-1.0/lib/python3.8/site-packages/MDAnalysis/tests/datafiles.py in <module>
     41 
     42 try:
---> 43     from MDAnalysisTests.datafiles import *
     44 except ImportError:
     45     print("*** ERROR ***")

~/checkouts/readthedocs.org/user_builds/mdauserguide/conda/rms-1.0/lib/python3.8/site-packages/MDAnalysisTests/__init__.py in <module>
    124 try:
    125     import matplotlib
--> 126     matplotlib.use('agg', warn=False)
    127 except ImportError:
    128     pass

TypeError: use() got an unexpected keyword argument 'warn'

In [10]: u = mda.Universe(PDB_xvf, TRR_xvf)
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-10-9948230bad34> in <module>
----> 1 u = mda.Universe(PDB_xvf, TRR_xvf)

NameError: name 'PDB_xvf' is not defined

In [11]: u.trajectory.add_auxiliary('protein_force', XVG_BZ2)
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-11-34309ff5edd5> in <module>
----> 1 u.trajectory.add_auxiliary('protein_force', XVG_BZ2)

NameError: name 'u' is not defined

In [12]: for ts in u.trajectory:
   ....:     print(ts.aux.protein_force)
   ....: 
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-12-3f68dbf72bd7> in <module>
----> 1 for ts in u.trajectory:
      2     print(ts.aux.protein_force)

NameError: name 'u' is not defined

Passing arguments to auxiliary data

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.

To set a timestep or ??

‘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. If there are no auxiliary steps assigned to a given timestep (or none within cutoff, if set), the representative value(s) are set to np.nan.

Iterating over auxiliary data

Auxiliary data may not perfectly line up with the trajectory, or have missing data.

In [13]: from MDAnalysis.tests.datafiles import PDB, TRR
---------------------------------------------------------------------------
TypeError                                 Traceback (most recent call last)
<ipython-input-13-52c333738bd6> in <module>
----> 1 from MDAnalysis.tests.datafiles import PDB, TRR

~/checkouts/readthedocs.org/user_builds/mdauserguide/conda/rms-1.0/lib/python3.8/site-packages/MDAnalysis/tests/datafiles.py in <module>
     41 
     42 try:
---> 43     from MDAnalysisTests.datafiles import *
     44 except ImportError:
     45     print("*** ERROR ***")

~/checkouts/readthedocs.org/user_builds/mdauserguide/conda/rms-1.0/lib/python3.8/site-packages/MDAnalysisTests/__init__.py in <module>
    124 try:
    125     import matplotlib
--> 126     matplotlib.use('agg', warn=False)
    127 except ImportError:
    128     pass

TypeError: use() got an unexpected keyword argument 'warn'

In [14]: u_long = mda.Universe(PDB, TRR)
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-14-ca574921ef39> in <module>
----> 1 u_long = mda.Universe(PDB, TRR)

NameError: name 'PDB' is not defined

In [15]: u_long.trajectory.add_auxiliary('protein_force', XVG_BZ2, dt=200)
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-15-53191d76ddcb> in <module>
----> 1 u_long.trajectory.add_auxiliary('protein_force', XVG_BZ2, dt=200)

NameError: name 'u_long' is not defined

In [16]: for ts in u_long.trajectory:
   ....:     print(ts.time, ts.aux.protein_force[:4])
   ....: 
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-16-24060ca3ba09> in <module>
----> 1 for ts in u_long.trajectory:
      2     print(ts.time, ts.aux.protein_force[:4])

NameError: name 'u_long' is not defined

The trajectory ProtoReader methods next_as_aux() and iter_as_aux() allow for movement through only trajectory timesteps for which auxiliary data is available.

In [17]: for ts in u_long.trajectory.iter_as_aux('protein_force'):
   ....:     print(ts.time, ts.aux.protein_force[:4])
   ....: 
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-17-eb9c57d7b5fe> in <module>
----> 1 for ts in u_long.trajectory.iter_as_aux('protein_force'):
      2     print(ts.time, ts.aux.protein_force[:4])

NameError: name 'u_long' is not defined

This may be used to avoid representative values set to np.nan, particularly when auxiliary data is less frequent.

Sometimes the auxiliary data is longer than the trajectory.

In [18]: u_short = mda.Universe(PDB)
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-18-aaa693c28066> in <module>
----> 1 u_short = mda.Universe(PDB)

NameError: name 'PDB' is not defined

In [19]: u_short.trajectory.add_auxiliary('protein_force', XVG_BZ2)
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-19-9bf03c7a03c5> in <module>
----> 1 u_short.trajectory.add_auxiliary('protein_force', XVG_BZ2)

NameError: name 'u_short' is not defined

In [20]: for ts in u_short.trajectory:
   ....:     print(ts.time, ts.aux.protein_force)
   ....: 
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-20-c24b04aeef54> in <module>
----> 1 for ts in u_short.trajectory:
      2     print(ts.time, ts.aux.protein_force)

NameError: name 'u_short' is not defined

In order to acess 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.

In [21]: for step in u_short.trajectory.iter_auxiliary('protein_force'):
   ....:     print(step.data)
   ....: 
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-21-b3827dc427a3> in <module>
----> 1 for step in u_short.trajectory.iter_auxiliary('protein_force'):
      2     print(step.data)

NameError: name 'u_short' is not defined

To iterate over only a certain section of the auxiliary:

In [22]: for step in u_short.trajectory.iter_auxiliary('protein_force', start=1, step=2):
   ....:     print(step.time)
   ....: 
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-22-bf3fa2af3071> in <module>
----> 1 for step in u_short.trajectory.iter_auxiliary('protein_force', start=1, step=2):
      2     print(step.time)

NameError: name 'u_short' is not defined

The trajectory remains unchanged, and the auxiliary will be returned to the current timestep after iteration is complete.

Accessing auxiliary attributes

To check the values of attributes of an added auxiliary, use get_aux_attribute().

In [23]: u.trajectory.get_aux_attribute('protein_force', 'dt')
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-23-5b3164df381b> in <module>
----> 1 u.trajectory.get_aux_attribute('protein_force', 'dt')

NameError: name 'u' is not defined

If attributes are settable, they can be changed using set_aux_attribute().

In [24]: u.trajectory.set_aux_attribute('protein_force', 'data_selector', [1])
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-24-de9e36c640bc> in <module>
----> 1 u.trajectory.set_aux_attribute('protein_force', 'data_selector', [1])

NameError: name 'u' is not defined

The auxiliary may be renamed using set_aux_attribute with ‘auxname’, or more directly by using rename_aux().

In [25]: u.trajectory.ts.aux.protein_force
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-25-eeb820e67c0b> in <module>
----> 1 u.trajectory.ts.aux.protein_force

NameError: name 'u' is not defined

In [26]: u.trajectory.rename_aux('protein_force', 'f')
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-26-2b6f1b68545f> in <module>
----> 1 u.trajectory.rename_aux('protein_force', 'f')

NameError: name 'u' is not defined

In [27]: u.trajectory.ts.aux.f
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-27-71c2bf052ebf> in <module>
----> 1 u.trajectory.ts.aux.f

NameError: name 'u' is not defined

Recreating auxiliaries

To recreate an auxiliary, the set of attributes necessary to replicate it can first be obtained with get_description(). The returned dictionary can then be passed to auxreader() to load a new copy of the original auxiliary reader.

In [28]: description = aux.get_description()
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-28-1c956469c981> in <module>
----> 1 description = aux.get_description()

NameError: name 'aux' is not defined

In [29]: list(description.keys())
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-29-8acc739bb738> in <module>
----> 1 list(description.keys())

NameError: name 'description' is not defined

In [30]: del aux
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-30-501c038ea324> in <module>
----> 1 del aux

NameError: name 'aux' is not defined

In [31]: mda.auxiliary.core.auxreader(**description)
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-31-46a012a8d339> in <module>
----> 1 mda.auxiliary.core.auxreader(**description)

NameError: name 'description' is not defined

The ‘description’ of any or all the auxiliaries added to a trajectory can be obtained using get_aux_descriptions().

In [32]: descriptions = u.trajectory.get_aux_descriptions(['f'])
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-32-66db4ac34bff> in <module>
----> 1 descriptions = u.trajectory.get_aux_descriptions(['f'])

NameError: name 'u' is not defined

To reload, pass the dictionary into add_auxiliary().

In [1]: u2 = mda.Universe(PDB, TRR)
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-1-80d0a701162a> in <module>
----> 1 u2 = mda.Universe(PDB, TRR)

NameError: name 'PDB' is not defined

In [2]: for desc in descriptions:
   ...:     u2.trajectory.add_auxiliary(**desc)
   ...: 
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-2-73376cbc62d1> in <module>
----> 1 for desc in descriptions:
      2     u2.trajectory.add_auxiliary(**desc)

NameError: name 'descriptions' is not defined