10.1. 辅助读者 `MDAnalysis.auxiliary`

辅助子模块包含用于从弹道中读取“辅助”数据并允许与弹道时间步长对齐的代码。中的其他方法 MDAnalysis.coordinates.base.ProtoReader 允许将辅助数据与轨迹一起添加和读取。

辅助数据是伴随未存储在要由轨迹读取器读取的常规轨迹文件中的轨迹的时间序列。它们可以在内部存储(例如，在数组中)或从文件中读取。通常，假设辅助数据是按时间排序的，并且不包含重复项。

10.1.1. 支持的格式

当前支持的格式：

读者

格式化

扩展名(IF文件)

备注

XVGReader

XVG

Xvg

(默认)

由Gromacs在模拟或分析期间生成。读取有关初始化的完整文件。

XVGFileReader

XVG-F

Xvg

备用xvg文件读取器，依次从文件中读取每个步骤，以减少内存占用。 XVGReader 是.xvg文件的默认读取器。

EDRReader

EDR

EDR

由Gromacs在模拟过程中生成。在初始化时读取完整文件

10.1.2. 辅助API

辅助读取器继承自基础 AuxReader 。在独立使用中，它们允许迭代一组辅助数据中的每个步骤：

aux = MDAnalysis.auxiliary.XVG.XVGReader('auxdata.xvg')
for auxstep in aux:
    print(auxstep)

要仅迭代辅助语句的某些部分：：

for auxstep in aux[100:200]:
    # only steps 100-200
    do_something(auxstep)

或跳过以下步骤：

for auxstep in aux[100::10]:
    # every 10th step starting at 100
    do_something(auxstep)

一个基地 AuxFileReader 还提供了，扩展了 AuxReader 具有用于何时通过保持文件打开并根据需要一次读取步骤来从文件读取辅助数据的属性/方法。

A get_auxreader_for() 函数可用于返回相应的 AuxReader 为提供的格式或辅助数据集初始化，从数据类型/文件扩展名猜测格式：：

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

要在给定所提供的辅助数据和任何其他辅助读取器选项的情况下直接加载猜测的辅助读取器类的实例，函数 auxreader() 可以使用：：

aux = MDAnalysis.auxiliary.auxreader('auxdata.xvg', dt=2)
for auxstep in aux:
   do_something(auxstep)

10.1.2.1. 辅助词和轨迹

为了与轨迹数据对准，辅助读取器提供了将每个辅助步长分配给最近的轨迹时间步长、读取分配给轨迹时间步长的所有步长并计算该时间步长的辅助数据的(多个)代表值的方法。

从辅助步长的时间确定辅助步长到轨迹时间步长的‘分配’， dt 轨迹的第一帧的轨迹和时间(通过 Timestep 轨迹的实例)，如下所示：：

frame = floor((time_at_step - time_at_frame_0 + dt/2)/dt)

如果没有为给定时间步长分配辅助步骤(或在 cutoff ，如果设置)，则将代表值设置为 np.nan 。

10.1.2.1.1. 将辅助项添加到轨迹

辅助数据可以通过添加到轨迹读取器中 add_auxiliary() 方法。辅助数据可以作为AuxReader实例传递，或者直接作为例如文件名传递，在这种情况下 get_auxreader_for() 用来猜测合适的读取器。例如：

u = MDAnalysis.Universe(PDB, XTC)
u.trajectory.add_auxiliary('pullforce', './pull_force.xvg')

当轨迹帧被更新时，辅助数据将被相应地读取、更新，并且代表性辅助值将例如可用。 u.trajectory.ts.aux.pullforce 。

10.1.2.1.2. 由辅助器进行迭代

弹道 ProtoReader 方法： next_as_aux() 和 iter_as_aux() 仅允许通过轨迹时间步长移动，其中一个或多个步长落在 cutoff 从一个给定的辅助器中被分配。这可用于避免将代表值设置为 np.nan ，特别是当辅助数据不太频繁时：：

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

如果辅助数据更频繁并且截止(如果设置)足够高， next_as_aux() 和 iter_as_aux() 行为方式与 ProtoReader next() 和 __iter__() 。

为了访问每个单独步长的辅助值，包括轨迹时间范围之外的那些辅助值， iter_auxiliary() 允许独立于轨迹在辅助对象上迭代：：

for auxstep in u.trajectory.iter_auxiliary('pullforce'):
    do_something(auxstep)

要仅迭代辅助语句的特定部分，请执行以下操作：

for auxstep in u.trajectory.iter_auxiliary('pullforce', start=100, step=10):
    # every 10th step from 100
    do_something(auxstep)

轨迹保持不变，迭代完成后，辅助时间步长返回当前时间步长。

