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 等参数。它们具体是：

命令¹	作用
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)

PPbank Cli docs