Metadata-Version: 2.5
Name: figwig
Version: 0.3.1
Summary: A fast, multithreaded reader and writer of bigWig files, into and out of numpy.
Project-URL: Homepage, https://github.com/jmschrei/figwig
Project-URL: Repository, https://github.com/jmschrei/figwig
Project-URL: Issues, https://github.com/jmschrei/figwig/issues
Project-URL: Documentation, https://figwig.readthedocs.io
Author-email: Jacob Schreiber <jmschreiber91@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: bigwig,bioinformatics,genomics,machine-learning
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.10
Requires-Dist: numba>=0.58
Requires-Dist: numpy>=1.23
Provides-Extra: bam2bw
Requires-Dist: biopython>=1.73; extra == 'bam2bw'
Requires-Dist: deflate>=0.9; extra == 'bam2bw'
Requires-Dist: isal>=1.8; extra == 'bam2bw'
Requires-Dist: pyfaidx>=0.8; extra == 'bam2bw'
Requires-Dist: pysam>=0.22; extra == 'bam2bw'
Requires-Dist: tqdm>=4.60; extra == 'bam2bw'
Provides-Extra: cuda
Requires-Dist: cupy-cuda12x>=13; extra == 'cuda'
Provides-Extra: dev
Requires-Dist: biopython>=1.73; extra == 'dev'
Requires-Dist: build>=1.0; extra == 'dev'
Requires-Dist: deflate>=0.9; extra == 'dev'
Requires-Dist: isal>=1.8; extra == 'dev'
Requires-Dist: kaitaistruct>=0.10; extra == 'dev'
Requires-Dist: pybigtools<0.3,>=0.2.5; extra == 'dev'
Requires-Dist: pybigwig>=0.3.26; (sys_platform != 'win32') and extra == 'dev'
Requires-Dist: pyfaidx>=0.8; extra == 'dev'
Requires-Dist: pysam>=0.22; (sys_platform != 'win32') and extra == 'dev'
Requires-Dist: pytest-xdist>=3.5; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Requires-Dist: tqdm>=4.60; extra == 'dev'
Requires-Dist: twine>=4.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: sphinx-rtd-theme>=2.0; extra == 'docs'
Requires-Dist: sphinx>=7.0; extra == 'docs'
Provides-Extra: fast
Requires-Dist: deflate>=0.9; extra == 'fast'
Provides-Extra: isal
Requires-Dist: isal>=1.8; extra == 'isal'
Description-Content-Type: text/markdown

# figwig

