Generate, bin, filter, and correct Hic objects — FAN-C 0.9.1-beta documentation

# Generate, bin, filter, and correct Hic objects

After we have obtained a filtered `ReadPairs` object, we can easily convert it into a `Hic` matrix.

    hic_folder = mkdir(os.path.join(output_folder, 'hic'))
    hic_file = os.path.join(hic_folder, 'example.hic')
    hic = pairs.to_hic(file_name=hic_file)

Note that this only uses valid pairs for Hi-C object creation and creates fragment-level Hi-C matrix, using the same fragment definitions as in the original `ReadPairs` object.

Note

If you have multiple Hi-C objects for the same sample, for example from different replicates or sequencing runs, we recommend merging them at this stage:

    from fanc.hic import Hic
    merged_hic = Hic.merge([hic_rep1, hic_rep2]])

The fragment-level Hi-C objects can very easily be binned:

    binned_hic = hic.bin(1000000,
                         file_name=os.path.join(hic_folder, 'binned_1mb.hic'),
                         threads=4)

Just like `ReadPairs`, `Hic` can also be filtered. Currently, the two available filters are `LowCoverageFilter` and `DiagonalFilter`:

    from fanc.hic import LowCoverageFilter
    lc_filter = LowCoverageFilter(binned_hic, rel_cutoff=0.2)
    binned_hic.filter(lc_filter)
    binned_hic.run_queued_filters()

- `LowCoverageFilter` removes all Hi-C “edges” (pixels) in regions that have low coverage. The cutoff can either be expressed in absolute numbers of pairs (`cutoff`) or as a fraction of the median coverage of all regions (`rel_cutoff`). We highly recommend filtering for low coverage before matrix balancing

- `DiagonalFilter` removes all edges at the diagonal. Some researcher have achieved better normalisation results by setting the matrix diagonal to 0 before normalisation.

Finally, we can normalise the matrix using matrix balancing. You have the choice of either Knight-Ruiz matrix balancing (KR, `kr_balancing`) or iterative correction (ICE, `ice_balancing`). KR balancing is typically faster, but also consumes a lot more memory, especially for high matrix resolutions. ICE is slow, and might not always converge to a solution, but is much more memory efficient in its implementation.

    from fanc.hic import kr_balancing
    kr_balancing(binned_hic, whole_matrix=False,
                 restore_coverage=False)

With KR balancing, you can choose to restore the original valid pairs count using `restore_coverage=True`. If this is set to `False`, edge weights represent ligation probabilities rather than counts. If you set `whole_matrix=True`, the balancing will be done on the whole genome matrix. The default is to do it on a per-chromosome basis.

The bias vector will be stored in the matrix, and is automatically applied when querying the object.