README.md

Initial version

README.md

@@ -1,3 +1,237 @@
-# miRNAseq
+### 安装指南
 
-用于miRNA-seq二代测序数据分析
+```bash
+# 激活choppy环境
+source activate choppy
+# 安装app
+choppy install chenziyin/miRNAseq
+```
+
+
+
+### 快速使用
+
+1. 新建项目文件夹
+
+2. 准备样本描述文件：samples.csv
+
+   - 文件需为csv格式（以逗号分隔的文本）
+   - 文件中必须包含的列为：
+     - sample_id：样本名称，该名称将自动作为生成结果文件的前缀名
+     - raw_fastq：原始FASTQ测试数据所在OSS路径
+     - adapter_seq：建库时所使用3’ 接头序列（详见附录A. 常用建库方法接头序列）
+     - randomBase_in_adapter：接头末端的随机碱基个数（详见附录A. 常用建库方法接头序列）
+
+   > 注意：
+   >
+   > 使用excel制作csv文件时，请不要将保存的csv文件直接作为输入，易导致异常错误。
+   >
+   > 推荐使用文本编辑器（如记事本，notepad++等）打开csv文件，确认：
+   >
+   > （1）每2个值之间使用逗号分隔，行末没有逗号
+   >
+   > （2）逗号前后没有多余的空格（非常重要！！！）
+   >
+   > （3）每行前后没有多余的逗号，且没有多余的仅由逗号组成的行
+   >
+   > 如果在服务器上运行choppy，推荐使用 ``` vim samples.csv``` 命令新建samples.csv文件，并将表格以逗号分隔的纯文本形式粘贴至其中，并按```esc```+```ZZ``` 退出
+
+3. 批量提交任务
+
+   ```bash
+   choppy batch miRNAseq-latest <File::samples.csv> --project-name <String::project_name>
+   ```
+
+   参数说明：
+
+   - ```<File::samples.csv>```：此处填写在上一步之做的***samples.csv***所在路径 
+   - ```<String::project_name>```：自定义项目名称，app的运行结果将自动存储在以该名称命名的文件夹下
+
+   > 注意：
+   >
+   > 1） 左右尖角括号（<>）代表此处的值需要由用户根据实际情况键入相应的值。替换入具体值后左右不需要保留尖叫括号
+   >
+   > 2）```--project-name```为必须参数，project_name中包含空格，短横线等特殊字符会导致异常
+
+
+
+### app测试
+
+用于app测试的文件位于 ***oss://choppy-app-example-data/miRNAseq/*** 目录下
+
+- **Test_10k_NEXTflex.fastq.gz** 中包含了NEXTflex small RNA kit v3所建文库的测序结果中的前10000条read
+
+- **test_10k_QIAseq.fastq.gz** 中包含了QIAseq miRNA kit所建文库的测序结果中的前10000条read
+
+- **samples.csv**是app测试时所需提交的samples.csv文件
+
+  
+
+### 输出文件说明
+
+运行APP后，
+
+每个sample对应一个文件夹，文件夹下结构如下：
+
+— call-Align2Mature
+
+​		— <sample_ID>.align2mature.log
+
+​		— <sample_ID>.align2mature.sam
+
+​		— <sample_ID>.matureUnaligned.fastq
+
+— call-LengthStats
+
+​		— **<sample_ID>.trimAdapt.lengthDistribute**
+
+— call-ReadFilter
+
+​		—  <sample_ID>.trimAdapt.filter.fastq.gz
+
+​		— <sample_ID>.filter.log
+
+— call-ReadStats
+
+​		—**<sample_ID>.readStats**
+
+— Call-TrimAdapt/
+
+​		— <sample_ID>.trimAdapt.fastq.gz
+
+​		— <sample_ID>.trimAdapt.log
+
+
+
+-  **<sample_ID>.matureMiR.readCount**：定位到每个miRNA的原始read数
+
+- 质量控制文件
+
+  - **<sample_ID>.readStats**：文库中read去向
+    - Total Input：测序得到的总read数
+    - Adapter dimer：引物二聚体read数
+    - Low quality：由于质量不符合要求损失的read数（包括单碱基质量过低，或N碱基数目过多）
+    - Too short：由于插入片段长度过短损失的read数
+    - For align： 所有通过质量过滤，进入序列比对环节的的片段数
+    - Mature miRNA：成熟miRNA片段数
+
+  - **<sample_ID>.trimAdapt.lengthDistribute**：文库中插入片段长度分布
+
+    
+
+
+### APP概述
+
+miRNAseq analysis pipeline 是一个全自动app，用于对miRNA-seq二代测序FASTQ结果中的human miRNA片段定量。
+
+#### 适用范围：
+
+1. 本APP适用于ILLUMINA系列测序仪（HiSeq, NextSeq, NovaSeq等）产生的SE50/SE75二代测序数据。对于PE数据，请提供R1 FASTQ和3‘接头序列作为数据源
+
+2. 本APP默认用于Human miRNA定量。如用于其他物种，请通过 ```dir_index_mature```和```prefix_index_mature```参数制定相应物种的参考miRNA序列组
+
+3. 目前尚不支持UMI分析
+
+
+
+### 流程与参数
+
+
+
+#### 适用的软件及版本
+
+- Fastp：0.19.6
+- Bowtie: 1.2.2
+
+
+
+### 流程示意
+
+![smallRNA analysis pipeline_ForChoppy](/Users/ziyin/Desktop/assets/smallRNA analysis pipeline_ForChoppy.jpg)
+
+#### 参考基因组
+
+下载自 *miRBase v22.1* ( [http://www.mirbase.org](http://www.mirbase.org/) ）mature.fa 并进行一下编辑：
+
+（1）仅提取出其中人miRNA序列
+
+（2）将U碱基转化为T碱基
+
+（3）合并序列相同的 miRNA ID
+
+（4）根据成熟体所对应的剪切前体（pre-miRNA），将成熟体序列两端各延伸5bp
+
+
+
+#### 详细参数
+
+1. 切除接头：根据```adapter_sequence``` 序列进行切除，切除时使用fastp默认参数
+
+2. 质量过滤：
+
+   1）一条read中，质量不满足```qualified_quality_phred（default:20）``` 的碱基在read占比超过```unqualified_percent_limit(default:20)```%时，该read将被过滤
+
+   2） read中，N碱基数目超过```n_base_limit (default: 5)```的read将被过滤
+
+3. 长度过滤：去接头后长度小于```length_required（default：16）```的read将被过滤
+
+4. miRNA识别
+
+   - 使用bowtie（end-to-end模式）进行匹配
+
+   - 配对后，错配碱基的质量和小于```sum_unmatch_quality_limit (default:40)```即被认定匹配成功
+     - 即错配碱基测序置信度较高（Q-value>30）时，最多允许1个错配。
+     - 随着错配碱基测序置信度（Q-value）的降低，允许的错配数增多
+
+
+
+## 附录
+
+### A.常用建库方法及接头序列
+
+| 建库试剂盒                                                   | adapter_seq            | randomBase_in_adapter | 参考资料 |
+| ------------------------------------------------------------ | ---------------------- | --------------------- | -------- |
+| Truseq smallRNA library prep kit (Illumina)                  | TGGAATTCTCGGGTGCCAAGG  | 0                     | [1]      |
+| QIAseq miRNA Library Kit (QIAGEN)                            | AACTGTAGGCACCATCAAT    | 0                     | [2       |
+| NEBNext Multiplex Small RNA Library Prep Set for Illumina (NEB) | AAGATCGGAAGAGCACACGTCT | 0                     | [3]      |
+| NEXTflex small RNA Kit                                       | TGGAATTCTCGGGTGCCAAGG  | 4                     | [4]      |
+
+[1] Illumina Adapter Sequences ([1000000002](http://choppy.3steps.cn/chenziyin/miRNAseq/src/branch/master/commit/1000000002694) v07) From <http://support.illumina.com.cn/downloads/illumina-customer-sequence-letter.html>
+
+[2] <https://www.qiagen.com/us/resources/faq?id=>[f12b85b4](http://choppy.3steps.cn/chenziyin/miRNAseq/src/branch/master/commit/f12b85b4)-df4f-43b5-9e82-[a4fd0ddbdc](http://choppy.3steps.cn/chenziyin/miRNAseq/src/branch/master/commit/a4fd0ddbdcc0)&lang=en
+
+[3] NEBNext Multiplex Small RNA Library Prep Set for Illumina manual
+
+[4] NEXTflex® Small RNA-Seq Kit v3 Automation Guide 
+
+### B. FAQ
+
+**Q1 结果中没有检测到miRNA / miRNA检出率过低 **
+
+**A2.** 
+
+首先需要确认是否切接头成功。方法为打开～/Call-TrimAdapt/trimAdapt.log日志文件，查看Filtering result*项目下的：
+
+***reads with adpater trimmed***：该项为接头切除成功的read数，数值过低说明接头识别失败，需要检查提供的接头序列（```adapter_seq```）是否正确。
+
+之后打开～/call-ReadStats/<sample_ID>.readStats文件查看文库中片段组成：
+
+（1）***Adapter dimer***较高提示建库过程中连接效率低，文库产物被大量的引物二聚体所占据
+
+（2）***Low quality***较高提示此次测序质量较差，可以用于比对的片段占比较低
+
+（3）***Too short***：较高提示抽提/建库过程存在问题或者样本质量较差，导致文库中插入大量的短（16bp一下）片段
+
+（4）若***For align***： 项数值正常，而检测到的miRNA数量低，考虑
+
+​		a. 如果建库时使用了4N引物，
+
+​			查看samples.csv中，```randomBase_in_adapter```是否设置正确。
+
+​		    查看～/call-TrimAdapt/**<sample_ID>.trimAdapt.log**日志文件，若其中没有trim 4 random base相关记录，则可能是```randomBase_in_adapter```设置不正确
+
+​			打开～ /call-LengthStats/**<sample_ID>.trimAdapt.lengthDistribute**，若片段主要分布在32bp附近，则很可能是4N碱基未切除成功
+
+​		b. 如果建库时未使用4N引物
+
+​		打开～ /call-LengthStats/**<sample_ID>.trimAdapt.lengthDistribute**，查看片段长度分布