docs/randsample.md

   1 # Randsample
   2
   3 ## Overview
   4 The `randsample` command is part of the MACS3 suite of tools and is used to randomly sample a certain number or percentage of tags from alignment files. This can be useful in ChIP-Seq analysis where a subset of the data is required for downstream analysis.
   5
   6 ## Detailed Description
   7
   8 The `randsample` command takes in one or multiple input alignment files and produces an output file with the randomly sampled tags. It uses an efficient algorithm to sample the tags, improving the quality of your data for further analysis.
   9
  10 ## Command Line Options
  11
  12 The command line options for `randsample` are defined in `/MACS3/Commands/randsample_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 BED 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 `randsample` command:
  30
  31 ```bash
  32 macs3 randsample -i treatment.bam -o sampled.bed -f BAM -g hs -n experiment1 --mfold 10 30
  33 ```
  34
  35 In this example, the program will randomly sample tags from the `treatment.bam` file and write the result to `sampled.bed`. 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 `randsample`
  38
  39 Q: What does `randsample` do?
  40 A: `randsample` is a tool in the MACS3 suite that randomly samples a certain number or percentage of tags from alignment files. It is useful in ChIP-Seq analysis where a subset of the data is required for downstream analysis.
  41
  42 Q: How do I use `randsample`?
  43 A: You can use `randsample` 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 `randsample`.
  44
  45 ## Troubleshooting `randsample`
  46
  47 If you're having trouble using `randsample`, here are some things to try:
  48
  49 - Make sure your input files are in the correct format. `randsample` 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 `randsample`
  53
  54 As of now, there are no known issues or limitations with `randsample`. If you encounter a problem, please submit an issue on the MACS3 GitHub page.