설정(Config) 파일 사용하기

설정 파일(configuration file)은 워크플로의 규칙과 워크플로의 설정을 분리할 때 유용한 Snakemake의 기능입니다. 예를 들어, 여러 샘플에 대해 동일한 시퀀싱 트리밍(trimming) 워크플로를 실행한다고 가정해 봅시다. 지금까지 배운 기술들로는 매번 샘플 이름을 직접 Snakefile에서 수정해야 할 것입니다. 하지만 설정 파일을 사용하면 Snakefile은 그대로 두고, 실행할 때마다 샘플 정보가 담긴 다른 설정 파일만 제공하면 됩니다. 설정 파일은 특정 프로그램의 파라미터를 정의하거나 기본값을 재정의하는 데에도 유용합니다.

첫 번째 예시: 단일 샘플 ID로 규칙 실행하기

샘플 ID를 기반으로 출력 파일을 만드는 다음 Snakefile을 보십시오. 샘플 ID는 설정 파일에서 가져오며, config라는 이름의 Python 딕셔너리를 통해 제공됩니다.

configfile: "config.one_sample.yml"

SAMPLE = config['sample']

rule all:
    output:
        expand("one_sample.{s}.out", s=SAMPLE)
    shell:
        "touch {output}"

기본 설정 파일인 config.one_sample.yml의 내용은 다음과 같습니다. 여기서는 sample 값을 XYZ_123으로 설정하고 one_sample.XYZ_123.out 파일을 생성하도록 합니다.

sample: XYZ_123

Snakefile에 적힌 configfile: 지시문은 명령줄에서 --configfile 옵션을 사용하여 재정의할 수 있습니다. config.one_sample_b.yml 파일이 다음과 같다고 합시다.

sample: ABC_456

이제 snakemake --configfile config.one_sample_b.yml -j 1을 실행하면 샘플 값이 ABC_456으로 설정되어 one_sample.ABC_456.out 파일이 생성됩니다.

설정 파일에 여러 샘플 ID 지정하기

여러 샘플을 처리할 때도 YAML의 리스트 형식을 사용하면 매우 간편합니다. snakefile.multi_samples라는 이름의 다음 예시를 보십시오.

configfile: "config.multi_samples.yml"

SAMPLES = config['samples']

rule all:
    input:
        expand("one_sample.{s}.out", s=SAMPLES)

rule make_single_sample_wc:
    output:
        "one_sample.{s}.out"
    shell:
        "touch {output}"

그리고 이와 짝을 이루는 config.multi_samples.yml 설정 파일입니다.

samples:
- DEF_789
- GHI_234
- JKL_567

여기서는 몇 가지 중요한 개념이 함께 사용되었습니다.

먼저, 설정 파일의 samples 키 아래에 목록 형식으로 값들을 지정했습니다. 따라서 config['samples']는 Python의 리스트(list)가 됩니다.

둘째, 와일드카드 규칙을 사용하여 하나의 규칙으로 여러 파일을 생성하도록 했습니다.

마지막으로, 기본 규칙에서 expand 함수를 사용하여 와일드카드 규칙이 생성해야 할 최종 파일들의 목록을 구성했습니다.

이제 설정 파일의 샘플 목록만 편집하거나, 아예 다른 샘플 목록이 담긴 설정 파일을 제공하는 것만으로 워크플로를 유연하게 실행할 수 있습니다!

설정 파일에 명령줄 파라미터 지정하기

설정 파일은 샘플 ID뿐만 아니라 거의 모든 정보를 담을 수 있습니다.

예를 들어 게놈을 비교할 때 사용하는 sourmash sketch 명령의 k-mer 크기를 설정해 보겠습니다.

rule sketch_genomes:
    output:
       "GCF_000017325.1.fna.gz.sig",
       "GCF_000020225.1.fna.gz.sig",
    params:
        ksize=config['ksize'],
    shell: """
        sourmash sketch dna -p k={params.ksize} genomes/*.fna.gz --name-from-first
    """

이 방식의 장점은 다음과 같습니다. * params 블록을 사용함으로써 이것이 조정 가능한 매개변수임을 다른 사람에게 명확히 알릴 수 있습니다. * Snakefile 코드를 직접 건드리지 않고도 설정 파일만으로 k-mer 크기를 조절할 수 있습니다.

참고로, 설정 파일의 값이 정수인지 문자열인지 확인하거나 기본값을 제공하고 싶을 때는 Python의 .get() 메서드를 사용할 수도 있습니다. (예: config.get('ksize', 31))

