流程管理工具（Workflow & Environment Management）¶

# 推荐的频道配置顺序（~/.condarc）
channels:
  - conda-forge      # 最大的社区频道，优先级最高
  - bioconda         # 生信专用频道（FastQC, Kraken2, Bowtie2等）
  - defaults         # Anaconda官方频道

# Mamba 是 Conda 的 C++ 加速替代品，解析依赖快 10-50 倍
# 2024年后推荐直接安装 Miniforge3（预装 mamba + conda-forge 默认频道）
# Mambaforge 已于 2024 年 6 月正式废弃，功能已并入 Miniforge3
# 安装 Miniforge3 后无需额外安装 mamba，开箱即用

# 用法和 conda 完全一致，只是把 conda 换成 mamba
mamba create -n metagenome python=3.9
mamba install -c bioconda kraken2 bracken bowtie2

# 注意：mamba activate 不可用，激活环境仍需使用 conda activate

# 场景：安装 A 需要 libgcc=12，但 B 需要 libgcc=11

# 解决方案1：创建独立环境（最推荐）
conda create -n tool_a -c bioconda tool_a
conda create -n tool_b -c bioconda tool_b

# 解决方案2：用 mamba 替代 conda（更快的依赖解析）
mamba install -c bioconda tool_a tool_b

# 解决方案3：指定版本
conda install tool_a=2.1 tool_b=1.3

# 最佳实践：一个分析流程一个环境，不要把所有工具装在一个环境里

# environment.yml - 肠道宏基因组分析流程环境
name: metagenome_pipeline
channels:
  - conda-forge
  - bioconda
  - defaults
dependencies:
  - python=3.9
  - fastqc=0.12.1
  - multiqc=1.34
  - fastp=1.3.3
  - bowtie2=2.5.1
  - kraken2=2.1.3
  - bracken=2.9
  - samtools=1.21
  - pip:
    - pandas==2.0.3
    - scipy==1.11.1
    - matplotlib==3.7.2

# HPC不允许Docker（需root权限），用Singularity替代
# Singularity可以直接使用Docker镜像

# 拉取Docker镜像转为Singularity格式
singularity pull kraken2.sif docker://staphb/kraken2:2.1.3

# 运行容器
singularity exec kraken2.sif kraken2 --version

# 绑定数据目录（让容器内能访问外部数据）
singularity exec --bind /data:/data kraken2.sif kraken2 \
    --db /data/kraken2_db \
    --output /data/output.txt \
    /data/sample.fastq

# === 大数据文件（必须忽略！） ===
*.fastq
*.fastq.gz
*.fq
*.fq.gz
*.bam
*.sam
*.sra

# === 分析结果（可重新生成） ===
results/
output/
*.html     # MultiQC/FastQC报告

# === 数据库文件（太大） ===
*_db/
*.k2d

# === 临时文件 ===
*.tmp
*.log
__pycache__/
.ipynb_checkpoints/

# === 系统文件 ===
.DS_Store
Thumbs.db

