CLI Reference

Quick reference

cooler [OPTIONS] COMMAND [ARGS]...

Data ingest
cooler cload	Create a cooler from genomic point pairs and bins.
cooler load	Create a cooler from a pre-binned matrix.

Reduction
cooler merge	Merge multiple coolers with identical axes.
cooler coarsen	Coarsen a cooler to a lower resolution.
cooler zoomify	Generate a multi-resolution cooler file by coarsening.

Normalization
cooler balance	Out-of-core matrix balancing.

Export/visualization
cooler info	Display a cooler’s info and metadata.
cooler dump	Dump a cooler’s data to a text stream.
cooler show	Display and browse a cooler with matplotlib.

File manipulation/info
cooler tree	Display a file’s data hierarchy.
cooler attrs	Display a file’s attribute hierarchy.
cooler ls	List all coolers inside a file.
cooler cp	Copy a cooler from one file to another or within the same file.
cooler mv	Rename a cooler within the same file.
cooler ln	Create a hard, soft or external link to a cooler.

Helper commands
cooler makebins	Generate fixed-width genomic bins.
cooler digest	Generate fragment-delimited genomic bins.
cooler csort	Sort and index a contact list.

Options

-v, --verbose: Verbose logging.

-d, --debug: On error, drop into the post-mortem debugger shell.

-V, --version: Show the version and exit.

