4.1.1. 分析构建块 MDAnalysis.analysis.base

MDAnalysis提供了用于创建分析类的构建块。可以将每个分析类别视为对轨迹帧执行特定分析并将结果存储在该工具中的“工具”。

分析类派生自 AnalysisBase 通过子类化。这种继承为用户提供了通用的工作流程和API，并使许多附加功能自动可用(如框架选择和详细的进度条)。分析课的要点是：

1. 分析工具是派生自 AnalysisBase 。

2. 实例化分析时， Universe 或 AtomGroup 该分析操作与为特定分析保持固定的任何其他参数一起提供。

3. 该分析通过以下方式执行 run() 方法。它有一组共同的参数，例如能够选择对其执行分析的帧。这个 verbose 关键字参数启用其他输出。默认情况下会显示进度条，其中还会显示分析结束前剩余时间的估计值。

4. 结果始终存储在属性中 AnalysisBase.results ，它是 Results ，一种允许通过属性访问条目的词典。每个分析类决定存储什么以及如何存储 Results 并需要对其进行记录。对于时间序列， AnalysisBase.times 包含分析的帧的时间戳。

4.1.1.1. Example of using a standard analysis tool

例如， MDAnalysis.analysis.rms.RMSD 按以下方式执行均方根距离分析：

import MDAnalysis as mda
from MDAnalysisTests.datafiles import TPR, XTC

from MDAnalysis.analysis import rms

u = mda.Universe(TPR, XTC)

# (2) instantiate analysis
rmsd = rms.RMSD(u, select='name CA')

# (3) the run() method can select frames in different ways
# run on all frames (with progressbar)
rmsd.run(verbose=True)

# or start, stop, and step can be used
rmsd.run(start=2, stop=8, step=2)

# a list of frames to run the analysis on can be passed
rmsd.run(frames=[0,2,3,6,9])

# a list of booleans the same length of the trajectory can be used
rmsd.run(frames=[True, False, True, True, False, False, True, False,
                 False, True])

# (4) analyze the results, e.g., plot
t = rmsd.times
y = rmsd.results.rmsd[:, 2]   # RMSD at column index 2, see docs

import matplotlib.pyplot as plt
plt.plot(t, y)
plt.xlabel("time (ps)")
plt.ylabel("RMSD (Å)")

4.1.1.2. 编写新的分析工具

为了编写新的分析工具，从 AnalysisBase 并至少定义 _single_frame() 方法，如中所述 AnalysisBase 。

参见

这一章 Writing your own trajectory analysis 在 User Guide 包含使用编写分析工具的分步示例 AnalysisBase 。

4.1.1.3. 班级

这个 Results 和 AnalysisBase 类是中几乎所有MDAnalysis工具的基本构建块 MDAnalysis.analysis 模块。它们的目标是易于使用和扩展。

AnalysisFromFunction 以及 analysis_class() 函数是简单的包装器，如果只需要编写单帧分析函数，则可以更轻松地创建功能齐全的分析工具。

class MDAnalysis.analysis.base.AnalysisBase(trajectory, verbose=False, **kwargs)

用于定义多框架分析的基类

该类被设计为创建多结构件分析的样板。这个类将自动负责设置轨迹读取器以进行迭代，并提供显示进度表。计算结果存储在 results 属性。

To define a new Analysis, AnalysisBase needs to be subclassed and _single_frame() must be defined. It is also possible to define _prepare() and _conclude() for pre- and post-processing. All results should be stored as attributes of the Results container.

参数:

• trajectory (MDAnalysis.coordinates.base.ReaderBase) -- 弹道阅读器

• verbose (bool, optional) -- 启用更多日志记录和调试

times

时间点时间数组。仅在调用 AnalysisBase.run()

类型:

numpy.ndarray

frames

时间步帧索引的数组。仅在调用 AnalysisBase.run()

类型:

numpy.ndarray

results

计算结果在调用后存储 AnalysisBase.run()

类型:

Results

示例

from MDAnalysis.analysis.base import AnalysisBase

class NewAnalysis(AnalysisBase):
    def __init__(self, atomgroup, parameter, **kwargs):
        super(NewAnalysis, self).__init__(atomgroup.universe.trajectory,
                                          **kwargs)
        self._parameter = parameter
        self._ag = atomgroup

    def _prepare(self):
        # OPTIONAL
        # Called before iteration on the trajectory has begun.
        # Data structures can be set up at this time
        self.results.example_result = []

    def _single_frame(self):
        # REQUIRED
        # Called after the trajectory is moved onto each new frame.
        # store an example_result of `some_function` for a single frame
        self.results.example_result.append(some_function(self._ag,
                                                         self._parameter))

    def _conclude(self):
        # OPTIONAL
        # Called once iteration on the trajectory is finished.
        # Apply normalisation and averaging to results here.
        self.results.example_result = np.asarray(self.example_result)
        self.results.example_result /=  np.sum(self.result)

之后，可以像这样运行新的分析