설정 파일 디버깅하기

Snakemake를 실행할 때 실제로 어떤 설정값이 적용되었는지 확인하고 싶을 때가 있습니다. 이럴 때는 Python의 pprint 모듈을 사용하면 편리합니다.

import pprint

configfile: "config.multi_samples.yml"

# config 딕셔너리 출력
print('적용된 설정(config):')
pprint.pprint(config)

SAMPLES = config['samples']

rule all:
    input:
        expand("one_sample.{s}.out", s=SAMPLES)
...

실행하면 다음과 같이 딕셔너리 구조가 예쁘게 출력되어 어떤 값들이 로드되었는지 쉽게 확인할 수 있습니다.

적용된 설정(config):
{'samples': ['DEF_789', 'GHI_234', 'JKL_567']}

고급 사용법

명령줄에서 직접 설정값 제공하기

별도의 파일을 만들지 않고도 명령줄에서 특정 설정값을 바로 지정하거나 재정의할 수 있습니다.

snakemake -j 1 -C sample=ZZZ_123 ksize=21

-C (또는 --config) 옵션을 사용하면 설정 파일의 내용을 무시하거나 새로운 변수를 바로 주입할 수 있습니다.

여러 설정 파일 동시에 사용하기

--configfiles 옵션을 사용하면 여러 개의 YAML 파일을 동시에 제공할 수 있습니다. 파일들이 겹치는 키를 가지고 있다면 나중에 지정된 파일의 값이 우선합니다.

요약

설정 파일을 사용하면 다음의 이점을 얻을 수 있습니다. 1. 워크플로 로직(Snakefile)과 실제 데이터 정보(Config)를 분리할 수 있습니다. 2. 동일한 워크플로를 다양한 데이터셋에 쉽게 재사용할 수 있습니다. 3. 소스 코드를 직접 수정하는 것보다 휴먼 에러를 줄일 수 있습니다. 4. 팀원 간의 협업 시 설정값 공유가 쉬워집니다.

참고 문서

Snakemake 공식 문서 - Configuration
YAML 및 JSON 문법 가이드

