Peaks module — FAN-C 0.9.1-beta documentation

# Peaks module

class `fanc.peaks.` `DistancePeakFilter`(cutoff=1, mask=None)

  Bases: `fanc.peaks.PeakFilter`

  Filter for peaks where regions are closer than this cutoff in bins.

  `valid`(row)

    Map valid_peak to MaskFilter.valid(self, row).

    Parameters

      row – A pytables Table row.

    Returns

      The boolean value returned by valid_edge.

  `valid_peak`(peak)

    Evaluate whether a peak passes FDR cutoffs set in __init__ :param peak: An `Edge` object :return: True if peak passes internal FDR cutoffs, False otherwise

class `fanc.peaks.` `EnrichmentPeakFilter`(enrichment_cutoff=None, enrichment_ll_cutoff=None, enrichment_h_cutoff=None, enrichment_v_cutoff=None, enrichment_d_cutoff=None, mask=None)

  Bases: `fanc.peaks.PeakFilter`

  Filter peaks that do not have a sufficiently strong observed/expected ratio.

  `valid`(row)

    Map valid_peak to MaskFilter.valid(self, row).

    Parameters

      row – A pytables Table row.

    Returns

      The boolean value returned by valid_edge.

  `valid_peak`(peak)

    Determine if a `RaoPeak` object is valid or should be filtered.

    When implementing custom PeakFilter this method must be overridden. It should return False for `RaoPeak` objects that are to be fitered and True otherwise.

    Internally, the `RaoPeakInfo` object will iterate over all RaoPeak instances to determine their validity on an individual basis.

    Parameters

      peak – A `RaoPeak` object

    Returns

      True if `PeakFilter` is valid, False otherwise

class `fanc.peaks.` `FdrPeakFilter`(mask=None, fdr_cutoff=None, fdr_ll_cutoff=None, fdr_v_cutoff=None, fdr_h_cutoff=None, fdr_d_cutoff=None)

  Bases: `fanc.peaks.PeakFilter`

  Filter for peaks that do not pass a certain FDR cutoff.

  `valid`(row)

    Map valid_peak to MaskFilter.valid(self, row).

    Parameters

      row – A pytables Table row.

    Returns

      The boolean value returned by valid_edge.

  `valid_peak`(peak)

    Evaluate whether a peak passes FDR cutoffs set in __init__ :param peak: An `Edge` object :return: True if peak passes interal FDR cutoffs, False otherwise

class `fanc.peaks.` `FdrSumFilter`(cutoff=1.0, mask=None)

  Bases: `fanc.peaks.PeakFilter`

  Remove peaks that have a q-value sum > cutoff.

  `valid`(row)

    Map valid_peak to MaskFilter.valid(self, row).

    Parameters

      row – A pytables Table row.

    Returns

      The boolean value returned by valid_edge.

  `valid_peak`(peak)

    Determine if a `RaoPeak` object is valid or should be filtered.

    When implementing custom PeakFilter this method must be overridden. It should return False for `RaoPeak` objects that are to be fitered and True otherwise.

    Internally, the `RaoPeakInfo` object will iterate over all RaoPeak instances to determine their validity on an individual basis.

    Parameters

      peak – A `RaoPeak` object

    Returns

      True if `PeakFilter` is valid, False otherwise

class `fanc.peaks.` `LazyPeak`(row, nodes_table, bin_size=1)

  Bases: `fanc.matrix.LazyEdge`

  Container for a Peak/enriched contact in a Hi-C matrix.

  This class implements `LazyPeak`, which provides lazy loading of attributes from a PyTables table row.

class `fanc.peaks.` `MappabilityPeakFilter`(mask=None, mappability_cutoff=None, mappability_ll_cutoff=None, mappability_v_cutoff=None, mappability_h_cutoff=None, mappability_d_cutoff=None)

  Bases: `fanc.peaks.PeakFilter`

  Filter for peaks that do not pass a certain FDR cutoff.

  `valid`(row)

    Map valid_peak to MaskFilter.valid(self, row).

    Parameters

      row – A pytables Table row.

    Returns

      The boolean value returned by valid_edge.

  `valid_peak`(peak)

    Evaluate whether a peak passes FDR cutoffs set in __init__ :param peak: An `Edge` object :return: True if peak passes interal FDR cutoffs, False otherwise

class `fanc.peaks.` `ObservedPeakFilter`(cutoff=1, mask=None)

  Bases: `fanc.peaks.PeakFilter`

  Filter for peaks that do not pass a certain FDR cutoff.

  `valid`(row)

    Map valid_peak to MaskFilter.valid(self, row).

    Parameters

      row – A pytables Table row.

    Returns

      The boolean value returned by valid_edge.

  `valid_peak`(peak)

    Evaluate whether a peak passes FDR cutoffs set in __init__ :param peak: An `Edge` object :return: True if peak passes interal FDR cutoffs, False otherwise

class `fanc.peaks.` `Peak`(source, sink, *args, **kwargs)

  Bases: `fanc.matrix.Edge`

  Container for a Peak/enriched contact in a Hi-C matrix.

class `fanc.peaks.` `PeakFilter`(mask=None)

  Bases: `fanc.general.MaskFilter`

  Abstract class that provides filtering functionality for the peaks in a `RaoPeakInfo` object.

  Extends MaskFilter and overrides valid(self, row) to make `RaoPeakInfo` filtering more “natural”.

  To create custom filters for the `RapPeakInfo` object, extend this class and override the valid_peak(self, peak) method. valid_peak should return False for a specific `Edge` object if the object is supposed to be filtered/masked and True otherwise. See `DiagonalFilter` for an example.

  Pass a custom filter to the `filter()` method in `Hic` to apply it.

  `valid`(row)

    Map valid_peak to MaskFilter.valid(self, row).

    Parameters

      row – A pytables Table row.

    Returns

      The boolean value returned by valid_edge.

  abstract `valid_peak`(peak)

    Determine if a `RaoPeak` object is valid or should be filtered.

    When implementing custom PeakFilter this method must be overridden. It should return False for `RaoPeak` objects that are to be fitered and True otherwise.

    Internally, the `RaoPeakInfo` object will iterate over all RaoPeak instances to determine their validity on an individual basis.

    Parameters

      peak – A `RaoPeak` object

    Returns

      True if `PeakFilter` is valid, False otherwise

