Expected and O/E calculations — FAN-C 0.9.1-beta documentation

# Expected and O/E calculations

The following steps assume that you ran the `fanc auto` command in Example analysis. Additionally, we set up the Python session like this:

    import fanc
    import matplotlib.pyplot as plt
    import fanc.plotting as fancplot

    hic_500kb = fanc.load("output/hic/binned/fanc_example_500kb.hic")

If you want to try the tutorial with an equivalent Cooler file, load the Hi-C file like this instead:

    hic_500kb = fanc.load("architecture/other-hic/fanc_example.mcool@500kb")

or like this if you want to work with a Juicer file built from the same data:

    hic_500kb = fanc.load("architecture/other-hic/fanc_example.juicer.hic@500kb")

Note that there may be minor differences in the results due to the “zooming” and balancing applied by the different tools.

`RegionMatrixContainer` objects (see here) have a builtin function to calculate expected values from existing matrix data called `expected_values()`. This function calculates and returns intra-chromosomal, intra-chromosomal per chromosome, and inter-chromosomal expected values.

    intra_expected, intra_expected_chromosome, inter_expected = hic_500kb.expected_values()

Here, `intra_expected` is a list of average (/expected) contact values, where the position of the value in the list corresponds to the separation between genomic regions in bins. `intra_expected_chromosome` is a dictionary with chromosome names as keys, and an expected value list as value calculated on a per-chromosome basis. `inter_expected` is a single, average inter-chromosomal contact value.

The expected values are typically plotted on a log-log scale, as illustrated here using chromosome 19:

    # obtain bin distances
    bin_size = hic_500kb.bin_size
    distance = list(range(0, bin_size * len(intra_expected_chromosome['chr19']), bin_size))

    # plot expected values
    fig, ax = plt.subplots()
    plt.plot(distance, intra_expected_chromosome['chr19'])
    ax.set_xscale('log')
    ax.set_yscale('log')
    ax.set_xlabel("Distance")
    ax.set_ylabel("Average contacts")
    plt.show()

FAN-C also has a built-in function for plotting the expected values, `distance_decay_plot()`. Additional named arguments are passed on to `ax.plot`, for example to change the line color. The function returns a `matplotlib` axes object, which can then be further customised:

    ax = fancplot.distance_decay_plot(hic_500kb, chromosome='chr18', color='mediumturquoise')

To compare the expected values of multiple samples, just provide multiple Hic objects:

    lowc_hindiii = fanc.load("architecture/other-hic-update/lowc_hindiii_100k_1mb.hic")
    lowc_mboi = fanc.load("architecture/other-hic-update/lowc_mboi_100k_1mb.hic")
    ax = fancplot.distance_decay_plot(lowc_hindiii, lowc_mboi, chromosome='chr1',
                                      labels=['HindIII', 'MboI'])

Note: as Hi-C matrices are normalised on a per-chromosome basis in FAN-C by default, it would be misleading to plot the overall normalised intra-chromosomal expected values, or to use them for downstream analysis. We can, however, also calculate the unnormalised expected values easily enough.

    intra_expected_nonorm, intra_expected_chromosome_nonorm, inter_expected_nonorm = hic_500kb.expected_values(norm=False)

    # obtain bin distances
    bin_size = hic_500kb.bin_size
    distance = list(range(0, bin_size * len(intra_expected_nonorm), bin_size))

    # plot expected values
    fig, ax = plt.subplots()
    plt.plot(distance, intra_expected_nonorm)
    ax.set_xscale('log')
    ax.set_yscale('log')
    ax.set_xlabel("Distance")
    ax.set_ylabel("Average contacts (not normalised)")
    plt.show()

If you are simply interested in plotting the unnormalised values, you can use

    ax = fancplot.distance_decay_plot(hic_500kb, norm=False)

Expected values rarely need to be calculated explicitly in FAN-C analysis functions, but will be calculated (or retrieved) on demand whenever necessary. To obtain observed/expected matrices, for example, please refer to RegionMatrixContainer.