restrict pipeline to use one ip replicate and control replicate, update usage on sample sheet design

Author: Kevin-Brockers

CHANGELOG.md

@@ -21,6 +21,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - [[PR #493](https://github.com/nf-core/chipseq/pull/493)] - Follow up to #487.
 - [[#492](https://github.com/nf-core/chipseq/issues/492), [#417](https://github.com/nf-core/chipseq/issues/417)] - Refactor local modules to nf-core standard.
 - [[#416](https://github.com/nf-core/chipseq/issues/416)] - Moved the KHMER_UNIQUEKMERS logic to prepare_genome
+- [[#510](https://github.com/nf-core/chipseq/issues/510)] - Restrict the usage to one IP replicate against one control see: [#440](https://github.com/nf-core/chipseq/issues/440)
+  replicate.
 
 ### Parameters
 

bin/check_samplesheet.py

@@ -212,9 +212,12 @@ def check_samplesheet(file_in, file_out):
                             sample,
                         )
 
+                    set_control_replicates = set()
                     for idx, val in enumerate(sample_mapping_dict[sample][replicate]):
                         control = "_REP".join(val[-1].split("_REP")[:-1])
                         control_replicate = val[-1].split("_REP")[-1]
+                        set_control_replicates.update(control_replicate)
+
                         if control and (
                             control not in sample_mapping_dict.keys()
                             or int(control_replicate) not in sample_mapping_dict[control].keys()
@@ -225,6 +228,12 @@ def check_samplesheet(file_in, file_out):
                                 val[-1],
                             )
 
+                    # Check that a given sample-replicate have only one control replicate
+                    if len(set_control_replicates) > 1:
+                        print_error(
+                            f"Sample: {sample}, replicate {replicate} has more than one control replicate! Revise the experimental design, see: 'Note on IP and control replicates'"
+                        )
+
                     ## Write to file
                     for idx in range(len(sample_mapping_dict[sample][replicate])):
                         fastq_files = sample_mapping_dict[sample][replicate][idx]

docs/usage.md

@@ -47,6 +47,48 @@ WT_INPUT,BLA203A30_S21_L002_R1_001.fastq.gz,,2,,,
 WT_INPUT,BLA203A31_S21_L003_R1_001.fastq.gz,,3,,,
 ```
 
+### Note on IP and control replicates
+
+The pipeline is designed to handle one IP and matching control replicate, see section above. However there can be
+situations where one might want to make multiple comparisons of the IP sample against several different controls. In
+those cases it is advisable to encode these comparisons either in the sample column or as another replicate.
+
+- Encoding in sample names:
+
+```csv title="samplesheet.csv"
+sample,fastq_1,fastq_2,replicate,antibody,control,control_replicate
+WT_BCATENIN_IP,BLA203A1_S27_L006_R1_001.fastq.gz,,1,BCATENIN,WT_INPUT,1
+WT_BCATENIN_IP_CONTROL_2,BLA203A1_S27_L006_R1_001.fastq.gz,,1,BCATENIN,WT_INPUT,2
+WT_BCATENIN_IP_CONTROL_3,BLA203A1_S27_L006_R1_001.fastq.gz,,1,BCATENIN,WT_INPUT,3
+WT_INPUT,BLA203A6_S32_L006_R1_001.fastq.gz,,1,,,
+WT_INPUT,BLA203A30_S21_L001_R1_001.fastq.gz,,2,,,
+WT_INPUT,BLA203A31_S21_L003_R1_001.fastq.gz,,3,,,
+```
+
+- Encoding as new biological replicates:
+
+```csv title="samplesheet.csv"
+sample,fastq_1,fastq_2,replicate,antibody,control,control_replicate
+WT_BCATENIN_IP,BLA203A1_S27_L006_R1_001.fastq.gz,,1,BCATENIN,WT_INPUT,1
+WT_BCATENIN_IP,BLA203A1_S27_L006_R1_001.fastq.gz,,2,BCATENIN,WT_INPUT,2
+WT_BCATENIN_IP,BLA203A1_S27_L006_R1_001.fastq.gz,,3,BCATENIN,WT_INPUT,3
+WT_INPUT,BLA203A6_S32_L006_R1_001.fastq.gz,,1,,,
+WT_INPUT,BLA203A30_S21_L001_R1_001.fastq.gz,,2,,,
+WT_INPUT,BLA203A31_S21_L003_R1_001.fastq.gz,,3,,,
+```
+
+- The following design, one IP replicate against more than one control replicate, is not allowed:
+
+```csv title="samplesheet.csv"
+sample,fastq_1,fastq_2,replicate,antibody,control,control_replicate
+WT_BCATENIN_IP,BLA203A1_S27_L006_R1_001.fastq.gz,,1,BCATENIN,WT_INPUT,1
+WT_BCATENIN_IP,BLA203A1_S27_L006_R1_001.fastq.gz,,1,BCATENIN,WT_INPUT,2
+WT_BCATENIN_IP,BLA203A1_S27_L006_R1_001.fastq.gz,,1,BCATENIN,WT_INPUT,3
+WT_INPUT,BLA203A6_S32_L006_R1_001.fastq.gz,,1,,,
+WT_INPUT,BLA203A30_S21_L001_R1_001.fastq.gz,,2,,,
+WT_INPUT,BLA203A31_S21_L003_R1_001.fastq.gz,,3,,,
+```
+
 ### Full design
 
 The pipeline will auto-detect whether a sample is single- or paired-end using the information provided in the samplesheet. The samplesheet can have as many columns as you desire, however, there is a strict requirement for the first 7 columns to match those defined in the table below.