|
| 1 | +Workflows and Parameters |
| 2 | +======================== |
| 3 | + |
| 4 | +This page provides guidance on using pairtools for the most common Hi-C protocols and |
| 5 | +helps users fine-tune the pipeline for different variations of the Hi-C protocol. |
| 6 | +It covers recommended parameters and best practices for processing Hi-C data using pairtools. |
| 7 | + |
| 8 | +Typical Hi-C Workflow |
| 9 | +---------------------- |
| 10 | + |
| 11 | +A typical pairtools workflow for processing standard Hi-C data is outlined below. |
| 12 | +Please, note that this is a shorter version; you can find a more detailed and reproducible example in chapter :ref:`examples/pairtools_walkthrough`. |
| 13 | + |
| 14 | +1. Align sequences to the reference genome with ``bwa mem``: |
| 15 | + |
| 16 | + .. code-block:: console |
| 17 | +
|
| 18 | + bwa mem -SP index_file input.R1.fastq input.R2.fastq > input.sam |
| 19 | +
|
| 20 | +2. Parse alignments into Hi-C pairs using ``pairtools parse``: |
| 21 | + |
| 22 | + .. code-block:: console |
| 23 | +
|
| 24 | + pairtools parse -c /path/to/chrom_sizes -o output.pairs.gz input.sam |
| 25 | +
|
| 26 | +3. Sort pairs using ``pairtools sort``: |
| 27 | + |
| 28 | + |
| 29 | + .. code-block:: console |
| 30 | +
|
| 31 | +
|
| 32 | + pairtools sort --nproc 8 -o output.sorted.pairs.gz output.pairs.gz |
| 33 | +
|
| 34 | +4. Detect and remove duplicates using ``pairtools dedup`` and generate statistics: |
| 35 | + |
| 36 | + .. code-block:: console |
| 37 | +
|
| 38 | + pairtools dedup \ |
| 39 | + --output output.nodups.pairs.gz \ |
| 40 | + --output-dups output.dups.pairs.gz \ |
| 41 | + --output-unmapped output.unmapped.pairs.gz |
| 42 | + --output-stats output.dedup.stats \ |
| 43 | + output.sorted.pairs.gz |
| 44 | +
|
| 45 | +5. Aggregate into a cooler file: |
| 46 | + |
| 47 | + .. code-block:: console |
| 48 | +
|
| 49 | + cooler cload pairs -c1 2 -p1 3 -c2 4 -p2 5 /path/to/chrom_sizes:1000 output.nodups.pairs.gz output.1000.cool |
| 50 | +
|
| 51 | +
|
| 52 | +
|
| 53 | +
|
| 54 | +Recommended pairtools parameters for standard Hi-C protocols |
| 55 | +------------------------------------------------------------ |
| 56 | + |
| 57 | +To adapt the standard workflow for common variations of the Hi-C protocol, consider adjusting the following parameters: |
| 58 | + |
| 59 | +1. ``pairtools parse --walks-policy``: |
| 60 | + |
| 61 | +This parameter determines how pairtools parse handles reads with multiple alignments (walks). We recommend specifying the value explicitly, as the default has changed between versions of ``pairtools parse``. |
| 62 | + |
| 63 | +Our current recommendation is to use ``--walks-policy 5unique``, which is the default setting in the latest version of pairtools. With this option, pairtools parse reports the two 5'-most unique alignments on each side of a paired read as a pair. |
| 64 | + |
| 65 | +This option increases the number of reported pairs compared to the most conservative ``--walks-policy mask``. However, it's important to note that ``5unique`` can potentially report pairs of non-directly ligated fragments (i.e., two fragments separated by one or more other DNA fragments). Such non-direct (also known as "higher-order" or "nonadjacent") ligations have slightly different statistical properties than direct ligations, as illustrated in several Pore-C papers [`1 <https://www.biorxiv.org/content/10.1101/833590v1.full>`_ , `2 <https://www.nature.com/articles/s41467-023-36899-x>`_]. |
| 66 | + |
| 67 | +An alternative is the ``--walks-policy 3unique`` policy, which reports the two 3'-most unique alignments on each side of |
| 68 | + a paired read as a pair, thus decreasing the chance of reporting non-direct ligations. |
| 69 | + However, ``3unique`` may not work well in situations where the combined length of a read pair is longer than the length of a DNA fragment (e.g. long read experiments). |
| 70 | + In this case, the 3' sides of the two reads will cover the same locations in the DNA molecule, and the 3' alignments may end up identical. |
| 71 | + |
| 72 | +Finally, the experimental ``--walks-policy all`` option reports all alignments of a read pair as separate pairs. This option maximizes the number of reported pairs. The downside is that it breaks the assumption that there is only one pair per read, which is not compatible with retrieval of .sam records from .pairsam output and may also complicate the interpretation of pair statistics. |
| 73 | + |
| 74 | +2. ``pairtools select "(mapq1>=30) and (mapq2>=30)"``: |
| 75 | + |
| 76 | +This filtering command selects only pairs with high-quality alignments, |
| 77 | + where both reads in a pair have a mapping quality (MAPQ) score of 30 or higher. |
| 78 | + Applying this filter helps remove false alignments between partially homologous sequences, which often cause artificial high-frequency interactions in Hi-C maps. |
| 79 | + This step is essential for generating maps for high-quality dot calls. |
| 80 | + |
| 81 | + Note that we recommend storing the most comprehensive, unfiltered list of pairs and applying the filter on the fly prior to contact aggregation: |
| 82 | + |
| 83 | + .. code-block:: console |
| 84 | +
|
| 85 | + pairtools select "(mapq1>=30) and (mapq2>=30)" output.nodups.pairs.gz | \ |
| 86 | + cooler cload pairs -c1 2 -p1 3 -c2 4 -p2 5 chromsizes.txt:1000 - output.mapq_30.1000.cool |
| 87 | +
|
| 88 | +
|
| 89 | +Technical tips |
| 90 | +-------------- |
| 91 | + |
| 92 | +- **Pipe between commands to save space and I/O throughput** |
| 93 | + |
| 94 | + Use Unix pipes to connect the output of one command directly to the input of the next command in the pipeline. |
| 95 | + This eliminates the need to store intermediate files on disk, saving storage space and reducing I/O overhead. |
| 96 | + Specifically, mapping, parsing, sorting and deduplication can all be connected into a single pipeline: |
| 97 | + |
| 98 | + .. code-block:: console |
| 99 | +
|
| 100 | + bwa mem -SP index input.R1.fastq input.R2.fastq | \ |
| 101 | + pairtools parse -c chromsizes.txt | \ |
| 102 | + pairtools sort | \ |
| 103 | + --output output.nodups.pairs.gz \ |
| 104 | + --output-dups output.dups.pairs.gz \ |
| 105 | + --output-unmapped output.unmapped.pairs.gz |
| 106 | + --output-stats output.dedup.stats |
| 107 | +
|
| 108 | +- **Use recommended compression for efficient storage and processing.** .sam, .pairs and .pairsam files are text-based format that are rather inefficient and slow to process. |
| 109 | + Pairtools recognize .bam, .gz and .lz4 file extensions and automatically compress and decompress files on the fly. |
| 110 | + Compression saves space, and reduces I/O overhead at a relatively minor CPU cost. |
| 111 | + |
| 112 | +- **Parallelize tasks and manage resources effectively for faster execution.** |
| 113 | + Each pairtool has the CLI flags --nproc-in and --nproc-out to control the number of cores dedicated |
| 114 | + to input decompression and output compression. Additionally, `pairtools sort` parallelizes sorting with `--nproc`.ß |
| 115 | + |
| 116 | +Example Workflows |
| 117 | +----------------- |
| 118 | + |
0 commit comments