Use command to perform pileups, and to visualize them.

Submodules command

usage: [-h] [--features_format {bed,bedpe,auto}] [--view VIEW]
                  [--flank FLANK] [--minshift MINSHIFT] [--maxshift MAXSHIFT]
                  [--nshifts NSHIFTS] [--expected EXPECTED] [--ooe OOE]
                  [--mindist MINDIST] [--maxdist MAXDIST]
                  [--ignore_diags IGNORE_DIAGS] [--excl_chrs EXCL_CHRS]
                  [--incl_chrs INCL_CHRS] [--subset SUBSET] [--anchor ANCHOR]
                  [--by_window] [--by_strand] [--by_distance] [--local]
                  [--coverage_norm] [--rescale]
                  [--rescale_flank RESCALE_FLANK]
                  [--rescale_size RESCALE_SIZE]
                  [--clr_weight_name CLR_WEIGHT_NAME] [-p N_PROC] [-o OUTNAME]
                  [--seed SEED] [-l {DEBUG,INFO,WARNING,ERROR,CRITICAL}]
                  [--post_mortem] [-v]
                  cool_path features

Positional Arguments


Cooler file with your Hi-C data

A 3-column bed file or a 6-column double-bed file

i.e. chr1,start1,end1,chr2,start2,end2. Should be tab-delimited.

With a bed file, will consider all cis combinations of intervals. To pileup features along the diagonal instead, use the --local argument.

Can be piped in via stdin, then use “-”

Named Arguments

--features_format, --basetype

Possible choices: bed, bedpe, auto

Format of the features. Options:

bed: chrom, start, end bedpe: chrom1, start1, end1, chrom2, start2, end2 auto (default): determined from the file name extension Has to be explicitly provided is features is piped through stdin

Default: “auto”


Path to a file which defines which regions of the chromosomes to use

--flank, --pad
Flanking of the windows around the centres of specified features

i.e. final size of the matrix is 2 × flank+res, in bp. Ignored with --rescale, use --rescale_flank instead

Default: 100000


Shortest shift for random controls, bp

Default: 100000


Longest shift for random controls, bp

Default: 1000000


Number of control regions per averaged window

Default: 10

File with expected (output of cooltools compute-expected).

If None, don’t use expected and use randomly shifted controls

If expected is provided, normalize each snipper individually. If False,

will accumulate all expected snippets just like forrandomly shifted controls

Default: True

Minimal distance of interactions to use, bp.

If “auto”, uses 2*flank+2 (in bins) as mindist to avoid first two diagonals


Maximal distance of interactions to use


How many diagonals to ignore

Default: 2


Exclude these chromosomes from analysis

Default: “chrY,chrM”

Include these chromosomes; default is all.

--excl_chrs overrides this

Default: “all”

Take a random sample of the bed file.

Useful for files with too many featuers to run as is, i.e. some repetitive elements. Set to 0 or lower to keep all data

Default: 0

A UCSC-style coordinate.

Use as an anchor to create intersections with coordinates in the features

Perform by-window pile-ups.

Create a pile-up for each coordinate in the features. Not compatible with –by_strand and –by_distance

Default: False

Perform by-strand pile-ups.

Create a separate pile-up for each strand combination in the features.

Default: False

Perform by-distance pile-ups.

Create a separate pile-up for each distance band using [0, 50000, 100000, 200000, …) as edges.

Default: False


Create local pileups, i.e. along the diagonal

Default: False


If empty clr_weight_name, add coverage normalization using chromosome marginals

Default: False

Rescale all features to the same size.

Do not use centres of features and flank, and rather use the actual feature sizes and rescale pileups to the same shape and size

Default: False

--rescale_flank, --rescale_pad

If –rescale, flanking in fraction of feature length

Default: 1.0

Size to rescale to.

If --rescale, used to determine the final size of the pileup, i.e. it will be size×size. Due to technical limitation in the current implementation, has to be an odd number

Default: 99

--clr_weight_name, --weight_name
Name of the norm to use for getting balanced data.

Provide empty argument to calculate pileups on raw data (no masking bad pixels).

Default: “weight”

-p, --nproc, --n_proc
Number of processes to use.

Each process works on a separate chromosome, so might require quite a bit more memory, although the data are always stored as sparse matrices

Default: 1

-o, --outname
Name of the output file.

If not set, file is saved in the current directory and the name is generated automatically to include important information and avoid overwriting files generated with different settings.

Default: “auto”


Set specific seed value to ensure reproducibility

-l, --log


Set the logging level

Default: “INFO”


Enter debugger if there is an error

Default: False

-v, --version

show program’s version number and exit command

usage: [-h] [--cmap CMAP] [--symmetric SYMMETRIC] [--vmin VMIN]
                  [--vmax VMAX] [--scale {linear,log}] [--cols COLS]
                  [--rows ROWS] [--col_order COL_ORDER]
                  [--row_order ROW_ORDER] [--query QUERY]
                  [--norm_corners NORM_CORNERS] [--score SCORE]
                  [--center CENTER] [--ignore_central IGNORE_CENTRAL]
                  [--quaich] [--dpi DPI] [--output OUTPUT] [--post_mortem]
                  [--input_pups INPUT_PUPS [INPUT_PUPS ...]] [-v]

Named Arguments

Colourmap to use


Default: “coolwarm”


Whether to make colormap symmetric around 1, if log scale

Default: True


Value for the lowest colour


Value for the highest colour


Possible choices: linear, log

Whether to use linear or log scaling for mapping colours

Default: “log”


Which value to map as columns


Which value to map as rows


Order of columns to use, space or comma separated


Order of rows to use, space or comma separated


“Pandas query top select pups to plot from concatenated input files

Whether to normalize pileups by their top left and bottom right corners.

0 for no normalization, positive number to define the size of the corner squares whose values are averaged

Default: 0

Whether to calculate score and add it to the top right corner of each

pileup. Will use the ‘coolpup.get_score’ function with ‘center’ and ‘ignore_central’ arguments.

Default: True

How many central pixels to consider when calculating enrichment for

off-diagonal pileups.

Default: 3

How many central bins to ignore when calculating insulation for

local (on-diagonal) non-rescaled pileups.

Default: 3

Activate if pileups are named accodring to Quaich naming convention

to get information from the file name

Default: False


DPI of the output plot. Try increasing if heatmaps look blurry

Default: 300

--output, -o

Where to save the plot

Default: “pup.pdf”


Enter debugger if there is an error

Default: False


All files to plot

-v, --version

show program’s version number and exit