v1.0 · MIT

genomeblocks

Fluent building blocks for regulatory genomics — from peaks to chromatin networks in a handful of expressive chained calls.

Works with ChIP-seq ATAC-seq Hi-C · HiChIP GTF / GENCODE BigWig JASPAR motifs

Quickstart → View on GitHub

Why genomeblocks?

Regulatory-genomics analyses usually end up as a cocktail of bedtools, PyRanges, cooler, pyBigWig, GTF parsing boilerplate, graph libraries, and one-off heatmap code. genomeblocks unifies those pieces behind a small set of composable objects, grouped into three color-coded families:

LociIntervals A list-of-intervals container with set algebra (&, |, -, ^), slop, sort, merge, nearest, indexed overlap queries, and signal extraction.
LocusIntervals A single interval with a canonical UID (chrom:start-end(strand)) used everywhere as a stable key.
signalIntervals Threaded bigWig extraction (pybigtools backend, pure-Python fallback), TMM normalization, and comparative heatmaps.
GenesAnnotation GENCODE / GTF / UCSC parser yielding Gene → Transcript → Exon/CDS/UTR hierarchies, with enhancer-to-gene assignment in one call.
motifsAnnotation JASPAR motif scanning over a FASTA genome; TF family lookups and enrichment helpers.
AtlasAnnotation GIGGLE-style enrichment of a region set against thousands of BED tracks (ChIP-Atlas scale) via one sparse index.
ArchitectureNetworks A chromatin-contact graph (graph-tool) built from BEDPE loops or mcool matrices; distance-decay O/E normalization, gene annotation, hub discovery.
bedpeNetworks BEDPE parsing + pair-to-bed intersection for loops and pairwise-interval data.
browserNetworks An IGV-like, SVG-clean multi-track region viewer built on matplotlib.

Everything is chainable: the output of one stage is always a first-class object accepted by the next.

60-second example

Three stages, each one a pure object you can hand to the next:

from genomeblocks import Architecture, Genes, Loci

# ① CREs: ATAC peaks, extended ±100 bp, sorted, merged
cre = (Loci.make("atac_peaks.narrowPeak")
           .slop(100)
           .sort()
           .merge())

# Super-enhancers that overlap CREs
se = cre.intersect(Loci.make("H3K27ac_SE.bed"))

# ② Contact graph: CRE-resolved HiChIP loops, Hi-C weights, O/E normalization
arch = (Architecture.make(cre, "RNAP_loops.bedpe", r=2500)
                    .add_mcool(cre, "RNAP.mcool", resolution=5000)
                    .normalize(cre))

# ③ Gene annotation: which annotation class does each super-enhancer fall into?
genes = Genes.make("gencode.v38.annotation.gtf", promoter_r=1000)
counts = genes.annotations(se & cre).groupby("annotation").size()

1 Build intervals. Peaks → CREs via Loci.

2 Wire the network. Loops + contacts via Architecture.

3 Annotate. Gene classes for each CRE via Genes.

Documentation map

Section	When to read it
Installation	Setup with conda or pip.
Quickstart	A 10-minute tour end-to-end.
Concepts	The mental model — UIDs, lazy indexes, chainable APIs.
Example: AR & FOXA1	A complete real-data walkthrough, concept by concept.
User Guide → Loci	Interval algebra in depth.
User Guide → Genes	GTF parsing & enhancer-to-gene.
User Guide → Architecture	Chromatin-contact networks.
User Guide → Signal	BigWig extraction & heatmaps.
User Guide → Browser	Multi-track region plots.
User Guide → BEDPE	Loops & paired intervals.
User Guide → Motifs	TF motif scanning.
API Reference	Full method signatures.
User Guide → Atlas	GIGGLE-style enrichment against BED collections.
Release Notes	What’s in v1.0 and the fixes it ships.
Credits	Upstream tools & citations.

Citing

If genomeblocks is useful in your work, please cite the GitHub repository:

Altintas, U. B. (2024). genomeblocks: Fluent building blocks for regulatory genomics.
https://github.com/birkiy/genomeblocks

genomeblocks stands on top of several excellent upstream libraries — please also cite the ones whose module was load-bearing in your analysis. The Credits page lists them all with BibTeX.

License

MIT. See LICENSE.