DOCSEARCHbyAlgolia
Submit Docs

pyBigWig

repository·master·Indexed 42 days ago

https://github.com/deeptools/pybigwig

A Python extension for reading and writing bigWig and bigBed files using libBigWig. It provides high-performance access to genomic interval data using 0-based half-open coordinates and supports NumPy arrays for optimized operations. Version 0.3.26.

Tokens
1.8K
Snippets
6
Records
11
Agent score
54%

What's inside pyBigWig

  1. Explore Python interfaces for libBigWig

    master

    There are two primary Python interfaces available that utilize libBigWig:

    1. pyBigWig: The primary interface maintained in this repository.
    2. bw-python: An alternative interface maintained by Brent Pederson.

    Developers are encouraged to test both to see which best fits their requirements.

  2. Coordinate system in pyBigWig

    master

    pyBigWig uses 0-based half-open coordinates, consistent with Wiggle, bigWig, and bigBed formats.

    • To access the first base on chr1, use start=0 and end=1.
    • To access bases 100 to 115, use start=99 and end=115.

  3. Use Numpy with pyBigWig

    master

    If numpy was installed prior to installing pyBigWig, the library supports numpy arrays for high-performance operations.

    • Check support: Verify with pyBigWig.numpy == 1.
    • Input: addEntries() can accept numpy arrays for coordinates and values.
    • Output: values() can return a numpy vector if numpy=True is passed as an argument.
    >>> import pyBigWig
>>> import numpy
>>> pyBigWig.numpy
1

>>> # Using numpy for input
>>> bw.addEntries(chroms, starts, ends=ends, values=values0)

>>> # Using numpy for output
>>> bw.values('1', 0, 10, numpy=True)
array([ 0.74336642, ...])

  4. Understand bigWig statistics behavior

    master
    When using the library to compute statistics, note that min, max, and mean are expected to match the results produced by BigWigSummary. However, stdev and coverage results may differ from Kent's tools, as Kent's tools are noted to potentially produce incorrect results for these specific metrics.

  5. Install pyBigWig

    master

    You can install the pyBigWig extension using pip or conda.

    Requirements

    Before installing, ensure the following non-Python dependencies are installed on your system (including their headers and libraries):

    • libcurl (and the curl-config configuration tool)
    • zlib
    # Using pip
pip install pyBigWig

# Using conda
conda install pybigwig -c conda-forge -c bioconda

  6. Add entries to a bigWig file

    master

    Entries in a bigWig file must be added in order. pyBigWig supports three internal storage formats via the addEntries() method:

    1. bedGraph format: Uses chroms, starts, ends, and values lists. bw.addEntries(["chr1", "chr1"], [0, 100], ends=[5, 120], values=[0.0, 1.0])
    2. variableStep format: Uses a fixed span and variable step sizes. bw.addEntries("chr1", [500, 600, 635], values=[-2.0, 150.0, 25.0], span=20)
    3. fixedStep format: Uses a fixed step and fixed span. bw.addEntries("chr1", 900, values=[-5.0, -20.0, 25.0], span=20, step=30)

    Validation: pyBigWig validates that entries are added in order. To skip this check for performance (at your own risk), use validate=False.

    >>> # bedGraph style
>>> bw.addEntries(["chr1", "chr1", "chr1"], [0, 100, 125], ends=[5, 120, 126], values=[0.0, 1.0, 200.0])

>>> # variableStep style
>>> bw.addEntries("chr1", [500, 600, 635], values=[-2.0, 150.0, 25.0], span=20)

>>> # fixedStep style
>>> bw.addEntries("chr1", 900, values=[-5.0, -20.0, 25.0], span=20, step=30)

>>> # Disabling order validation
>>> bw.addEntries(["chr1", "chr1", "chr1"], [100, 0, 125], ends=[120, 5, 126], values=[0.0, 1.0, 200.0], validate=False)

  7. Retrieve bigBed entries using entries()

    master

    bigBed files contain entries consisting of intervals and an associated string. Use the entries(chrom, start, end, withString=True) method to retrieve them.

    • Return value: A list of tuples. Each tuple contains (start, end, associated_string).
    • String format: The string is returned exactly as stored in the file. To understand the fields within the string, call bb.SQL() to see the table definition.
    • Memory optimization: If you only need the interval positions and not the data string, set withString=False. This returns a list of (start, end) tuples.
    >>> bb = pyBigWig.open("https://www.encodeproject.org/files/ENCFF001JBR/@@download/ENCFF001JBR.bigBed")
>>> bb.entries('chr1', 10000000, 10020000)
[(10009333, 10009640, '61035\t130\t-\t0.026\t0.42\t404'), (10014007, 10014289, '61047\t136\t-\t0.029\t0.42\t404'), (10014373, 10024307, '61048\t630\t-\t5.420\t0.00\t2672399')]

>>> bb.entries('chr1', 10000000, 10020000, withString=False)
[(10009333, 10009640), (10014007, 10014289), (10014373, 10024307)]

  8. Add a header to a bigWig file

    master

    When opening a file for writing, you must add a header before adding entries. The header defines the chromosomes and their lengths in a specific order.

    • Format: A list of tuples [(chrom, length), ...].
    • Case Sensitivity: Chromosome names are case-sensitive (e.g., chr1 vs Chr1).
    • Zoom Levels: By default, up to 10 zoom levels are created. You can set maxZooms=0 to create a file with only intervals and no zoom levels, but note that tools like IGV may not work with maxZooms=0.
    >>> bw.addHeader([("chr1", 1000000), ("chr2", 1500000)])
>>> bw.addHeader([("chr1", 1000000), ("chr2", 1500000)], maxZooms=0)

  9. Check remote file access support

    master

    The ability to access remote files depends on whether curl was available during installation. Check support using the pyBigWig.remote attribute:

    • 1: Remote access is supported.
    • 0: Remote access is not supported.
    >>> pyBigWig.remote
1

  10. Read bigWig files in C

    master

    To read data from a bigWig file using the C API, you must first initialize the library with bwInit(), then open the file using bwOpen(). You can access values in a range, retrieve overlapping intervals, or compute statistics.

    Key functions:

    • bwInit(size_t size): Initializes the library. The size parameter specifies the amount of space to allocate for data (e.g., 1<<17 for 128KiB).
    • bwOpen(const char *filename, const char *url, const char *mode): Opens a local or remote file. Use mode `

  11. Open a bigWig or bigBed file

    master

    Use pyBigWig.open() to open a file. This works for both local files and remote URLs (e.g., via HTTPS).

    • Default mode: Files are opened for reading. If the file does not exist, the function returns None and prints an error message.
    • Write mode: Pass `