[![PyPI Downloads](https://static.pepy.tech/personalized-badge/figwig?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=ORANGE&left_text=downloads)](https://pepy.tech/projects/figwig) [![Unit Tests](https://github.com/jmschrei/figwig/actions/workflows/python-package.yml/badge.svg)](https://github.com/jmschrei/figwig/actions/workflows/python-package.yml) [![Documentation Status](https://readthedocs.org/projects/figwig/badge/?version=latest)](https://figwig.readthedocs.io/en/latest/?badge=latest)

[[docs](https://figwig.readthedocs.io/en/latest/index.html)][[release notes](https://figwig.readthedocs.io/en/latest/whats_new.html)]

A fast, multithreaded reader and writer of bigWig and figwig files, into and out of
numpy. Also contains a formal specification of the figwig file format, which holds
any number of per-base tracks over one genome with a JSON record of attributes for
each, and reads windows from any subset of them in one call, into
`(windows, tracks, width)`. `figwig bw2fw`, `fw2bw` and `bam2fw` convert bigWigs
and reads to and from a figwig file.

Built on work from Nezar Abdennur and Jack Huey.

Loading training data for a genomics model means reading the signal under tens
or hundreds of thousands of windows: 1,000 bp around every peak and background
region of an experiment, say. figwig reads all of them in one call, straight
into a float32 array, from one bigWig or from several at once, and writes
bigWigs from the same windows, such as a model's predictions, or from
intervals. The common readers make one call per window, and each call holds
Python's GIL, so adding threads does not help them. figwig decompresses and
compresses with zlib or libdeflate and decodes with numba, all without the
GIL, so its threads run in parallel. It depends only on numpy and numba.

Its command, `figwig bam2bw`, turns SAM/BAM files of reads, or BED/tsv files
of fragments, into bigWigs of per-base counts. It is
[bam2bw](https://github.com/jmschrei/bam2bw) with faster readers, the same
outputs, and `-c` added.

| | figwig | fastest other tool |
|---|---|---|
| Read 167,750 windows of 1,000 bp from an ATAC-seq bigWig | **0.103 s** on 8 threads | 1.25 s, pybigtools |
| Write 15.9 million per-base counts | **0.14 s** on 8 threads | 4.20 s, pyBigWig |
| Write 21.2 million intervals, with zoom levels | **0.45 s** on 8 threads | 5.47 s, pybigtools |
| Convert a 2.4 GB ATAC-seq BAM to two stranded bigWigs | **4.65 s**, 910 MB peak, at `-p 2` | 58.48 s, 3,039 MB peak, bam2bw 0.5.1 |
| The same BAM's per-base coverage, like deepTools | **1.6 s** at `-p 8` | 14.9 s on 8 processes, `bamCoverage --binSize 1`, the same value at every base |
| Read 8,192 windows of 2,048 bp from 48 count tracks on chr1 | **0.071 s** on 8 threads, **0.040 s** on 32, from one figwig file | 0.19 s and 0.083 s from 48 bigWigs, figwig; 5.9 s pybigtools; 4.0 s zarr |
| A DataLoader batch of 64 windows x 48 tracks as a CUDA tensor | **4 ms** from one figwig file | 30 ms from the bigWigs, figwig; 120 ms pybigtools |
| 10 pseudobulks of 10,246 cells over 8,192 windows | **0.23 s** on 8 threads | 4.9 s from an in-memory scipy CSR; 95 s from one bigWig per cell |
| Convert 257.6 million 10x fragments to 10,246 per-cell tracks | **8 s** at `-p 8`, **3.9 s** at `-p 32`, 19 GB peak | 140 s, 24 GB, a pandas recipe; 217 s, 8 GB, SnapATAC2 (fragments, not counts) |

Measured on a 2x AMD EPYC 9575F with Python 3.13 and numba 0.68. The
[benchmarks page](https://figwig.readthedocs.io/en/latest/benchmarks.html) has
every setup, the other tables (figwig files against bigWigs, zarr and HDF5 at
6, 48 and 512 tracks; writers; threads) and the plots.

<!-- readme-table:start -->
<details>
<summary>Read time, write time and file size by assay, against what most people use today</summary>

Each cell is figwig against the baseline, figwig first, in bold where it is smaller. figwig ran on 8 threads unless a note says otherwise; each baseline is given its fastest setting (the other tools mostly do not gain from threads). Reads are windows of 2,048 bp unless noted. The Hi-C reads run on one thread, figwig and cooler alike.

| Setting | Baseline | Read | Write | Size |
|---|---|---|---|---|
| 1 ATAC-seq track, 167,750 windows of 1,000 bp on random signal bases and negatives | one bigWig; read by pybigtools, written by pyBigWig | **98.4 ms** vs 1.86 s (pybigtools, 1 thread, sorted windows) | **0.245 s** vs 8.13 s (pyBigWig, 1 thread) | **64.4 MB** vs 64.4 MB (pyBigWig) |
| 48 count tracks over chr1, 8,192 windows of 2,048 bp | one bigWig per track; read by pybigtools, written by pyBigWig | **72.7 ms** vs 4.68 s (pybigtools, 1 thread) | **2.04 s** vs 69.4 s (pyBigWig, 1 thread) | **97.2 MB** vs 1.08 GB (pyBigWig) |
| 1,024 count tracks over chr1, 1,024 windows of 2,048 bp | one bigWig per track; read by pybigtools, written by figwig | **0.172 s** vs 22.4 s (pybigtools, 1 thread) | **33.2 s** vs 497 s (bigWigs written by figwig from a file of groups of 8; pyBigWig not run) | **2.04 GB** vs 21.2 GB (the bigWigs written by figwig; pyBigWig not run) |
| 10x PBMC scATAC-seq, 10,246 cells, 492 million cut sites; reads: 10 pseudobulks over 8,192 windows of 2,048 bp on K562 ATAC peaks | SnapATAC2 (write, size) and a scipy CSR matrix in memory (read) | **0.289 s** vs 0.445 s (scipy CSR, 8 threads) | **8.27 s** vs 218 s (SnapATAC2, 8 threads) | 1.11 GB vs 1.02 GB (SnapATAC2, which stores fragments rather than per-base counts) |
| K562 Fiber-seq BAM, 99,685 alignments, 886 MB; reads: m6A summed over all reads in 8,192 windows of 2,048 bp | a pysam loop with `modified_bases` (write), the BAM (size) and a scipy CSR matrix in memory (read) | **86.4 ms** vs 0.263 s (scipy CSR, 1 thread) | **9.52 s** vs 245 s (pysam, 1 thread, m6A and 5mC placed, nothing written) | **605 MB** vs 886 MB (the BAM) |
| K562 Hi-C, 5 kb, 907M contacts; 2 Mb diagonal window as a dense 400 x 400 block | cooler (Python API) | window: **0.878 ms** vs 18.9 ms | 47.6 s vs 42.3 s | 979 MB vs 748 MB |
| Single-cell Hi-C, mouse ES cells (Nagano 2017), 3,882 cells, 10 kb, 626M contacts; 2 Mb diagonal window summed over the cells of 4 labels, (4, 200, 200), and one whole cell | scool (cooler) | pseudobulk window: **14.8 ms** vs 23.6 s; one cell: 8.09 s vs 14 ms | **60 s** vs 314 s | **1.45 GB** vs 1.95 GB |

- The 1,024-track baseline write and size are the 1,024 bigWigs figwig wrote with 10 zoom levels (497 s, 21.2 GB); pyBigWig was not run at that size.
- scATAC-seq: figwig and SnapATAC2 hold the same 491,845,610 fragment ends of the 10,246 called cells (every cell's figwig total is twice its SnapATAC2 fragment count), and figwig and the scipy matrix gave identical sums over the windows.
- The scipy matrix is 14.8 GB in memory (the read times leave out building it and opening the figwig file, which takes 5 ms), where the figwig file is 1.11 GB.
- SnapATAC2 stores each cell's fragments, so counts over windows or peaks are still to be computed from its output.
- Fiber-seq: figwig and the pysam pass agree on the m6A total of each of the 99,685 alignments over its span, and on the sums over the windows (the file and the matrix both hold the 0 to 255 probabilities).
- The pysam loop places 204,449,545 m6A and 15,488,000 5mC calls and keeps only the m6A calls, in a scipy matrix of 13.4 GB that the read time leaves out building; the figwig file also holds the 5mC, nucleosome, MSP and FIRE channels.
- Reading times leave out opening the figwig file, which takes 1.39 s here, and loading the scipy matrix.
- With both triangles (1.79 GB at 5 kb) the figwig file also reads a bin's whole row in 36.2 ms against cooler's 8.97 s.
- With one track per cell in track order (level 6, 2.47 GB) the figwig file reads one whole cell in 12.2 ms.

Measured by `benchmarks/readme_table/run.py` on 2026-11-11 on AMD EPYC 9575F 64-Core Processor (256 cores), figwig 0.3.0 at 2858597; the numbers are in `benchmarks/readme_table/results.json`.

</details>
<!-- readme-table:end -->

## Installation

```bash
pip install figwig
```

Or, with [uv](https://docs.astral.sh/uv/):

```bash
uv add figwig
```

It needs Python 3.10 or later, numpy 1.23 or later, and numba 0.58 or later.
Optional extras:

- `figwig[fast]` adds the `deflate` package, which writes bigWigs several
  times faster and reads figwig files about twice as fast.
- `figwig[isal]` adds the `isal` package, whose ISA-L reads bigWigs 1.3 to 1.6
  times faster, with the same values.
- `figwig[bam2bw]` adds pysam, pyfaidx, biopython, tqdm, isal and deflate,
  which `figwig bam2bw` needs. `figwig bam2bw` runs on Linux and macOS, since
  pysam does not support Windows.
- `figwig[cuda]` adds cupy (for CUDA 12; install `cupy-cuda13x` or
  `cupy-cuda11x` otherwise), with which `FigWigReader.read(..., device="cuda")`
  lands windows in GPU memory, for `torch.from_dlpack` and its JAX and
  TensorFlow equivalents.

```bash
pip install "figwig[fast]"
pip install "figwig[isal]"
pip install "figwig[bam2bw]"
pip install "figwig[cuda]"
```

### Development install

```bash
git clone https://github.com/jmschrei/figwig.git
cd figwig
uv sync --extra dev
uv run pytest -n 8    # the tests on 8 cores; the first run compiles the kernels
```

## Claude Code Skill

figwig ships a [Claude Code](https://claude.com/claude-code) skill that
teaches a coding agent to use figwig in any project: reading windows,
writing predictions, intervals and counts, converting reads with
`figwig bam2bw`, figwig files and their converters, the rules a write
follows, what each error means, and how much threads gain. Install it into
`~/.claude/skills/figwig` with:

```bash
figwig install-skill
```

After upgrading figwig, run `figwig install-skill --force` to replace the
installed copy, which it otherwise leaves, with a message. `-d DIRECTORY`
installs into another skills directory, and `--symlink` links to the copy
inside the installed package instead of copying it.

## Python API

The examples read two public ENCODE bigWigs: the ATAC-seq signal of HG02943
(ENCFF830RWF, 238 MB) and the DNase-seq signal of dorsolateral prefrontal
cortex (ENCFF989SAK, 645 MB).

```bash
wget https://www.encodeproject.org/files/ENCFF830RWF/@@download/ENCFF830RWF.bigWig
wget https://www.encodeproject.org/files/ENCFF989SAK/@@download/ENCFF989SAK.bigWig
```

#### Reading windows

```python
import numpy
from figwig import BigWigReader

bw = BigWigReader("ENCFF830RWF.bigWig")
chroms = numpy.array(["chr1", "chr1", "chr2"])
starts = numpy.array([1_000_000, 2_500_000, 300_000])
y = bw.read(chroms, starts, width=1000, n_jobs=8)
print(y.shape, y.dtype)
# (3, 1000) float32
print(y.sum(axis=1))
# [116.  43.  10.]
```

Window `j` covers `[starts[j], starts[j] + width)` on `chroms[j]`, 0-based as
in BED files, and is written into row `j`, whatever order the windows are
given in. A base that no interval covers is `missing`, 0 unless given, and a
base past the end of its chromosome is NaN, or `oob` if given. A
`BigWigReader` reads the file's index once and keeps it, and can be pickled to
DataLoader workers.

#### Reading several bigWigs into one array

```python
import numpy
from figwig import read_bigwig

chroms = numpy.array(["chr1", "chr1", "chr2"])
starts = numpy.array([1_000_000, 2_500_000, 300_000])
y = read_bigwig(["ENCFF830RWF.bigWig", "ENCFF989SAK.bigWig"], chroms, starts,
	width=1000)
print(y.shape)
# (3, 2, 1000)
```

Channel `i` holds the values from the `i`-th file, in the
`(batch, channels, length)` layout that sequence models take, and every
file's work shares one pool of threads.

#### Writing windows

```python
import numpy
from figwig import read_bigwig
from figwig import write_bigwig

chrom_sizes = {"chr1": 248_956_422, "chr2": 242_193_529}
chroms = numpy.array(["chr2", "chr1", "chr1"])
starts = numpy.array([300_000, 2_500_000, 1_000_000])
y_hat = numpy.random.default_rng(0).random((3, 2, 1000), dtype=numpy.float32)

write_bigwig(["plus.bw", "minus.bw"], chrom_sizes, chroms, starts, y_hat)
y = read_bigwig(["plus.bw", "minus.bw"], chroms, starts, width=1000)
print(numpy.array_equal(y, y_hat))
# True
```

`write_bigwig` takes what `read_bigwig` gives, such as a model's predictions
for the same windows. A base whose value is `missing`, 0.0 unless given, or
NaN is left out of the file, so that reading with the same `missing` gives
the values back.

#### Writing a batch at a time

```python
from figwig import BigWigReader
from figwig import BigWigWriter

chrom_sizes = {"chr1": 248_956_422, "chr2": 242_193_529}
with BigWigWriter("example.bw", chrom_sizes) as writer:
	writer.write("chr1", [1000, 2000], [0.5, 2.0], ends=[1500, 2100])
	writer.write("chr1", [5000, 5003, 5004], [[3], [1], [1]])
	writer.write("chr2", [10_000], [[0.0, 1.5, 1.5, 0.0, 2.5]])

y = BigWigReader("example.bw").read(["chr1", "chr2"], [5000, 10_000], width=6)
print(y)
# [[3.  0.  0.  1.  1.  0. ]
#  [0.  1.5 1.5 0.  2.5 0. ]]
```

`BigWigWriter` writes intervals (with `ends`), single bases (windows of width
1) and windows as they come, so a track larger than memory can be written a
batch at a time. Each call's items come after the last call's, in the order
of `chrom_sizes`. The header, index and zoom levels are written when the
writer is closed.

#### Reading and writing figwig files

```python
import numpy
from figwig import FigWigReader
from figwig import FigWigWriter

chrom_sizes = {"chr1": 248_956_422, "chr2": 242_193_529}
tracks = [
	{"name": "atac.+", "assay": "ATAC-seq", "strand": "+"},
	{"name": "atac.-", "assay": "ATAC-seq", "strand": "-"},
]
counts = numpy.random.default_rng(0).poisson(0.1, (3, 2, 2114))
chroms = numpy.array(["chr2", "chr1", "chr1"])
starts = numpy.array([300_000, 2_500_000, 1_000_000])

with FigWigWriter("example.fw", chrom_sizes, tracks, genome="hg38") as fw:
	fw.write(chroms, starts, counts)

fw = FigWigReader("example.fw")
y = fw.read(chroms, starts, width=2114, tracks=fw.select(strand="+"))
print(y.shape, y.dtype, numpy.array_equal(y[:, 0], counts[:, 0]))
# (3, 1, 2114) uint8 True
```

A figwig file holds many tracks over one genome, each with attributes that
`select` matches, and is read like a bigWig: many windows of one width in
one call, from any subset of the tracks, into `(windows, tracks, width)` in
the tracks' own dtype. The same read gives the nonzero bases as a sparse
list with `sparse=True`, the tracks summed per label with `labels=`, or
each window summed per bin with `bins=`; `sums` gives each track's total
over intervals of any lengths; `tile_sums` gives each track's sum per tile,
or per bin of a zoom level, without decoding a chunk; and `device="cuda"`
lands the output of `read` and `sums` in GPU memory, where
`torch.from_dlpack` takes it without a copy. A base no track wrote is 0, as
is a bigWig's no-data unless `bw2fw --missing nan` keeps them apart.

A file is written in position order, for reading windows across many
tracks, or in track order, for reading a few tracks over the genome, and
`figwig reorder` rewrites it in the other; `write_sparse` takes nonzero
bases as entries, such as the cut sites of single cells. `fw.tracks`,
`fw.stats` and `fw.chrom_sizes` say what a file holds, as `figwig info`
does from the shell. The first read of each kind in a new environment
compiles its kernels, with nothing printed meanwhile; numba caches them
beside the package, or in the user's cache directory when the package
directory is read-only, and `NUMBA_CACHE_DIR` chooses another.

The [figwig files](https://figwig.readthedocs.io/en/latest/figwig.html) guide
covers the layout, the API and the converters, and
[the format page](https://figwig.readthedocs.io/en/latest/format.html)
specifies the format byte by byte, with a Kaitai Struct definition and a
reference reader. The
[reading](https://figwig.readthedocs.io/en/latest/reading.html) and
[writing](https://figwig.readthedocs.io/en/latest/writing.html) guides cover
values and coordinates, chromosomes a file does not have, PyTorch data
loaders, binned values, the files figwig refuses and falling back to another
reader, compression, zoom levels, and files identical to pyBigWig's.

## Command line

#### figwig bam2bw

```bash
figwig bam2bw my.bam -s hg38.chrom.sizes -n test-run -p 8                  # test-run.+.bw, test-run.-.bw
figwig bam2bw fragments.tsv.gz -s hg38.chrom.sizes -n test-run -f -u -p 8  # test-run.bw
```

`figwig bam2bw` is bam2bw 0.5.1 with the same arguments, output files and
messages, except that `-p` is a number of cores, 1 unless given, `-c` is new,
and a BAM whose header disagrees with the sizes is reported on stderr first.
By default it counts the 5' end of every mapped read at each base and writes
the two strands to two bigWigs; `-u` writes one, `-f` counts both ends of each
fragment, `-3p` the 3' ends, `-c` every aligned base of each read (the
coverage deepTools' `bamCoverage` gives), `-ps`, `-ns`, `-sf` and `-r` shift
and scale the counts, and `-z` writes zoom levels. SAM files, `--mate_pairs`,
remote files and malformed records go through bam2bw's own pysam or line
loop, so that their result, or their error, is bam2bw's. The bigWigs hold
bam2bw's entries but not its bytes. `figwig bam2bw -h` lists the arguments,
and the [documentation](https://figwig.readthedocs.io/en/latest/bam2bw.html)
says how files are read and shared across cores.

#### figwig bw2fw, fw2bw, bam2fw, fiberbam2fw, reorder, merge and info

```bash
figwig bw2fw -o k562.fw -m tracks.tsv -g hg38 -p 8 atac.+.bw atac.-.bw dnase.bw   # bigWigs -> k562.fw
figwig fw2bw k562.fw -o bigwigs -p 8 --select assay=ATAC-seq                      # tracks -> bigwigs/<name>.bw
figwig bam2fw a.bam b.bam -s hg38.chrom.sizes -n k562 -m files.tsv -p 8          # reads -> k562.fw
figwig bam2fw fragments.tsv.gz -s hg38.chrom.sizes -n pbmc --barcode-column 4 --cells cells.tsv -f -p 8   # a track per cell
figwig fiberbam2fw fibers.bam -n fibers -g hg38 -p 8                               # Fiber-seq reads -> a track per read and channel
figwig reorder k562.fw by_track.fw --order tracks                                # the other order
figwig merge -o all.fw k562.fw hepg2.fw                                          # files -> one file
figwig info k562.fw                                                              # what the file holds
```

`figwig bw2fw` writes bigWigs as the tracks of one figwig file, named after
their files or by a metadata table whose other columns become the tracks'
attributes, or adds them to a file with `--append`; `figwig fw2bw` writes a
figwig file's tracks back as bigWigs with such a table; `figwig bam2fw`
takes `figwig bam2bw`'s arguments and writes each input file as its own pair
of stranded tracks, or a fragments file as one track per cell with
`--barcode-column`; `figwig fiberbam2fw` writes a Fiber-seq BAM as five tracks per
read (m6A and 5mC probabilities, nucleosomes, MSPs, FIRE quality) with the
read's alignment and tags as attributes; `figwig reorder` rewrites a file in the other order;
`figwig merge` copies several files' tracks into one; and `figwig info`
prints a file's tracks, attributes and statistics. The
[converters](https://figwig.readthedocs.io/en/latest/converters.html) page
has the options.

#### figwig install-skill

Installs the Claude Code skill; see [above](#claude-code-skill).

## Origin

figwig began as the bigWig reader inside
[tangermeme](https://github.com/jmschrei/tangermeme)'s `extract_loci`
(PR #107). It was checked there against pybigtools, bit for bit, on the
training and validation sets of 92 Cherimoya models and on 3,131 synthetic
cases.
