docs/pileup.md

   1 # Pileup
   2
   3 ## Overview
   4 The `pileup` command is part of the MACS3 suite of tools and is used to pile up alignment files. It is particularly useful in ChIP-Seq analysis where summarizing the read depth at each genomic location is required.
   5
   6 ## Detailed Description
   7
   8 The `pileup` command takes in one or multiple input files and produces an output file with the piled-up alignments. It uses an efficient algorithm to pile up the alignments, improving the quality of your data for further analysis.
   9
  10 ## Command Line Options
  11
  12 The command line options for `pileup` are defined in `/MACS3/Commands/pileup_cmd.py` and `/bin/macs3` files. Here is a brief overview of these options:
  13
  14 - `-i` or `--ifile`: The input files. These should be in BAM or BED format. This option is required and can take multiple files.
  15 - `-o` or `--ofile`: The output file. This will be in bedGraph format.
  16 - `-f` or `--format`: The format of the input file. Default is AUTO. Other options include SAM, BAM, and BED.
  17 - `-g` or `--gsize`: The size of the genome. Can be an integer or a string like '2.7e9'. Default is 'hs' for human genome size.
  18 - `-n` or `--name`: The name string of the experiment. This will be used to generate output file names. Default is 'NA'.
  19 - `-s` or `--tsize`: The tag size. Default is None.
  20 - `-B` or `--BAM`: Store results in BAM format. If this option is set, MACS will store all tags that pass quality filters to a BAM file including tags that failed to pass the shifting model.
  21 - `-m` or `--mfold`: The mfold range. Default is [5,50].
  22 - `--bw`: The bandwidth used to compute the fragment size. Default is 300.
  23 - `--fix-bimodal`: If set, MACS will not model but use the user-determined fragment size.
  24 - `--nomodel`: If set, MACS will not build the shifting model.
  25 - `--extsize`: While '--nomodel' is set, MACS uses this parameter to extend reads in 5'->3' direction to fix-sized fragments.
  26
  27 ## Example Usage
  28
  29 Here is an example of how to use the `pileup` command:
  30
  31 ```bash
  32 macs3 pileup -i treatment.bam -o piledup.bedGraph -f BAM -g hs -n experiment1
  33 ```
  34
  35 In this example, the program will pile up the alignments in the `treatment.bam` file and write the result to `piledup.bedGraph`. The input file is in BAM format, the genome size is set to 'hs' (human), and the name of the experiment is 'experiment1'.
  36
  37 ## FAQs about `pileup`
  38
  39 Q: What does `pileup` do?
  40 A: `pileup` is a tool in the MACS3 suite that piles up alignment files. It is useful in ChIP-Seq analysis where summarizing the read depth at each genomic location is required.
  41
  42 Q: How do I use `pileup`?
  43 A: You can use `pileup` by providing it with one or multiple input files, an output file, and various other options as required. See the [Example Usage](#example-usage) section above for an example of how to use `pileup`.
  44
  45 ## Troubleshooting `pileup`
  46
  47 If you're having trouble using `pileup`, here are some things to try:
  48
  49 - Make sure your input files are in the correct format. `pileup` requires BAM or BED files.
  50 - Make sure the parameters you provide are appropriate for your data. Different parameters will yield different results.
  51
  52 ## Known issues or limitations of `pileup`
  53
  54 As of now, there are no known issues or limitations with `pileup`. If you encounter a problem, please submit an issue on the MACS3 GitHub page.