import MDAnalysis as mda
from MDAnalysisTests.datafiles import PSF, DCD

u = mda.Universe(PSF, DCD)

na = NewAnalysis(u.select_atoms('name CA'), 35)
na.run(start=10, stop=20)
print(na.results.example_result)
# results can also be accessed by key
print(na.results["example_result"])

在 1.0.0 版本发生变更: 支持设置 start ， stop ，以及 step 已被移除。现在应将这些参数直接传递给 AnalysisBase.run() 。

在 2.0.0 版本发生变更: 已添加 results

run(start=None, stop=None, step=None, frames=None, verbose=None, *, progressbar_kwargs={})

执行计算

参数:

• start (int, optional) -- 分析的起始框架

• stop (int, optional) -- 停止分析框架

• step (int, optional) -- 要在每个分析的帧之间跳过的帧数

• frames (array_like, optional) -- 用于切片轨迹的整数或布尔数组； frames 只能使用 instead 的 start ， stop ，以及 step 。设置 both frames 并且至少有一项 start ， stop ， step 设置为非默认值将引发 ValueError 。。。版本已添加：：2.2.0

• verbose (bool, optional) -- 启用详细信息

• progressbar_kwargs (dict, optional) -- 带有有关进度条位置等的自定义参数的ProgressBar关键字；请参见 MDAnalysis.lib.log.ProgressBar 查看完整的列表。

在 2.2.0 版本发生变更: 添加了分析任意帧的功能，方法是在 frames 关键字参数。

在 2.5.0 版本发生变更: 增列 progressbar_kwargs 参数，允许修改tqdm进度条的描述、位置等

class MDAnalysis.analysis.base.AnalysisFromFunction(function, trajectory=None, *args, **kwargs)

创建一个 AnalysisBase 来自使用原子组的函数

参数:

• function (callable) -- 函数在每一帧求值

• trajectory (MDAnalysis.coordinates.Reader, optional) -- 要迭代的轨迹。如果 None 在Args和Kwargs中发现的第一个原子群被用作轨迹的来源。

• *args (list) -- arguments for function

• **kwargs (dict) -- arguments for function and AnalysisBase

results.frames

分析中使用的模拟框架

类型:

numpy.ndarray

results.times

分析中使用的模拟时间

类型:

numpy.ndarray

results.timeseries

调用后存储的包装函数的每一帧的结果 AnalysisFromFunction.run() 。

类型:

numpy.ndarray

抛出:

ValueError -- if function has the same kwargs as AnalysisBase

示例

def rotation_matrix(mobile, ref):
    return mda.analysis.align.rotation_matrix(mobile, ref)[0]

rot = AnalysisFromFunction(rotation_matrix, trajectory,
                            mobile, ref).run()
print(rot.results.timeseries)

在 1.0.0 版本发生变更: Support for directly passing the start, stop, and step arguments has been removed. These should instead be passed to AnalysisFromFunction.run().

在 2.0.0 版本发生变更: 原 results 现在存储为 results.timeseries

class MDAnalysis.analysis.base.Results(*args, **kwargs)

用于存储结果的容器对象。

Results are dictionaries that provide two ways by which values can be accessed: by dictionary key results["value_key"] or by object attribute, results.value_key. Results stores all results obtained from an analysis after calling run().

该实现类似于 sklearn.utils.Bunch 中的类 scikit-learn 。

抛出:

• AttributeError -- 如果分配的属性与默认属性同名。

• ValueError -- 如果密钥不是 str 因此不能按属性访问。

示例

>>> from MDAnalysis.analysis.base import Results
>>> results = Results(a=1, b=2)
>>> results['b']
2
>>> results.b
2
>>> results.a = 3
>>> results['a']
3
>>> results.c = [1, 2, 3, 4]
>>> results['c']
[1, 2, 3, 4]

在 2.0.0 版本加入.

MDAnalysis.analysis.base.analysis_class(function)

将在单帧上操作的函数转换为 AnalysisBase 班级。

参数:

function (callable) -- 函数在每一帧求值

results.frames

分析中使用的模拟框架

类型:

numpy.ndarray

results.times

分析中使用的模拟时间

类型:

numpy.ndarray

results.timeseries

调用后存储的包装函数的每一帧的结果 AnalysisFromFunction.run() 。

类型:

numpy.ndarray

抛出:

ValueError -- if function has the same kwargs as AnalysisBase

示例

在库中使用时，我们建议使用以下样式

def rotation_matrix(mobile, ref):
    return mda.analysis.align.rotation_matrix(mobile, ref)[0]
RotationMatrix = analysis_class(rotation_matrix)

它也可以用作装饰品。

@analysis_class
def RotationMatrix(mobile, ref):
    return mda.analysis.align.rotation_matrix(mobile, ref)[0]

rot = RotationMatrix(u.trajectory, mobile, ref).run(step=2)
print(rot.results.timeseries)

在 2.0.0 版本发生变更: 原 results 现在存储为 results.timeseries