OmicsTrace오믹스트레이스

분석을 다시 돌려도 같은 결과가 나올까요? Nextflow·nf-core와 Snakemake로 워크플로 관리하기

13분 읽기

📌 이 글에서 알 수 있는 것

  • 셸 스크립트 대신 워크플로 관리자를 쓰는 이유
  • nf-core/rnaseq 실행 옵션과 - vs -- 구분
  • work 디렉터리·캐시·-resume의 동작
  • Snakefile 구조와 dry run·conda·Slurm 실행, 선택 기준

🧩 셸 스크립트로는 왜 부족할까

run_all.sh에 단계를 적으면, 37번째 시료에서 멈췄을 때 처음부터 다시 돌려야 하고 도구 버전은 기억에 의존합니다. 워크플로 관리자는 이를 네 가지로 풀어 줍니다1.

  • 재개(resume): 끝난 단계는 건너뛰고 실패한 곳부터 돕니다.
  • 병렬화: 의존 그래프를 보고 독립인 작업을 동시에 돌립니다.
  • 실행 기록(provenance): 어떤 입력·명령·컨테이너로 무엇을 만들었는지 남깁니다.
  • 이식성: 같은 코드를 노트북, HPC(Slurm 같은 스케줄러), 클라우드에서 돌립니다.

대표적인 것이 Nextflow(Groovy 기반 워크플로 언어·실행기)2와 Snakemake(Python 기반, 파일 이름으로 의존성 정의)3입니다. 컨테이너·conda는 6편을 보세요.

Nextflow·Snakemake 명령 치트시트. 위는 Nextflow 옵션(한 줄 대시 -r, -profile, -resume)과 파이프라인 파라미터(두 줄 대시 --input, --outdir), work·캐시 설명. 아래는 Snakemake 주요 명령과 검증 순서.
그림 1. Nextflow·Snakemake 핵심 명령. 특정 제품을 권하지 않습니다.

🚀 Nextflow 설치

옵션은 Nextflow 26.10.5 문서 기준이며, Bash 3.2 이상과 Java 17 이상이 필요합니다4.

java -version
curl -s https://get.nextflow.io | bash
chmod +x nextflow
mkdir -p $HOME/.local/bin && mv nextflow $HOME/.local/bin/
export PATH="$PATH:$HOME/.local/bin"
nextflow info
  • curl … | bash: 공식 설치 스크립트. 실행 권한을 주고 PATH 폴더로 옮긴 뒤 nextflow info로 확인합니다. export는 현재 창에만 적용되니 ~/.bashrc(zsh는 ~/.zshrc)에도 넣으세요.
  • 자주 하는 실수: Java가 17 미만인 것(17~26 지원). 없으면 SDKMAN으로 sdk install java.

▶️ nf-core/rnaseq 실행하기

nf-core는 커뮤니티가 공동 관리하는 Nextflow 파이프라인 모음입니다5. 분석 흐름은 12편에서 다룰 nf-core/rnaseq 3.27.0으로 예를 듭니다6.

nextflow run nf-core/rnaseq -r 3.27.0 -profile test,docker --outdir results_test
  • -r 3.27.0: 파이프라인 버전(Git 태그). 문서는 브랜치보다 태그·커밋 ID를 권합니다7.
  • -profile test,docker: test는 작은 테스트 데이터, docker는 모든 도구를 Docker 컨테이너로 돌립니다(Docker 실행 필요). 뒤쪽이 앞쪽을 덮어씁니다.
  • --outdir: 최종 결과 폴더.
  • 자주 하는 실수: -profile을 빼 PATH의 도구로 돌아, 컴퓨터마다 결과가 달라집니다.

실제 데이터는 아래처럼 samplesheet.csv를 만듭니다(단일 말단은 fastq_2 칸을 비움).

sample,fastq_1,fastq_2,strandedness
CTRL_1,/data/s1_R1.fastq.gz,/data/s1_R2.fastq.gz,auto

nextflow run nf-core/rnaseq -r 3.27.0 -profile docker \
    --input samplesheet.csv --outdir results \
    --fasta ref.fa --gtf genes.gtf -resume
  • --input: samplesheet. strandedness가 auto면 리드 100만 개로 가닥 특이성을 추정합니다6.
  • --fasta·--gtf: 참조 유전체와 주석. 판본을 적어 두세요.
  • -resume: 이전 캐시를 재사용합니다.
  • 자원: 정렬 등 큰 단계는 CPU 12개·메모리 72GB를 요청해, 작은 컴퓨터에선 … exceeds available CPUs(또는 memory)로 멈춥니다. 아래 -c 예로 상한을 정하세요(STAR는 사람 유전체에 약 38GB). 메모리가 적다고 --aligner hisat2로 바꾸는 건 답이 아닙니다(색인 생성 요청이 더 크고, 정량도 빠짐)6.
  • 자주 하는 실수: Docker가 없는 HPC에서 docker 프로필을 쓰는 것입니다. singularity·apptainer를 쓰세요.

