# Dock User Guide

Dock 模块是通过串联分子对接软件 python API 来实现各类分子设计与评估功能、筛选等工作流的自动化模块。   
目前, Dock 仅针对 Schrodinger Suites 进行开发，并计划在未来添加更多主流分子对接软件的支持。

**关于Schrodinger虚拟环境**  
由于Schrodinger Suite使用了闭源环境提供Python API调用, 使用 `Dock` 模块相关功能(包括CLI命令)脚本时, 应该保证您正处于由 Schrodinger 建立的虚拟环境中，并在该环境中安装 `pyCADD`。 
* 现在，Dock 模块的 CLI 接口 `pycadd-dock` 已能够自动创建 schrodinger 虚拟 python 环境，并在其中运行 Dock 模块，您无需进行额外的`source`等操作。 `pycadd-dock` 通过 `SCHRODINGER` 变量确定您的 Schrodinger 安装位置，如果您的 `SCHRODINGER` 变量未指定，则在首次运行`pycadd-dock`接口时，会提示您提供 Schrodinger Suite 的安装目录路径。
* 通过 python 导入 Dock 模块仍然需要您自行创建或激活 Schrodinger 虚拟环境。例如使用 
    ```
    $SCHRODINGER/run schrodinger_virtualenv.py schrodinger.ve
    source schrodinger.ve/bin/activate
    python3 -m pip install pycadd -U
    ```
    命令可在当前目录下创建名为 `schrodinger.ve` 的虚拟环境，激活并在其中安装 `pyCADD`。 更多信息请参阅 [如何建立Schrodinger Python Virtual Env](https://content.schrodinger.com/Docs/r2022-1/python_api/intro.html#per-user-virtual-environments-for-installing-additional-modules)。

## Download PDB file(s)
`pyCADD` 的 `pycadd-dock download` 提供了从PDB数据库进行多线程批量下载PDB结构文件的功能（需要互联网）。
使用 `pycadd-dock download -i PDBID` 下载单一结构，或在一个文件 `example.csv` 中列出您想要下载的PDB ID：

```
1FBY
3OAP
4K6I
5JI0
```
然后使用 `pycadd-dock download -f example.csv [-s SAVE_DIR]` (在当前目录或指定目录SAVE_DIR) 批量下载它们。

## Docking of Many-to-many (Ensemble Docking)

`pyCADD` 的 `pycadd-dock ensemble-dock` 提供了高性能多核并行系综对接 (Ensemble Docking) 计算及数据处理的CLI接口。  

请确保当前工作目录在您想要保存项目文件的目录中, 并在目录中额外准备：

* 一个分行列出的, 包含所有受体蛋白所属 PDB ID的输入文件，支持的格式包括 **.csv** **.ini** **.in** **.yaml** **.yml**, 支持的输入文件格式请参阅 [为Ensemble Docking构建Dock输入文件的示例](#generate-input-files-for-ensemble-docking)。该输入文件可由`Demand`模块自动生成，或由您手动创建;  
* 一个需要对接的化合物库 **3D结构文件** **.pdb*  **.mae* **.sdf* 或其他Schrodinger支持的格式  
    如果晶体包含有多个不同名称(ID)的小分子配体, 请在文件中指明 (以逗号分隔) 以定义对接 Grid Box 的中心;   
    如包含相同名称的多个小分子，则 `Dock` 会自动选择其中之一定义为对接 Grid Box 的中心。

以下是一个输入文件的示例 *example.csv*：  
```
3OAP,9CR
5JI0,BRL
4K6I,9RA
```

提供一个准备就绪的用于对接的化合物库文件(其中含有若干个结构)，如 *library_file.sdf*，其中包含若干个已经完成了氢原子添加、质子化状态计算、能量最小化等预处理步骤的三维化合物结构。

然后 您可以通过命令
```bash
pycadd-dock ensemble-dock example.csv library_file.sdf -n 24 -p SP [--del_water/-w] [--redock] [--rmsd/-r] [-s/--save_dir <DIR>] [-O]
```
启动 Ensemble Docking。  
- -n / --parallel <NUM> 指定使用的并行核心数量，如未设定将默认使用系统最大核心数量的 75%。
- -p / --precision <SP | XP | HTVS> 指定对接精度，默认为 SP。
- -w / --del_water 指定是否删除晶体中的所有水分子。默认为保留口袋中心5埃范围内的水分子，其余删除。
- --redock 指定是否进行回顾性对接。即首先将PDB晶体的共晶小分子对接回口袋中，默认为不进行。
- -r / --rmsd 指定是否在对接过程中计算RMSD值。默认为不计算RMSD。
- -s / --save_dir <DIR> 指定结果保存目录，默认为当前工作目录。
- -O / --overwrite 指定是否覆盖已有结果。当前路径下如已运行过 Ensemble Docking 并留有结果文件时，默认将跳过已执行过的准备工作及对接，指定该参数则重新运行完整工作流并覆盖已有文件。

Dock 模块将会下载每一个PDB结构，自动完成晶体准备过程，并保留输入文件中指定小分子所结合的单一蛋白链（显示为 `PDBID-chain-X` 样式），生成对接 grid 文件，就如同常规分子对接流程的蛋白准备的工作流一样。  
然后，将*library_file.mae* 中的每一个化合物交叉对接到每一个受体中。对接结束后，**M** 个受体与 **N** 个配体的 Ensemble Docking 将会得到 **M x N** 的分数矩阵。单次对接不成功时, 矩阵中的对应位置将会留空。 
分数矩阵可用于您进一步的分析，或用于机器/深度学习建模等工作。  

使用 
```bash
pycadd-dock ensemble-dock --help
```
以获取更多帮助信息。

所有 Ensemble Docking 工作完成后, 将自动提取重要的对接结果数据, 并保存在 `result` 目录下的 `_DOCK_FINAL_RESULTS.csv`字样的文件中, 且将产生汇总矩阵文件`_matrix.csv`。

如果 Ensemble Docking 环节由于某些原因或意外被迫中断，您可以重新运行命令，已完成的部分将会自动跳过。您也可以使用`-O/--overwrite`参数来完全从头运行整个Ensemble Docking。  

数据提取环节意外中断时，可以使用数据提取命令来重新尝试提取及合并数据。数据提取仅尝试提取已有的结果文件，不会重新运行对接。未能成功提取的配体-受体对将会在矩阵中留空。


## Generate Input Files for Ensemble Docking

`pycadd-dock ensemble-dock` 支持三种输入文件格式：
* csv
* ini | in
* yaml | yml

**Note**
* 通过 `csv` 构建Dock输入文件，可以满足 `pycadd-dock ensemble-dock` 的需要，但由于其未含有受体通用名称 (如RXRα), 在调用 `pycadd-dock generate-report` 时，可能会报错，请改用另外两种格式。
* 通过 `ini` 构建Dock输入文件时，由于ini文件类型的特性，同一PDB ID不能出现在同一受体下中两次或以上。因此, 如果晶体含有多个共结晶配体，且需要分别计算，请将所有共结晶配体名称赋值于同一PDB ID下，并以英文逗号分隔。
* 通过 `yml/yaml` 构建Dock输入文件是推荐格式，可以满足所有情况下的需求，但需要注意：
    * 由于yaml语法要求，英文 `:` 后需要有一空格
    * yaml语法要求同一Section中的内容 应该具有相同的缩进，类似于python
    * yaml可以为同一晶体指定多个共结晶配体, 通过多行分割，并在每一行以 `-` 分割
    * 当共结晶配体名称仅由数字组成时，使用引号将其包裹(e.g '056')
* 可以使用 `Demand` 模块来为单个蛋白快速调研、生成 `Dock` 输入文件，仅需提供蛋白唯一识别号UniProt ID即可。请参阅 `Demand` 模块的使用说明。

以下是三种格式的示例：  

*csv*
```
1XJ7,DHT
1XQ3,R18
2AM9,TES
2AM9,DTT
2YLP,TES
2YLP,056
```

*ini | in*
```
[P10275]
    1XJ7: DHT
    1XQ3: R18
    2AM9: TES,DTT
    2YLP: TES,056
```

*yaml | yml (Recommended)*
```
P10275:
    1XJ7: DHT
    1XQ3: 
    - R18
    2AM9: 
    - TES
    - DTT
    2YLP:
    - TES
    - '056'
```