# 설정(Config) 파일 사용하기 설정 파일(configuration file)은 워크플로의 *규칙*과 워크플로의 *설정*을 분리할 때 유용한 Snakemake의 기능입니다. 예를 들어, 여러 샘플에 대해 동일한 시퀀싱 트리밍(trimming) 워크플로를 실행한다고 가정해 봅시다. 지금까지 배운 기술들로는 매번 샘플 이름을 직접 Snakefile에서 수정해야 할 것입니다. 하지만 설정 파일을 사용하면 Snakefile은 그대로 두고, 실행할 때마다 샘플 정보가 담긴 다른 설정 파일만 제공하면 됩니다. 설정 파일은 특정 프로그램의 파라미터를 정의하거나 기본값을 재정의하는 데에도 유용합니다. ## 첫 번째 예시: 단일 샘플 ID로 규칙 실행하기 샘플 ID를 기반으로 출력 파일을 만드는 다음 Snakefile을 보십시오. 샘플 ID는 설정 파일에서 가져오며, `config`라는 이름의 Python 딕셔너리를 통해 제공됩니다. ```python configfile: "config.one_sample.yml" SAMPLE = config['sample'] rule all: output: expand("one_sample.{s}.out", s=SAMPLE) shell: "touch {output}" ``` 기본 설정 파일인 `config.one_sample.yml`의 내용은 다음과 같습니다. 여기서는 `sample` 값을 `XYZ_123`으로 설정하고 `one_sample.XYZ_123.out` 파일을 생성하도록 합니다. ```yaml sample: XYZ_123 ``` Snakefile에 적힌 `configfile:` 지시문은 명령줄에서 `--configfile` 옵션을 사용하여 재정의할 수 있습니다. `config.one_sample_b.yml` 파일이 다음과 같다고 합시다. ```yaml sample: ABC_456 ``` 이제 `snakemake --configfile config.one_sample_b.yml -j 1`을 실행하면 샘플 값이 `ABC_456`으로 설정되어 `one_sample.ABC_456.out` 파일이 생성됩니다. ## 설정 파일에 여러 샘플 ID 지정하기 여러 샘플을 처리할 때도 YAML의 리스트 형식을 사용하면 매우 간편합니다. `snakefile.multi_samples`라는 이름의 다음 예시를 보십시오. ```python configfile: "config.multi_samples.yml" SAMPLES = config['samples'] rule all: input: expand("one_sample.{s}.out", s=SAMPLES) rule make_single_sample_wc: output: "one_sample.{s}.out" shell: "touch {output}" ``` 그리고 이와 짝을 이루는 `config.multi_samples.yml` 설정 파일입니다. ```yaml samples: - DEF_789 - GHI_234 - JKL_567 ``` 여기서는 몇 가지 중요한 개념이 함께 사용되었습니다. 먼저, 설정 파일의 `samples` 키 아래에 목록 형식으로 값들을 지정했습니다. 따라서 `config['samples']`는 Python의 리스트(list)가 됩니다. 둘째, [와일드카드 규칙](wildcards.qmd)을 사용하여 하나의 규칙으로 여러 파일을 생성하도록 했습니다. 마지막으로, [기본 규칙](../ch10-default-rule.qmd)에서 `expand` 함수를 사용하여 와일드카드 규칙이 생성해야 할 최종 파일들의 목록을 구성했습니다. 이제 설정 파일의 샘플 목록만 편집하거나, 아예 다른 샘플 목록이 담긴 설정 파일을 제공하는 것만으로 워크플로를 유연하게 실행할 수 있습니다! ## 설정 파일에 명령줄 파라미터 지정하기 설정 파일은 샘플 ID뿐만 아니라 거의 모든 정보를 담을 수 있습니다. 예를 들어 게놈을 비교할 때 사용하는 `sourmash sketch` 명령의 k-mer 크기를 설정해 보겠습니다. ```python rule sketch_genomes: output: "GCF_000017325.1.fna.gz.sig", "GCF_000020225.1.fna.gz.sig", params: ksize=config['ksize'], shell: """ sourmash sketch dna -p k={params.ksize} genomes/*.fna.gz --name-from-first """ ``` 이 방식의 장점은 다음과 같습니다. * `params` 블록을 사용함으로써 이것이 조정 가능한 매개변수임을 다른 사람에게 명확히 알릴 수 있습니다. * Snakefile 코드를 직접 건드리지 않고도 설정 파일만으로 k-mer 크기를 조절할 수 있습니다. 참고로, 설정 파일의 값이 정수인지 문자열인지 확인하거나 기본값을 제공하고 싶을 때는 Python의 `.get()` 메서드를 사용할 수도 있습니다. (예: `config.get('ksize', 31)`) ## 설정 파일 디버깅하기 Snakemake를 실행할 때 실제로 어떤 설정값이 적용되었는지 확인하고 싶을 때가 있습니다. 이럴 때는 Python의 `pprint` 모듈을 사용하면 편리합니다. ```python import pprint configfile: "config.multi_samples.yml" # config 딕셔너리 출력 print('적용된 설정(config):') pprint.pprint(config) SAMPLES = config['samples'] rule all: input: expand("one_sample.{s}.out", s=SAMPLES) ... ``` 실행하면 다음과 같이 딕셔너리 구조가 예쁘게 출력되어 어떤 값들이 로드되었는지 쉽게 확인할 수 있습니다. ``` 적용된 설정(config): {'samples': ['DEF_789', 'GHI_234', 'JKL_567']} ``` ## 고급 사용법 ### 명령줄에서 직접 설정값 제공하기 별도의 파일을 만들지 않고도 명령줄에서 특정 설정값을 바로 지정하거나 재정의할 수 있습니다. ```bash snakemake -j 1 -C sample=ZZZ_123 ksize=21 ``` `-C` (또는 `--config`) 옵션을 사용하면 설정 파일의 내용을 무시하거나 새로운 변수를 바로 주입할 수 있습니다. ### 여러 설정 파일 동시에 사용하기 `--configfiles` 옵션을 사용하면 여러 개의 YAML 파일을 동시에 제공할 수 있습니다. 파일들이 겹치는 키를 가지고 있다면 나중에 지정된 파일의 값이 우선합니다. ## 요약 설정 파일을 사용하면 다음의 이점을 얻을 수 있습니다. 1. 워크플로 로직(Snakefile)과 실제 데이터 정보(Config)를 분리할 수 있습니다. 2. 동일한 워크플로를 다양한 데이터셋에 쉽게 재사용할 수 있습니다. 3. 소스 코드를 직접 수정하는 것보다 휴먼 에러를 줄일 수 있습니다. 4. 팀원 간의 협업 시 설정값 공유가 쉬워집니다. ## 참고 문서 * [Snakemake 공식 문서 - Configuration](https://snakemake.readthedocs.io/en/stable/snakefiles/configuration.html) * YAML 및 JSON 문법 가이드