10.2. 辅助读者 MDAnalysis.auxiliary.base

用于派生所有辅助数据读取器的基类。请参阅中的API MDAnalysis.auxiliary.__init__ 。

class MDAnalysis.auxiliary.base.AuxStep(dt=1, initial_time=0, time_selector=None, data_selector=None, constant_dt=True, memory_limit=None)

辅助时间步长的基类。

存储当前辅助步骤的辅助数据。在创作上， step 设置为-1。

在 2.4.0 版本发生变更: 添加了MEMORY_LIMIT参数以控制引发内存使用警告。

参数:

• dt (float, optional) -- 辅助步骤之间的时间变化(以PS为单位)。如果未指定，将尝试从辅助数据确定；否则默认为1 ps。在以下情况下忽略 constant_dt 是假的。

• initial_time (float, optional) -- 第一个辅助步骤的时间(PS)。如果未指定，将尝试从辅助数据确定；否则默认为0 ps。在以下情况下忽略 constant_dt 是假的。

• time_selector (optional) -- 在启用时间选择的情况下，从每个步骤读取的全套数据中选择‘Time’值的键；类型将根据辅助数据格式的不同而有所不同(请参阅个别AuxReader文档)。如果 None (缺省值)，时间的计算方式为： time = step * dt + initial_time

• data_selector (optional) -- 如果读卡器启用了数据选择，则按键从为每个步骤读取的全套数据中选择感兴趣的辅助数据值；类型将根据辅助数据格式的不同而有所不同(请参阅各个AuxReader文档)。如果 None (默认值)，则返回完整的数据集。

• constant_dt (bool, optional) -- (默认值：True)如果满足以下条件，则设置为False dt 在辅助数据集中不是恒定的，在这种情况下，有效的 time_selector 必须提供。

• memory_limit (float, optional) -- 按辅助数据设置发出警告的内存使用阈值(GB)。默认：1 GB。

step

当前辅助步骤的编号(从0开始)。

类型:

集成

property data

当前步骤的相关辅助值(如ndarray)。

如果启用了数据选择并且有效，则从每个步骤读取的全套数据中读取 data_selector 则指定；否则默认为完整的数据集。

property time

当前辅助步长的时间(以ps为单位)(浮点数)。

如果启用了时间选择并且有效，则从该组辅助数据读取每个步骤 time_selector 是指定的；否则计算为 step * dt + initial_time 。

class MDAnalysis.auxiliary.base.AuxReader(represent_ts_as='closest', auxname=None, cutoff=None, **kwargs)

辅助读取器的基类。

允许对来自轨迹、常规位置/速度等的附加(辅助)的一组数据进行迭代。该辅助数据可以存储在例如数组或单独的文件中。

请参阅 辅助API 以获取更多有关使用的信息。

在 2.4.0 版本发生变更: 的行为 cutoff 已更改，指定未设置截止的默认参数现在为None，而不是-1。

在 2.4.0 版本发生变更: AuxReader 实例现在有一个 copy() 方法，该方法创建实例的深层副本。

参数:

• auxname (str, optional) -- 辅助数据的名称。当添加到轨迹时，时间步长的代表性辅助值可以被访问为 ts.aux.auxname 或 ts.aux['auxname'] 。

• represent_ts_as (str) -- 用于计算轨迹时间步长的辅助数据代表值的方法。看见 calc_representative() 以获取有效选项。

• cutoff (float, optional) -- 辅助步长距离轨迹时间步长比 cutoff (在PS中)在计算代表值时将被忽略。如果为None(默认)，则将使用分配给该时间点的所有辅助步骤。

• **kwargs -- 要传递给的选项 AuxStep

auxstep

AuxStep 对象，其中包含当前步骤的数据。

frame_data

词典包含 data 从分配给当前轨迹时间步长的每个辅助步长开始，由步长和轨迹时间步长之间的时间差(即 auxstep.time - ts.time ；单位：PS)

类型:

DICT

frame_rep

当前轨迹时间步长的辅助数据的代表值。

