# Biflow

**Repository Path**: FateMoney/biflow

## Basic Information

- **Project Name**: Biflow
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-07-11
- **Last Updated**: 2026-04-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Biflow：生物信息工作流管理器

Biflow 是一个面向生物信息分析的轻量级工作流管理程序：用 YAML 描述流程图（DAG），由适配器把参数“翻译”为可执行命令，再由执行器按依赖关系在本机/容器内运行。

## 目录结构

```text
.
├─ main.py                 # 入口：-c 单流程；-g 多流程合并
├─ core/                   # DAG/节点模型
├─ executor/               # 执行器：运行适配器 + 执行命令 + 断点续跑
├─ adapters/               # 各工具适配器：把 node.params 转为 node.commands
├─ util/                   # YAML/日志/Docker 辅助
├─ config/                 # 示例流程：step1..step8 + population_genomics_pipeline.yaml
└─ tutorial/INDEX.md       # 适配器参数文档索引
```

## 安装依赖

主机侧（运行 `python main.py` 的机器）：

- Python 3.9+
- `pip install -U networkx pyyaml`
- Docker

容器侧（运行分析工具的镜像）：

- 使用本仓库的 `docker/dockerfile` 构建（推荐）

## 推荐用法：主机调度 + 容器执行工具

### 1) 构建镜像

在仓库内的docker目录执行：

```bash
docker build --progress=plain -t biflow-main .
```

如果你遇到 conda/mamba 解依赖失败（例如 base Python 过新），请用 `--no-cache` 并粘贴 `--progress=plain` 的完整日志便于定位：

```bash
docker build --progress=plain --no-cache -t biflow-main .
```

### 2) 启动容器（后台常驻）

把你的工作目录挂载到容器内 `/work`：

```bash
docker run -d \
  --name main \
  -v /your/local/path/biflow_work:/work \
  biflow-main
```

说明：

- 流程 YAML 的 `docker_containers` 里容器名需要与 `--name` 一致（例如这里是 `main`）。
- 执行器会用 `docker cp` 把 `adapters/` 和 `core/` 同步进容器的 `/biflow_code`，因此镜像不需要内置 Biflow 源码。
- 镜像默认 `WORKDIR` 设为 `/data` 只是为了交互式进入容器时有个落脚点；流程里各工具基本都用 `/work/...` 绝对路径，不依赖工作目录。

### 3) 准备数据目录

建议目录结构：

```text
/your/local/path/biflow_work/
├─ input/
│  ├─ 01_rawFastq/          # 原始测序数据（*.fastq.gz）
│  ├─ ref/
│  │  └─ genome.fa
│  ├─ chromosomes.tsv       # 染色体分类表（Step1 用）
│  └─ samples.txt           # 样本表（部分步骤用）
└─ output/                  # 程序自动生成
```

`chromosomes.tsv`（无表头，TAB 分隔）示例：

```tsv
chr1    auto
chr2    auto
chrX    chrX
chrY    chrY
MT    mt
```

`samples.txt`（有表头，TAB 分隔）示例（第 2 列为性别，第 3 列为群体名，第 4/5 列为 R1/R2 文件名）：

```text
SampleID    Sex    Group    R1    R2
Angus1    F    Angus    Angus1_R1.fastq.gz    Angus1_R2.fastq.gz
Angus2    M    Angus    Angus2_R1.fastq.gz    Angus2_R2.fastq.gz
Hanwoo1    F    Hanwoo    Hanwoo1_R1.fastq.gz    Hanwoo1_R2.fastq.gz
Hanwoo2    M    Hanwoo    Hanwoo2_R1.fastq.gz    Hanwoo2_R2.fastq.gz
```

### 4) 运行流程

有两种运行方式

1、把多个流程合并为一个流程一起运行：

```bash
python main.py -g config/population_genomics_pipeline.yaml
```

 2、单独运行

```
python main.py -c config/step1_chromosome.yaml
```

第一次使用推荐选择单独运行的方式。

## 配置文件写法（YAML）

配置文件核心结构：

- `global`：这部分是全局配置，`flow_name`是图的名称，可随意设置；`parallel`控制是否允许同一层次的节点并行运行；`log_dir`是存放日志的目录，注意请使用宿主机的绝对路径。
- `docker_containers`：`容器名: [节点id...]`，用于指定每个节点在哪个容器里运行（容器名必须与 `docker run --name ...` 一致）
- `nodes`：节点列表；每个节点包含 `id/tool/subcommand/input_dir/output_dir/params/dependencies`

- `input_dir`：节点的输入文件目录，请使用容器内路径
- `output_dir`：节点的输出目录，请使用容器内路径
- `params`：控制节点运行的参数
- `dependencies`：节点依赖的前置节点，即例如id为4的节点依赖节点1，则节点4会在节点1运行结束后才执行。

最小节点示例：

```yaml
- id: 4
  tool: iqtree
  subcommand: run
  input_dir:
    - alignment: /work/output/step7_alignments/autosome.phy
  output_dir: /work/output/step7_trees
  dependencies: [1]
  params:
    - iqtree_path: iqtree
    - model: GTR+G
    - bootstrap: 1000
    - threads: 8
    - other_options: "-st DNA"
    - output_prefix: autosome
```

适配器参数详见：`tutorial/INDEX.md`。