class `fanc.peaks.` `PeakInfo`(file_name=None, mode='a', tmpdir=None, _table_name_regions='regions', _table_name_peaks='edges')

  Bases: `fanc.matrix.RegionMatrixTable`

  General-purpose class for recording peaks in Hic (and similar) data.

  A peak has the following information: source, sink: coordinates of the highest peak pixel in the Hi-C matrix observed: observed value of the peak in the Hi-C matrix, generally uncorrected expected: expected value of the peak at this position in the Hi-C matrix p_value: a P-value that reflects how likely it is to observe a peak with these properties at random x, y: coordinates of the peak centroid, if it is larger than one pixel radius: radius of the peak, expressed in bins (can be converted to base pairs)

  class `ChromosomeDescription`

    Bases: `tables.description.IsDescription`

    Description of the chromosomes in this object.

  class `MaskDescription`

    Bases: `tables.description.IsDescription`

  class `RegionDescription`

    Bases: `tables.description.IsDescription`

    Description of a genomic region for PyTables Table

  `add_contact`(contact, *args, **kwargs)

    Alias for `add_edge()`

    Parameters

      - contact – `Edge`

      - args – Positional arguments passed to `_add_edge()`

      - kwargs – Keyword arguments passed to `_add_edge()`

  `add_contacts`(contacts, *args, **kwargs)

    Alias for `add_edges()`

  `add_edge`(edge, check_nodes_exist=True, *args, **kwargs)

    Add an edge / contact between two regions to this object.

    Parameters

      - edge – `Edge`, dict with at least the attributes source and sink, optionally weight, or a list of length 2 (source, sink) or 3 (source, sink, weight).

      - check_nodes_exist – Make sure that there are nodes that match source and sink indexes

      - args – Positional arguments passed to `_add_edge()`

      - kwargs – Keyword arguments passed to `_add_edge()`

  `add_edge_from_dict`(edge, *args, **kwargs)

    Direct method to add an edge from dict input.

    Parameters

      edge – dict with at least the keys “source” and “sink”. Additional keys will be loaded as edge attributes

  `add_edge_from_edge`(edge, *args, **kwargs)

    Direct method to add an edge from `Edge` input.

    Parameters

      edge – `Edge`

  `add_edge_from_list`(edge, *args, **kwargs)

    Direct method to add an edge from list or tuple input.

    Parameters

      edge – List or tuple. Should be of length 2 (source, sink) or 3 (source, sink, weight)

  `add_edge_simple`(source, sink, weight=None, *args, **kwargs)

    Direct method to add an edge from `Edge` input.

    Parameters

      - source – Source region index

      - sink – Sink region index

      - weight – Weight of the edge

  `add_edges`(edges, flush=True, *args, **kwargs)

    Bulk-add edges from a list.

    List items can be any of the supported edge types, list, tuple, dict, or `Edge`. Repeatedly calls `add_edge()`, so may be inefficient for large amounts of data.

    Parameters

      edges – List (or iterator) of edges. See `add_edge()` for details

  `add_mask_description`(name, description)

    Add a mask description to the _mask table and return its ID.

    Parameters

      - name (str) – name of the mask

      - description (str) – description of the mask

    Returns

      id of the mask

    Return type

      int

  `add_region`(region, *args, **kwargs)

    Add a genomic region to this object.

    This method offers some flexibility in the types of objects that can be loaded. See parameters for details.

    Parameters

      region – Can be a `GenomicRegion`, a str in the form ‘<chromosome>:<start>-<end>[:<strand>], a dict with at least the fields ‘chromosome’, ‘start’, and ‘end’, optionally ‘ix’, or a list of length 3 (chromosome, start, end) or 4 (ix, chromosome, start, end).

  `add_regions`(regions, *args, **kwargs)

    Bulk insert multiple genomic regions.

    Parameters

      regions – List (or any iterator) with objects that describe a genomic region. See `add_region` for options.

  static `bin_intervals`(intervals, bins, interval_range=None, smoothing_window=None, nan_replacement=None, zero_to_nan=False)

    Bin a given set of intervals into a fixed number of bins.

    Parameters

      - intervals – iterator of tuples (start, end, score)

      - bins – Number of bins to divide the region into

      - interval_range – Optional. Tuple (start, end) in base pairs of range of interval to be binned. Useful if intervals argument does not cover to exact genomic range to be binned.

      - smoothing_window – Size of window (in bins) to smooth scores over

      - nan_replacement – NaN values in the scores will be replaced with this value

      - zero_to_nan – If True, will convert bins with score 0 to NaN

    Returns

      iterator of tuples: (start, end, score)

  static `bin_intervals_equidistant`(intervals, bin_size, interval_range=None, smoothing_window=None, nan_replacement=None, zero_to_nan=False)

    Bin a given set of intervals into bins with a fixed size.

    Parameters

      - intervals – iterator of tuples (start, end, score)

      - bin_size – Size of each bin in base pairs

      - interval_range – Optional. Tuple (start, end) in base pairs of range of interval to be binned. Useful if intervals argument does not cover to exact genomic range to be binned.

      - smoothing_window – Size of window (in bins) to smooth scores over

      - nan_replacement – NaN values in the scores will be replaced with this value

      - zero_to_nan – If True, will convert bins with score 0 to NaN

    Returns

      iterator of tuples: (start, end, score)

  property `bin_size`

    Return the length of the first region in the dataset.

    Assumes all bins have equal size.

    Returns

      int

  `binned_regions`(region=None, bins=None, bin_size=None, smoothing_window=None, nan_replacement=None, zero_to_nan=False, *args, **kwargs)

    Same as region_intervals, but returns `GenomicRegion` objects instead of tuples.

    Parameters

      - region – String or class:~GenomicRegion object denoting the region to be binned

      - bins – Number of bins to divide the region into

      - bin_size – Size of each bin (alternative to bins argument)

      - smoothing_window – Size of window (in bins) to smooth scores over

      - nan_replacement – NaN values in the scores will be replaced with this value

      - zero_to_nan – If True, will convert bins with score 0 to NaN

      - args – Arguments passed to _region_intervals

      - kwargs – Keyword arguments passed to _region_intervals

    Returns

      iterator of `GenomicRegion` objects

  `bins_to_distance`(bins)

    Convert fraction of bins to base pairs

    Parameters

      bins – float, fraction of bins

    Returns

      int, base pairs

  property `chromosome_bins`

    Returns a dictionary of chromosomes and the start and end index of the bins they cover.

    Returned list is range-compatible, i.e. chromosome bins [0,5] cover chromosomes 1, 2, 3, and 4, not 5.

  property `chromosome_lengths`

    Returns a dictionary of chromosomes and their length in bp.

  `chromosomes`()

    List all chromosomes in this regions table. :return: list of chromosome names.

  `close`(copy_tmp=True, remove_tmp=True)

    Close this HDF5 file and run exit operations.

    If file was opened with tmpdir in read-only mode: close file and delete temporary copy.

    If file was opened with tmpdir in write or append mode: Replace original file with copy and delete copy.

    Parameters

      - copy_tmp – If False, does not overwrite original with modified file.

      - remove_tmp – If False, does not delete temporary copy of file.

  `distance_to_bins`(distance)

    Convert base pairs to fraction of bins.

    Parameters

      distance – distance in base pairs

    Returns

      float, distance as fraction of bin size

  `downsample`(n, file_name=None)

    Sample edges from this object.

    Sampling is always done on uncorrected Hi-C matrices.

    Parameters

      - n – Sample size or reference object. If n < 1 will be interpreted as a fraction of total reads in this object.

      - file_name – Output file name for down-sampled object.

    Returns

      `RegionPairsTable`

  `edge_data`(attribute, *args, **kwargs)

    Iterate over specific edge attribute.

    Parameters

      - attribute – Name of the attribute, e.g. “weight”

      - args – Positional arguments passed to `edges()`

      - kwargs – Keyword arguments passed to `edges()`

    Returns

      iterator over edge attribute

  `edge_subset`(key=None, *args, **kwargs)

    Get a subset of edges.

    This is an alias for `edges()`.

    Returns

      generator (`Edge`)

  property `edges`

    Iterate over contacts / edges.

    `edges()` is the central function of `RegionPairsContainer`. Here, we will use the `Hic` implementation for demonstration purposes, but the usage is exactly the same for all compatible objects implementing `RegionPairsContainer`, including `JuicerHic` and `CoolerHic`.

        import fanc

        # file from FAN-C examples
        hic = fanc.load("output/hic/binned/fanc_example_1mb.hic")

    We can easily find the number of edges in the sample `Hic` object:

        len(hic.edges)  # 8695

    When used in an iterator context, `edges()` iterates over all edges in the `RegionPairsContainer`:

        for edge in hic.edges:
            # do something with edge
            print(edge)
            # 42--42; bias: 5.797788472650082e-05; sink_node: chr18:42000001-43000000; source_node: chr18:42000001-43000000; weight: 0.12291311562018173
            # 24--28; bias: 6.496381719803623e-05; sink_node: chr18:28000001-29000000; source_node: chr18:24000001-25000000; weight: 0.025205961072838057
            # 5--76; bias: 0.00010230955745211447; sink_node: chr18:76000001-77000000; source_node: chr18:5000001-6000000; weight: 0.00961709840049876
            # 66--68; bias: 8.248432587969082e-05; sink_node: chr18:68000001-69000000; source_node: chr18:66000001-67000000; weight: 0.03876763316345468
            # ...

    Calling `edges()` as a method has the same effect:

        # note the '()'
        for edge in hic.edges():
            # do something with edge
            print(edge)
            # 42--42; bias: 5.797788472650082e-05; sink_node: chr18:42000001-43000000; source_node: chr18:42000001-43000000; weight: 0.12291311562018173
            # 24--28; bias: 6.496381719803623e-05; sink_node: chr18:28000001-29000000; source_node: chr18:24000001-25000000; weight: 0.025205961072838057
            # 5--76; bias: 0.00010230955745211447; sink_node: chr18:76000001-77000000; source_node: chr18:5000001-6000000; weight: 0.00961709840049876
            # 66--68; bias: 8.248432587969082e-05; sink_node: chr18:68000001-69000000; source_node: chr18:66000001-67000000; weight: 0.03876763316345468
            # ...

    Rather than iterate over all edges in the object, we can select only a subset. If the key is a string or a `GenomicRegion`, all non-zero edges connecting the region described by the key to any other region are returned. If the key is a tuple of strings or `GenomicRegion`, only edges between the two regions are returned.

        # select all edges between chromosome 19
        # and any other region:
        for edge in hic.edges("chr19"):
            print(edge)
            # 49--106; bias: 0.00026372303696871666; sink_node: chr19:27000001-28000000; source_node: chr18:49000001-50000000; weight: 0.003692122517562033
            # 6--82; bias: 0.00021923129703834945; sink_node: chr19:3000001-4000000; source_node: chr18:6000001-7000000; weight: 0.0008769251881533978
            # 47--107; bias: 0.00012820949175399097; sink_node: chr19:28000001-29000000; source_node: chr18:47000001-48000000; weight: 0.0015385139010478917
            # 38--112; bias: 0.0001493344481069762; sink_node: chr19:33000001-34000000; source_node: chr18:38000001-39000000; weight: 0.0005973377924279048
            # ...

        # select all edges that are only on
        # chromosome 19
        for edge in hic.edges(('chr19', 'chr19')):
            print(edge)
            # 90--116; bias: 0.00021173151730025176; sink_node: chr19:37000001-38000000; source_node: chr19:11000001-12000000; weight: 0.009104455243910825
            # 135--135; bias: 0.00018003890596887822; sink_node: chr19:56000001-57000000; source_node: chr19:56000001-57000000; weight: 0.10028167062466517
            # 123--123; bias: 0.00011063368998965993; sink_node: chr19:44000001-45000000; source_node: chr19:44000001-45000000; weight: 0.1386240135570439
            # 92--93; bias: 0.00040851066434864896; sink_node: chr19:14000001-15000000; source_node: chr19:13000001-14000000; weight: 0.10090213409411629
            # ...

        # select inter-chromosomal edges
        # between chromosomes 18 and 19
        for edge in hic.edges(('chr18', 'chr19')):
            print(edge)
            # 49--106; bias: 0.00026372303696871666; sink_node: chr19:27000001-28000000; source_node: chr18:49000001-50000000; weight: 0.003692122517562033
            # 6--82; bias: 0.00021923129703834945; sink_node: chr19:3000001-4000000; source_node: chr18:6000001-7000000; weight: 0.0008769251881533978
            # 47--107; bias: 0.00012820949175399097; sink_node: chr19:28000001-29000000; source_node: chr18:47000001-48000000; weight: 0.0015385139010478917
            # 38--112; bias: 0.0001493344481069762; sink_node: chr19:33000001-34000000; source_node: chr18:38000001-39000000; weight: 0.0005973377924279048
            # ...

    By default, `edges()` will retrieve all edge attributes, which can be slow when iterating over a lot of edges. This is why all file-based FAN-C `RegionPairsContainer` objects support lazy loading, where attributes are only read on demand.

        for edge in hic.edges('chr18', lazy=True):
            print(edge.source, edge.sink, edge.weight, edge)
            # 42 42 0.12291311562018173 <fanc.matrix.LazyEdge for row /edges/chrpair_0_0.row (Row), pointing to row #0>
            # 24 28 0.025205961072838057 <fanc.matrix.LazyEdge for row /edges/chrpair_0_0.row (Row), pointing to row #1>
            # 5 76 0.00961709840049876 <fanc.matrix.LazyEdge for row /edges/chrpair_0_0.row (Row), pointing to row #2>
            # 66 68 0.03876763316345468 <fanc.matrix.LazyEdge for row /edges/chrpair_0_0.row (Row), pointing to row #3>
            # ...

    Warning

    The lazy iterator reuses the `LazyEdge` object in every iteration, and overwrites the `LazyEdge` attributes. Therefore do not use lazy iterators if you need to store edge objects for later access. For example, the following code works as expected `list(hic.edges())`, with all `Edge` objects stored in the list, while this code `list(hic.edges(lazy=True))` will result in a list of identical `LazyEdge` objects. Always ensure you do all edge processing in the loop when working with lazy iterators!

    When working with normalised contact frequencies, such as obtained through matrix balancing in the example above, `edges()` automatically returns normalised edge weights. In addition, the `bias` attribute will (typically) have a value different from 1.

    When you are interested in the raw contact frequency, use the `norm=False` parameter:

        for edge in hic.edges('chr18', lazy=True, norm=False):
            print(edge.source, edge.sink, edge.weight)
            # 42 42 2120.0
            # 24 28 388.0
            # 5 76 94.0
            # 66 68 470.0
            # ...

    You can also choose to omit all intra- or inter-chromosomal edges using `intra_chromosomal=False` or `inter_chromosomal=False`, respectively.

    Returns

      Iterator over `Edge` or equivalent.

  `edges_dict`(*args, **kwargs)

    Edges iterator with access by bracket notation.

    This iterator always returns unnormalised edges.

    Returns

      dict or dict-like iterator

  `expected_values`(selected_chromosome=None, norm=True, *args, **kwargs)

    Calculate the expected values for genomic contacts at all distances.

    This calculates the expected values between genomic regions separated by a specific distance. Expected values are calculated as the average weight of edges between region pairs with the same genomic separation, taking into account unmappable regions.

    It will return a tuple with three values: a list of genome-wide intra-chromosomal expected values (list index corresponds to number of separating bins), a dict with chromosome names as keys and intra-chromosomal expected values specific to each chromosome, and a float for inter-chromosomal expected value.

    Parameters

      - selected_chromosome – (optional) Chromosome name. If provided, will only return expected values for this chromosome.

      - norm – If False, will calculate the expected values on the unnormalised matrix.

      - args – Not used in this context

      - kwargs – Not used in this context

    Returns

      list of intra-chromosomal expected values, dict of intra-chromosomal expected values by chromosome, inter-chromosomal expected value

  `expected_values_and_marginals`(selected_chromosome=None, norm=True, force=False, *args, **kwargs)

    Calculate the expected values for genomic contacts at all distances and the whole matrix marginals.

    This calculates the expected values between genomic regions separated by a specific distance. Expected values are calculated as the average weight of edges between region pairs with the same genomic separation, taking into account unmappable regions.

    It will return a tuple with three values: a list of genome-wide intra-chromosomal expected values (list index corresponds to number of separating bins), a dict with chromosome names as keys and intra-chromosomal expected values specific to each chromosome, and a float for inter-chromosomal expected value.

    Parameters

      - selected_chromosome – (optional) Chromosome name. If provided, will only return expected values for this chromosome.

      - norm – If False, will calculate the expected values on the unnormalised matrix.

      - args – Not used in this context

      - kwargs – Not used in this context

    Returns

      list of intra-chromosomal expected values, dict of intra-chromosomal expected values by chromosome, inter-chromosomal expected value

  `filter`(edge_filter, queue=False, log_progress=True)

    Filter edges in this object by using a `MaskFilter`.

    Parameters

      - edge_filter – Class implementing `MaskFilter`.

      - queue – If True, filter will be queued and can be executed along with other queued filters using `run_queued_filters()`

      - log_progress – If true, process iterating through all edges will be continuously reported.

  `filter_rao`(queue=False)

    Convenience function that applies a `RaoMergedPeakFilter`.

    Parameters

      queue – If True, filter will be queued and can be executed along with other queued filters using run_queued_filters

  `find_region`(query_regions, _regions_dict=None, _region_ends=None, _chromosomes=None)

    Find the region that is at the center of a region.

    Parameters

      query_regions – Region selector string, :class:~GenomicRegion, or list of the former

    Returns

      index (or list of indexes) of the region at the center of the query region

  `flush`(silent=False, update_mappability=True)

    Write data to file and flush buffers.

    Parameters

      - silent – do not print flush progress

      - update_mappability – After writing data, update mappability and expected values

  `get_mask`(key)

    Search _mask table for key and return Mask.

    Parameters

      - key (int) – search by mask name

      - key – search by mask ID

    Returns

      Mask

  `get_masks`(ix)

    Extract mask IDs encoded in parameter and return masks.

    IDs are powers of 2, so a single int field in the table can hold multiple masks by simply adding up the IDs. Similar principle to UNIX chmod (although that uses base 8)

    Parameters

      ix (int) – integer that is the sum of powers of 2. Note that this value is not necessarily itself a power of 2.

    Returns

      list of Masks extracted from ix

    Return type

      list (Mask)

  `intervals`(*args, **kwargs)

    Alias for region_intervals.

  `mappable`(region=None)

    Get the mappability of regions in this object.

    A “mappable” region has at least one contact to another region in the genome.

    Returns

      `array` where True means mappable and False unmappable

  `marginals`(masked=True, *args, **kwargs)

    Get the marginals vector of this Hic matrix.

    Sums up all contacts for each bin of the Hi-C matrix. Unmappable regoins will be masked in the returned vector unless the `masked` parameter is set to `False`.

    By default, corrected matrix entries are summed up. To get uncorrected matrix marginals use `norm=False`. Generally, all parameters accepted by `edges()` are supported.

    Parameters

      - masked – Use a numpy masked array to mask entries corresponding to unmappable regions

      - kwargs – Keyword arguments passed to `edges()`

  `matrix`(key=None, log=False, default_value=None, mask=True, log_base=2, *args, **kwargs)

    Assemble a `RegionMatrix` from region pairs.

    Parameters

      - key – Matrix selector. See `edges()` for all supported key types

      - log – If True, log-transform the matrix entries. Also see log_base

      - log_base – Base of the log transformation. Default: 2; only used when log=True

      - default_value – (optional) set the default value of matrix entries that have no associated edge/contact

      - mask – If False, do not mask unmappable regions

      - args – Positional arguments passed to `regions_and_matrix_entries()`

      - kwargs – Keyword arguments passed to `regions_and_matrix_entries()`

    Returns

      `RegionMatrix`

  classmethod `merge`(matrices, *args, **kwargs)

    Merge multiple `RegionMatrixContainer` objects.

    Merging is done by adding the weight of edges in each object.

    Parameters

      matrices – list of `RegionMatrixContainer`

    Returns

      merged `RegionMatrixContainer`

  `possible_contacts`()

    Calculate the possible number of contacts in the genome.

    This calculates the number of potential region pairs in a genome for any possible separation distance, taking into account the existence of unmappable regions.

    It will calculate one number for inter-chromosomal pairs, return a list with the number of possible pairs where the list index corresponds to the number of bins separating two regions, and a dictionary of lists for each chromosome.

    Returns

      possible intra-chromosomal pairs, possible intra-chromosomal pairs by chromosome, possible inter-chromosomal pairs

  `region_bins`(*args, **kwargs)

    Return slice of start and end indices spanned by a region.

    Parameters

      args – provide a `GenomicRegion` here to get the slice of start and end bins of onlythis region. To get the slice over all regions leave this blank.

    Returns

  `region_data`(key, value=None)

    Retrieve or add vector-data to this object. If there is existing data in this object with the same name, it will be replaced

    Parameters

      - key – Name of the data column

      - value – vector with region-based data (one entry per region)

  `region_intervals`(region, bins=None, bin_size=None, smoothing_window=None, nan_replacement=None, zero_to_nan=False, score_field='score', *args, **kwargs)

    Return equally-sized genomic intervals and associated scores.

    Use either bins or bin_size argument to control binning.

    Parameters

      - region – String or class:~GenomicRegion object denoting the region to be binned

      - bins – Number of bins to divide the region into

      - bin_size – Size of each bin (alternative to bins argument)

      - smoothing_window – Size of window (in bins) to smooth scores over

      - nan_replacement – NaN values in the scores will be replaced with this value

      - zero_to_nan – If True, will convert bins with score 0 to NaN

      - args – Arguments passed to _region_intervals

      - kwargs – Keyword arguments passed to _region_intervals

    Returns

      iterator of tuples: (start, end, score)

  `region_subset`(region, *args, **kwargs)

    Takes a class:~GenomicRegion and returns all regions that overlap with the supplied region.

    Parameters

      region – String or class:~GenomicRegion object for which covered bins will be returned.

  property `regions`

    Iterate over genomic regions in this object.

    Will return a `GenomicRegion` object in every iteration. Can also be used to get the number of regions by calling len() on the object returned by this method.

    Returns

      RegionIter

  `regions_and_edges`(key, *args, **kwargs)

    Convenient access to regions and edges selected by key.

    Parameters

      - key – Edge selector, see `edges()`

      - args – Positional arguments passed to `edges()`

      - kwargs – Keyword arguments passed to `edges()`

    Returns

      list of row regions, list of col regions, iterator over edges

  `regions_and_matrix_entries`(key=None, score_field=None, *args, **kwargs)

    Convenient access to non-zero matrix entries and associated regions.

    Parameters

      - key – Edge key, see `edges()`

      - oe – If True, will divide observed values by their expected value at the given distance. False by default

      - oe_per_chromosome – If True (default), will do a per-chromosome O/E calculation rather than using the whole matrix to obtain expected values

      - score_field – (optional) any edge attribute that returns a number can be specified here for filling the matrix. Usually this is defined by the `_default_score_field` attribute of the matrix class.

      - args – Positional arguments passed to `edges()`

      - kwargs – Keyword arguments passed to `edges()`

    Returns

      list of row regions, list of col regions, iterator over (i, j, weight) tuples

  property `regions_dict`

    Return a dictionary with region index as keys and regions as values.

    Returns

      dict {region.ix: region, …}

  static `regions_identical`(pairs)

    Check if the regions in all objects in the list are identical.

    Parameters

      pairs – `list` of `RegionBased` objects

    Returns

      True if chromosome, start, and end are identical between all regions in the same list positions.

  `run_queued_filters`(log_progress=True)

    Run queued filters.

    Parameters

      log_progress – If true, process iterating through all edges will be continuously reported.

  `scaling_factor`(matrix, weight_column=None)

    Compute the scaling factor to another matrix.

    Calculates the ratio between the number of contacts in this Hic object to the number of contacts in another Hic object.

    Parameters

      - matrix – A `Hic` object

      - weight_column – Name of the column to calculate the scaling factor on

    Returns

      float

  `subset`(*regions, **kwargs)

    Subset a Hic object by specifying one or more subset regions.

    Parameters

      - regions – string or GenomicRegion object(s)

      - kwargs – Supports file_name: destination file name of subset Hic object; tmpdir: if True works in tmp until object is closed additional parameters are passed to `edges()`

    Returns

      `Hic`

  `to_bed`(file_name, subset=None, **kwargs)

    Export regions as BED file

    Parameters

      - file_name – Path of file to write regions to

      - subset – optional `GenomicRegion` or str to write only regions overlapping this region

      - kwargs – Passed to `write_bed()`

  `to_bigwig`(file_name, subset=None, **kwargs)

    Export regions as BigWig file.

    Parameters

      - file_name – Path of file to write regions to

      - subset – optional `GenomicRegion` or str to write only regions overlapping this region

      - kwargs – Passed to `write_bigwig()`

  `to_gff`(file_name, subset=None, **kwargs)

    Export regions as GFF file

    Parameters

      - file_name – Path of file to write regions to

      - subset – optional `GenomicRegion` or str to write only regions overlapping this region

      - kwargs – Passed to `write_gff()`