10.1.2.1.3. 访问辅助属性

要检查添加的辅助对象的属性值，请使用 get_aux_attribute() ，例如：

pullf_dt = u.trajectory.get_aux_attribute('pullforce', 'dt')

如果属性是可设置的，则可以使用 set_aux_attribute() ，例如：

u.trajectory.set_aux_attribute('pullforce', 'data_selector', [1])

可以使用以下命令重命名该辅助项 set_aux_attribute ，或者更直接地通过使用 rename_aux() ：：

u.trajectory.rename_aux('pullforce', 'pullf')

10.1.2.2. 正在重新创建辅助设备

要重新创建辅助对象，可以首先使用以下命令获取复制该辅助对象所需的属性集 get_description() 。然后，可以将返回的词典传递给 auxreader() 要加载原始辅助读卡器的新副本：：

description = aux.get_description()
del(aux)
reload_aux = MDAnalysis.auxiliary.auxreader(**description)

添加到轨迹中的任何或所有辅助部件的“描述”可以使用 get_aux_descriptions() ：：

descriptions = u.trajectory.get_aux_descriptions()

仅获取选定辅助设备的说明：：

descriptions = u.trajectory.get_aux_descriptions(['pullf', 'pullx'])

并重新加载：：

for descr in descriptions:
    new_u.new_trajectory.add_auxiliary(**descr)

10.1.2.3. 辅助步骤类

AuxStep实例保存当前步骤的辅助数据。每当读取新的辅助步骤时，它都会更新。

AuxStep类从基类派生 AuxStep 。给定辅助读取器的适当AuxStep类在读取器中由 _Auxstep 属性。

10.1.2.3.1. 属性

以下内容继承自 AuxStep ：

step
当前辅助步长(从0开始)。

_data
当前步骤的所有记录数据，以数字数组形式表示。

time
当前辅助步长的时间，以浮点数表示(以ps为单位)。由 _data 如果启用了时间选择并且有效的 time_selector 提供的；否则使用 dt 和 initial_time 。

data
当前步骤感兴趣的辅助值，以数字数组的形式表示。根据以下内容确定 _data ID数据选择在有效的 data_selector 提供；否则设置为 _data 。