➖ 한 줄 대시와 두 줄 대시는 다릅니다

공식 문서는 한 줄 대시(-)는 Nextflow 자체 옵션, 두 줄 대시(–)는 파이프라인으로 넘기는 파라미터로 나눕니다7.

구분예
Nextflow 옵션 (-)-r, -profile, -resume, -params-file, -c, -w
파이프라인 파라미터 (--)--input, --outdir, --fasta, --gtf

--resume은 직접 짠 파이프라인에선 파라미터가 될 뿐 재개되지 않고, nf-core에선 파라미터 검사 오류로 멈춥니다. -outdir은 “Unknown option” 오류가 납니다.

🗂️ work 디렉터리, 캐시, -resume

Nextflow는 작업(task)마다 이름·입력·스크립트·컨테이너 등으로 해시를 계산해 work/ 아래 고유 폴더에서 실행합니다. 입력 파일은 경로·수정 시각·크기로 판단합니다. -resume은 같은 해시가 캐시(.nextflow/cache)에 있고 work/에 출력이 남은 작업만 건너뜁니다8.

  • 둘 다 지켜야 합니다. .nextflow/와 work/가 모두 남고 같은 폴더에서 실행해야 재개됩니다.
  • 고치면 다시 돕니다. 스크립트·컨테이너·입력을 바꾼 단계부터 그 뒤까지 다시 돕니다. NFS처럼 수정 시각이 어긋나는 곳에선 -c 설정에 process.cache = 'lenient'(경로·크기만 비교)를 씁니다8.
nextflow log
nextflow clean -n -before <run_name>
  • log: 지난 실행 이름·세션 ID·상태. 특정 실행은 -resume <세션 ID>로 잇습니다(이름을 쓰면 마지막 실행).
  • clean -n: 지울 목록만 보는 dry run. -f로 바꾸면 실제 삭제이고, -before·-but으로 범위를 정합니다9.
  • 자주 하는 실수: rm -rf work 후 -resume을 기대하는 것입니다.

⚙️ 파라미터 파일, 설정 파일, 기관 프로필

nextflow run nf-core/rnaseq -r 3.27.0 -profile singularity \
    -params-file params.yaml -c custom.config -resume
  • -params-file: 파라미터를 YAML·JSON으로 묶습니다(input: samplesheet.csv처럼 한 줄씩). 같은 값이 겹치면 명령줄 --가 이 파일보다 우선합니다7.
  • -c custom.config: 자원·스케줄러 설정을 덧붙입니다. 예) process { resourceLimits = [cpus: 8, memory: 40.GB, time: 24.h] }처럼 사양 이하로 적으면 이를 넘는 요청만 상한으로 줄어듭니다10.
  • 자주 하는 실수: -c 파일에 파라미터를 넣는 것입니다. nf-core 문서는 오류가 난다며 금지합니다6.

기관 HPC 설정은 nf-core/configs에 프로필로 있어 -profile <기관명>으로 쓰고, 오프라인 클러스터에는 nf-core pipelines download(nf-core/tools 4.x)로 받아 옮깁니다11.

🐍 Snakemake: 규칙과 파일 이름으로 잇기

Snakemake는 “이 출력을 만들려면 이 입력이 필요하다"는 규칙(rule)에서 목표 파일부터 거꾸로 작업을 계산합니다3. {sample} 같은 와일드카드가 파일 이름의 빈칸을 채웁니다.

SAMPLES = ["A", "B"]

rule all:
    input: expand("results/{sample}.sorted.bam", sample=SAMPLES)

rule align:
    input: r1="data/{sample}_R1.fastq.gz", r2="data/{sample}_R2.fastq.gz"
    output: "results/{sample}.bam"
    threads: 4
    conda: "envs/align.yaml"
    shell: "bwa mem -t {threads} ref.fa {input.r1} {input.r2} | samtools view -b -o {output} -"

rule sort:
    input: "results/{sample}.bam"
    output: "results/{sample}.sorted.bam"
    conda: "envs/align.yaml"
    shell: "samtools sort -o {output} {input}"
  • rule all: 최종 목표. expand()가 시료 이름을 채웁니다.
  • input·output·shell: 입력, 출력, 명령. Snakefile로 저장하고 같은 폴더에 data/A_R1.fastq.gz처럼 이름을 맞춘 FASTQ, bwa index ref.fa로 만든 색인, envs/align.yaml(channels: [conda-forge, bioconda], dependencies: [bwa, samtools] 두 줄)을 둡니다.
  • 자주 하는 실수: 파일 이름이 다른 것입니다. MissingInputException에 sample=A.sorted가 보여도 data/ 이름부터 보세요.

