Quickstart with the FAN-C API

After you have installed FAN-C (see Installation), you can import the module from a Python console or script:

import fanc

The following tutorials will assume that you have loaded the fanc module in this manner.

Loading datasets

Any analysis typically begins with loading datasets into your workspace. FAN-C tries to make this as simple as possible with the load() function. If you already have processed Hi-C files, either from the fanc command line application (see Generating Hi-C matrices with fanc or Individual pipeline steps), or from a compatible Hi-C application (.cool or .mcool from Cooler or .hic from Juicer), simply load them into your workspace using load() - no need to specify the type of file you are loading:

data = fanc.load("/path/to/file.hic")

When dealing with multi-resolution Hi-C files such as .mcool from Cooler or .hic from Juicer, you can load a specific resolution using the @ notation:

data = fanc.load("/path/to/file.mcool@25000")

load() is not limited to Hi-C files, but also works on any other file produced with FAN-C, such as RegionPairs files, Genome, analysis results like FoldChangeMatrix and generally most other FAN-C files.

load() even works on most of the common file formats for genomic datasets, such as BED, GFF, BigWig, Tabix, BEDPE and more. Try it out on your dataset of choice and chances are load() can handle it. And if it does not, consider raising an issue on Github to ask for support.

Internally, load() finds a suitable class for the type of data in the supplied file, and opens the file using that class. For example, the result of

hic = fanc.Hic("output/hic/binned/fanc_example_1mb.hic")

is equivalent to

hic = fanc.load("output/hic/binned/fanc_example_1mb.hic")

with the big advantage that you don’t need to worry about remembering class names or their location within the FAN-C module hierarchy. In both cases, the type of the returned object is fanc.hic.Hic:

# check the type fo the object
type(hic)  # fanc.hic.Hic

Here are a few more examples:

cool = fanc.load("test.cool")
type(cool)  # fanc.compatibility.cooler.CoolerHic

juicer = fanc.load("test_juicer.hic")
type(juicer)  # fanc.compatibility.juicer.JuicerHic

fragments = fanc.load("hg19_chr18_19_re_fragments.bed")
type(fragments)  # genomic_regions.regions.Bed

bam = fanc.load("test.bam")
type(bam)  # pysam.libcalignmentfile.AlignmentFile

ins = fanc.load("architecture/domains/fanc_example_100kb.insulation")
type(ins)  # fanc.architecture.domains.InsulationScores

# and many other data types

The next section will discuss Common interfaces that make working with genomic data in general and FAN-C objects specifically straightforward and simple.

Logging

FAN-C uses the logging module. In a python session, use a statement like

import logging
logging.basicConfig(level=logging.INFO,
                    format='%(asctime)s %(message)s')

to enable basic console logging. Have a look the logging documentation for more information on log levels and handlers.