类型:

ndarray

备注

假设辅助数据是按时间排序的，并且不包含重复项。

attach_auxiliary(coord_parent, aux_spec: str | Dict[str, str] | None = None, format: str | None = None, **kwargs) → None

中指定的数据 aux_spec 发送到 coord_parent

此方法从内部调用 MDAnalysis.coordinates.base.ReaderBase.add_auxiliary() 。 add_auxiliary 应该与AuxReader的类型无关，因此方法调用指向此处。首先，对参数进行一些检查，以确保正确处理输入。然后，将辅助阅读器(S)与适当的 data_selector 都与 coord_parent 从那里 add_auxiliary 被召唤了。

参数:

• coord_parent (MDAnalysis.coordinates.base.ReaderBase) -- 要附加辅助数据的读取器对象。

• aux_spec (str, Dict[str, str], None) -- 指定要添加到的数据 coord_parent 。字符串类型用于 MDAnalysis.auxiliary.XVG.XVGReader 只有这样。词典是提供以下信息的标准方式 aux_spec 信息(另请参阅： MDAnalysis.auxiliary.EDR )。传球 None 导致添加所有数据。

返回类型:

None

抛出:

ValueError -- 如果尝试将数据添加到 aux_spec 已分配的密钥。

calc_representative()

根据中的数据计算具有代表性的辅助值 frame_data 。

目前实施的用于计算代表性价值的选项包括：

• closest ：默认；距离轨迹时间步长最近的步长的值

• average ：分配给轨迹时间步长的步数的平均值。

此外，如果 cutoff 指定，则在计算代表值时仅考虑轨迹时间步长的此时间内的步长。

如果没有为时间步长指定任何辅助步长，或者没有一个步长在截止范围内，则代表值将设置为 np.nan 。

返回:

表示时间步长的辅助值的数组。

返回类型:

ndarray

property constant_dt

如果满足以下条件，则为真 dt 在整个辅助器中是恒定的(存储在 auxstep )

copy()

返回AuxReader的深层副本

property data_selector

用于从为每个步骤读取的完整数据集中选择感兴趣的辅助数据值的键(存储在 auxstep )。

辅助格式之间的类型不同，具体取决于每个步骤的数据读入和存储方式-例如，来自.xvg文件的数据以列表和 data_selector 必须是有效索引的列表。如果读取器没有启用数据选择， data_selector 将默认为 None 。

查看每个单独的辅助阅读器。

property dt

辅助步骤之间的时间变化(存储在 auxstep ；单位：PS)

get_description()

获取复制AuxReader所需的参数值。

可以使用以下命令复制AuxReader auxreader() ：：

description = original_aux.get_description()
new_aux = MDAnalysis.auxiliary.auxreader(**description)

生成的词典也可以直接传递给 add_auxiliary() 要将辅助对象重新加载到轨迹中，请执行以下操作：

trajectory.add_auxiliary(**description)

返回:

可用于复制AuxReader的关键字参数和值。

返回类型:

dict

property initial_time

第一个辅助步骤的时间(存储在 auxstep ；单位：PS)

move_to_ts(ts)

将辅助阅读器放置在轨迹时间步长之前 ts 。

呼叫 next() 应读取轨迹时间步长的第一个辅助步长 ts 或者，如果没有为该时间步长分配辅助步长(如在较不频繁的辅助数据的情况下)，则之后的第一个辅助步长 ts 。

参数:

ts (Timestep object) -- 辅助阅读器要放置在其之前的轨迹时间步长。

property n_steps

辅助数据中的总步数。

next()

移动到辅助数据的下一步。

next_nonempty_frame(ts)

找到可以计算其代表性辅助值的下一个轨迹帧。

也就是说，下一个轨迹帧，一个或多个辅助步骤被指定到该轨迹帧并落在截止点内。

从当前步长开始查找。如果在找到轨迹帧之前到达辅助数据的末尾，则不返回任何内容。

参数:

ts (Timestep object) -- 从要为其找到下一个非空帧的轨迹开始的任何时间步长。