class `fanc.peaks.` `RaoMergedPeakFilter`(cutoff=0.02, mask=None)

  Bases: `fanc.peaks.PeakFilter`

  Filter merged peaks exactly the same way that Rao et al. (2014) do.

  It removes peaks that are singlets and have a q-value sum >.02.

  `valid`(row)

    Map valid_peak to MaskFilter.valid(self, row).

    Parameters

      row – A pytables Table row.

    Returns

      The boolean value returned by valid_edge.

  `valid_peak`(peak)

    Determine if a `RaoPeak` object is valid or should be filtered.

    When implementing custom PeakFilter this method must be overridden. It should return False for `RaoPeak` objects that are to be fitered and True otherwise.

    Internally, the `RaoPeakInfo` object will iterate over all RaoPeak instances to determine their validity on an individual basis.

    Parameters

      peak – A `RaoPeak` object

    Returns

      True if `PeakFilter` is valid, False otherwise

class `fanc.peaks.` `RaoPeakCaller`(p=None, w_init=None, min_locus_dist=None, max_w=20, min_ll_reads=16, process_inter=False, correct_inter='fdr', n_processes=4, slice_size=2000, min_mappable_fraction=0.7, cluster=False)

  Bases: `object`

  Class that calls peaks the same way Rao et al. (2014) propose.

  Every pixel in a Hi-C matrix is evaluated based on its local “neighborhood”, i.e. the pixel’s observed value is compared to the expected value calculated from all pixels in its close surroundings.

  If a pixel is significantly enriched with respect to all investigated neighborhoods, it is assumed to be a “peak”.

  Four neighborhood types are calculated:

  - “donut”: Pixels surrounding the investigated pixel in a certain distance range

  - “lower-left” Pixels to the “lower-left” of a given pixel

  - “horizontal”: Pixels left and right of a given pixel

  - “vertical”: Pixels above and below a given pixel

  While the first neighborhood type most generally calculates enrichment of local background, the other types of neighborhoods serve mostly to exclude false-positive results from non-peak structures, such as TAD boundaries.

  The `RaoPeakCaller` is initialized with the peak calling parameters and run using `call_peaks()`.

  FDRs for intra-chromosomal peaks are automatically corrected for multiple testing using the “lamda-chunking” methodology introduced in Rao et al. 2014. FDRs for inter-chromosomal peaks are corrected by default using the Benjamini Hochberg false-discovery rate correction (but ‘bonferroni’ is also an option)

  `call_peaks`(hic, chromosome_pairs=None, file_name=None, intra_expected=None, inter_expected=None)

    Call peaks in Hi-C matrix.

    This method will determine each pixel’s likelihood to be a “true” peak. By default, only pixels with non-zero count and an observed/expected ratio > 1.0 for each neighborhood will be reported, because these can by definition not be true peaks.

    The peak calling behavior can be influenced by modifying the object attributes set when initializing `RaoPeakCaller`.

    Parameters

      - hic – A `Hic` object

      - chromosome_pairs – If None, all chromosome pairs will be investigated for peaks. Otherwise specify a list of chromosome name tuples (e.g. [(‘chr1’, ‘chr1’), (‘chr1’, ‘chr3’), …])

      - file_name – An optional filename that backs the returned `RaoPeakInfo` object

      - intra_expected – A dict of the form <chromosome>:<list of expected values> to override expected value calculation

      - inter_expected – A float describing the expected value for inter-chromosomal contact matrix entries

    Returns

      `RaoPeakInfo` object

  static `e_d`(m, i, j, e, w=1, p=0)

    Compute the average value of pixels in the “donut” neighborhood of a pixel.

  static `e_h`(m, i, j, e, w=1, p=0)

    Compute the average value of pixels in the horizontal neighborhood of a pixel.

  static `e_ll`(m, i, j, e, w=1, p=0)

    Compute the average value of pixels in the lower-left neighborhood of a pixel.

  static `e_v`(m, i, j, e, w=1, p=0)

    Compute the average value of pixels in the vertical neighborhood of a pixel.

  static `find_chunk`(value, chunk_func=<function RaoPeakCaller.<lambda>>)

    Use bisection to find a matching lambda chunk for a given expected value.

  static `ll_sum`(m, i, j, w=1, p=0)

    Compute the sum of pixels in the lower-left neighborhood of a pixel.

