pybigtools

The base module for opening a bigWig or bigBed. The only defined function is open.

View Source

1from .pybigtools import *
2
3__doc__ = pybigtools.__doc__
4if hasattr(pybigtools, "__all__"):
5    __all__ = pybigtools.__all__

__version__ = '0.1.4-dev'

def open(path_url_or_file_like, mode=None):

This is the entrypoint for working with bigWigs or bigBeds.

The first argument can take one of three values: 1) A path to a file as a string 2) An http url for a remote file as a string 3) A file-like object with a read and seek method

When writing, only a file path can be used.

The mode is either "w", "r", or None. "r" or None will open a bigWig or bigBed for reading (but will not allow writing). "w" Will open a bigWig/bigBed for writing (but will not allow reading).

If passing a file-like object, simultaneous reading of different intervals is not supported and may result in incorrect behavior.

This returns one of the following:

BigWigWrite
BigWigRead
BigBedWrite
BigBedRead

def bigWigAverageOverBed(bigwig, bed, names=None):

Gets the average values from a bigWig over the entries of a bed file.

Parameters: bigWig (str): The path to the bigWig. bed (str): The path to the bed. names (None, bool, or int):
If None, then each return value will be a single float, the average value over an interval in the bed file.
If True, then each return value will be a tuple of the value of column 4 and the average value over the interval with that name in the bed file.
If False, then each return value will be a tuple of the interval in the format {chrom}:{start}-{end} and the average value over that interval.
If 0, then each return value will match as if False was passed.
If a 1+, then each return value will be a tuple of the value of column of this parameter (1-based) and the average value over the interval.

Returns: This returns a generator of values. (Therefore, to save to a list, do list(bigWigAverageOverBed(...)))
If no name is specified (see the names parameter above), then returns a generator of floats.
If a name column is specified (see above), then returns a generator of tuples ({name}, {average})

class BigWigWrite:

This class is the interface for writing a bigWig.

def write(self, /, chroms, vals):

Writes the values passsed to the bigwig file. The underlying file will be closed automatically when the function completes (and no other operations will be able to be performed).

The chroms argument should be a dictionary with keys as chromosome names and values as their length.
The vals argument should be an iterable with values (String, int, int, float) that represents each value to write in the format (chromosome, start, end, value).

def close(self, /):

close()

Manually closed the file. No other operations will be allowed after it is closed. This is done automatically after write is performed.

class BigBedWrite:

This class is the interface for writing to a bigBed.

def write(self, /, chroms, vals):

Writes the values passsed to the bigwig file. The underlying file will be closed automatically when the function completes (and no other operations will be able to be performed).
The chroms argument should be a dictionary with keys as chromosome names and values as their length.
The vals argument should be an iterable with values (String, int, int, String) that represents each value to write in the format (chromosome, start, end, rest)
The rest String should consist of tab-delimited fields.

def close(self, /):

Manually closed the file. No other operations will be allowed after it is closed. This is done automatically after write is performed.

class BigWigRead:

This class is the interface for reading a bigWig.

def intervals(self, /, chrom, start=None, end=None):

Returns the intervals of a given range on a chromosome. The result is an iterator of (int, int, float) in the format (start, end, value). The intervals may not be contiguous if the values in the bigwig are not.

The chrom argument is the name of the chromosome.
The start and end arguments denote the range to get values for.
If end is not provided, it defaults to the length of the chromosome.
If start is not provided, it defaults to the beginning of the chromosome.

This returns an IntervalIterator.

def values( self, /, chrom, start=None, end=None, bins=None, summary=None, exact=None):

Returns the values of a given range on a chromosome. The result is an iterator of floats, of length (end - start).
If a value does not exist in the bigwig for a specific base, it will be nan.

This returns a numpy array.

def chroms(self, /, chrom=None):

Returns the chromosomes in a bigwig, and their lengths.

The chroms argument can be either String or None.
If it is None, then all chroms will be returned.
If it is a String, then the length of that chromosome will be returned.
If the chromosome doesn't exist, nothing will be returned.

class BigBedRead:

This class is the interface for reading a bigBed.

def entries(self, /, chrom, start=None, end=None):

Returns the entries of a given range on a chromosome. The result is an iterator of (int, int, String) in the format (start, end, rest).
The entries may not be contiguous if the values in the bigbed are not.
The chrom argument is the name of the chromosome.
The start and end arguments denote the range to get values for.
If end is not provided, it defaults to the length of the chromosome.
If start is not provided, it defaults to the beginning of the chromosome.

This returns an EntriesIterator.

def chroms(self, /, chrom=None):

Returns the chromosomes in a bigwig, and their lengths.
The chroms argument can be either String or None. If it is None, then all chroms will be returned. If it is a String, then the length of that chromosome will be returned.
If the chromosome doesn't exist, nothing will be returned.

class IntervalIterator:

This class is an iterator for Values from a bigWig.
It returns only values that exist in the bigWig, skipping any missing intervals.

class EntriesIterator:

This class is an interator for the entries in a bigBed file.