CLI Reference — cooler 0.10.3 documentation (original) (raw)
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
: 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
Path to JSON file containing user metadata.
--assembly
Name of genome assembly (e.g. hg19, mm10)
-c1, --chrom1
chrom1 field number (one-based) [required]
-p1, --pos1
pos1 field number (one-based) [required]
-c2, --chrom2
chrom2 field number (one-based) [required]
-p2, --pos2
pos2 field number (one-based) [required]
--chunksize
Number of input lines to load at a time
-0, --zero-based
Positions are zero-based [default: False]
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
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
: 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
Path to JSON file containing user metadata.
--assembly
Name of genome assembly (e.g. hg19, mm10)
-p, --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
: 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
Path to JSON file containing user metadata.
--assembly
Name of genome assembly (e.g. hg19, mm10)
-p, --nproc
Number of processes to split the work between. [default: 8]
-c2, --chrom2
chrom2 field number (one-based)
-p2, --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
: 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
Path to JSON file containing user metadata.
--assembly
Name of genome assembly (e.g. hg19, mm10)
-c, --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
: 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>: 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
‘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
Path to JSON file containing user metadata.
--assembly
Name of genome assembly (e.g. hg19, mm10)
--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
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 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/
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
Size of the merge buffer in number of pixel table rows. [default: 20000000]
--field
Specify the names of value columns to merge as ‘’. Repeat the –field option for each one. Use ‘,dtype=’ to specify the dtype. Include ‘,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
Gridding factor. The contact matrix is coarsegrained by grouping each chromosomal contact block into k-by-k element tiles [default: 2]
-n, -p, --nproc
Number of processes to use for batch processing chunks of pixels [default: 1, i.e. no process pool]
-c, --chunksize
Number of pixels allocated to each process [default: 10000000]
--field
Specify the names of value columns to merge as ‘’. Repeat the –field option for each one. Use ‘,dtype=’ to specify the dtype. Include ‘,agg=’ to specify an aggregation function different from ‘sum’.
-o, --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
Number of processes to use for batch processing chunks of pixels [default: 1, i.e. no process pool]
-c, --chunksize
Number of pixels allocated to each process [default: 10000000]
-r, --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
Output file or URI
--field
Specify the names of value columns to merge as ‘’. Repeat the --field option for each one. Use ‘:dtype=’ to specify the dtype. Include ‘,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
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
Number of processes to split the work between. [default: 8]
-c, --chunksize
Control the number of pixels handled by each worker process at a time. [default: 10000000]
--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 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
Print the value of a specific info field.
-m, --metadata
Print the user metadata in JSON format.
-o, --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