옵션은 Snakemake 9.27.1 기준입니다12.

snakemake -n --sdm conda
snakemake --cores 4 --sdm conda
snakemake --executor slurm --jobs 50 --profile profiles/slurm
snakemake --dag | dot -Tsvg > dag.svg
  • -n(--dry-run): 실행 없이 작업 목록(위 예는 align 2·sort 2·all 1)만 봅니다. 실행할 때와 같은 옵션을 붙이세요.
  • --cores 4: 로컬 최대 코어 수.
  • --sdm conda(--software-deployment-method): 규칙의 conda: 환경으로 실행합니다. 컨테이너는 --sdm apptainer입니다13.
  • --executor slurm: 따로 설치한 snakemake-executor-plugin-slurm으로 제출합니다. --jobs는 동시 제출 수, --profile은 옵션·자원을 적은 profile.yaml이나 그 폴더입니다14.
  • --dag | dot: 작업 그래프를 Graphviz로 그립니다.
  • 자주 하는 실수: --sdm conda를 빼 conda:가 무시되고 PATH의 다른 버전 도구가 쓰이는 것입니다.

Snakemake는 -resume 없이도 있는 출력을 건너뛰고(강제 종료 뒤엔 --rerun-incomplete), 재실행 기준에 코드·파라미터·입력·환경이 들어 있어 규칙을 고치면 그 규칙부터 다시 돕니다12.

⚖️ 무엇을 고를까

검증된 표준 분석을 그대로 쓸 때는 Nextflow + nf-core, 맞춤 분석이거나 Python에 익숙하면 Snakemake가 잘 맞습니다.

✅ 실행 결과는 이렇게 검증합니다

  1. test 프로필 먼저: 같은 버전·컨테이너로 끝까지 도는지 봅니다.
  2. MultiQC(QC 통합 보고서): results/multiqc/<정렬기>/(기본 star_salmon)에서 시료별 QC와 소프트웨어 버전 표를 봅니다6.
  3. pipeline_info/: 도구 버전 파일(3.27.0은 nf_core_rnaseq_software_mqc_versions.yml)과 params_<날짜>.json(실제 파라미터)을 보관합니다.
  4. Methods에 적기: 예) “nf-core/rnaseq 3.27.0(Nextflow 26.10.5, Singularity 프로필)으로 처리했고 참조는 GRCh38, Ensembl ○○판 주석을 썼다.” 파이프라인 DOI 인용도 요청합니다6.

⚠️ 한계와 주의 — 자주 하는 실수

  • 버전 미고정: -r이 없으면 처음 받아 둔 코드가 쓰여, 다른 컴퓨터나 nextflow pull 뒤엔 같은 명령이 다른 버전으로 돕니다6.
  • work 용량: 중간 BAM까지 남아 결과보다 커집니다. -w로 scratch에 두고15 nextflow clean으로 정리하세요. cleanup = true는 성공 시 자동 삭제하지만 재개가 불가능해집니다16.
  • HPC 장시간 실행: Nextflow 본체는 끝까지 살아 있어야 하니 6편의 tmux·nohup이나 nextflow -bg run …으로 띄우고(로그인 노드 실행이 금지되면 본체도 작업으로 제출), 작업은 -profile <기관명>으로 스케줄러에 보냅니다. 이미지 캐시는 NXF_SINGULARITY_CACHEDIR(apptainer는 NXF_APPTAINER_CACHEDIR)로 공용 폴더에 둡니다.
  • 한계: 워크플로 관리자는 실행을 재현할 뿐, 파라미터가 라이브러리에 맞는지는 보장하지 않습니다.

🏛️ 지금 어디까지 왔나

  • 판본(2026-11-06): Nextflow 26.10.5, nf-core/rnaseq 3.27.0(Nextflow 25.10.4 이상 필요), Snakemake 9.27.1.
  • 커뮤니티: nf-core 파이프라인 124개(2025년 2월), GitHub 기여자 2,600명 이상17.

🧪 연구자 노트

  • 직접 짜기 전에 nf-core처럼 검증된 파이프라인을 -profile test로 먼저 돌려 보세요.
  • 실행이 끝나면 버전 파일과 파라미터 파일을 결과와 함께 보관하세요. 몇 달 뒤 Methods를 쓸 때 가장 먼저 찾게 됩니다.

🙋 그래서 나에게는? — 실습 전 체크리스트

  • nextflow info·snakemake --version으로 실행기 버전을 기록했다
  • nf-core 실행에 -r <버전>을 붙였다
  • 같은 버전으로 -profile test,<컨테이너>를 먼저 통과시켰다
  • work/ 위치와 정리 계획이 있다
  • pipeline_info/의 버전·파라미터 파일을 보관하고 Methods에 버전을 적었다