See the cooler_cli.ipynb Jupyter Notebook for specific examples on usage: (https://github.com/open2c/cooler-binder).

cooler cload

Create a cooler from genomic pairs and bins.

Choose a subcommand based on the format of the input contact list.

cooler cload [OPTIONS] COMMAND [ARGS]...

Commands

hiclib

pairix

pairs

tabix

cooler cload pairs

Bin any text file or stream of pairs.

Pairs data need not be sorted. Accepts compressed files. To pipe input from stdin, set PAIRS_PATH to ‘-‘.

BINS : One of the following

<TEXT:INTEGER> : 1. Path to a chromsizes file, 2. Bin size in bp

<TEXT> : Path to BED file defining the genomic bin segmentation.

PAIRS_PATH : Path to contacts (i.e. read pairs) file.

COOL_PATH : Output COOL file path or URI.

cooler cload pairs [OPTIONS] BINS PAIRS_PATH COOL_PATH

Arguments

BINS: Required argument

PAIRS_PATH: Required argument

COOL_PATH: Required argument

Options

--metadata <metadata>: Path to JSON file containing user metadata.

--assembly <assembly>: Name of genome assembly (e.g. hg19, mm10)

-c1, --chrom1 <chrom1>: chrom1 field number (one-based) [required]

-p1, --pos1 <pos1>: pos1 field number (one-based) [required]

-c2, --chrom2 <chrom2>: chrom2 field number (one-based) [required]

-p2, --pos2 <pos2>: pos2 field number (one-based) [required]

--chunksize <chunksize>: Number of input lines to load at a time

-0, --zero-based: Positions are zero-based [default: False]

--comment-char <comment_char>: Comment character that indicates lines to ignore. [default: #]

-N, --no-symmetric-upper: Create a complete square matrix without implicit symmetry. This allows for distinct upper- and lower-triangle values

--input-copy-status <input_copy_status>: Copy status of input data when using symmetric-upper storage. | unique: Incoming data comes from a unique half of a symmetric map, regardless of how the coordinates of a pair are ordered. duplex: Incoming data contains upper- and lower-triangle duplicates. All input records that map to the lower triangle will be discarded! | If you wish to treat lower- and upper-triangle input data as distinct, use the --no-symmetric-upper option. [default: unique]

--field <field>: Specify quantitative input fields to aggregate into value columns using the syntax --field <field-name>=<field-number>. Optionally, append : followed by dtype=<dtype> to specify the data type (e.g. float), and/or agg=<agg> to specify an aggregation function different from sum (e.g. mean). Field numbers are 1-based. Passing ‘count’ as the target name will override the default behavior of storing pair counts. Repeat the --field option for each additional field.

--temp-dir <temp_dir>: Create temporary files in a specified directory. Pass - to use the platform default temp dir.

--no-delete-temp: Do not delete temporary files when finished.

--max-merge <max_merge>: Maximum number of chunks to merge before invoking recursive merging [default: 200]

--storage-options <storage_options>: Options to modify the data filter pipeline. Provide as a comma-separated list of key-value pairs of the form ‘k1=v1,k2=v2,…’. See http://docs.h5py.org/en/stable/high/dataset.html#filter-pipeline for more details.

-a, --append: Pass this flag to append the output cooler to an existing file instead of overwriting the file.

cooler cload pairix

Bin a pairix-indexed contact list file.

BINS : One of the following

<TEXT:INTEGER> : 1. Path to a chromsizes file, 2. Bin size in bp

<TEXT> : Path to BED file defining the genomic bin segmentation.

PAIRS_PATH : Path to contacts (i.e. read pairs) file.

COOL_PATH : Output COOL file path or URI.

See also: ‘cooler csort’ to sort and index a contact list file

Pairix on GitHub: <https://github.com/4dn-dcic/pairix>.

cooler cload pairix [OPTIONS] BINS PAIRS_PATH COOL_PATH

Arguments

BINS: Required argument

PAIRS_PATH: Required argument

COOL_PATH: Required argument

Options

--metadata <metadata>: Path to JSON file containing user metadata.

--assembly <assembly>: Name of genome assembly (e.g. hg19, mm10)

-p, --nproc <nproc>: Number of processes to split the work between. [default: 8]

-0, --zero-based: Positions are zero-based [default: False]

-s, --max-split <max_split>: Divide the pairs from each chromosome into at most this many chunks. Smaller chromosomes will be split less frequently or not at all. Increase ths value if large chromosomes dominate the workload on multiple processors. [default: 2]

cooler cload tabix

Bin a tabix-indexed contact list file.

BINS : One of the following

<TEXT:INTEGER> : 1. Path to a chromsizes file, 2. Bin size in bp

<TEXT> : Path to BED file defining the genomic bin segmentation.

PAIRS_PATH : Path to contacts (i.e. read pairs) file.

COOL_PATH : Output COOL file path or URI.

See also: ‘cooler csort’ to sort and index a contact list file

Tabix manpage: <http://www.htslib.org/doc/tabix.html>.

cooler cload tabix [OPTIONS] BINS PAIRS_PATH COOL_PATH

Arguments

BINS: Required argument

PAIRS_PATH: Required argument

COOL_PATH: Required argument

Options

--metadata <metadata>: Path to JSON file containing user metadata.

--assembly <assembly>: Name of genome assembly (e.g. hg19, mm10)

-p, --nproc <nproc>: Number of processes to split the work between. [default: 8]

-c2, --chrom2 <chrom2>: chrom2 field number (one-based)

-p2, --pos2 <pos2>: pos2 field number (one-based)

-0, --zero-based: Positions are zero-based [default: False]

-s, --max-split <max_split>: Divide the pairs from each chromosome into at most this many chunks. Smaller chromosomes will be split less frequently or not at all. Increase ths value if large chromosomes dominate the workload on multiple processors. [default: 2]

cooler cload hiclib

Bin a hiclib HDF5 contact list (frag) file.

BINS : One of the following

<TEXT:INTEGER> : 1. Path to a chromsizes file, 2. Bin size in bp

<TEXT> : Path to BED file defining the genomic bin segmentation.

PAIRS_PATH : Path to contacts (i.e. read pairs) file.

COOL_PATH : Output COOL file path or URI.

hiclib on BitBucket: <https://github.com/mirnylab/hiclib-legacy>.

cooler cload hiclib [OPTIONS] BINS PAIRS_PATH COOL_PATH

Arguments

BINS: Required argument

PAIRS_PATH: Required argument

COOL_PATH: Required argument

Options

--metadata <metadata>: Path to JSON file containing user metadata.

--assembly <assembly>: Name of genome assembly (e.g. hg19, mm10)

-c, --chunksize <chunksize>: Control the number of pixels handled by each worker process at a time. [default: 100000000]

cooler load

Create a cooler from a pre-binned matrix.

BINS_PATH : One of the following

<TEXT:INTEGER> : 1. Path to a chromsizes file, 2. Bin size in bp

<TEXT> : Path to BED file defining the genomic bin segmentation.

PIXELS_PATH : Text file containing nonzero pixel values. May be gzipped. Pass ‘-’ to use stdin.

COOL_PATH : Output COOL file path or URI.

Notes

Two input format options (tab-delimited). Input pixel file may be compressed.

COO: COO-rdinate sparse matrix format (a.k.a. ijv triple). 3 columns: “bin1_id, bin2_id, count”,

BG2: 2D version of the bedGraph format. 7 columns: “chrom1, start1, end1, chrom2, start2, end2, count”

Examples

cooler load -f bg2 <chrom.sizes>:<binsize> in.bg2.gz out.cool

cooler load [OPTIONS] BINS_PATH PIXELS_PATH COOL_PATH

Arguments

BINS_PATH: Required argument

PIXELS_PATH: Required argument

COOL_PATH: Required argument

Options

-f, --format <format>: ‘coo’ refers to a tab-delimited sparse triplet file (bin1, bin2, count). ‘bg2’ refers to a 2D bedGraph-like file (chrom1, start1, end1, chrom2, start2, end2, count). [required]

--metadata <metadata>: Path to JSON file containing user metadata.

--assembly <assembly>: Name of genome assembly (e.g. hg19, mm10)

--field <field>: Add supplemental value fields or override default field numbers for the specified format. Specify quantitative input fields to aggregate into value columns using the syntax --field <field-name>=<field-number>. Optionally, append : followed by dtype=<dtype> to specify the data type (e.g. float). Field numbers are 1-based. Repeat the --field option for each additional field.

-c, --chunksize <chunksize>: Size (in number of lines/records) of data chunks to read and process from the input file at a time. These chunks will be saved as temporary partial Coolers and merged at the end. Also specifies the size of the buffer during the merge step.

--count-as-float: Store the ‘count’ column as floating point values instead of as integers. Can also be specified using the –field option.

--one-based: Pass this flag if the bin IDs listed in a COO file are one-based instead of zero-based.

--comment-char <comment_char>: Comment character that indicates lines to ignore. [default: #]

-N, --no-symmetric-upper: Create a complete square matrix without implicit symmetry. This allows for distinct upper- and lower-triangle values

--input-copy-status <input_copy_status>: Copy status of input data when using symmetric-upper storage. | unique: Incoming data comes from a unique half of a symmetric matrix, regardless of how element coordinates are ordered. Execution will be aborted if duplicates are detected. duplex: Incoming data contains upper- and lower-triangle duplicates. All lower-triangle input elements will be discarded! | If you wish to treat lower- and upper-triangle input data as distinct, use the --no-symmetric-upper option instead. [default: unique]

--temp-dir <temp_dir>: Create temporary files in a specified directory. Pass - to use the platform default temp dir.

--no-delete-temp: Do not delete temporary files when finished.

--storage-options <storage_options>: Options to modify the data filter pipeline. Provide as a comma-separated list of key-value pairs of the form ‘k1=v1,k2=v2,…’. See http://docs.h5py.org/en/stable/high/dataset.html#filter-pipeline for more details.

-a, --append: Pass this flag to append the output cooler to an existing file instead of overwriting the file.

cooler merge

Merge multiple coolers with identical axes.

OUT_PATH : Output file path or URI.

IN_PATHS : Input file paths or URIs of coolers to merge.

Notes

Data columns merged:

pixels/bin1_id, pixels/bin2_id, pixels/<value columns>

Data columns preserved:

chroms/name, chroms/length bins/chrom, bins/start, bins/end

Additional columns in the the input files are not transferred to the output.

cooler merge [OPTIONS] OUT_PATH [IN_PATHS]...

Arguments

OUT_PATH: Required argument

IN_PATHS: Optional argument(s)

Options

-c, --chunksize <chunksize>: Size of the merge buffer in number of pixel table rows. [default: 20000000]

--field <field>: Specify the names of value columns to merge as ‘<name>’. Repeat the –field option for each one. Use ‘<name>,dtype=<dtype>’ to specify the dtype. Include ‘,agg=<agg>’ to specify an aggregation function different from ‘sum’.

-a, --append: Pass this flag to append the output cooler to an existing file instead of overwriting the file.

cooler coarsen

Coarsen a cooler to a lower resolution.

Works by pooling k-by-k neighborhoods of pixels and aggregating. Each chromosomal block is coarsened individually.

COOL_PATH : Path to a COOL file or Cooler URI.

cooler coarsen [OPTIONS] COOL_PATH

Arguments

COOL_PATH: Required argument

Options

-k, --factor <factor>: Gridding factor. The contact matrix is coarsegrained by grouping each chromosomal contact block into k-by-k element tiles [default: 2]

-n, -p, --nproc <nproc>: Number of processes to use for batch processing chunks of pixels [default: 1, i.e. no process pool]

-c, --chunksize <chunksize>: Number of pixels allocated to each process [default: 10000000]

--field <field>: Specify the names of value columns to merge as ‘<name>’. Repeat the –field option for each one. Use ‘<name>,dtype=<dtype>’ to specify the dtype. Include ‘,agg=<agg>’ to specify an aggregation function different from ‘sum’.

-o, --out <out>: Output file or URI [required]

-a, --append: Pass this flag to append the output cooler to an existing file instead of overwriting the file.

cooler zoomify

Generate a multi-resolution cooler file by coarsening.

COOL_PATH : Path to a COOL file or Cooler URI.

cooler zoomify [OPTIONS] COOL_PATH

Arguments

COOL_PATH: Required argument

Options

-n, -p, --nproc <nproc>: Number of processes to use for batch processing chunks of pixels [default: 1, i.e. no process pool]

-c, --chunksize <chunksize>: Number of pixels allocated to each process [default: 10000000]

-r, --resolutions <resolutions>: Comma-separated list of target resolutions. Use suffixes B or N to specify a progression: B for binary (geometric steps of factor 2), N for nice (geometric steps of factor 10 interleaved with steps of 2 and 5). Examples: 1000B=1000,2000,4000,8000,… 1000N=1000,2000,5000,10000,… 5000N=5000,10000,25000,50000,… 4DN is an alias for 1000,2000,5000N [default: B]

--balance: Apply balancing to each zoom level. Off by default.

--balance-args <balance_args>: Additional arguments to pass to cooler balance. To deal with space ambiguity, use quotes to pass multiple arguments, e.g. --balance-args '--nproc 8 --ignore-diags 3'. Note that nproc for balancing must be specified independently of zoomify arguments.

-i, --base-uri <base_uri>: One or more additional base coolers to aggregate from, if needed.

-o, --out <out>: Output file or URI

--field <field>: Specify the names of value columns to merge as ‘<name>’. Repeat the --field option for each one. Use ‘<name>:dtype=<dtype>’ to specify the dtype. Include ‘,agg=<agg>’ to specify an aggregation function different from ‘sum’.

--legacy: Use the legacy layout of integer-labeled zoom levels.

cooler balance

Out-of-core matrix balancing.

Matrix must be symmetric. See the help for various filtering options to mask out poorly mapped bins.

COOL_PATH : Path to a COOL file.

cooler balance [OPTIONS] COOL_PATH

Arguments

COOL_PATH: Required argument

Options

--cis-only: Calculate weights against intra-chromosomal data only instead of genome-wide.

--trans-only: Calculate weights against inter-chromosomal data only instead of genome-wide.

--ignore-diags <ignore_diags>: Number of diagonals of the contact matrix to ignore, including the main diagonal. Examples: 0 ignores nothing, 1 ignores the main diagonal, 2 ignores diagonals (-1, 0, 1), etc. [default: 2]

--ignore-dist <ignore_dist>: Distance from the diagonal in bp to ignore. The maximum of the corresponding number of diagonals and –ignore-diags will be used.

--mad-max <mad_max>: Ignore bins from the contact matrix using the ‘MAD-max’ filter: bins whose log marginal sum is less than mad-max median absolute deviations below the median log marginal sum of all the bins in the same chromosome. [default: 5]

--min-nnz <min_nnz>: Ignore bins from the contact matrix whose marginal number of nonzeros is less than this number. [default: 10]

--min-count <min_count>: Ignore bins from the contact matrix whose marginal count is less than this number. [default: 0]

--blacklist <blacklist>: Path to a 3-column BED file containing genomic regions to mask out during the balancing procedure, e.g. sequence gaps or regions of poor mappability.

-p, --nproc <nproc>: Number of processes to split the work between. [default: 8]

-c, --chunksize <chunksize>: Control the number of pixels handled by each worker process at a time. [default: 10000000]

--tol <tol>: Threshold value of variance of the marginals for the algorithm to converge. [default: 1e-05]

--max-iters <max_iters>: Maximum number of iterations to perform if convergence is not achieved. [default: 200]

--name <name>: Name of column to write to. [default: weight]

-f, --force: Overwrite the target dataset, ‘weight’, if it already exists.

--check: Check whether a data column ‘weight’ already exists.

--stdout: Print weight column to stdout instead of saving to file.

--convergence-policy <convergence_policy>: What to do with weights when balancing doesn’t converge in max_iters. ‘store_final’: Store the final result, regardless of whether the iterations converge to the specified tolerance; ‘store_nan’: Store a vector of NaN values to indicate that the matrix failed to converge; ‘discard’: Store nothing and exit gracefully; ‘error’: Abort with non-zero exit status. [default: store_final]

cooler info

Display a cooler’s info and metadata.

COOL_PATH : Path to a COOL file or cooler URI.

cooler info [OPTIONS] COOL_PATH

Arguments

COOL_PATH: Required argument

Options

-f, --field <field>: Print the value of a specific info field.

-m, --metadata: Print the user metadata in JSON format.

-o, --out <out>: Output file (defaults to stdout)

cooler dump

Dump a cooler’s data to a text stream.

COOL_PATH : Path to COOL file or cooler URI.

cooler dump [OPTIONS] COOL_PATH

Arguments

COOL_PATH: Required argument

Options

-t, --table <table>: Which table to dump. Choosing ‘chroms’ or ‘bins’ will cause all pixel-related options to be ignored. Note that for coolers stored in symmetric-upper mode, ‘pixels’ only holds the upper triangle values of the matrix. [default: pixels]

-c, --columns <columns>: Restrict output to a subset of columns, provided as a comma-separated list.

-H, --header: Print the header of column names as the first row. [default: False]

--na-rep <na_rep>: Missing data representation. Default is empty ‘’.

--float-format <float_format>: Format string for floating point numbers (e.g. ‘.12g’, ‘03.2f’). [default: g]

-r, --range <range>: The coordinates of a genomic region shown along the row dimension, in UCSC-style notation. (Example: chr1:10,000,000-11,000,000). If omitted, the entire contact matrix is printed.

-r2, --range2 <range2>: The coordinates of a genomic region shown along the column dimension. If omitted, the column range is the same as the row range.

-f, --fill-lower: For coolers using ‘symmetric-upper’ storage, populate implicit areas of the genomic query box by generating lower triangle pixels. If not specified, only upper triangle pixels are reported. This option has no effect on coolers stored in ‘square’ mode. [default: False]

-b, --balanced, --no-balance: Apply balancing weights to data. This will print an extra column called balanced [default: False]

--join: Print the full chromosome bin coordinates instead of bin IDs. This will replace the bin1_id column with chrom1, start1, and end1, and the bin2_id column with chrom2, start2 and end2. [default: False]

--annotate <annotate>: Join additional columns from the bin table against the pixels. Provide a comma separated list of column names (no spaces). The merged columns will be suffixed by ‘1’ and ‘2’ accordingly.

--one-based-ids: Print bin IDs as one-based rather than zero-based.

--one-based-starts: Print start coordinates as one-based rather than zero-based.

-k, --chunksize <chunksize>: Sets the number of pixel records loaded from disk at one time. Can affect the performance of joins on high resolution datasets. [default: 1000000]

-o, --out <out>: Output text file If .gz extension is detected, file is written using zlib. Default behavior is to stream to stdout.

cooler show

Display and browse a cooler in matplotlib.

COOL_PATH : Path to a COOL file or Cooler URI.

RANGE : The coordinates of the genomic region to display, in UCSC notation. Example: chr1:10,000,000-11,000,000

cooler show [OPTIONS] COOL_PATH RANGE

Arguments

COOL_PATH: Required argument

RANGE: Required argument

Options

-r2, --range2 <range2>: The coordinates of a genomic region shown along the column dimension. If omitted, the column range is the same as the row range. Use to display asymmetric matrices or trans interactions.

-b, --balanced: Show the balanced contact matrix. If not provided, display the unbalanced counts.

-o, --out <out>: Save the image of the contact matrix to a file. If not specified, the matrix is displayed in an interactive window. The figure format is deduced from the extension of the file, the supported formats are png, jpg, svg, pdf, ps and eps.

--dpi <dpi>: The DPI of the figure, if saving to a file

-s, --scale <scale>: Scale transformation of the colormap: linear, log2 or log10. Default is log10.

-f, --force: Force display very large matrices (>=10^8 pixels). Use at your own risk as it may cause performance issues.

--zmin <zmin>: The minimal value of the color scale. Units must match those of the colormap scale. To provide a negative value use a equal sign and quotes, e.g. -zmin=’-0.5’

--zmax <zmax>: The maximal value of the color scale. Units must match those of the colormap scale. To provide a negative value use a equal sign and quotes, e.g. -zmax=’-0.5’

--cmap <cmap>: The colormap used to display the contact matrix. See the full list at http://matplotlib.org/examples/color/colormaps_reference.html

--field <field>: Pixel values to display. [default: count]

cooler tree

Display a file’s data hierarchy.

cooler tree [OPTIONS] URI

Arguments

URI: Required argument

Options

-L, --level <level>

cooler attrs

Display a file’s attribute hierarchy.

cooler attrs [OPTIONS] URI

Arguments

URI: Required argument

Options

-L, --level <level>

cooler ls

List all coolers inside a file.

cooler ls [OPTIONS] COOL_PATH

Arguments

COOL_PATH: Required argument

Options

-l, --long: Long listing format

cooler cp

Copy a cooler from one file to another or within the same file.

See also: h5copy, h5repack tools from HDF5 suite.

cooler cp [OPTIONS] SRC_URI DST_URI

Arguments

SRC_URI: Required argument

DST_URI: Required argument

Options

-w, --overwrite: Truncate and replace destination file if it already exists.

cooler mv

Rename a cooler within the same file.

cooler mv [OPTIONS] SRC_URI DST_URI

Arguments

SRC_URI: Required argument

DST_URI: Required argument

Options

-w, --overwrite: Truncate and replace destination file if it already exists.

cooler ln

Create a hard link to a cooler (rather than a true copy) in the same file. Also supports soft links (in the same file) or external links (different files).

cooler ln [OPTIONS] SRC_URI DST_URI

Arguments

SRC_URI: Required argument

DST_URI: Required argument

Options

-w, --overwrite: Truncate and replace destination file if it already exists.

-s, --soft: Creates a soft link rather than a hard link if the source and destination file are the same. Otherwise, creates an external link. This type of link uses a path rather than a pointer.

cooler makebins

Generate fixed-width genomic bins.

Output a genome segmentation at a fixed resolution as a BED file.

CHROMSIZES_PATH : UCSC-like chromsizes file, with chromosomes in desired order.

BINSIZE : Resolution (bin size) in base pairs <int>.

cooler makebins [OPTIONS] CHROMSIZES_PATH BINSIZE

Arguments

CHROMSIZES_PATH: Required argument

BINSIZE: Required argument

Options

-o, --out <out>: Output file (defaults to stdout)

-H, --header: Print the header of column names as the first row. [default: False]

-i, --rel-ids <rel_ids>: Include a column of relative bin IDs for each chromosome. Choose whether to report them as 0- or 1-based.

cooler digest

Generate fragment-delimited genomic bins.

Output a genome segmentation of restriction fragments as a BED file.

CHROMSIZES_PATH : UCSC-like chromsizes file, with chromosomes in desired order.

FASTA_PATH : Genome assembly FASTA file or folder containing FASTA files (uncompressed).

ENZYME : Name of restriction enzyme

cooler digest [OPTIONS] CHROMSIZES_PATH FASTA_PATH ENZYME

Arguments

CHROMSIZES_PATH: Required argument

FASTA_PATH: Required argument

ENZYME: Required argument

Options

-o, --out <out>: Output file (defaults to stdout)

-H, --header: Print the header of column names as the first row. [default: False]

-i, --rel-ids <rel_ids>: Include a column of relative bin IDs for each chromosome. Choose whether to report them as 0- or 1-based.

cooler csort

Sort and index a contact list.

Order the mates of each pair record so that all contacts are upper triangular with respect to the chromosome ordering given by the chromosomes file, sort contacts by genomic location, and index the resulting file.

PAIRS_PATH : Contacts (i.e. read pairs) text file, optionally compressed.

CHROMOSOMES_PATH : File listing desired chromosomes in the desired order. May be tab-delimited, e.g. a UCSC-style chromsizes file. Contacts mapping to other chromosomes will be discarded.

Notes

csort can also be used to sort and index a text representation of a contact matrix in bedGraph-like format. In this case, substitute pos1 and pos2 with start1 and start2, respectively.

Requires Unix tools: sort, bgzip + tabix or pairix.

If indexing with Tabix, the output file will have the following properties:

Upper triangular: the read pairs on each row are assigned to side 1 or 2 in such a way that (chrom1, pos1) is always “less than” (chrom2, pos2)

Rows are lexicographically sorted by chrom1, pos1, chrom2, pos2; i.e. “positionally sorted”

Compressed with bgzip [*]

Indexed using Tabix [*] on chrom1 and pos1.

If indexing with Pairix, the output file will have the following properties:

Upper triangular: the read pairs on each row are assigned to side 1 or 2 in such a way that (chrom1, pos1) is always “less than” (chrom2, pos2)

Rows are lexicographically sorted by chrom1, chrom2, pos1, pos2; i.e. “block sorted”

Compressed with bgzip [*]

Indexed using Pairix [+] on chrom1, chrom2 and pos1.

[*] Tabix manpage: <http://www.htslib.org/doc/tabix.html>. [+] Pairix on Github: <https://github.com/4dn-dcic/pairix>

cooler csort [OPTIONS] PAIRS_PATH CHROMOSOMES_PATH

Arguments

PAIRS_PATH: Required argument

CHROMOSOMES_PATH: Required argument

Options

-c1, --chrom1 <chrom1>: chrom1 field number in the input file (starting from 1) [required]

-c2, --chrom2 <chrom2>: chrom2 field number [required]

-p1, --pos1 <pos1>: pos1 field number [required]

-p2, --pos2 <pos2>: pos2 field number [required]

-i, --index <index>: Select the preset sort and indexing options [default: pairix]

--flip-only: Only flip mates; no sorting or indexing. Write to stdout. [default: False]

-p, --nproc <nproc>: Number of processors [default: 8]

-0, --zero-based: Read positions are zero-based [default: False]

--sep <sep>: Data delimiter in the input file [default: t]

--comment-char <comment_char>: Comment character to skip header [default: #]

--sort-options <sort_options>: Quoted list of additional options to sort command

-o, --out <out>: Output gzip file

-s1, --strand1 <strand1>: strand1 field number (deprecated)

-s2, --strand2 <strand2>: strand2 field number (deprecated)