class `fanc.peaks.` `RaoPeakFilter`(mask=None)

  Bases: `fanc.peaks.PeakFilter`

  Filter peaks exactly the same way that Rao et al. (2014) do.

  It only retains peaks that

  1. are at least 2-fold enriched over either the donut or lower-left neighborhood

  2. are at least 1.5-fold enriched over the horizontal and vertical neighborhoods

  3. are at least 1.75-fold enriched over both the donut and lower-left neighborhood

  4. have an FDR <= 0.1 in every neighborhood

  `valid`(row)

    Map valid_peak to MaskFilter.valid(self, row).

    Parameters

      row – A pytables Table row.

    Returns

      The boolean value returned by valid_edge.

  `valid_peak`(peak)

    Determine if a `RaoPeak` object is valid or should be filtered.

    When implementing custom PeakFilter this method must be overridden. It should return False for `RaoPeak` objects that are to be fitered and True otherwise.

    Internally, the `RaoPeakInfo` object will iterate over all RaoPeak instances to determine their validity on an individual basis.

    Parameters

      peak – A `RaoPeak` object

    Returns

      True if `PeakFilter` is valid, False otherwise

class `fanc.peaks.` `RaoPeakInfo`(file_name=None, mode='a', tmpdir=None, _table_name_regions='regions', _table_name_peaks='edges')

  Bases: `fanc.matrix.RegionMatrixTable`

  Information about peaks called by `RaoPeakCaller`.

  A peak has the following information:

  source, sink: coordinates of the highest peak pixel in the Hi-C matrix observed: observed value of the peak in the Hi-C matrix, generally uncorrected e_ll: expected value of the peak given its lower-left neighborhood e_h: expected value of the peak given its horizontal neighborhood e_v: expected value of the peak given its vertical neighborhood e_d: expected value of the peak given its surrounding (donut) neighborhood e_ll_chunk: “lambda-chunk” this peak falls into given its ‘ll’ neighborhood e_h_chunk: “lambda-chunk” this peak falls into given its ‘h’ neighborhood e_v_chunk: “lambda-chunk” this peak falls into given its ‘v’ neighborhood e_d_chunk: “lambda-chunk” this peak falls into given its ‘d’ neighborhood fdr_ll: FDR of the peak given its lower-left neighborhood fdr_h: FDR of the peak given its horizontal neighborhood fdr_v: FDR of the peak given its vertical neighborhood fdr_d: FDR of the peak given its surrounding (donut) neighborhood

  For more information about neighborhoods and peak information, see `RaoPeakCaller`.

  class `ChromosomeDescription`

    Bases: `tables.description.IsDescription`

    Description of the chromosomes in this object.

  class `MaskDescription`

    Bases: `tables.description.IsDescription`

  class `RegionDescription`

    Bases: `tables.description.IsDescription`

    Description of a genomic region for PyTables Table

  `add_contact`(contact, *args, **kwargs)

    Alias for `add_edge()`

    Parameters

      - contact – `Edge`

      - args – Positional arguments passed to `_add_edge()`

      - kwargs – Keyword arguments passed to `_add_edge()`

  `add_contacts`(contacts, *args, **kwargs)

    Alias for `add_edges()`

  `add_edge`(edge, check_nodes_exist=True, *args, **kwargs)

    Add an edge / contact between two regions to this object.

    Parameters

      - edge – `Edge`, dict with at least the attributes source and sink, optionally weight, or a list of length 2 (source, sink) or 3 (source, sink, weight).

      - check_nodes_exist – Make sure that there are nodes that match source and sink indexes

      - args – Positional arguments passed to `_add_edge()`

      - kwargs – Keyword arguments passed to `_add_edge()`

  `add_edge_from_dict`(edge, *args, **kwargs)

    Direct method to add an edge from dict input.

    Parameters

      edge – dict with at least the keys “source” and “sink”. Additional keys will be loaded as edge attributes

  `add_edge_from_edge`(edge, *args, **kwargs)

    Direct method to add an edge from `Edge` input.

    Parameters

      edge – `Edge`

  `add_edge_from_list`(edge, *args, **kwargs)

    Direct method to add an edge from list or tuple input.

    Parameters

      edge – List or tuple. Should be of length 2 (source, sink) or 3 (source, sink, weight)

  `add_edge_simple`(source, sink, weight=None, *args, **kwargs)

    Direct method to add an edge from `Edge` input.

    Parameters

      - source – Source region index

      - sink – Sink region index

      - weight – Weight of the edge

  `add_edges`(edges, flush=True, *args, **kwargs)

    Bulk-add edges from a list.

    List items can be any of the supported edge types, list, tuple, dict, or `Edge`. Repeatedly calls `add_edge()`, so may be inefficient for large amounts of data.

    Parameters

      edges – List (or iterator) of edges. See `add_edge()` for details

  `add_mask_description`(name, description)

    Add a mask description to the _mask table and return its ID.

    Parameters

      - name (str) – name of the mask

      - description (str) – description of the mask

    Returns

      id of the mask

    Return type

      int

  `add_region`(region, *args, **kwargs)

    Add a genomic region to this object.

    This method offers some flexibility in the types of objects that can be loaded. See parameters for details.

    Parameters

      region – Can be a `GenomicRegion`, a str in the form ‘<chromosome>:<start>-<end>[:<strand>], a dict with at least the fields ‘chromosome’, ‘start’, and ‘end’, optionally ‘ix’, or a list of length 3 (chromosome, start, end) or 4 (ix, chromosome, start, end).

  `add_regions`(regions, *args, **kwargs)

    Bulk insert multiple genomic regions.

    Parameters

      regions – List (or any iterator) with objects that describe a genomic region. See `add_region` for options.

  static `bin_intervals`(intervals, bins, interval_range=None, smoothing_window=None, nan_replacement=None, zero_to_nan=False)

    Bin a given set of intervals into a fixed number of bins.

    Parameters

      - intervals – iterator of tuples (start, end, score)

      - bins – Number of bins to divide the region into

      - interval_range – Optional. Tuple (start, end) in base pairs of range of interval to be binned. Useful if intervals argument does not cover to exact genomic range to be binned.

      - smoothing_window – Size of window (in bins) to smooth scores over

      - nan_replacement – NaN values in the scores will be replaced with this value

      - zero_to_nan – If True, will convert bins with score 0 to NaN

    Returns

      iterator of tuples: (start, end, score)

  static `bin_intervals_equidistant`(intervals, bin_size, interval_range=None, smoothing_window=None, nan_replacement=None, zero_to_nan=False)

    Bin a given set of intervals into bins with a fixed size.

    Parameters

      - intervals – iterator of tuples (start, end, score)

      - bin_size – Size of each bin in base pairs

      - interval_range – Optional. Tuple (start, end) in base pairs of range of interval to be binned. Useful if intervals argument does not cover to exact genomic range to be binned.

      - smoothing_window – Size of window (in bins) to smooth scores over

      - nan_replacement – NaN values in the scores will be replaced with this value

      - zero_to_nan – If True, will convert bins with score 0 to NaN

    Returns

      iterator of tuples: (start, end, score)

  property `bin_size`

    Return the length of the first region in the dataset.

    Assumes all bins have equal size.

    Returns

      int

  `binned_regions`(region=None, bins=None, bin_size=None, smoothing_window=None, nan_replacement=None, zero_to_nan=False, *args, **kwargs)

    Same as region_intervals, but returns `GenomicRegion` objects instead of tuples.

    Parameters

      - region – String or class:~GenomicRegion object denoting the region to be binned

      - bins – Number of bins to divide the region into

      - bin_size – Size of each bin (alternative to bins argument)

      - smoothing_window – Size of window (in bins) to smooth scores over

      - nan_replacement – NaN values in the scores will be replaced with this value

      - zero_to_nan – If True, will convert bins with score 0 to NaN

      - args – Arguments passed to _region_intervals

      - kwargs – Keyword arguments passed to _region_intervals

    Returns

      iterator of `GenomicRegion` objects

  `bins_to_distance`(bins)

    Convert fraction of bins to base pairs

    Parameters

      bins – float, fraction of bins

    Returns

      int, base pairs

  property `chromosome_bins`

    Returns a dictionary of chromosomes and the start and end index of the bins they cover.

    Returned list is range-compatible, i.e. chromosome bins [0,5] cover chromosomes 1, 2, 3, and 4, not 5.

  property `chromosome_lengths`

    Returns a dictionary of chromosomes and their length in bp.

  `chromosomes`()

    List all chromosomes in this regions table. :return: list of chromosome names.

  `close`(copy_tmp=True, remove_tmp=True)

    Close this HDF5 file and run exit operations.

    If file was opened with tmpdir in read-only mode: close file and delete temporary copy.

    If file was opened with tmpdir in write or append mode: Replace original file with copy and delete copy.

    Parameters

      - copy_tmp – If False, does not overwrite original with modified file.

      - remove_tmp – If False, does not delete temporary copy of file.

  `distance_to_bins`(distance)

    Convert base pairs to fraction of bins.

    Parameters

      distance – distance in base pairs

    Returns

      float, distance as fraction of bin size

  `downsample`(n, file_name=None)

    Sample edges from this object.

    Sampling is always done on uncorrected Hi-C matrices.

    Parameters

      - n – Sample size or reference object. If n < 1 will be interpreted as a fraction of total reads in this object.

      - file_name – Output file name for down-sampled object.

    Returns

      `RegionPairsTable`

  `edge_data`(attribute, *args, **kwargs)

    Iterate over specific edge attribute.

    Parameters

      - attribute – Name of the attribute, e.g. “weight”

      - args – Positional arguments passed to `edges()`

      - kwargs – Keyword arguments passed to `edges()`

    Returns

      iterator over edge attribute

  `edge_subset`(key=None, *args, **kwargs)

    Get a subset of edges.

    This is an alias for `edges()`.

    Returns

      generator (`Edge`)

  property `edges`

    Iterate over contacts / edges.

    `edges()` is the central function of `RegionPairsContainer`. Here, we will use the `Hic` implementation for demonstration purposes, but the usage is exactly the same for all compatible objects implementing `RegionPairsContainer`, including `JuicerHic` and `CoolerHic`.

        import fanc

        # file from FAN-C examples
        hic = fanc.load("output/hic/binned/fanc_example_1mb.hic")

    We can easily find the number of edges in the sample `Hic` object:

        len(hic.edges)  # 8695

    When used in an iterator context, `edges()` iterates over all edges in the `RegionPairsContainer`:

        for edge in hic.edges:
            # do something with edge
            print(edge)
            # 42--42; bias: 5.797788472650082e-05; sink_node: chr18:42000001-43000000; source_node: chr18:42000001-43000000; weight: 0.12291311562018173
            # 24--28; bias: 6.496381719803623e-05; sink_node: chr18:28000001-29000000; source_node: chr18:24000001-25000000; weight: 0.025205961072838057
            # 5--76; bias: 0.00010230955745211447; sink_node: chr18:76000001-77000000; source_node: chr18:5000001-6000000; weight: 0.00961709840049876
            # 66--68; bias: 8.248432587969082e-05; sink_node: chr18:68000001-69000000; source_node: chr18:66000001-67000000; weight: 0.03876763316345468
            # ...

    Calling `edges()` as a method has the same effect:

        # note the '()'
        for edge in hic.edges():
            # do something with edge
            print(edge)
            # 42--42; bias: 5.797788472650082e-05; sink_node: chr18:42000001-43000000; source_node: chr18:42000001-43000000; weight: 0.12291311562018173
            # 24--28; bias: 6.496381719803623e-05; sink_node: chr18:28000001-29000000; source_node: chr18:24000001-25000000; weight: 0.025205961072838057
            # 5--76; bias: 0.00010230955745211447; sink_node: chr18:76000001-77000000; source_node: chr18:5000001-6000000; weight: 0.00961709840049876
            # 66--68; bias: 8.248432587969082e-05; sink_node: chr18:68000001-69000000; source_node: chr18:66000001-67000000; weight: 0.03876763316345468
            # ...

    Rather than iterate over all edges in the object, we can select only a subset. If the key is a string or a `GenomicRegion`, all non-zero edges connecting the region described by the key to any other region are returned. If the key is a tuple of strings or `GenomicRegion`, only edges between the two regions are returned.

        # select all edges between chromosome 19
        # and any other region:
        for edge in hic.edges("chr19"):
            print(edge)
            # 49--106; bias: 0.00026372303696871666; sink_node: chr19:27000001-28000000; source_node: chr18:49000001-50000000; weight: 0.003692122517562033
            # 6--82; bias: 0.00021923129703834945; sink_node: chr19:3000001-4000000; source_node: chr18:6000001-7000000; weight: 0.0008769251881533978
            # 47--107; bias: 0.00012820949175399097; sink_node: chr19:28000001-29000000; source_node: chr18:47000001-48000000; weight: 0.0015385139010478917
            # 38--112; bias: 0.0001493344481069762; sink_node: chr19:33000001-34000000; source_node: chr18:38000001-39000000; weight: 0.0005973377924279048
            # ...

        # select all edges that are only on
        # chromosome 19
        for edge in hic.edges(('chr19', 'chr19')):
            print(edge)
            # 90--116; bias: 0.00021173151730025176; sink_node: chr19:37000001-38000000; source_node: chr19:11000001-12000000; weight: 0.009104455243910825
            # 135--135; bias: 0.00018003890596887822; sink_node: chr19:56000001-57000000; source_node: chr19:56000001-57000000; weight: 0.10028167062466517
            # 123--123; bias: 0.00011063368998965993; sink_node: chr19:44000001-45000000; source_node: chr19:44000001-45000000; weight: 0.1386240135570439
            # 92--93; bias: 0.00040851066434864896; sink_node: chr19:14000001-15000000; source_node: chr19:13000001-14000000; weight: 0.10090213409411629
            # ...

        # select inter-chromosomal edges
        # between chromosomes 18 and 19
        for edge in hic.edges(('chr18', 'chr19')):
            print(edge)
            # 49--106; bias: 0.00026372303696871666; sink_node: chr19:27000001-28000000; source_node: chr18:49000001-50000000; weight: 0.003692122517562033
            # 6--82; bias: 0.00021923129703834945; sink_node: chr19:3000001-4000000; source_node: chr18:6000001-7000000; weight: 0.0008769251881533978
            # 47--107; bias: 0.00012820949175399097; sink_node: chr19:28000001-29000000; source_node: chr18:47000001-48000000; weight: 0.0015385139010478917
            # 38--112; bias: 0.0001493344481069762; sink_node: chr19:33000001-34000000; source_node: chr18:38000001-39000000; weight: 0.0005973377924279048
            # ...

    By default, `edges()` will retrieve all edge attributes, which can be slow when iterating over a lot of edges. This is why all file-based FAN-C `RegionPairsContainer` objects support lazy loading, where attributes are only read on demand.

        for edge in hic.edges('chr18', lazy=True):
            print(edge.source, edge.sink, edge.weight, edge)
            # 42 42 0.12291311562018173 <fanc.matrix.LazyEdge for row /edges/chrpair_0_0.row (Row), pointing to row #0>
            # 24 28 0.025205961072838057 <fanc.matrix.LazyEdge for row /edges/chrpair_0_0.row (Row), pointing to row #1>
            # 5 76 0.00961709840049876 <fanc.matrix.LazyEdge for row /edges/chrpair_0_0.row (Row), pointing to row #2>
            # 66 68 0.03876763316345468 <fanc.matrix.LazyEdge for row /edges/chrpair_0_0.row (Row), pointing to row #3>
            # ...

    Warning

    The lazy iterator reuses the `LazyEdge` object in every iteration, and overwrites the `LazyEdge` attributes. Therefore do not use lazy iterators if you need to store edge objects for later access. For example, the following code works as expected `list(hic.edges())`, with all `Edge` objects stored in the list, while this code `list(hic.edges(lazy=True))` will result in a list of identical `LazyEdge` objects. Always ensure you do all edge processing in the loop when working with lazy iterators!

    When working with normalised contact frequencies, such as obtained through matrix balancing in the example above, `edges()` automatically returns normalised edge weights. In addition, the `bias` attribute will (typically) have a value different from 1.

    When you are interested in the raw contact frequency, use the `norm=False` parameter:

        for edge in hic.edges('chr18', lazy=True, norm=False):
            print(edge.source, edge.sink, edge.weight)
            # 42 42 2120.0
            # 24 28 388.0
            # 5 76 94.0
            # 66 68 470.0
            # ...

    You can also choose to omit all intra- or inter-chromosomal edges using `intra_chromosomal=False` or `inter_chromosomal=False`, respectively.

    Returns

      Iterator over `Edge` or equivalent.

  `edges_dict`(*args, **kwargs)

    Edges iterator with access by bracket notation.

    This iterator always returns unnormalised edges.

    Returns

      dict or dict-like iterator

  `expected_values`(selected_chromosome=None, norm=True, *args, **kwargs)

    Calculate the expected values for genomic contacts at all distances.

    This calculates the expected values between genomic regions separated by a specific distance. Expected values are calculated as the average weight of edges between region pairs with the same genomic separation, taking into account unmappable regions.

    It will return a tuple with three values: a list of genome-wide intra-chromosomal expected values (list index corresponds to number of separating bins), a dict with chromosome names as keys and intra-chromosomal expected values specific to each chromosome, and a float for inter-chromosomal expected value.

    Parameters

      - selected_chromosome – (optional) Chromosome name. If provided, will only return expected values for this chromosome.

      - norm – If False, will calculate the expected values on the unnormalised matrix.

      - args – Not used in this context

      - kwargs – Not used in this context

    Returns

      list of intra-chromosomal expected values, dict of intra-chromosomal expected values by chromosome, inter-chromosomal expected value

  `expected_values_and_marginals`(selected_chromosome=None, norm=True, force=False, *args, **kwargs)

    Calculate the expected values for genomic contacts at all distances and the whole matrix marginals.

    This calculates the expected values between genomic regions separated by a specific distance. Expected values are calculated as the average weight of edges between region pairs with the same genomic separation, taking into account unmappable regions.

    It will return a tuple with three values: a list of genome-wide intra-chromosomal expected values (list index corresponds to number of separating bins), a dict with chromosome names as keys and intra-chromosomal expected values specific to each chromosome, and a float for inter-chromosomal expected value.

    Parameters

      - selected_chromosome – (optional) Chromosome name. If provided, will only return expected values for this chromosome.

      - norm – If False, will calculate the expected values on the unnormalised matrix.

      - args – Not used in this context

      - kwargs – Not used in this context

    Returns

      list of intra-chromosomal expected values, dict of intra-chromosomal expected values by chromosome, inter-chromosomal expected value

  `filter`(edge_filter, queue=False, log_progress=True)

    Filter edges in this object by using a `MaskFilter`.

    Parameters

      - edge_filter – Class implementing `MaskFilter`.

      - queue – If True, filter will be queued and can be executed along with other queued filters using `run_queued_filters()`

      - log_progress – If true, process iterating through all edges will be continuously reported.

  `filter_enrichment`(enrichment_ll_cutoff=1.0, enrichment_h_cutoff=1.0, enrichment_v_cutoff=1.0, enrichment_d_cutoff=1.0, queue=False)

    Convenience function that applies a `ObservedExpectedRatioPeakFilter`. The actual algorithm and rationale used for filtering will depend on the internal _mapper attribute.

    Parameters

      queue – If True, filter will be queued and can be executed along with other queued filters using run_queued_filters

  `filter_fdr`(fdr_cutoff, queue=False)

    Convenience function that applies a `FdrPeakFilter`. The actual algorithm and rationale used for filtering will depend on the internal _mapper attribute.

    Parameters

      - fdr_cutoff – The false-discovery rate of every neighborhood enrichment must be lower or equal to this threshold

      - queue – If True, filter will be queued and can be executed along with other queued filters using run_queued_filters

  `filter_mappability`(cutoff, queue=False)

    Convenience function that applies a `MappabilityPeakFilter`. The actual algorithm and rationale used for filtering will depend on the internal _mapper attribute.

    Parameters

      - cutoff – Minimum mappability (fraction of 1)

      - queue – If True, filter will be queued and can be executed along with other queued filters using run_queued_filters

  `filter_observed`(cutoff, queue=False)

    Convenience function that applies a `ObservedPeakFilter`. The actual algorithm and rationale used for filtering will depend on the internal _mapper attribute.

    Parameters

      - cutoff – Minimum observed value

      - queue – If True, filter will be queued and can be executed along with other queued filters using run_queued_filters

  `filter_rao`(queue=False)

    Convenience function that applies all filters Rao et al. (2014) do.

    Parameters

      queue – If True, filter will be queued and can be executed along with other queued filters using run_queued_filters

  `find_region`(query_regions, _regions_dict=None, _region_ends=None, _chromosomes=None)

    Find the region that is at the center of a region.

    Parameters

      query_regions – Region selector string, :class:~GenomicRegion, or list of the former

    Returns

      index (or list of indexes) of the region at the center of the query region

  `flush`(silent=False, update_mappability=True)

    Write data to file and flush buffers.

    Parameters

      - silent – do not print flush progress

      - update_mappability – After writing data, update mappability and expected values

  `get_mask`(key)

    Search _mask table for key and return Mask.

    Parameters

      - key (int) – search by mask name

      - key – search by mask ID

    Returns

      Mask

  `get_masks`(ix)

    Extract mask IDs encoded in parameter and return masks.

    IDs are powers of 2, so a single int field in the table can hold multiple masks by simply adding up the IDs. Similar principle to UNIX chmod (although that uses base 8)

    Parameters

      ix (int) – integer that is the sum of powers of 2. Note that this value is not necessarily itself a power of 2.

    Returns

      list of Masks extracted from ix

    Return type

      list (Mask)

  `intervals`(*args, **kwargs)

    Alias for region_intervals.

  `mappable`(region=None)

    Get the mappability of regions in this object.

    A “mappable” region has at least one contact to another region in the genome.

    Returns

      `array` where True means mappable and False unmappable

  `marginals`(masked=True, *args, **kwargs)

    Get the marginals vector of this Hic matrix.

    Sums up all contacts for each bin of the Hi-C matrix. Unmappable regoins will be masked in the returned vector unless the `masked` parameter is set to `False`.

    By default, corrected matrix entries are summed up. To get uncorrected matrix marginals use `norm=False`. Generally, all parameters accepted by `edges()` are supported.

    Parameters

      - masked – Use a numpy masked array to mask entries corresponding to unmappable regions

      - kwargs – Keyword arguments passed to `edges()`

  `matrix`(key=None, log=False, default_value=None, mask=True, log_base=2, *args, **kwargs)

    Assemble a `RegionMatrix` from region pairs.

    Parameters

      - key – Matrix selector. See `edges()` for all supported key types

      - log – If True, log-transform the matrix entries. Also see log_base

      - log_base – Base of the log transformation. Default: 2; only used when log=True

      - default_value – (optional) set the default value of matrix entries that have no associated edge/contact

      - mask – If False, do not mask unmappable regions

      - args – Positional arguments passed to `regions_and_matrix_entries()`

      - kwargs – Keyword arguments passed to `regions_and_matrix_entries()`

    Returns

      `RegionMatrix`

  classmethod `merge`(matrices, *args, **kwargs)

    Merge multiple `RegionMatrixContainer` objects.

    Merging is done by adding the weight of edges in each object.

    Parameters

      matrices – list of `RegionMatrixContainer`

    Returns

      merged `RegionMatrixContainer`

  `merged_peaks`(file_name=None, euclidian_distance=20000)

    Merge spatially proximal peaks.

    Parameters

      - file_name – Optional file to save merged peak info to.

      - euclidian_distance – Maximal distance in base pairs to still consider two peaks to be the same

    Returns

      `PeakInfo`

  `possible_contacts`()

    Calculate the possible number of contacts in the genome.

    This calculates the number of potential region pairs in a genome for any possible separation distance, taking into account the existence of unmappable regions.

    It will calculate one number for inter-chromosomal pairs, return a list with the number of possible pairs where the list index corresponds to the number of bins separating two regions, and a dictionary of lists for each chromosome.

    Returns

      possible intra-chromosomal pairs, possible intra-chromosomal pairs by chromosome, possible inter-chromosomal pairs

  `region_bins`(*args, **kwargs)

    Return slice of start and end indices spanned by a region.

    Parameters

      args – provide a `GenomicRegion` here to get the slice of start and end bins of onlythis region. To get the slice over all regions leave this blank.

    Returns

  `region_data`(key, value=None)

    Retrieve or add vector-data to this object. If there is existing data in this object with the same name, it will be replaced

    Parameters

      - key – Name of the data column

      - value – vector with region-based data (one entry per region)

  `region_intervals`(region, bins=None, bin_size=None, smoothing_window=None, nan_replacement=None, zero_to_nan=False, score_field='score', *args, **kwargs)

    Return equally-sized genomic intervals and associated scores.

    Use either bins or bin_size argument to control binning.

    Parameters

      - region – String or class:~GenomicRegion object denoting the region to be binned

      - bins – Number of bins to divide the region into

      - bin_size – Size of each bin (alternative to bins argument)

      - smoothing_window – Size of window (in bins) to smooth scores over

      - nan_replacement – NaN values in the scores will be replaced with this value

      - zero_to_nan – If True, will convert bins with score 0 to NaN

      - args – Arguments passed to _region_intervals

      - kwargs – Keyword arguments passed to _region_intervals

    Returns

      iterator of tuples: (start, end, score)

  `region_subset`(region, *args, **kwargs)

    Takes a class:~GenomicRegion and returns all regions that overlap with the supplied region.

    Parameters

      region – String or class:~GenomicRegion object for which covered bins will be returned.

  property `regions`

    Iterate over genomic regions in this object.

    Will return a `GenomicRegion` object in every iteration. Can also be used to get the number of regions by calling len() on the object returned by this method.

    Returns

      RegionIter

  `regions_and_edges`(key, *args, **kwargs)

    Convenient access to regions and edges selected by key.

    Parameters

      - key – Edge selector, see `edges()`

      - args – Positional arguments passed to `edges()`

      - kwargs – Keyword arguments passed to `edges()`

    Returns

      list of row regions, list of col regions, iterator over edges

  `regions_and_matrix_entries`(key=None, score_field=None, *args, **kwargs)

    Convenient access to non-zero matrix entries and associated regions.

    Parameters

      - key – Edge key, see `edges()`

      - oe – If True, will divide observed values by their expected value at the given distance. False by default

      - oe_per_chromosome – If True (default), will do a per-chromosome O/E calculation rather than using the whole matrix to obtain expected values

      - score_field – (optional) any edge attribute that returns a number can be specified here for filling the matrix. Usually this is defined by the `_default_score_field` attribute of the matrix class.

      - args – Positional arguments passed to `edges()`

      - kwargs – Keyword arguments passed to `edges()`

    Returns

      list of row regions, list of col regions, iterator over (i, j, weight) tuples

  property `regions_dict`

    Return a dictionary with region index as keys and regions as values.

    Returns

      dict {region.ix: region, …}

  static `regions_identical`(pairs)

    Check if the regions in all objects in the list are identical.

    Parameters

      pairs – `list` of `RegionBased` objects

    Returns

      True if chromosome, start, and end are identical between all regions in the same list positions.

  `run_queued_filters`(log_progress=True)

    Run queued filters.

    Parameters

      log_progress – If true, process iterating through all edges will be continuously reported.

  `scaling_factor`(matrix, weight_column=None)

    Compute the scaling factor to another matrix.

    Calculates the ratio between the number of contacts in this Hic object to the number of contacts in another Hic object.

    Parameters

      - matrix – A `Hic` object

      - weight_column – Name of the column to calculate the scaling factor on

    Returns

      float

  `subset`(*regions, **kwargs)

    Subset a Hic object by specifying one or more subset regions.

    Parameters

      - regions – string or GenomicRegion object(s)

      - kwargs – Supports file_name: destination file name of subset Hic object; tmpdir: if True works in tmp until object is closed additional parameters are passed to `edges()`

    Returns

      `Hic`

  `to_bed`(file_name, subset=None, **kwargs)

    Export regions as BED file

    Parameters

      - file_name – Path of file to write regions to

      - subset – optional `GenomicRegion` or str to write only regions overlapping this region

      - kwargs – Passed to `write_bed()`

  `to_bigwig`(file_name, subset=None, **kwargs)

    Export regions as BigWig file.

    Parameters

      - file_name – Path of file to write regions to

      - subset – optional `GenomicRegion` or str to write only regions overlapping this region

      - kwargs – Passed to `write_bigwig()`

  `to_gff`(file_name, subset=None, **kwargs)

    Export regions as GFF file

    Parameters

      - file_name – Path of file to write regions to

      - subset – optional `GenomicRegion` or str to write only regions overlapping this region

      - kwargs – Passed to `write_gff()`

`fanc.peaks.` `overlap_peaks`(peaks, max_distance=6000)

  Calculate overlap between different peak calls.

  Useful for comparing peak calls across different samples or conditions.

  Parameters

    - peaks (dict) – Peaks to overlap. Dictionary of `fanc.data.network.PeakInfo`, keys are dataset names.

    - max_distance (int) – Maximum distance between peaks for overlap

  Returns

    DataFrame of overlap statistics and dictionary containing overlapping peaks. Keys are sets of dataset names.

  Return type

    (pandas.DataFrame, fanc.data.network.PeakInfo)