Metadata-Version: 2.4
Name: genomeblocks
Version: 2.0.1
Summary: Fluent building blocks for regulatory genomics, as columnar tables.
Author: Umut Berkay Altintas
License: MIT License
Project-URL: Homepage, https://birkiy.github.io/genomeblocks/
Project-URL: Documentation, https://birkiy.github.io/genomeblocks/
Project-URL: Repository, https://github.com/birkiy/genomeblocks
Project-URL: Issues, https://github.com/birkiy/genomeblocks/issues
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
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: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: pandas>=2.0
Requires-Dist: pyarrow
Requires-Dist: narwhals>=1.0
Requires-Dist: scipy
Requires-Dist: matplotlib
Requires-Dist: pybigtools>=0.2
Requires-Dist: cooler
Requires-Dist: tqdm
Provides-Extra: motifs
Requires-Dist: MOODS-python; extra == "motifs"
Provides-Extra: lightmotif
Requires-Dist: lightmotif; extra == "lightmotif"
Provides-Extra: fast
Requires-Dist: polars; extra == "fast"
Provides-Extra: bam
Requires-Dist: pysam; extra == "bam"
Provides-Extra: viz
Requires-Dist: logomaker; extra == "viz"
Provides-Extra: interop
Requires-Dist: polars; extra == "interop"
Requires-Dist: bioframe; extra == "interop"
Requires-Dist: pyranges; extra == "interop"
Requires-Dist: pybedtools; extra == "interop"
Requires-Dist: anndata; extra == "interop"
Requires-Dist: xarray; extra == "interop"
Requires-Dist: biopython; extra == "interop"
Requires-Dist: networkx; extra == "interop"
Requires-Dist: igraph; extra == "interop"
Requires-Dist: MOODS-python; extra == "interop"
Requires-Dist: pyBigWig; extra == "interop"
Requires-Dist: ncls; extra == "interop"
Requires-Dist: pyfaidx; extra == "interop"
Requires-Dist: pyliftover; extra == "interop"
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pysam; extra == "test"
Requires-Dist: polars; extra == "test"
Requires-Dist: bioframe; extra == "test"
Requires-Dist: pyranges; extra == "test"
Requires-Dist: pybedtools; extra == "test"
Requires-Dist: anndata; extra == "test"
Requires-Dist: xarray; extra == "test"
Requires-Dist: biopython; extra == "test"
Requires-Dist: networkx; extra == "test"
Requires-Dist: igraph; extra == "test"
Requires-Dist: MOODS-python; extra == "test"
Requires-Dist: pyBigWig; extra == "test"
Requires-Dist: ncls; extra == "test"
Requires-Dist: pyfaidx; extra == "test"
Requires-Dist: duckdb; extra == "test"
Requires-Dist: seaborn; extra == "test"
Requires-Dist: plotly; extra == "test"
Requires-Dist: altair; extra == "test"
Requires-Dist: logomaker; extra == "test"
Requires-Dist: lightmotif; extra == "test"
Provides-Extra: all
Requires-Dist: genomeblocks[bam,fast,interop,motifs,viz]; extra == "all"
Dynamic: license-file

Genomeblocks
============

Fluent building blocks for regulatory genomics, as columnar tables.

- `Loci`: interval tables with set algebra (`& | - ^`), `slop` / `sort` / `merge` / `nearest`, indexed lookups and signal extraction.
- `Genes`: GTF / GFF3 / UCSC gene models as three linked tables (genes, transcripts, features); annotation and ATAC-supported isoforms.
- `Pairs` and `Architecture`: BEDPE loops and the chromatin-contact graph over CREs — Hi-C weights from `.mcool`, O/E normalisation, hubs.
- `signal`: bigWig signal cubes, TMM normalisation, heatmaps; `motifs`: motif scanning with any engine; `Atlas`: GIGGLE-style enrichment.
- `browser`, `igv_html`, `View`: a matplotlib region view, a shareable IGV page and a one-file interactive browser.

Every table hands itself to pandas, polars, Arrow, bioframe, pyranges, pybedtools, AnnData, duckdb, seaborn and friends, and takes their frames back. The heavy work runs through swappable backends (numpy / cgranges / ncls / bioframe / pyranges / bedtools for intervals, pybigtools / pyBigWig / pure Python for bigWigs, MOODS / lightmotif / Biopython for motifs, graph-tool / scipy / igraph / networkx for graphs, ...) with the same answer whichever engine runs.

📖 **Documentation**: [birkiy.github.io/genomeblocks](https://birkiy.github.io/genomeblocks/) — start with the [quickstart](https://birkiy.github.io/genomeblocks/quickstart/).

Quick Start
-----------

```python
import genomeblocks as gb

cre = (gb.Loci.make("atac.narrowPeak")          # a table: numpy columns, row = join key
         .slop(100).sort().merge())

se = cre & gb.as_loci("H3K27ac_SE.bed")          # anything interval-like goes in

genes = gb.Genes.make("gencode.v38.annotation.gtf")   # 0-based tables, GTF or GFF3
labels = genes.annotations(se)                   # Promoter-TSS / Exonic / Intronic / ...

A = (gb.Architecture.make(cre, "loops.bedpe", r=2500)
       .add_mcool("hic.mcool", resolution=5000)
       .normalize().annotate(genes).strength())
hubs = A.prime_hubs()

S = cre.signal(["atac.bw", "h3k27ac.bw"], n_bins=200, flank=3000)   # (rows, tracks, bins)
cre.to_polars(); A.to_pandas(); genes.to_arrow()                    # and back: Loci.from_frame(df)
cre.intersect(se, backend="bioframe")             # or: with gb.use_backend(intervals="pyranges"): ...
```

Setup
-----

```bash
pip install genomeblocks                 # every default backend except a motif engine
pip install "genomeblocks[motifs]"       # + MOODS, the motif engine (compiled at install)
pip install "genomeblocks[lightmotif]"   # or lightmotif (prebuilt wheels); same hits
pip install "genomeblocks[all]"          # + polars, pysam, logomaker and every other engine
```

The conda package (recipe in `conda-recipe/`, for Bioconda) ships MOODS. The conda-only engines (graph-tool, cgranges, bedtools) are optional extras; `environment.yml` builds the full development environment:

```bash
conda env create -f environment.yml
conda activate genomeblocks
```

`gb.backends()` lists what is installed and what each family uses. See [the documentation](https://birkiy.github.io/genomeblocks/) for installation details, the concepts, module guides, interoperability, backends and the API reference.

License
-------

MIT — see [LICENSE](LICENSE).
