13.2.10. 助手函数 `MDAnalysis.lib.util`

其他地方不适合的小帮助器函数。

在 0.11.0 版本发生变更: 将数学函数移到lib.mDamath中

13.2.10.1. 文件和目录

MDAnalysis.lib.util.filename(name, ext=None, keep=False)[源代码]

返回附加了后缀的新名称；替换其他扩展名。

参数:

name (str or NamedStream) -- 文件名；扩展名将被替换，除非 keep=True ； name 也可以是 NamedStream (及其 NamedStream.name 将相应更改)
ext (None or str) -- 要在新文件名中使用的扩展名
keep (bool) --
- False ：将现有扩展名替换为 ext ；
- True ：保留旧扩展名(如果存在)

在 0.9.0 版本发生变更: 亦准许 NamedStream 穿过去。

MDAnalysis.lib.util.openany(datasource, mode='rt', reset=True)[源代码]

的上下文管理器 anyopen() 。

打开 datasource 的上下文时将其关闭 with 语句退出。

datasource 可以是文件名或流(请参见 isstream() )。如果可能，将流重置到其起始位置(通过 seek() 或 reset() )。

此函数的优势在于，可以将非常不同的输入源(“流”)用于“文件”，范围从磁盘上的文件(包括压缩文件)到打开的文件对象，再到套接字和字符串-只要它们具有类似文件的接口。

参数:

datasource (a file or a stream) --
mode ({'r', 'w'} (optional)) -- 以r(读取)或w(写入)模式打开
reset (bool (optional)) -- 试着去阅读 (mode ‘R’)从头开始的流 [True]

示例

打开一个gzip文件并逐行处理它：：

with openany("input.pdb.gz") as pdb:
    for line in pdb:
        if line.startswith('ATOM'):
            print(line)

打开一个URL并阅读它：：

import urllib2
with openany(urllib2.urlopen("https://www.mdanalysis.org/")) as html:
    print(html.read())

参见

anyopen()

MDAnalysis.lib.util.anyopen(datasource, mode='rt', reset=True)[源代码]

打开数据源(压缩、压缩、解压缩)并返回一个流。

datasource 可以是文件名或流(请参见 isstream() )。默认情况下，如果可能，会将流重置为其起始位置(通过 seek() 或 reset() )。

如果可能，该属性 stream.name 设置为文件名或“<stream>”，如果没有文件名与 数据源 。

参数:

datasource -- 文件(来自 file 或 open() )或流(例如，来自 urllib2.urlopen() 或 io.StringIO )
mode ({'r', 'w', 'a'} (optional)) -- 以r(读取)、w(写入)或a(Ppend)模式打开。此字符串直接传递给文件打开处理程序(Python的Openfe、bz2或gzip)。如果文件打开处理程序支持，则支持更复杂的模式。
reset (bool (optional)) -- 试着去阅读 (mode ‘R’)从头开始的流

返回类型:

file-like object

参见

openany(): 与一起使用 with 声明。

在 0.9.0 版本发生变更: 仅返回 stream 并试图设置 stream.name = filename 而不是以前返回元组的行为 (stream, filename) 。

在 2.0.0 版本发生变更: 在以下情况下，新的读取处理程序支持Pickle功能 datasource 是一个文件名。中返回自定义可拾取文件流。 MDAnalysis.lib.picklable_file_io 。

MDAnalysis.lib.util.greedy_splitext(p)[源代码]

拆分路径中的扩展名 p 在最左边的分隔符。

使用分隔符将扩展名与文件名分开 os.extsep (由使用 os.path.splitext() )。

参数:: p (str) -- 路径
返回:: (根，扩展名) --在哪里 root 是删除了所有扩展名的完整路径和文件名，而 extension 是所有扩展名的字符串。
返回类型:: tuple

示例

>>> from MDAnalysis.lib.util import greedy_splitext
>>> greedy_splitext("/home/joe/protein.pdb.bz2")
('/home/joe/protein', '.pdb.bz2')

MDAnalysis.lib.util.which(program)[源代码]

确定可执行文件的完整路径 program 在……上面 PATH 。