以下内容存储在AuxStep中。父辅助读取器具有相同的属性，但不是私有的(No_)(请参见 AuxReader类 (见下文)。

_dt
辅助步骤之间的时间变化(以PS为单位)。如果未指定，将尝试从辅助数据确定；否则默认为1 ps。

_initial_time
第一个辅助步骤的时间(PS)。如果未指定，将尝试从辅助数据确定；否则默认为0 ps。

_time_selector
从每一步读取的全套辅助数据中获取时间的选择键 (_data )(如果读卡器未启用时间选择，则忽略)。类型取决于辅助格式-例如，数据存储在列中的位置，time_selector可以是‘time’列的索引。默认值为 None ，在这种情况下，步长时间从 dt ， initial_time 和 step 。

_data_selector
选择键，用于从每个步骤读取的全套辅助数据中获取感兴趣的数据 (_data )(如果读卡器未启用数据选择，则忽略)。至于 time_selector ，类型取决于辅助格式。如果 None (默认值)、 _data 返回。

_constant_dt
辅助数据中DT是否为常量的布尔值。默认值为 True 。

10.1.2.3.2. 方法：

以下方法继承自 AuxStep ：

__init__(**kwargs)
根据以下条件设置适当的属性 科瓦格人 。

要在特定AusStep中启用时间/数据选择，必须提供以下内容：

_select_time(key)
以浮点数的形式返回由 key 从… _data (从当前步骤读入的全套数据)。加薪 ValueError 如果 key 不是辅助格式的有效时间选择符。

_select_data(key)
以ndarray形式返回由 key (可以是例如多个单独的‘键’的列表) _data 。加薪 ValueError 如果 key 不是辅助格式的有效数据选择符。

取决于助词的格式，因此也取决于 data ，可能需要为特定的辅助步骤重载以下内容：

_empty_data()
以与相同的格式返回np.array data 将所有值设置为 np.nan 。当没有为当前帧指定辅助步数时，用作轨迹的代表性辅助值。

10.1.2.4. AuxReader类

10.1.2.4.1. 登记处

为了便于猜测合适的辅助阅读器，所有辅助阅读器都应适当设置 format 属性。对于文件，这将是预期的文件扩展名(全部大写)。

10.1.2.4.2. 复制辅助体

复制辅助设备所需属性的名称存储在 required_attrs ，最初在基本AuxReader中设置。如果某个特定的AuxReader引入了重新加载辅助设备所需的其他属性，则应添加这些属性。

10.1.2.4.3. 属性

以下属性继承自 AuxReader ：

auxname
辅助数据将存储在轨迹中的名称。

represent_ts_as
用于计算时间步长的代表性辅助值的方法。缺省值为“最接近”。

cutoff
在计算时间步长的代表值时忽略辅助步骤的截止时间(PS)。

auxstep
这个 AuxStep 对象来存储当前步骤的数据。使用的特定辅助步骤将取决于辅助格式。

n_steps
辅助步骤的总数。

frame_data
data 从分配给最后读取轨迹时间步长的每个辅助步长开始。

frame_rep
上次读取轨迹时间步长的辅助数据的代表值。

以下内容存储在 auxstep 作为私有属性(With_)，但可以从辅助读取器访问；请参阅辅助步骤类上面。

step

time

dt

initial_time

time_selector

data_selector

constant_dt

AuxFileReader 提供：

auxfile
辅助文件的文件对象。

每个辅助读卡器子类还将设置：

_auxdata
用于加载辅助数据的‘aux data’值--例如，指向包含辅助数据的文件的路径。将在获取用于重新创建的辅助器的‘描述’时使用。

每个辅助阅读器类还必须标识适当的 AuxStep 使用 _Auxstep 类属性

10.1.2.4.4. 方法：

以下方法继承自 AuxReader ：

__init__(**kwargs)
根据以下条件设置适当的属性 科瓦格人 。

__len__()
辅助数据中的步数。

next()
前进到下一步。

__iter__()
允许通过每个辅助步骤进行迭代。

__getitem__(step)
如果 step 是单个索引，则移动到该步骤并返回 AuxStep ；如果是列表或切片，则返回指定辅助步骤的迭代器。请参阅中的示例辅助API 上面。

rewind()
重新定位到第一步。

update_ts(ts)
读取指定给轨迹步长的辅助步长 ts 中的代表值进行计算和更新 ts 。返回 ts 。

read_ts(ts)
读取指定给轨迹步长的辅助步长 ts 并计算有代表性的价值。

move_to_ts(ts)
移动到轨迹时间步长之前的辅助步长 ts ，这样呼叫 _read_next_step 读取分配给的第一个步骤 ts 或者，当辅助数据频率较低且未向其分配步骤时 ts ，接下来的第一步 ts 。

step_to_frame(step, ts, return_time_diff=False)
返回由描述的轨迹的帧编号 ts 辅助步骤要达到的 step 是分配的。还可以选择返回步骤和返回的帧之间的时间差。

step_to_time(step)
返回辅助步骤的时间 step 。

next_nonempty_frame(ts)
返回下一个轨迹帧的帧编号(在当前辅助时间之后)，可以为其计算具有代表性的辅助值(即，其中至少有一个指定的辅助步长 cutoff )。

calc_representative()
返回计算所得的代表值 data 所指定的方法 represent_ts_as 和 cutoff 。

__enter__()
上下文管理器的输入方法(返回SELF)。

__exit__()
上下文管理器的退出方法(调用 close() )。

__del__()
打电话 close() 。

get_description
获取复制辅助设备所需的属性值(如中所列 required_attrs )，并作为词典返回。

__eq__
通过检查复制辅助设备所需的每个属性来检查等价性(如中所列 required_attrs )是平等的。

每个AuxReader必须子类 AuxReader 并另外定义：

__init__(auxdata, **kwargs)
额外的处理 科瓦格人 以及任何必要的初始处理 辅助数据 。必须 super() 通过 AuxReader 。

_read_next_step()
读取下一个辅助步骤中的数据并更新 auxstep 视情况而定。加薪 StopIteration 当尝试读过最后一步时。

_go_to_step(i)
移动到并阅读步骤 i (从0开始)从辅助数据。当我超出范围时引发ValueError。更新 auxstep 然后回来。

根据辅助数据的格式，可能还需要定义/覆盖以下内容：

read_all_times()
返回每个步骤的时间列表(仅在以下情况下需要 constant_dt 可能为假)。

count_n_steps()
返回总步数(仅在 _n_steps not otherwise set during _ _init__)。

_restart()
在第一步之前重新定位

close()

为方便起见，当从打开的文件中读取辅助数据时，一次一个步骤， AuxFileReader 延展 AuxReader 通过提供以下内容(这些内容可能会被适当的子类覆盖)：

__init__(auxfile, **kwargs)
打开 辅助文件 和任何额外的处理 科瓦格人 。

_restart() ，
寻求从…开始 auxfile

close()
关 auxfile

_go_to_step(i)
遍历所有步骤，直到步骤 i 已经到达了。

_reopen()
关 auxfile 然后重新开张。

10.1. 辅助读者 MDAnalysis.auxiliary