# === 不忽略的（显式保留） ===
!environment.yml
!Snakefile
!scripts/*.sh
!scripts/*.py

project/
├── .git/                    # Git仓库（自动生成）
├── .gitignore               # 忽略规则
├── README.md                # 项目说明
├── environment.yml          # 环境配置（必须追踪）
├── software_versions.txt    # 软件版本记录
├── Snakefile                # 流程文件（必须追踪）
├── config.yaml              # 参数配置（必须追踪）
├── scripts/                 # 分析脚本（必须追踪）
│   ├── 01_qc.sh
│   ├── 02_trim.sh
│   └── ...
├── data/                    # 原始数据（.gitignore忽略）
├── results/                 # 分析结果（.gitignore忽略）
└── logs/                    # 运行日志（.gitignore忽略）

#!/bin/bash
# conda_setup.sh - Conda环境管理全套命令
# 适用场景：从零搭建宏基因组分析环境

# === 1. 安装 Mamba（加速conda） ===
# 2024年后推荐直接安装 Miniforge3（预装 mamba），而非往 base 环境添加 mamba
# Mambaforge 已废弃，功能已并入 Miniforge3
# 下载地址：https://github.com/conda-forge/miniforge
# 如果你已有旧版 conda，也可以这样安装（但不推荐）：
# conda install -n base -c conda-forge mamba -y

# === 2. 创建分析环境 ===
mamba create -n metagenome python=3.9 -y
# -n metagenome: 环境名
# python=3.9: 指定Python版本

# === 3. 激活环境 ===
conda activate metagenome

# === 4. 安装生信工具 ===
# 质控工具
mamba install -c bioconda -c conda-forge fastqc=0.12.1 multiqc=1.34 fastp=1.3.3 -y

# 比对和物种注释
mamba install -c bioconda -c conda-forge bowtie2=2.5.1 kraken2=2.1.3 bracken=2.9 -y

# 辅助工具
mamba install -c bioconda -c conda-forge samtools=1.21 seqkit=2.5.1 -y

# Python包
pip install pandas==2.0.3 scipy==1.11.1 matplotlib==3.7.2 scikit-learn==1.3.0

# === 5. 验证安装 ===
fastqc --version        # FastQC v0.12.1
fastp --version          # fastp 1.3.3
bowtie2 --version        # bowtie2-2.5.1
kraken2 --version        # Kraken version 2.1.3
python --version         # Python 3.9.x

# === 6. 导出环境配置 ===
conda env export > environment.yml
# 这个文件要加入Git追踪！

# === 7. 记录软件版本 ===
echo "=== Software Versions ===" > software_versions.txt
fastqc --version >> software_versions.txt 2>&1
fastp --version >> software_versions.txt 2>&1
bowtie2 --version 2>&1 | head -1 >> software_versions.txt
kraken2 --version >> software_versions.txt 2>&1
python --version >> software_versions.txt 2>&1
date >> software_versions.txt
echo "版本记录完成: software_versions.txt"

# === 8. 从environment.yml还原环境（换电脑时） ===
# conda env create -f environment.yml
# conda activate metagenome

# === 9. 查看已有环境 ===
conda env list

# === 10. 删除环境（不再需要时） ===
# conda env remove -n metagenome

#!/bin/bash
# git_workflow.sh - 生信项目Git工作流
# 从创建仓库到日常提交的完整流程

# === 1. 初始化仓库 ===
cd ~/projects/metagenome_pipeline   # 进入项目目录
git init                             # 初始化Git仓库
# 输出: Initialized empty Git repository

# === 2. 创建 .gitignore ===
cat > .gitignore << 'EOF'
# 大数据文件
*.fastq
*.fastq.gz
*.bam
*.sam
data/

# 分析结果（可重新生成）
results/
output/

# 数据库
*_db/

# 临时文件
*.tmp
*.log
__pycache__/
.ipynb_checkpoints/
EOF

# === 3. 首次提交 ===
git add .gitignore
git add environment.yml
git add software_versions.txt
git add Snakefile
git add config.yaml
git add scripts/
# 注意：不要 git add . 因为可能会把大文件加进去
# 只添加需要追踪的文件

git commit -m "feat: 初始化宏基因组分析流程

- 添加 environment.yml 环境配置
- 添加 Snakefile 流程定义
- 添加分析脚本 (scripts/)
- 配置 .gitignore 忽略数据文件"

# === 4. 连接远程仓库（GitHub） ===
git remote add origin https://github.com/username/metagenome_pipeline.git
git branch -M main                  # 重命名默认分支为main
git push -u origin main             # 首次推送（-u 设置上游分支）

# === 5. 日常工作流 ===
# 修改了脚本后：
git status                           # 查看修改了哪些文件
git diff scripts/03_kraken2.sh       # 查看具体修改内容
git add scripts/03_kraken2.sh        # 添加修改的文件
git commit -m "fix: 修复Kraken2 confidence参数"   # 提交
git push                             # 推送到远程

# === 6. 查看历史 ===
git log --oneline -10                # 查看最近10条提交记录
# 输出示例：
# a1b2c3d fix: 修复Kraken2 confidence参数
# e4f5g6h feat: 添加Shannon多样性分析脚本
# i7j8k9l feat: 初始化宏基因组分析流程

# === 7. 分支管理（添加新功能时） ===
git checkout -b feature/diversity    # 创建并切换到新分支
# ... 在新分支上开发 ...
git add scripts/diversity.py
git commit -m "feat: 添加多样性分析模块"
git checkout main                    # 切回主分支
git merge feature/diversity          # 合并新功能
git branch -d feature/diversity      # 删除已合并的分支

# ============================================================
# environment.yml - 肠道宏基因组分析流程环境配置
# Gut Metagenome Analysis Pipeline Environment
# ============================================================
#
# 使用方法：
#   创建环境: conda env create -f environment.yml
#   激活环境: conda activate metagenome_pipeline
#   更新环境: conda env update -f environment.yml
#   导出环境: conda env export > environment.yml
#
# 作者: [用户]
# 日期: 2026-04
# ============================================================

name: metagenome_pipeline

channels:
  - conda-forge       # 社区维护频道（优先级最高）
  - bioconda          # 生信工具专用频道
  - defaults           # Anaconda官方频道

dependencies:
  # --- Python ---
  - python=3.9.18

  # --- 质控工具 ---
  - fastqc=0.12.1     # reads质量评估
  - multiqc=1.34      # 汇总多个QC报告
  - fastp=1.3.3      # reads清洗和过滤

  # --- 比对工具 ---
  - bowtie2=2.5.1     # 短reads比对（去宿主）
  - samtools=1.21     # SAM/BAM文件处理

  # --- 物种注释 ---
  - kraken2=2.1.3     # k-mer物种分类
  - bracken=2.9       # Kraken2丰度估计校正

  # --- 辅助工具 ---
  - seqkit=2.5.1      # FASTA/FASTQ瑞士军刀
  - csvtk=0.27.2      # CSV/TSV处理

  # --- 流程管理 ---
  - snakemake>=8.0            # 工作流管理（v8引入插件架构，v9进一步重构）
  # Snakemake 8+ 起采用插件架构，HPC 集群需额外安装执行器插件
  # 例如：pip install snakemake-executor-plugin-slurm

  # --- Python包（pip安装） ---
  # 注意：environment.yml 中只能有一个 pip: 子项，所有 pip 包写在一起
  - pip:
    - snakemake-executor-plugin-slurm  # HPC SLURM 集群执行器插件
    - pandas==2.0.3          # 数据分析
    - scipy==1.11.1          # 科学计算
    - matplotlib==3.7.2      # 基础绘图
    - scikit-learn==1.3.0    # 机器学习
    - scikit-bio==0.5.9      # 生态多样性计算

# 新版Conda（4.6+）推荐用：
conda activate metagenome     # 推荐

# 旧版用法（可能在老服务器上遇到）：
source activate metagenome    # 旧版

# 如果 conda activate 报错：
# CommandNotFoundError: Your shell has not been properly configured
# 需要先运行：
conda init bash
# 然后重启终端

# rule all 不执行任何命令
# 它的作用是定义最终目标文件（告诉Snakemake"我要什么"）

# 正确理解：
rule all:
    input:
        expand("results/{sample}_report.txt", sample=SAMPLES)
# Snakemake从这些目标文件反向推导需要执行哪些rule

# 常见错误：以为rule all会执行第一个
# 实际上：Snakemake是从output到input反向推导的

Docker:
- 需要 root 权限（普通用户无法运行）
- 存在安全隐患（root权限可能影响整个集群）
- HPC管理员通常禁用Docker

Singularity:
- 不需要 root 权限（普通用户可直接使用）
- 可以直接使用 Docker 镜像（singularity pull docker://...）
- HPC集群的标准选择

结论：HPC上用Singularity，本地开发可以用Docker

必须忽略（文件太大）：
✗ 原始数据：*.fastq.gz, *.bam, *.sam
✗ 数据库文件：*_db/, *.k2d
✗ 分析结果：results/, output/

必须追踪（核心资产）：
✓ 分析脚本：scripts/*.sh, scripts/*.py
✓ 流程文件：Snakefile, *.smk
✓ 环境配置：environment.yml
✓ 项目配置：config.yaml
✓ 版本记录：software_versions.txt
✓ 说明文档：README.md

常见错误：
✗ 把.fastq.gz加入Git → 仓库膨胀到几十GB
✗ 忘记追踪environment.yml → 环境不可复现

# {sample} 是通配符，Snakemake自动匹配
rule fastp:
    input:
        "data/{sample}_R1.fastq.gz"     # {sample} = sample1, sample2, ...
    output:
        "results/{sample}_clean.fastq.gz"

# 常见错误：在shell命令中直接写 {sample}
# 正确：用 {wildcards.sample}（在shell块中）或 {input}/{output}（引用文件）
    shell:
        "fastp -i {input} -o {output}"   # 正确
        # "fastp -i data/{sample}_R1.fastq.gz"  # 错误！shell中需要 {wildcards.sample}