返回:

轨迹中包含辅助对象的下一个帧的索引。

返回类型:

int

备注

返回的索引可能超出了轨迹的范围。

read_ts(ts)

读取与轨迹时间步长对应的辅助步长 ts 。

阅读分配给的辅助步骤 ts (范围内的步骤 ts.dt/2 轨迹时间步长/帧的长度-即更接近 ts 而不是前一帧或后一帧)。然后，根据这些辅助步骤中的每个步骤中的数据计算时间步长的“代表值”。

要更新 ts 使用具有代表性的值，使用 update_ts 取而代之的是。

参数:

ts (Timestep object) -- 要读取其相应辅助数据的轨迹时间步长。

参见

update_ts()

备注

辅助读取器将最终定位在分配给轨迹帧的最后一步，或者如果该帧不包括辅助步骤(当辅助数据不那么频繁时)，则定位在该帧之前的最新辅助步骤。

property represent_ts_as

计算辅助数据的具有代表性的时间步长值的方法。

rewind()

返回并阅读第一步。

property step

当前辅助步骤的编号(存储在 auxstep ；从0开始)。

step_to_frame(step, ts, return_time_diff=False)

计算辅助步长的最近轨迹帧 step 。

从给定的DT、时间和帧开始计算 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))

步长和计算出的帧之间的时间差也可以通过返回 return_time_diff 。

参数:

• step (int) -- 要为其计算最接近轨迹帧的辅助步数。

• ts (Timestep object) -- (任意)计算的帧编号所对应的轨迹的时间步长。

• return_time_diff (bool, optional) -- (缺省值：FALSE)另外返回 step 和返回的帧。

返回:

• frame_index ( 整型或无 )--最接近(在时间上)给定辅助步骤的轨迹帧的编号。如果步长索引超出辅助数据的范围， None 而是返回。

• time_diff ( 浮动(可选) )--之间的时间差 step 和 frame_index 。

备注

假设轨迹DT是一致的。返回的帧编号可能超出了轨迹的范围。

step_to_time(i)

辅助阶梯的返回时间 i 。

使用以下方法计算 dt 和 initial_time 如果 constant_dt 为True；否则从每个步骤的辅助数据读取的时间列表中。

参数:

i (int) -- 返回时间的步骤的索引(从0开始)

返回:

time --步长时间(PS) i

返回类型:

float

抛出:

ValueError -- 什么时候 i 不在有效范围内

property time

当前辅助步长的时间(存储在 auxstep ；单位：PS)

property time_selector

从为每个步骤读取的全套数据中选择“时间”值的键。存储在 austep 。

辅助格式之间的类型不同，具体取决于每个步骤的数据的读入和存储方式；例如，来自.xvg文件的数据以列表和 time_selector 必须是有效的索引。如果读取器没有启用时间选择， time_selector 将默认为 None 。

查看每个单独的辅助阅读器。

update_ts(ts)

读取轨迹时间步长对应的辅助步长并更新 ts 。

打电话 read_ts() ，然后更新 ts 具有代表性的价值。 auxname 必须设置；代表值将可在 ts 作为 ts.aux.auxname 或 ts.aux['auxname'] 。

参数:

ts (Timestep object) -- 要读取和更新相应辅助数据的轨迹时间步长。

返回:

ts 中具有代表性的辅助值 ts.aux 进行适当的更新。

返回类型:

Timestep

抛出:

ValueError -- 如果 auxname 未设置。

参见

read_ts()

class MDAnalysis.auxiliary.base.AuxFileReader(filename, **kwargs)

从文件读取的辅助读取器的基类。

使用特定于从打开的文件读取辅助数据的属性和方法扩展AuxReader，以便在辅助文件可能太大而无法一次读入时使用。

参数:

• filename (str) -- 包含辅助数据的文件的位置。

• **kwargs -- 其他AuxReader选项。

参见

AuxReader

auxfile

辅助文件的文件对象。

close()

关 辅助文件 。