MAC3_CALLPEAK(1)

📦
version 3.0.4 · 5 versions
, in ubuntu stonking

✨ NAME ✨

mac3_callpeak — Model-based Analysis for ChIP-Sequencing 👑

(Also that's a whole macs3 callpeak situation, bestie, and it serves.)

🎀 DESCRIPTION 🎀

okay so, hi, welcome to the main character of MACS3 💅 this is the tool that finds your peaks. Here's the vibe of how you call it:

macs3 callpeak [-h] -t TFILE [TFILE ...] [-c [CFILE ...]]
               [-f {AUTO,BAM,SAM,BED,ELAND,ELANDMULTI,ELANDEXPORT,BOWTIE,BAMPE,BEDPE,FRAG}]
               [-g GSIZE] [-s TSIZE] [--keep-dup KEEPDUPLICATES] [--barcodes BARCODEFILE]
               [--max-count MAXCOUNT] [--outdir OUTDIR] [-n NAME] [-B] [--verbose VERBOSE]
               [--trackline] [--SPMR] [--nomodel] [--shift SHIFT] [--extsize EXTSIZE] [--bw BW]
               [--d-min D_MIN] [-m MFOLD MFOLD] [--fix-bimodal] [-q QVALUE | -p PVALUE]
               [--scale-to {large,small}] [--down-sample] [--seed SEED] [--tempdir TEMPDIR]
               [--nolambda] [--slocal SMALLLOCAL] [--llocal LARGELOCAL] [--max-gap MAXGAP]
               [--min-length MINLEN] [--broad] [--broad-cutoff BROADCUTOFF] [--cutoff-analysis]
               [--call-summits] [--fe-cutoff FECUTOFF] [--to-large] [--ratio RATIO]
               [--buffer-size BUFFER_SIZE]

🌸 options 🌸

  • -h, --help — shows this help message and exits. the classic. the icon. 🫶

🧚 Input files arguments 🧚

  • -t, --treatment TFILE [TFILE ...] — the ChIP-seq treatment file. and like, if you hand it multiple files as -t A B C, it reads them all and pools them together. REQUIRED, bestie. no treatment file, no peaks. 💀
  • -c, --control [CFILE ...] — the control file. same pooling energy: give it -c A B C and it pools them all to estimate the ChIP-seq background noise. 🌫️
  • -f, --format — the format of the tag file, and your choices are {AUTO,BAM,SAM,BED,ELAND,ELANDMULTI,ELANDEXPORT,BOWTIE,BAMPE,BEDPE,FRAG}. The default AUTO option lets MACS decide which format the file is (except for BAMPE, BEDPE, and FRAG, which you have to set explicitly, no guessing on those). Please check the definition in README. 📖

Please note that if the format is set as BAMPE, BEDPE, or FRAG, MACS3 calls its special Paired-end mode to call peaks by piling up the actual ChIPed fragments defined by both aligned ends, instead of predicting the fragment size first and extending reads. ✨

Also please note that the BEDPE only contains three columns, and is NOT the same BEDPE format used by BEDTOOLS. 🙈 The FRAG format is for single-cell ATACseq fragment file, which is a five-column BEDPE file with an extra barcode and fragment count column. Also please note that if FRAG is used, MACS3 won't remove any duplicates, i.e. --keep-dup will be always set as all.

DEFAULT: "AUTO"

  • -g, --gsize GSIZE — Effective genome size. It can be 1.0e+9 or 1000000000, or a shortcut: 'hs' for human (2,913,022,398), 'mm' for mouse (2,652,783,500), 'ce' for C. elegans (100,286,401) and 'dm' for fruitfly (142,573,017). Default: hs. 🌈

The effective genome size numbers for the above four species are collected from Deeptools: https: //deeptools.readthedocs.io/en/develop/content/feature/effectiveGenomeSize.html — please refer to deeptools to define the best genome size you plan to use. (yes, that URL is printed exactly like that in the original, we don't fix, we respect 👑)

  • -s, --tsize TSIZE — Tag size / read length. This will override the auto detected tag size. DEFAULT: Not set 🌸
  • --keep-dup KEEPDUPLICATES — controls the behavior towards duplicate tags at the exact same location — the same coordination and the same strand. The 'auto' option makes MACS calculate the maximum tags at the exact same location based on binomal distribution using 1e-5 as pvalue cutoff; and the 'all' option keeps every tag. If an integer is given, at most this number of tags will be kept at the same location. 🧮

Note: if you've used samtools or picard to flag reads as 'PCR/Optical duplicate' in bit 1024, MACS3 will still read them although the reads may be decided by MACS3 as duplicate later. If you plan to rely on samtools/picard/any other tool to filter duplicates, please remove those duplicate reads and save a new alignment file, then ask MACS3 to keep all by --keep-dup all. 🫶

Also, please note that if the format is FRAG, this option will be ignored and MACS3 will behave always like --keep-dup all.

The default is to keep one tag at the same location. Default: 1

  • --barcodes BARCODEFILE — a plain text file containing the barcodes for the fragment file while the format is 'FRAG'. Won't have any effect if the format is not 'FRAG'. Each row in the file should only have the barcode string. MACS3 will extract only the fragments for the specified barcodes. 🎟️
  • --max-count MAXCOUNT — in the FRAG format file, the fifth column indicates the count of fragments found at the exact same location from the same barcode. By default, MACS3 treats each fragment count as indicated. However, if this option is enabled and set as a positive integer, MACS3 will not count more than the specified number. If this is set as 0, MACS3 will behave as the default setting to keep all counts. 🔢

Please note that callpeak -f FRAG --max-count 1 is supposed to generate the same result as callpeak -f BEDPE --keep-dup all on fragment files. This option will be ignored if the format is not FRAG.

💖 Output arguments 💖

  • --outdir OUTDIR — if specified, all output files will be written to that directory. Default: the current working directory 📁
  • -n, --name NAME — Experiment name, which will be used to generate output file names. DEFAULT: "NA" 🏷️
  • -B, --bdg — whether or not to save extended fragment pileup, and local lambda tracks (two files) at every bp into a bedGraph file. DEFAULT: False 📈
  • --verbose VERBOSE — set verbose level of runtime message. 0: only show critical message, 1: show additional warning message, 2: show process information, 3: show debug messages. DEFAULT: 2 🗣️
  • --trackline — instruct MACS to include trackline in the header of output files, including the bedGraph, narrowPeak, gappedPeak, BED format files. To include this trackline is necessary while uploading them to the UCSC genome browser. You can also mannually add these trackline to corresponding output files. 🌐

For example, in order to upload narrowPeak file to UCSC browser, add this to as the first line — track type=narrowPeak name="my_peaks" description="my peaks". Default: Not to include trackline.

  • --SPMR — If True, MACS will SAVE signal per million reads for fragment pileup profiles. It won't interfere with computing pvalue/qvalue during peak calling, since internally MACS3 keeps using the raw pileup and scaling factors between larger and smaller dataset to calculate statistics measurements. If you plan to use the signal output in bedGraph to call peaks using bdgcmp and bdgpeakcall, you shouldn't use this option because you will end up with different results. 😭 However, this option is recommended for displaying normalized pileup tracks across many datasets. Require -B to be set. Default: False

🦋 Shifting model arguments 🦋

  • --nomodel — whether or not to build the shifting model. If True, MACS will not build model. by default it means shifting size = 100, try to set extsize to change it. It's highly recommended that while you have many datasets to process and you plan to compare different conditions, aka differential calling, use both 'nomodel' and 'extsize' to make signal files from different datasets comparable. DEFAULT: False 🛠️
  • --shift SHIFT — (NOT the legacy --shiftsize option! ⚠️) The arbitrary shift in bp. Use discretion while setting it other than default value. When NOMODEL is set, MACS will use this value to move cutting ends (5') towards 5'->3' direction, then apply EXTSIZE to extend them to fragments. When this value is negative, ends will be moved toward 3'->5' direction. Recommended to keep it as default 0 for ChIP-Seq datasets, or -1 * half of EXTSIZE together with EXTSIZE option for detecting enriched cutting loci such as certain DNAseI-Seq datasets. Note, you can't set values other than 0 if format is BAMPE or BEDPE for paired-end data. DEFAULT: 0.
  • --extsize EXTSIZE — The arbitrary extension size in bp. When nomodel is true, MACS will use this value as fragment size to extend each read towards 3' end, then pile them up. It's exactly twice the number of obsolete SHIFTSIZE. In previous language, each read is moved 5'->3' direction to middle of fragment by 1/2 d, then extended to both direction with 1/2 d. This is equivalent to say each read is extended towards 5'->3' into a d size fragment. DEFAULT: 200. EXTSIZE and SHIFT can be combined when necessary. Check SHIFT option. 📏
  • --bw BW — Band width for picking regions to compute fragment size. This value is only used while building the shifting model. Tweaking this is not recommended. DEFAULT: 300
  • --d-min D_MIN — Minimum fragment size in basepair. Any predicted fragment size less than this will be excluded. DEFAULT: 20 📐
  • -m, --mfold MFOLD MFOLD — Select the regions within MFOLD range of highconfidence enrichment ratio against background to build model. Fold-enrichment in regions must be lower than upper limit, and higher than the lower limit. Use as "-m 10 30". This setting is only used while building the shifting model. Tweaking it is not recommended. DEFAULT: 5 50 🎯
  • --fix-bimodal — whether turn on the auto pair model process. If set, when MACS failed to build paired model, it will use the nomodel settings, the --exsize parameter to extend each tags towards 3' direction. Not to use this automate fixation is a default behavior now. DEFAULT: False 🔧

👑 Peak calling arguments 👑

  • -q, --qvalue QVALUE — Minimum FDR (q-value) cutoff for peak detection. DEFAULT: 0.05. -q, and -p are mutually exclusive. 💥
  • -p, --pvalue PVALUE — Pvalue cutoff for peak detection. DEFAULT: not set. -q, and -p are mutually exclusive. If pvalue cutoff is set, qvalue will not be calculated and reported as -1 in the final .xls file. 📊
  • --scale-to {large,small} — set it to 'small' and the bigger sample gets scaled down to match the smaller one. Set it to 'larger' and the smaller sample gets scaled up to the bigger one. Out of the box it scales to 'small'. This option is the glow-up replacement for the crusty obsolete --to-large. And bestie, the default behavior is the one you actually want, because it generally leads to less significant p/q-values but more specific results. Just keep in mind that scaling down will influence the control/input sample more. DEFAULT: 'small', and the choice is either 'small' or 'large'. 💅
  • --down-sample — when set, the random sampling method will scale down the bigger sample. By default, MACS uses linear scaling. ⚠️ Warning: this option will make your result unstable and irreproducible, because each and every time, random reads would be selected. Consider using the randsample script instead. <not implmented>If used together with --SPMR, 1 million unique reads will be randomly picked.</not implemented> 🫠 Caution: due to the implementation, the final number of selected reads may not be as you expected! DEFAULT: False
  • --seed SEED — sets the random seed while down sampling data. It must be a non-negative integer in order to be effective. DEFAULT: not set 🌱
  • --tempdir TEMPDIR — optional directory where temp files get stored. DEFAULT: /tmp 🗂️
  • --nolambda — if True, MACS will use a fixed background lambda as the local lambda for every peak region. Normally, MACS calculates a dynamic local lambda to reflect the local bias caused by the potential chromatin accessibility. ✨
  • --slocal SMALLLOCAL — the small nearby region, in basepairs, used to calculate dynamic lambda. This is what captures the bias near the peak summit region. It's invalid if there's no control data. If you set this to 0, MACS will skip the slocal lambda calculation. Note that MACS will always perform a d-size local lambda calculation while control data is available. The final local bias would be the maximum of the lambda value from the d, slocal, and llocal size windows. While control is not available, d and slocal lambda won't be considered. DEFAULT: 1000
  • --llocal LARGELOCAL — the large nearby region, in basepairs, used to calculate dynamic lambda. This one is for capturing the surround bias. If you set this to 0, MACS will skip the llocal lambda calculation. Note that MACS will always perform a d-size local lambda calculation while control data is available. The final local bias would be the maximum of the lambda value from the d, slocal, and llocal size windows. While control is not available, d and slocal lambda won't be considered. DEFAULT: 10000.
  • --max-gap MAXGAP — maximum gap between significant sites for clustering them together. The DEFAULT value is the detected read length/tag size. 📏
  • --min-length MINLEN — minimum length of a peak. The DEFAULT value is the predicted fragment size d. Heads up: if you set a value smaller than the fragment size, it may have NO effect on the result. For BROAD peak calling, try setting a large value such as 500bps. You can also use the -- cutoff-analysis option with default setting, and check the column avelpeak under different cutoff values to decide a reasonable minlen value. 👑
  • --broad — if set, MACS will try to call broad peaks using the --broad-cutoff setting. Please tweak the --broad-cutoff setting to control the peak calling behavior. At the meantime, either -q or -p cutoff will be used to define regions with 'stronger enrichment' inside of broad peaks. The maximum gap is expanded to 4 * MAXGAP (the --max-gap parameter). As a result, MACS will output a gappedPeak and a broadPeak file instead of a narrowPeak file. Note that a broad peak will be reported even if there is no 'stronger enrichment' inside. DEFAULT: False 🦋
  • --broad-cutoff BROADCUTOFF — cutoff for the broad region. This option is not available unless --broad is set. If -p is set, this is a pvalue cutoff; otherwise it's a qvalue cutoff. Please note that in broad peakcalling mode, MACS3 uses this setting to control the overall peak calling behavior, then uses -q or -p to define regions inside the broad region as 'stronger' enrichment. DEFAULT: 0.1
  • --cutoff-analysis — while set, MACS3 will analyze the number or total length of peaks that can be called by different p-value cutoff, then output a summary table to help you decide a better cutoff. The table will be saved in the NAME_cutoff_analysis.txt file. Note, minlen and maxgap may affect the results. ⚠️ WARNING: May take ~30 folds longer time to finish. The result can be useful for users to decide a reasonable cutoff value. DEFAULT: False 🍓

🎀 Post-processing options 🎀

  • --call-summits — if set, MACS will use a more sophisticated signal processing approach to find subpeak summits in each enriched peak region. DEFAULT: False ⛰️
  • --fe-cutoff FECUTOFF — when set, the value will be used as the minimum requirement to filter out peaks with low foldenrichment. Note, MACS3 adds one as pseudocount while calculating fold-enrichment. By default, it is set as 1 so there is no filtering. DEFAULT: 1.0 ✨

💀 Obsolete options 💀

  • --to-large — obsolete option. Please use --scale-to large instead. 🙈
  • --ratio RATIO — obsolete option. Originally designed to normalize treatment and control with a customized ratio, now it won't have any effect. 🫠

👑 Other options 👑

  • --buffer-size BUFFER_SIZE — buffer size for incrementally increasing the internal array size used to store reads alignment information. In most cases, you don't have to change this parameter. However, if there's a large number of chromosomes/contigs/scaffolds in your alignment, it's recommended to specify a smaller buffer size in order to decrease memory usage (but it will take longer time to read alignment files). Minimum memory requested for reading an alignment file is about # of CHROMOSOME * BUFFER_SIZE * 8 Bytes. DEFAULT: 100000 🧚

✨ EXAMPLES ✨

okay bestie, copy-paste hours, let's go 🔥

  1. Peak calling for regular TF ChIP-seq:
$ macs3 callpeak -t ChIP.bam -c Control.bam -f BAM -g hs -n test -B -q 0.01
  1. Broad peak calling on Histone Mark ChIP-seq:
$ macs3 callpeak -t ChIP.bam -c Control.bam --broad -g hs --broad-cutoff 0.1
  1. Peak calling on ATAC-seq (paired-end mode):
$ macs3 callpeak -f BAMPE -t ATAC.bam -g hs -n test -B -q 0.01
  1. Peak calling on ATAC-seq (focusing on insertion sites, and using single-end mode):
$ macs3 callpeak -f BAM -t ATAC.bam -g hs -n test -B -q 0.01 --shift -50 --extension 100
  1. Peak calling on scATAC-seq (paired-end mode):
$ macs3 callpeak -f BEDPE -t scATAC.fragments.tsv.gz -g hs -n test -B -q 0.01
  1. Peak calling on scATAC-seq (paired-end mode):
$ macs3 callpeak -f FRAG -t scATAC.fragments.tsv.gz -g hs -n test -B -q 0.01
  1. Peak calling on scATAC-seq (paired-end mode) and only for given barcodes:
$ macs3 callpeak -f FRAG -t scATAC.fragments.tsv.gz -g hs -n test -B -q 0.01 --barcodes barcodes.txt

and that's a wrap, gorgeous 🫶 this whole read came from macs3 callpeak version 3.0.4, dated May 2026, living its best life as MAC3_CALLPEAK(1) in the manual. go call some peaks, you absolute main character 💖🌸✨

📦 where this page comes from