(周在http://stackoverflow.com/questions/377017/test-if-executable-exists-in-python)

参数:: programe (str) -- 可执行文件的名称
返回:: path --可执行文件的绝对路径(如果可以找到)，否则为 None
返回类型:: str or None

MDAnalysis.lib.util.realpath(*args)[源代码]

加入所有参数并返回实际路径，其根位置为 / 。

扩展‘~’、‘~USER’和环境变量，如 $HOME 。

退货 None 如果有任何参数是 None 。

MDAnalysis.lib.util.get_ext(filename)[源代码]

返回的小写扩展名 filename 没有前导圆点。

参数:

filename (str) --

返回:

root ( str )
ext ( str )

MDAnalysis.lib.util.check_compressed_format(root, ext)[源代码]

检查这是否为受支持的gzipping/bzip2ed文件格式，并返回大写格式。

参数:

root (str) -- 文件的路径，不带扩展名 ext
ext (str) -- 扩展名(目前只有“bz2”和“gz”被识别为压缩格式)

返回:

格式化 --大写格式扩展名 if 可以通过以下方式处理压缩 openany()

返回类型:

str

参见

openany: 用于动态打开和解压缩格式的函数；只有在 openany() 是公认的

MDAnalysis.lib.util.format_from_filename_extension(filename)[源代码]

从文件扩展名猜测文件格式。

参数:: filename (str) --
返回:: format
返回类型:: str
抛出:: TypeError -- 如果无法确定文件格式

MDAnalysis.lib.util.guess_format(filename)[源代码]

返回的格式为 filename

当前的启发式方法只考虑文件扩展名，并且可以绕过压缩格式扩展名。

参数:: filename (str or stream) -- 文件或流的路径，在这种情况下 filename.name 正在寻找格式的提示。
返回:: 格式化 --格式说明符(大写)
返回类型:: str
抛出:: ValueError -- 如果试探法不足以猜测支持的格式

在 0.11.0 版本加入: 移至lib.util

13.2.10.2. 溪流

许多阅读器并不局限于只阅读文件。他们还可以使用gZip压缩或bzip2压缩的文件(通过内部使用 openany() )。还可以提供更通用的流作为输入，例如 io.StringIO 实例(实质上是内存缓冲区)，方法是将这些实例包装到 NamedStream 。这 NamedStream 然后可以用来代替普通的文件名(通常，带有一个类：~MDAnalysis.core.Unibose.Aerse，但也可以写添加到这样的流，使用 MDAnalysis.Writer() )。

在下面的示例中，我们使用存储为字符串的PDB pdb_s ：：

import MDAnalysis
from MDAnalysis.lib.util import NamedStream
from io import StringIO

pdb_s = "TITLE     Lonely Ion\\nATOM      1  NA  NA+     1      81.260  64.982  10.926  1.00  0.00\\n"
u = MDAnalysis.Universe(NamedStream(StringIO(pdb_s), "ion.pdb"))
print(u)
#  <Universe with 1 atoms>
print(u.atoms.positions)
# [[ 81.26000214  64.98200226  10.92599964]]

提供具有正确扩展名(“.pdb”)的正确伪文件名非常重要 NamedStream 因为文件类型识别使用文件名的扩展名来确定文件格式，或者提供 format="pdb" 关键字参数设置为 Universe 。

当MDAnalysis被用作不同分析包之间的粘合剂时，当人们可以安排事情时，流的使用变得更加有趣，以便中间帧(通常是PDB格式)不被写入磁盘，而是通过例如 io.StringIO 缓冲区。

备注

由创建的远程连接 urllib2.urlopen() 是不可查找的，因此通常不能作为输入。但试试看..。

class MDAnalysis.lib.util.NamedStream(stream, filename, reset=True, close=False)[源代码]

流，该流还提供(假)名称。

通过包装一条溪流 stream 在此类中，它可以传递给使用文件名检查来做出决定的代码。例如。 os.path.split() 将在一个 NamedStream 。

该类可以用作上下文管理器。

NamedStream 是从 io.IOBase (以指示它是一个流)。许多通常需要字符串的操作也可以使用 NamedStream ；例如，中的大多数函数 os.path 将与以下对象一起工作 os.path.expandvars() 和 os.path.expanduser() ，它将返回 NamedStream 本身而不是字符串，如果没有进行替换的话。

示例

包装成 io.StringIO 要写入的实例：：

from io import StringIO
import os.path
stream = StringIO()
f = NamedStream(stream, "output.pdb")
print(os.path.splitext(f))

包装成 file 要从中读取的实例：：

stream = open("input.pdb")
f = NamedStream(stream, stream.name)

用作上下文管理器(在以下情况下自动关闭流 with 块在左侧)：：

with NamedStream(open("input.pdb"), "input.pdb") as f:
   # use f
   print f.closed  # --> False
   # ...
print f.closed     # --> True

备注

此类使用它自己的 __getitem__() 方法，因此如果 stream 机具 stream.__getitem__() 那么它将被屏蔽，并且不应该使用这个类。

警告

默认情况下， NamedStream.close() 将要 不关闭溪流 但相反， reset() 一切从头开始。 [1] 提供 force=True 关键字至 NamedStream.close() 总是关闭溪流。

初始化 NamedStream 从一个 stream 并给它一个 name 。

构造函数尝试将流倒回到开头，除非关键字 reset 设置为 False 。如果倒带失败，则会引发 MDAnalysis.StreamWarning 已经发行了。

参数:

stream (stream) -- 明流(例如 file 或 io.StringIO )
filename (str) -- 应与流关联的文件名
reset (bool (optional)) -- 从头开始流(任一 reset() 或 seek() )构造类实例时
close (bool (optional)) -- 在发生以下情况时关闭流 with 数据块退出或何时 close() ；请注意，缺省值为 而不是关闭溪流

备注

默认情况下，此流将 not 被关闭 with 和 close() (见那里)，除非 close 关键字设置为 True 。

在 0.9.0 版本加入.

close(force=False)[源代码]

重置或关闭流。

如果 NamedStream.close_stream 设置为 False (默认)，则此方法将 不关闭溪流 而且只有 reset() 它。

如果力 = True 关键字，则流将被关闭。

备注

这 close() 方法是非标准的。 del NamedStream 始终关闭基础流。

property closed: True 如果流已关闭。

fileno()[源代码]

返回流的基础文件描述符(一个整数)(如果存在)。

一个 IOError 如果IO对象不使用文件描述符，则引发。

flush()[源代码]

刷新流的写入缓冲区(如果适用)。

这对只读和非阻塞流不起任何作用。对于文件对象，还需要调用 os.fsync() 若要将内容写入磁盘，请执行以下操作。

readable()[源代码]

返回 True 如果可以读取流的话。

如果 False ， read() 将筹集 IOError 。

readline()[源代码]

从流中读取并返回一行。

如果指定了SIZE，将读取最大大小的字节。

对于二进制文件，行终止符始终为b‘n’；对于文本文件，要打开的新行参数可用于选择可识别的行终止符。

reset()[源代码]: 移到流的开头

seek(offset, whence=0)[源代码]

将流位置更改为给定的字节 offset 。

参数:

offset (int) -- offset 的位置进行解释。 whence 。
whence ({0, 1, 2} (optional)) -- 的值 whence 是：- io.SEEK_SET 或0-流的开始(默认)； offset 应为零或正数- io.SEEK_CUR 或1-当前流位置； offset 可能是负面的- io.SEEK_END 或2-流的末端； offset 通常为负值

返回:

以字节为单位的新绝对位置。

返回类型:

int

seekable()[源代码]

返回 True 如果流支持随机访问。

如果 False ， seek() ， tell() 和 truncate() 将筹集 IOError 。

tell()[源代码]: 返回当前流位置。

truncate(*size)[源代码]

将流的大小截断为 size 。

参数:: size (int (optional)) -- 这个 size 默认为当前位置(如果没有 size 提供了参数)。当前文件位置不变。

writable()[源代码]

返回 True 如果流可以写入。

如果 False ， write() 将筹集 IOError 。

MDAnalysis.lib.util.isstream(obj)[源代码]

检测是否 obj 是一条小溪。

我们认为任何具有方法的流都是

close()

和以下任一组

read(), readline(), readlines()
write(), writeline(), writelines()

参数:: obj (stream or str) --
返回:: True 如果 obj 是一条小溪， False 否则
返回类型:: bool

参见

io

在 0.9.0 版本加入.

13.2.10.3. 集装箱和清单

MDAnalysis.lib.util.iterable(obj)[源代码]: 退货 True 如果 obj 可以迭代，并且是 not 一个字符串也不是一个 NamedStream

MDAnalysis.lib.util.asiterable(obj)[源代码]

退货 obj 这样它就可以被迭代。

字符串是 not 检测为且可迭代，并包装到 list 只有一种元素。

参见

iterable

MDAnalysis.lib.util.hasmethod(obj, m)[源代码]: 返回 True 如果对象 obj 包含该方法 m 。

class MDAnalysis.lib.util.Namespace[源代码]: 类以允许在新命名空间中存储属性。

13.2.10.4. 阵列

MDAnalysis.lib.util.unique_int_1d(values)

查找一维整数数组的唯一元素。

该函数在排序数组上是最佳的。

参数:: values (numpy.ndarray) -- 数据类型的一维数组 numpy.int64 在其中找到唯一的值。
返回:: 已消除重复数据的副本 values 。
返回类型:: numpy.ndarray

在 0.19.0 版本加入.

MDAnalysis.lib.util.unique_rows(arr, return_index=False)[源代码]

返回数组的唯一行。

参数:

arr (numpy.ndarray) -- 形状数组 (n1, m) 。
return_index (bool, optional) -- 如果 True ，返回形成答案的数组的索引(请参见 numpy.unique() )

返回:

unique_rows ( numpy.ndarray )--形状数组 (n2, m) 只包含唯一的行 arr 。
r_idx ( Numpy.ndarray(可选) )--包含相应行索引的数组(如果 return_index 是 True )。

示例

从数组中删除重复行：

>>> import numpy as np
>>> from MDAnalysis.lib.util import unique_rows
>>> a = np.array([[0, 1], [1, 2], [1, 2], [0, 1], [2, 3]])
>>> b = unique_rows(a)
>>> b
array([[0, 1],
       [1, 2],
       [2, 3]])

参见

numpy.unique

MDAnalysis.lib.util.blocks_of(a, n, m)[源代码]

摘录……的视图 (n, m) 沿阵列对角线的块 a 。

参数:

a (numpy.ndarray) -- 输入数组，必须为C连续且至少为2D。
n (int) -- 第一维的块大小。
m (int) -- 第二维的块大小。

返回:

view --具有形状的原始数组的视图 (nblocks, n, m) ，在哪里 nblocks 是形状的小块的次数 (n, m) 穿上原件。

返回类型:

numpy.ndarray

抛出:

ValueError -- 如果提供的 n 和 m 不要分裂 a 为整数个块，或者如果 a 不是C连续的。

示例

>>> import numpy as np
>>> from MDAnalysis.lib.util import blocks_of
>>> arr = np.arange(16).reshape(4, 4)
>>> view = blocks_of(arr, 2, 2)
>>> view[:] = 100
>>> arr
array([[100, 100,   2,   3],
       [100, 100,   6,   7],
       [  8,   9, 100, 100],
       [ 12,  13, 100, 100]])

备注

n ， m 必须分开 a 分成相同的整数个块。请注意，如果块大小大于输入数组，则该数字将为零，从而导致空视图！

使用步长，因此要求数组是C连续的。

返回一个视图，因此编辑它会修改原始数组。

在 0.12.0 版本加入.

MDAnalysis.lib.util.group_same_or_consecutive_integers(arr)[源代码]

将整数数组拆分为相同或连续的序列列表。

参数:

arr (numpy.ndarray) --

返回:

列表： numpy.ndarray
示例
>>> import numpy as np
[>>> arr = np.array([ 2, 3, 4, 7, 8, 9, 10, 11, 15, 16])]
>>> group_same_or_consecutive_integers(arr)
[[数组([2，3，4])，数组([7，8，9，10，11])，数组([15，16])]]

13.2.10.5. 文件解析

class MDAnalysis.lib.util.FORTRANReader(fmt)[源代码]

FORTRANReader提供了一种解析文件中FORTRAN格式行的方法。

文件中各行的内容可以根据FORTRAN格式的编辑描述符进行解析(请参见 Fortran Formats 用于语法)。

此处仅支持简单的单字符说明符： I F E A X (请参阅 FORTRAN_format_regex )。

字符串将去掉前导空格和尾随空格。

使用FORTRAN格式字符串设置读卡器。

这根弦 fmt 应该看起来像‘2I10，2X，A8，2X，A8，3F20.10，2X，A8，2X，A8，F20.10’。

参数:: fmt (str) -- 行的Fortran格式编辑描述符，如所述 Fortran Formats

示例

解析标准CRD文件：：

atomformat = FORTRANReader('2I10,2X,A8,2X,A8,3F20.10,2X,A8,2X,A8,F20.10')
for line in open('coordinates.crd'):
    serial,TotRes,resName,name,x,y,z,chainID,resSeq,tempFactor = atomformat.read(line)

number_of_matches(line)[源代码]: 返回可以用合法值填充的格式条目的数量。

parse_FORTRAN_format(edit_descriptor)[源代码]

解析描述符。

参数:: edit_descriptor (str) -- Fortran格式编辑描述符
返回:: 包含总长度(字符)、重复、长度、格式、小数的词典
返回类型:: dict
抛出:: ValueError -- 这个 edit_descriptor 无法识别且无法解析

备注

说明符： L ES EN T TL TR / r S SP SS BN BZ 是 not 得到支持，科学记数法也不受支持 Ew.dEe 表格。

read(line)[源代码]

解析 line 根据格式字符串返回值列表。

值根据格式说明符转换为Python类型。

参数:: line (str) --
返回:: 具有适当类型的条目列表
返回类型:: list
抛出:: ValueError -- 无法进行任何转换(例如，int的空格)

参见

FORTRANReader.number_of_matches()

MDAnalysis.lib.util.FORTRAN_format_regex = '(?P<repeat>\\d+?)(?P<format>[IFEAX])(?P<numfmt>(?P<length>\\d+)(\\.(?P<decimals>\\d+))?)?': 常规表达(请参阅 re )解析简单的 FORTRAN edit descriptor 。 (?P<repeat>\d?)(?P<format>[IFELAX])(?P<numfmt>(?P<length>\d+)(\.(?P<decimals>\d+))?)?

13.2.10.6. 数据操作和处理

MDAnalysis.lib.util.fixedwidth_bins(delta, xmin, xmax)[源代码]

宽度回收箱 delta 那个封面 xmin ， xmax (或更大范围)。

仓位参数的计算使得仓位大小 delta 是有保证的。为了实现这一点，范围 [xmin, xmax] 可以增加。

可以为1D数据(然后所有参数都是简单的浮点数)或ND数据(然后参数以数组形式提供，每个条目对应于一维)计算bin。

参数:

delta (float or array_like) -- 料箱的所需间距
xmin (float or array_like) -- 下限(第一个面元的左边界)
xmax (float or array_like) -- 上界(最后一个面元的右边界)

返回:

DICT包含‘nbins’、‘Delta’、‘min’和‘max’；它们可以是浮点数，也可以是数组，具体取决于输入。

返回类型:

dict

示例

与一起使用 numpy.histogram() ：：

B = fixedwidth_bins(delta, xmin, xmax)
h, e = np.histogram(data, bins=B['Nbins'], range=(B['min'], B['max']))

MDAnalysis.lib.util.get_weights(atoms, weights)[源代码]

检查是否有 weights 参数与兼容 atoms 。

参数:

atoms (AtomGroup or array_like) -- 这些原子是 weights 应适用于。通常，这是一个 AtomGroup 但是因为只比较长度，所以任何与之对应的序列 len(atoms) 是可以接受的。
weights ({"mass", None} or array_like) -- 所有MDAnalysis函数或类都理解“MASS”，然后将使用 atoms.masses 。 None 表示所有原子的重量相等。使用 array_like 将自定义权重分配给 atoms 。

返回:

重量 --如果选择“MASS”， atoms.masses 是返回的，否则 weights (可以是 None )。

返回类型:

array_like or None

抛出:

TypeError -- 如果 weights 不是允许值之一，或者如果选择了“MASS”，但 atoms.masses 不可用。
ValueError -- 如果 weights 不是长度相同的一维数组 atoms ，则引发异常。 TypeError ，则也会引发 atoms.masses 未定义。

MDAnalysis.lib.util.ltruncate_int(value, ndigits)[源代码]

截断整数，保留最低有效数字

参数:

value (int) -- 要截断的值
ndigits (int) -- 要保留的位数

返回:

截断 --只有 ndigits 最低有效数字来自 value

返回类型:

int

示例

>>> from MDAnalysis.lib.util import ltruncate_int
>>> ltruncate_int(123, 2)
23
>>> ltruncate_int(1234, 5)
1234

MDAnalysis.lib.util.flatten_dict(d, parent_key=())[源代码]

拼合嵌套词典 d 转换成一个以元组为键的浅表字典。

参数:: d (dict) --
返回类型:: dict

备注

基于https://stackoverflow.com/a/6027615/by User https://stackoverflow.com/users/1897/imran

在 0.18.0 版本加入.

13.2.10.7. 字符串

MDAnalysis.lib.util.convert_aa_code(x)[源代码]

在3个字母和1个字母的氨基酸代码之间转换。

参数:: x (str) -- 1字母或3字母氨基酸代码
返回:: 3字母或1字母氨基酸代码
返回类型:: str
抛出:: ValueError -- 不能进行转换；没有定义氨基酸代码。

备注

数据在中定义 amino_acid_codes 和 inverse_aa_codes 。

MDAnalysis.lib.util.parse_residue(residue)[源代码]

加工残留物字符串。

参数:: residue (str) -- 这个残渣必须包含一个由1个字母、3个字母或4个字母组成的残数字符串、一个数字(残数)和一个原子标识符(可选)，它必须与残数之间用冒号(“：”)隔开。中间允许留有空格。
返回:: (3-letter aa string, resid, atomname) ；已知的1字母AA代码转换为3字母代码
返回类型:: tuple

示例

“LYS300：HZ1”-->(“Lys”，300，“HZ1”)
“K300：HZ1”-->(“Lys”，300，“HZ1”)
“K300”-->(“lys”，300，无)
“4GB300：H6O”-->(“4 GB”，300，“H6O”)
“4GB300”-->(“4 GB”，300，无)

MDAnalysis.lib.util.conv_float(s)[源代码]

转换对象 s 如果可能的话，漂浮起来。

要传入的函数 map() 或者是对清单的理解。如果参数可以解释为浮点数，则将其转换为浮点数，否则将返回原始对象。

13.2.10.8. 班级装饰者

MDAnalysis.lib.util.cached(key, universe_validation=False)[源代码]

在类中缓存属性。

要求类具有缓存词典 _cache 而且，有了 universe_validation, a universe with a cache dict :attr:`_ 高速缓存。

示例

如何将变量的缓存添加到类中 @cached 装饰师：：

class A(object):
    def__init__(self):
        self._cache = dict()

    @property
    @cached('keyname')
    def size(self):
        # This code gets run only if the lookup of keyname fails
        # After this code has been run once, the result is stored in
        # _cache with the key: 'keyname'
        return 10.0

    @property
    @cached('keyname', universe_validation=True)
    def othersize(self):
        # This code gets run only if the lookup
        # id(self) is not in the validation set under
        # self.universe._cache['_valid']['keyname']
        # After this code has been run once, id(self) is added to that
        # set. The validation set can be centrally invalidated at the
        # universe level (say, if a topology change invalidates specific
        # caches).
        return 20.0

在 0.9.0 版本加入.

MDAnalysis.lib.util.store_init_arguments(func)[源代码]

用于存储传递给类的init方法的参数的修饰符。

参数以词典形式存储在 cls._kwargs 。

备注

只进行浅层复制，如果参数在通过修饰器后被类更改，这将反映在存储的参数中。
如果不是空的， args 未解包并按原样存储在词典中。如果没有 args 都通过了，那么不 arg 词条将存储在词典中。

在 2.2.0 版本加入.

13.2.10.9. 函数装饰符

MDAnalysis.lib.util.static_variables(**kwargs)[源代码]

为函数或方法配备静态变量的修饰符。

通过向修饰符提供关键字参数和初始值来声明和初始化静态变量。

示例

>>> from MDAnalysis.lib.util import static_variables
>>> @static_variables(msg='foo calls', calls=0)
... def foo():
...     foo.calls += 1
...     print("{}: {}".format(foo.msg, foo.calls))
...
>>> foo()
foo calls: 1
>>> foo()
foo calls: 2

备注

基于https://stackoverflow.com/a/279586 by Claudiu

在 0.19.0 版本加入.

MDAnalysis.lib.util.warn_if_not_unique(groupmethod)[源代码]

装饰器触发 DuplicateWarning 如果基础组不是唯一的。

确保在修饰方法的执行过程中，只显示有关组唯一性的可能多个警告中的第一个。

抛出:: DuplicateWarning -- 如果 AtomGroup ， ResidueGroup ，或 SegmentGroup 其修饰方法是包含重复项的成员。

在 0.19.0 版本加入.

MDAnalysis.lib.util.check_coords(*coord_names, **options)[源代码]

用于自动坐标数组检查的装饰器。

此装饰器特别适用于 MDAnalysis.lib.distances 。它接受任意数量的位置参数，这些参数必须与修饰函数的位置参数名称相对应。然后，它检查相应的值是有效的坐标数组还是 AtomGroup 。如果输入是数组并且所有这些数组都是单个坐标(即，它们的形状是 (3,) )，修饰后的函数可以选择返回单个坐标(或角度)，而不是一组坐标(或角度)。这可用于使用最初设计为仅接受2-D坐标数组的函数来计算单个观测值。

如果输入是一个 AtomGroup 通过调用将其转换为其对应的位置数组 AtomGroup.positions 。

对每个单独的坐标数组执行的检查包括：

检查坐标数组是否为 numpy.ndarray 。
检查坐标数组是否具有 (n, 3) (或 (3,) 如果允许单个坐标；请参阅关键字参数 allow_single )。
自动将数据类型转换为 numpy.float32 。
可选地替换为副本；请参见关键字参数 enforce_copy 。
如果坐标数组不是C连续的，它们将被C连续的副本自动替换。
可选检查所有坐标数组的长度是否相等；请参见可选关键字参数 check_lengths_match 。

参数:

*coord_names (tuple) -- 与修饰函数的位置参数名称对应的任意数量的字符串。
**options (dict, optional) --
- enforce_copy (bool, optional) -- Enforce working on a copy of the coordinate arrays. This is useful to ensure that the input arrays are left unchanged. Default: True
- enforce_dtype (bool, optional) -- Enforce a conversion to float32. Default: True
- allow_single (bool, optional) -- Allow the input coordinate array to be a single coordinate with shape (3,).
- convert_single (bool, optional) -- If True, single coordinate arrays will be converted to have a shape of (1, 3). Only has an effect if allow_single is True. Default: True
- reduce_result_if_single (bool, optional) -- If True and all input coordinates are single, a decorated function func will return func()[0] instead of func(). Only has an effect if allow_single is True. Default: True
- check_lengths_match (bool, optional) -- If True, a ValueError is raised if not all coordinate arrays contain the same number of coordinates. Default: True
- allow_atomgroup (bool, optional) -- If False, a TypeError is raised if an AtomGroup is supplied Default: False

抛出:

ValueError -- 如果使用不带位置参数的修饰符(仅用于开发目的)。如果提供给修饰符的任何位置参数与修饰函数的任何位置参数的名称不对应。如果任何坐标数组具有错误的形状。
TypeError -- 如果任何坐标数组不是 numpy.ndarray 或者是一个 AtomGroup 。如果任何坐标数组的数据类型不能转换为 numpy.float32 。

示例

>>> import numpy as np
>>> import MDAnalysis as mda
>>> from MDAnalysis.tests.datafiles import PSF, DCD
>>> from MDAnalysis.lib.util import check_coords
>>> @check_coords('coords1', 'coords2', allow_atomgroup=True)
... def coordsum(coords1, coords2):
...     assert coords1.dtype == np.float32
...     assert coords2.flags['C_CONTIGUOUS']
...     return coords1 + coords2
...
>>> # automatic dtype conversion:
>>> coordsum(np.zeros(3, dtype=np.int64), np.ones(3))
array([1., 1., 1.], dtype=float32)
>>>
>>> # automatic handling of non-contiguous arrays:
>>> coordsum(np.zeros(3), np.ones(6)[::2])
array([1., 1., 1.], dtype=float32)
>>>
>>> # automatic handling of AtomGroups
>>> u = mda.Universe(PSF, DCD)
>>> try:
...     coordsum(u.atoms, u.select_atoms("index 1 to 10"))
... except ValueError as err:
...     err
ValueError('coordsum(): coords1, coords2 must contain the same number of coordinates, got [3341, 10].')
>>>
>>> # automatic shape checking:
>>> try:
...     coordsum(np.zeros(3), np.ones(6))
... except ValueError as err:
...     err
ValueError('coordsum(): coords2.shape must be (3,) or (n, 3), got (6,)')

在 0.19.0 版本加入.

在 2.3.0 版本发生变更: 现在可以接受 AtomGroup 作为输入，并添加了默认为FALSE的选项ALLOW_ATMGroup以保留旧行为

MDAnalysis.lib.util.check_atomgroup_not_empty(groupmethod)[源代码]

装饰器触发 ValueError 如果基础组为空。

避免在计算空原子组的属性时出现下游错误。

抛出:: ValueError -- 如果输入 AtomGroup ，则修饰方法的。

在 2.4.0 版本加入.

13.2.10.10. 代码管理

MDAnalysis.lib.util.deprecate(*args, **kwargs)[源代码]

发出DeproationWarning，向 old_name 的文档字符串，重新绑定 old_name.__name__ 并返回新的函数对象。

此函数也可用作装饰符。

它添加了一个重新构造的文本 .. deprecated:: release 使用已弃用的狮身人面像角色阻止到文档的末尾。这个 message 添加到弃用块下，并包含 release 其中该函数已弃用。

参数:

func (function) -- 要弃用的函数。
old_name (str, optional) -- 要弃用的函数的名称。缺省值为无，在这种情况下， func 是使用的。
new_name (str, optional) -- 函数的新名称。缺省值为None，在这种情况下，不推荐使用的消息为 old_name 已弃用。如果给出，不推荐使用的消息是 old_name 已弃用，并且 new_name 应该改为使用。
release (str) -- 该函数已弃用的发行版。出于技术原因，这是作为关键字参数给出的，但它是必需的；a ValueError 如果它丢失，则引发。
remove (str, optional) -- 计划删除该功能的版本。
message (str, optional) -- 对这一弃用的其他解释。在警告后的文档字符串中显示。

返回:

old_func --不推荐使用的函数。

返回类型:

function

示例

什么时候 deprecate() 用作以下示例中的函数，

oldfunc = deprecate(func, release="0.19.0", remove="1.0",
                    message="Do it yourself instead.")

然后 oldfunc 将在打印后返回值 DeprecationWarning ； func 仍然像以前一样可用。

当用作装饰者时， func 将被更改，并发出警告，并在DO字符串中包含弃用注释。

@deprecate(release="0.19.0", remove="1.0",
           message="Do it yourself instead.")
def func():
    \"\"\"Just pass\"\"\"
    pass

生成的文档字符串 (help(func) )将如下所示：

`func` is deprecated!

Just pass.

.. deprecated:: 0.19.0
   Do it yourself instead.
   `func` will be removed in 1.0.

(更改名称是可能的，但令人困惑 func 使用修饰符，因此不建议使用 new_func 与装饰符的关键字参数。)

在 0.19.0 版本加入.

class MDAnalysis.lib.util._Deprecate(old_name=None, new_name=None, release=None, remove=None, message=None)[源代码]

修饰器类来弃用旧函数。

请参阅 deprecate 有关详细信息，请参阅。

参见

deprecate

在 0.19.0 版本加入.

MDAnalysis.lib.util.dedent_docstring(text)[源代码]

Dedent Typical Python文档字符串。

参数:: text (str) -- 字符串，通常类似于 func.__doc__ 。
返回:: 从每行中删除了前导公共空格的字符串
返回类型:: str

参见

textwrap.dedent

在 0.19.0 版本加入.

13.2.10.11. 数据格式检查

MDAnalysis.lib.util.check_box(box)[源代码]

接受框输入，并根据数组的形状和是否所有角度都是90度来推断它表示的是哪种系统类型。

参数:

box (array_like) -- 系统的单位单元尺寸，可以是正交的或三斜的，并且必须以与返回的相同格式提供 MDAnalysis.coordinates.timestep.Timestep.dimensions ： [lx, ly, lz, alpha, beta, gamma] 。

返回:

方框类型 ({‘矫形’， 'tri_vecs' })--指示长方体类型的字符串(正交或三斜)。
checked_box ( numpy.ndarray )-
数据类型数组 numpy.float32 包含框信息：
- 如果 boxtype 是 'ortho' ， cecked_box 会有这样的形状 (3,) 包含正交框的x、y和z维的。
- 如果 boxtype 是 'tri_vecs' ， cecked_box 会有这样的形状 (3, 3) 在由返回的下三角矩阵中包含三斜向量的 triclinic_vectors() 。

抛出:

ValueError -- 如果 box 不属于以下形式 [lx, ly, lz, alpha, beta, gamma] 或包含无法转换为 numpy.float32 。

参见

MDAnalysis.lib.mdamath.triclinic_vectors

脚注

13.2.10. 助手函数 MDAnalysis.lib.util

13.2.10.1. 文件和目录

13.2.10.2. 溪流

13.2.10.3. 集装箱和清单

13.2.10.4. 阵列

13.2.10.5. 文件解析

13.2.10.6. 数据操作和处理

13.2.10.7. 字符串

13.2.10.8. 班级装饰者

13.2.10.9. 函数装饰符

13.2.10.10. 代码管理

13.2.10.11. 数据格式检查

13.2.10. 助手函数 `MDAnalysis.lib.util`