PPbank cli 工具
ppbank cli(ppbank 数据库命令行工具)是用于和 ppbank 数据库进行交互的命令行工具。使用前请保证系统的 Python 版本 > 3.6
它的使用非常简单,只需要:
-
使用
pip3 install ppbank
安装 -
使用形如
ppbank get/put/delete 2-IG-N
的方式操作数据库
详细的使用说明请看 使用说明
服务端已运行于公网和 91 之上,用户使用 ppbank 命令连接数据库进行操作。
PPbank 数据库命令行工具使用说明
ppbank 命令用于和 PPbank 数据库进行交互。请保证系统的 Python 版本 > 3.6
安装
-
运行
pip3 install ppbank
即可安装 ppbank 命令行工具到系统中。91 已经全局安装。将以下路径加入到用户
~/.bashrc
文件中即可。export PATH=/opt/bin/:/opt/python3.7/bin/:$PATH
-
新建并编辑配置文件
~/.ppbank/config
内容如下,以设置服务器地址:
[global]
API_ADDRESS = https://ppbankapi.snquantum.com/
API_ADDRESS是连接服务器的地址,https://ppbankapi.snquantum.com/ 是 ppbank api server 的公网域名。
如果是内部使用,则采用 http://api.ppbank.lab/ 是指向 91 的内部域名。
可以添加一行 SHOW_ADDRESS = True
让执行命令时显示服务器地址的提示信息。若不需要,设为 False 或者无需此行即可。
注意以上字符串不要加引号。
使用
- 使用形如
ppbank command [arguments]
格式的命令读写数据库。其中 command 为 get/put/delete 等操作,argument 为 name 等参数。它们具体是:
命令1 | 作用 |
---|---|
ls | 列出库中已有分子 |
get (name) | 指定文件夹名为分子名的路径,获取分子。如库中没有,或者当前文件夹以及被占用,则给出提示,返回 error。成功返回 ok。 |
get-att (name) | 指定文件夹名为分子名的路径,获取分子的附属文件。如果当前目录已经有分子文件夹则添加到分子文件内部。 |
get-by-energy (name, energy) | 获取分子,但是有能量截取 |
put (name) | 将文件夹分子系综放入数据库, 如果库中已有,则给出提示已有并返回 error,成功则返回 ok。格式不标准等其他错误就终止。 |
replace (name) | 将文件夹分子系综放入数据库,强制替换已有。成功返回 ok。格式不标准等其他错误就终止。 |
rm (name) | 无论有无,强制删除指定名字的分子。正常结束返回 ok。 |
trans (name) | 数据格式标准化(内部使用) |
例如 ppbank get 2-IG-C@All
会将 2-IG-C 分子系综从数据库中取出保存在本地 2-IG-C 文件夹中。其他 put/delete/replace 等命令的使用方法类似。name 即为操作的分子名字,同时也是分子文件夹的名字。ppbank ls
则会列出库中所有已有的分子名字。
分子名称遵循此规则:[氨基酸残基数]-[肽首字母缩略名称]-[修饰]@[方法名],每个分子名称都代表一个分子集合。
name 可以提供路径作为参数,例如2-IG-N
或者/xxx/xxx/2-IG-N
, 调用函数会将分子导入或导出于此路径。函数的返回值是 ok 或者 error。如遇获取不存在的分子,或者插入已经存在的分子等情况,会以返回值的形式返回错误,根据返回特定的信息,可以自动化处理。
输入输出所使用的分子目录的格式为:
2-IG-N # 文件夹名,定义分子类型
├── conformers.csv # 构型列表,构型名(xyz 文件名),以及二面角信息
└── xyzfiles # xyz 文件
├── 1.xyz
├── 2.xyz
├── 3.xyz
├── 4.xyz
├── 5.xyz
├── 6.xyz
├── 7.xyz
├── 8.xyz
└── 9.xyz
其中conformers.csv
的格式为:(注意保持字段顺序)
conf_name,dih,dih_pattern,energy, free_energy
1.xyz, -79.672464 73.137517 78.209517 -70.034427 -175.393735,,0,
2.xyz, -79.672464 73.137517 78.209517 -70.034427 -175.393735,,0.53,
3.xyz, 79.775187 -72.915380 -78.202357 69.669860 175.640935,,0.63,
4.xyz, 80.503011 -61.822300 82.027238 -66.545708 -176.760001,,0.73,
5.xyz, -80.605568 61.773737 -81.972349 66.519240 176.787131,,0.82,
6.xyz, 64.302447 -128.813377 -98.214639 14.087818 -175.932473,,1.23,
7.xyz, -73.531925 96.508380 96.469302 4.407415 -175.054001,,1.51,
8.xyz, 73.022488 -102.860313 -99.579128 1.176942 176.759693,,2.04,
9.xyz, 78.446928 -74.853998 -64.618264 157.350513 171.373810,,2.13,
conformers.csv
的每行是一个构型,包含 xyz 的名字(构型名字)和二面角数值。具体的xyz坐标则以构型名对应的文件的方式放在 xyzfiles 文件夹下。conformers.csv
文件包含的字段详细说明如下:
字段 | 意义 | 类型 |
---|---|---|
conf_name | 构型名,实际为 xyz 文件名 | 可变长度字符串 |
xyz | xyz 坐标 | 可变长度字符串 |
dih | 二面角 | 可变长度字符串 |
dih_pattern | 二面角模板定义 | 可变长度字符串 |
energy | 能量,缺省值为 INF 无穷大 | 浮点 |
free_energy | 自由能,缺省值为 INF 无穷大 | 浮点 |
如有其他额外的文件如用以描述分子(不是构型)的 simple_description.txt 和 detailed_desctiption.txt,文章和补充说明等也放在分子文件夹下面留用,不影响描述构型的标准格式。
**分子文件夹以此为标准入库,不再分成 xyz 和 dih 两种形式以免混淆,即要求同时提供 xyz 和生成好的二面角方可入库,入库前要完成 xyz 到二面角的转换。但是暂未要求强制校验。**取出时也是取出此形式,无需转换耗时。
以后有需要可以提供单独取出 xyz 或者二面角的函数。然而实际计算中读写数据库的时间相比计算时间其实可以忽略,如要节省存储空间可以本地自行删除 xyzfiles 文件夹,但是入库的时候还是要生成 xyz 以符合入库要求。
对于以后的只需要一些组合信息的查询,例如数据库匹配的高级的判断(不只看是否存在构型,而是结合能量范围构型数目或者能量值来匹配),可根据需求再新增相应函数。
- 运行
ppbank example
(待添加)可以获取分子文件夹格式样例,运行ppbank --help
以及ppbank command --help
来查看帮助。 - 分子整理入库成功后,请保留已标准化的源文件夹以备用和作为备份。
原 get-conformers 等命令考虑到便利性已经缩短为 get 等。
进阶
- Python中可以直接
import ppbank
,就可以直接使用相应函数。例如:
import ppbank
ans = ppbank.get ("2-IG-N") # call function directly.
if ans == "error":
print("can not get conformers ")
exit(-1)
# if has no error, the files were already getted in the path folder.
# then do something ...
- C 语言中可使用
system("ppbank get 2-IG-N")
的方式调用,后续提供以#include
的函数方式调用。 - Shell 脚本中使用,按照使用说明直接调用
ppbank
命令即可。 - 目前功能主要是提供标准化入库出库和基本查询,以后补充数据库统计以及更方便的构型的浏览。
参考
本部分提供更多详细的参考信息
ppbank 命令行工具环境要求:
-
Python 版本 > 3.6
-
因为 91 没有域名,需配置 /etc/host 添加服务器地址,一般用户使用公网的服务器则无需此配置
xxx.xxx.xxx.91 ppbank.lab # 出于安全考虑隐去了 91 的ip 地址,请填写 91 的地址 xxx.xxx.xxx.91 api.ppbank.lab
以上环境要求在 91 上面已经满足。
用 pyenv 以用户身份安装 python
若是普通的独立用户没有管理员权限,系统上没有 Python,则参考下面推荐用 pyenv 安装 Python,可以自动安装任意版本的 Python 。
# install pyenv
curl https://pyenv.run | bash
# add these to ~/.bashrc to enable the pyenv command
export PATH="$HOME/.pyenv/bin:$PATH"
eval "$(pyenv init -)"
eval "$(pyenv virtualenv-init -)"
# install python 3.7.4 version
pyenv install 3.7.4
# set current version
pyenv global 3.7.4
done!
#### other commands #####
# refresh
pyenv rehash
# delete a python version
pyenv uninstall 3.7.4
数据库的模型逻辑层级:
Molecules
Molecule(Conformers)
conformer
conformer
...
Molecule
Molecule
...
服务器端的 REST API
http://api.ppbank.snquantum.com/Molecules
http://api.ppbank.snquantum.com/Molecule
http://api.ppbank.snquantum.com/Conformers
http://api.ppbank.snquantum.com/Conformer
提供标准的 http 的 GET, POST, PUT, DELETE 进行 CRUD 操作。
以及 Application 和 Settings 等具体的自动生成的文档在 http://api.ppbank.snquantum.com/docs 查看
而 api
http://api.ppbank.snquantum.com/put_conformers
http://api.ppbank.snquantum.com/get_conformers
http://api.ppbank.snquantum.com/del_conformers
提供构文件夹形式的的查找读写并转换到提供命令行操作
数据对象字段和类型
Molecules:
mole_name = models.TextField()
residue_num = models.IntegerField(default=0)
seq = models.TextField()
modification = models.TextField()
docx_description = models.TextField()
detailed_description = models.TextField()
simple_description = models.TextField()
showxyz = models.TextField()
img = models.TextField()
Conformers
mole_name = models.TextField()
residue_num = models.IntegerField(default=0)
seq = models.IntegerField(default=0)
modification= models.TextField()
conf_name = models.TextField()
xyz = models.TextField()
dih = models.TextField()
dih_pattern = models.TextField()
energy = models.FloatField(default=INF)
free_energy = models.FloatField(default=INF)