⚠️ 이 글은 의학적 조언이 아니며, 특정 제품을 권하지 않습니다. 실제 옵션은 사용하는 도구 버전의 매뉴얼과 기관 SOP, 자체 검증 결과를 우선하세요.

❓ 자주 묻는 질문

Q. -resume을 붙였는데 처음부터 다시 돕니다. 왜 그럴까요? A. 다른 폴더에서 실행했는지, work/·.nextflow/를 지웠는지, --resume으로 썼는지 보세요. 입력을 다시 복사해 수정 시각이 바뀌어도 캐시가 깨집니다.

Q. nf-core 파이프라인 옵션을 바꾸려면 코드를 고쳐야 하나요? A. 대부분 -- 파라미터나 -params-file로 바꿉니다. 도구 인자나 자원은 -c 설정으로 덧붙이고 코드는 그대로 둬야 버전 관리가 쉽습니다.

Q. 이미 셸 스크립트가 잘 돌아가는데 꼭 옮겨야 하나요? A. 한 번만 돌릴 작은 분석이면 꼭 그렇지는 않습니다. 시료가 늘거나, 남이 다시 돌리거나, 논문에 실릴 분석이라면 얻는 것이 더 큽니다.

📚 오믹스 기술 시리즈

참고

  1. Wratten L 외. Reproducible, scalable, and shareable analysis pipelines with bioinformatics workflow managers. Nat Methods 2021;18:1161-8. doi:10.1038/s41592-021-01254-9 ↩︎

  2. Di Tommaso P 외. Nextflow enables reproducible computational workflows. Nat Biotechnol 2017;35:316-9. doi:10.1038/nbt.3820 ↩︎

  3. Mölder F 외. Sustainable data analysis with Snakemake. F1000Res 2021;10:33. doi:10.12688/f1000research.29032.3 ↩︎ ↩︎

  4. Nextflow 26.10.5 문서: Installation (2026-11-06 접속) — nextflow.io/docs ↩︎

  5. Ewels PA 외. The nf-core framework for community-curated bioinformatics pipelines. Nat Biotechnol 2020;38:276-8. doi:10.1038/s41587-020-0439-x ↩︎

  6. nf-core. nf-core/rnaseq 3.27.0 README·Usage·Output 문서, nextflow.config와 파이프라인 소스, 인용 DOI 10.5281/zenodo.1400710(2026-09-23 공개, 2026-11-06 접속) — nf-co.re/rnaseq ↩︎ ↩︎ ↩︎ ↩︎ ↩︎ ↩︎ ↩︎

  7. Nextflow 26.10.5 문서: Command line interface(옵션과 파라미터, Revision selection, Parameter precedence; 2026-11-06 접속) — nextflow.io/docs ↩︎ ↩︎ ↩︎

  8. Nextflow 26.10.5 문서: Caching and resuming (2026-11-06 접속) — nextflow.io/docs ↩︎ ↩︎

  9. Nextflow 26.10.5 문서: CLI reference nextflow clean (2026-11-06 접속) — nextflow.io/docs ↩︎

  10. Nextflow 26.10.5 문서: Process directives resourceLimits(24.04 도입, 상한을 넘는 요청만 상한으로 축소; 2026-11-06 접속) — nextflow.io/docs ↩︎

  11. nf-core/configs README·nf-core/tools 4.2.1 CLI (2026-11-06 접속) — github.com/nf-core/configs ↩︎

  12. Snakemake 9.27.1 명령줄 도움말(src/snakemake/cli.py: –dry-run, –cores, –jobs, –profile, –executor, –rerun-triggers, –dag, –rulegraph; 2026-11-06 접속) — snakemake.readthedocs.io ↩︎ ↩︎

  13. Snakemake 9.27.1 문서: Distribution and Reproducibility(–software-deployment-method, –sdm; 2026-11-06 접속) — snakemake.readthedocs.io ↩︎

  14. snakemake-executor-plugin-slurm 2.8.0 문서 (2026-11-06 접속) — snakemake.github.io/snakemake-plugin-catalog ↩︎

  15. Nextflow 26.10.5 문서: CLI reference nextflow run(-profile, -resume, -r, -w; 2026-11-06 접속) — nextflow.io/docs ↩︎

  16. Nextflow 26.10.5 문서: Configuration options, unscoped cleanup (2026-11-06 접속) — nextflow.io/docs ↩︎

  17. Langer BE 외. Empowering bioinformatics communities with Nextflow and nf-core. Genome Biol 2025;26:228. doi:10.1186/s13059-025-03673-9 ↩︎

#바이오인포매틱스#유전체분석#전사체#Nextflow#Snakemake

📚 함께 보면 좋은 글