pyBigWig: Accessing BigWig Files

Common errors

• FileNotFoundError: [Errno 2] No such file or directory: 'non_existent.bigWig'

  cause The bigWig file specified in `pyBigWig.open()` does not exist at the provided path.
  fix Verify the file path is correct and the file exists. Use an absolute path or ensure the relative path is accurate from where the script is run.

• ValueError: Function is not allowed on a file opened for writing.

  cause You are calling a read-only method (e.g., `values()`, `stats()`, `intervals()`) on a `pyBigWig` object that was opened with the mode `'w'` (write mode).
  fix If you intend to read data, open the file in read mode: `bw = pyBigWig.open('my.bigWig', 'r')` (or simply `pyBigWig.open('my.bigWig')` as 'r' is default).

• TypeError: Expected a list of tuples for addHeader, got <class 'dict'>

  cause The `addHeader()` method expects chromosome sizes as a list of `(chromosome_name, size)` tuples, but a dictionary was provided.
  fix Convert your dictionary of chromosome sizes to the required list of tuples: `bw_write.addHeader([(name, size) for name, size in chrom_sizes_dict.items()])`.

• Exception: There are no entries in the bigWig file.

  cause The bigWig file you are trying to query is genuinely empty, or in older versions (pre-0.3.25) there might have been misinterpretation of empty files.
  fix For genuinely empty files, handle this condition in your code (e.g., check `bw.is_empty()`). If you suspect a library issue, ensure you are on `pyBigWig` version 0.3.25 or later.

Warnings

• gotcha Explicitly close bigWig file objects using `bw.close()` after use to prevent potential memory leaks, especially when processing many files in a single session.
  Fix: Always call `bw.close()` for opened bigWig files. This issue was largely addressed in v0.3.17 but good practice remains.
• gotcha Attempting to perform read operations (e.g., `values()`, `stats()`) on a `pyBigWig` object opened in write mode (`'w'`) will result in an error.
  Fix: Ensure the file is opened in read mode (`'r'`, which is the default) for reading, or create a separate `pyBigWig` object for reading if simultaneous read/write-like logic is required.
• breaking Versions prior to 0.3.25 could incorrectly report a single random entry for a genuinely empty bigWig file, and versions prior to 0.3.18 might misinterpret bigWig files with all zero summary values as empty.
  Fix: Update to `pyBigWig` version 0.3.25 or later to ensure correct handling of empty files and files with zero summary values.
• gotcha BigWig files where the chromosome order in the header differs from the data sections could lead to issues.
  Fix: Update to `pyBigWig` version 0.3.24 or later, which includes a fix to handle such cases correctly.

Install

• pip install pyBigWig Install stable version

Imports

• pyBigWig

  import pyBigWig

Quickstart

This quickstart demonstrates how to create a simple bigWig file with dummy data, then open it in read mode to extract values, summary statistics, and intervals from specific genomic regions. It also shows the importance of closing the file handles.

import pyBigWig
import os

# Define a temporary bigWig file name
temp_bw_file = "temp_quickstart.bigWig"

# --- Writing a new bigWig file for demonstration ---
# Chromosome sizes are required for writing
chrom_sizes = {"chr1": 100000, "chr2": 50000}
bw_write = pyBigWig.open(temp_bw_file, "w")
bw_write.addHeader([(name, size) for name, size in chrom_sizes.items()])

# Add some dummy entries
bw_write.addEntries(
    ["chr1"] * 5,
    [0, 100, 200, 300, 400],
    [99, 199, 299, 399, 499],
    [0.1, 0.2, 0.3, 0.4, 0.5]
)
bw_write.addEntries("chr1", 5000, 5010, [1.0]*10, step=1, span=1)
bw_write.addEntries("chr2", 1000, 1005, [2.0]*5, step=1, span=1)
bw_write.close()
print(f"Created dummy bigWig file: {temp_bw_file}\n")

# --- Reading from the bigWig file ---
bw = pyBigWig.open(temp_bw_file)

print(f"Chromosomes found: {bw.chroms()}\n")

# Get values from a specific region on chr1
values_chr1 = bw.values("chr1", 0, 500)
print(f"Values on chr1 (0-500, first 10): {values_chr1[:10]}...\n")

# Get summary statistics for a region
summary_chr1 = bw.stats("chr1", 0, 1000, type="mean")
print(f"Mean value on chr1 (0-1000): {summary_chr1[0]}\n")

# Get intervals (start, end, value) for a region
intervals_chr1 = bw.intervals("chr1", 0, 1000)
print(f"Intervals on chr1 (0-1000, first 3): {intervals_chr1[:3]}...\n")

# Close the bigWig file to release resources
bw.close()

# Clean up the temporary file
if os.path.exists(temp_bw_file):
    os.remove(temp_bw_file)
    print(f"Cleaned up temporary file: {temp_bw_file}")