Printing a binning file with binning_tool_view

binning_tool_view prints the /tracks, /bins and /values tables of a binning_tool HDF5 file as tab-separated text on stdout. It reads only files with tracks_layout = 2. For any other file it prints the error of gain.binning.h5_reader.read_tracks() on stderr and exits with code 2. Every error the tool detects after parsing its arguments is one line on stderr, with exit code 2, and no traceback. A mistake in the arguments themselves, such as an unknown option or a missing file, prints the argparse usage message and an error line, then exits with code 2.

binning_tool_view run.h5 --tracks
binning_tool_view run.h5 --bins --matrix --region chr21:1-5_000_000
binning_tool_view run.h5 --matrix --track hg38/phyloP100way:mean --no-header

Tables

Choose at least one of --tracks, --bins and --matrix. With none of them the tool stops with an error that names the three options.

--tracks

One row per track. The first column is the track label, then come the columns of /tracks. The table has its own axis, so --tracks with --bins or --matrix is an error.

--bins

One row per bin, with the columns chrom, start and end.

--matrix

The values of /values: one row per bin, one column per track. --matrix alone prints the values only, row for row with --bins.

--bins --matrix

One joined table: the bin coordinates, then one column per track.

binning_tool_view run.h5 --bins --matrix

chrom   start   end     frags/*:B:sum   scores/one:max
chr1    1       10      2.0             1.0
chr1    11      20      0.0             1.0
chr2    1       10      1.0             nan

Selecting bins

--region REGION

Print only the bins that overlap a region. The option is repeatable and takes --bins or --matrix. The forms are chrom, chrom:start and chrom:start-end, with 1-based inclusive coordinates. chrom selects the whole chromosome. chrom:start runs to the end of the chromosome, as in samtools. Underscores and commas in a coordinate are allowed, for example chr1:1-5_000_000. The bins are not clipped: a region that touches part of a bin selects the whole bin. A bin that shares no base with the region is not selected. With several regions the tool prints the union, each bin once, in file order. A chromosome that is not in /bins is an error, and so is a start above the end.

binning_tool_view run.h5 --bins --region chr2 --region chr1:21-30

Selecting tracks

--track LABEL

Print only the track with this exact label. The option is repeatable and takes --matrix or --tracks. The columns come out in file order, not in option order. A label that matches no track, or more than one track, is an error that names the label.

binning_tool_view run.h5 --tracks --track hg38/phyloP100way:mean

Values

The tool prints a value as Python float text, so the text is lossless: 0.1, 1.0, 1e-300, inf. A missing value prints as nan. start and end print as integers. A tab or a newline inside a string value becomes a space.

The tool reads /values one block of rows at a time, and reads only the selected track columns of each block. The memory for the values stays flat for a large file. The memory for /bins and for the selected rows grows with the number of bins.

A closed pipe ends the tool without a message:

binning_tool_view run.h5 --matrix | head

Option reference

Print the /tracks, /bins and /values tables of a binning_tool HDF5 file as tab-separated text.

usage: binning_tool_view [-h] [--tracks] [--bins] [--matrix] [--region REGION]
                         [--track LABEL] [--header {label,index}]
                         [--no-header]
                         file

Positional Arguments

file

the HDF5 file written by binning_tool

Named Arguments

--tracks

print the /tracks table, one row per track

Default: False

--bins

print the /bins table: chrom, start and end of each bin

Default: False

--matrix

print the /values matrix, one column per track; with –bins, one joined table

Default: False

--region

print only the bins that overlap REGION: chrom, chrom:start or chrom:start-end, 1-based inclusive. Repeatable

Default: []

--track

print only the track with this exact label. Repeatable

Default: []

--header

Possible choices: label, index

head the matrix columns by track label (the default) or by track position

Default: 'label'

--no-header

do not print the header line

Default: False