gatac 0.1.0__tar.gz

gatac-0.1.0/.gitignore

@@ -0,0 +1,28 @@
+.DS_Store
+
+data/*
+refs/*
+uv.lock
+pixi.lock
+*.pyc
+*.log
+AGENTS.md
+GEMINI.md
+
+*.parquet
+*.csv
+*.h5ad
+.venv
+
+__pycache__/
+
+# doc build related
+_build/
+docs/_build/
+docs/api/generated/
+
+# llm
+agents/
+
+# CI test outputs
+test-data/

gatac-0.1.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Louis Faure
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

gatac-0.1.0/PKG-INFO

@@ -0,0 +1,227 @@
+Metadata-Version: 2.5
+Name: gatac
+Version: 0.1.0
+Summary: GPU-accelerated ATAC-seq fragment processing and tile matrix generation
+Project-URL: Documentation, https://gatac.readthedocs.io
+Project-URL: Source, https://github.com/scverse/gatac
+Project-URL: Issues, https://github.com/scverse/gatac/issues
+Project-URL: Changelog, https://gatac.readthedocs.io/en/latest/release-notes/index.html
+Author: Louis Faure
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Keywords: ATAC-seq,GPU,RAPIDS,chromatin accessibility,single-cell
+Classifier: Environment :: GPU :: NVIDIA CUDA :: 12
+Classifier: Environment :: GPU :: NVIDIA CUDA :: 13
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.13
+Requires-Dist: anndata>=0.10.8
+Requires-Dist: duckdb>=2.0
+Requires-Dist: h5py>=3.11
+Requires-Dist: matplotlib>=3.10
+Requires-Dist: numba>=0.60
+Requires-Dist: numpy>=2
+Requires-Dist: pandas>=2.3
+Requires-Dist: pyarrow>=22.0.0
+Requires-Dist: scanpy>=1.11.5
+Requires-Dist: scikit-learn>=1.6
+Requires-Dist: scipy>=1.13
+Requires-Dist: seaborn>=0.13.2
+Requires-Dist: statsmodels>=0.14
+Requires-Dist: tqdm>=4.66.0
+Provides-Extra: archr-compat
+Requires-Dist: annoy>=1.17; extra == 'archr-compat'
+Provides-Extra: bigwig
+Requires-Dist: pybigwig>=0.3.22; extra == 'bigwig'
+Provides-Extra: rapids-cu12
+Requires-Dist: cudf-cu12>=26.02; extra == 'rapids-cu12'
+Requires-Dist: cugraph-cu12>=26.02; extra == 'rapids-cu12'
+Requires-Dist: cuml-cu12>=26.02; extra == 'rapids-cu12'
+Requires-Dist: cupy-cuda12x[ctk]>=14; extra == 'rapids-cu12'
+Requires-Dist: nvidia-nvcomp-cu12>=5.1; extra == 'rapids-cu12'
+Provides-Extra: rapids-cu13
+Requires-Dist: cudf-cu13>=26.02; extra == 'rapids-cu13'
+Requires-Dist: cugraph-cu13>=26.02; extra == 'rapids-cu13'
+Requires-Dist: cuml-cu13>=26.02; extra == 'rapids-cu13'
+Requires-Dist: cupy-cuda13x[ctk]>=14; extra == 'rapids-cu13'
+Requires-Dist: nvidia-nvcomp-cu13>=5.1; extra == 'rapids-cu13'
+Description-Content-Type: text/markdown
+
+[![CI-Pass](https://github.com/scverse/gatac/actions/workflows/test-gpu.yml/badge.svg)](https://github.com/scverse/gatac/actions/workflows/test-gpu.yml)
+[![codecov](https://codecov.io/gh/scverse/gatac/graph/badge.svg?token=YMSDUHQRBB)](https://codecov.io/gh/scverse/gatac)
+
+# GATAC: GPU-Accelerated scATACseq Analysis
+
+GATAC is a GPU-accelerated toolkit for end-to-end ATAC-seq data processing.
+Starting from raw fragment files, it produces analysis-ready sparse matrices
+(tile, peak, and gene activity) that integrate directly with the
+[scverse](https://scverse.org) ecosystem — AnnData, Scanpy, and SnapATAC2.
+Computations are offloaded to the GPU via [RAPIDS cuDF](https://rapids.ai),
+[CuPy](https://cupy.dev), and [cuML](https://docs.rapids.ai/api/cuml/stable/),
+delivering 10–50× speedups over CPU-only workflows on typical single-cell
+datasets.
+
+GATAC workflow takes advantage of [Apache Parquet](https://parquet.apache.org) file format. Parquet's columnar layout and
+built-in compression make it an ideal staging format for GPU-based pipelines:
+columns are read independently, so only the genomic coordinates actually needed
+for a given operation are transferred to device memory. RAPIDS cuDF can read
+Parquet directly into GPU memory with zero CPU round-trips, enabling streaming
+aggregation over datasets that far exceed the size of available GPU RAM.
+
+## Installation
+
+GATAC needs Linux and an NVIDIA GPU. Install it with the extra of your CUDA
+version (`nvidia-smi` reports it), which installs RAPIDS and CuPy:
+
+```bash
+pip install 'gatac[rapids-cu12]'   # or 'gatac[rapids-cu13]'
+```
+
+From a clone of this repository: `uv sync --extra rapids-cu12`. See the
+[installation guide](https://gatac.readthedocs.io/en/latest/installation.html)
+for the optional extras and conda.
+
+## CLI Usage
+
+```bash
+# Convert TSV.GZ to Parquet
+gatac convert fragments.tsv.gz
+
+# Several samples: name each sample's cells by sample (sample1_<barcode>),
+# so that they stay distinct in a combined matrix. {sample} is written as is:
+# gatac fills it in for each file (samples/s1.tsv.gz -> s1_, ...)
+gatac convert "samples/*.tsv.gz" --output-dir parquets/ --barcode-prefix "{sample}_"
+
+# Cell Ranger outputs, all named atac_fragments.tsv.gz: prefix the files too
+# ({sample} is then the run directory: runs/A/outs/... -> A_)
+gatac convert "runs/*/outs/atac_fragments.tsv.gz" --output-dir parquets/ \
+    --file-prefix "{sample}_" --barcode-prefix "{sample}_"
+
+# Set (or change) the barcode prefix of a converted file, in place: only the
+# file footer is rewritten, in milliseconds
+gatac rename sample1.parquet --barcode-prefix sample1_
+
+# Compute quality metrics (TSSe, etc.)
+gatac metrics fragments.parquet -g annotations.gtf -o fragments_metrics.csv
+
+# Compute quality metrics (TSSe, etc.)
+gatac metrics fragments.parquet -g annotations.gtf --batch-size 64
+
+# Filter fragments by minimum fragment count
+gatac filter fragments.parquet -m 500 -o fragments_filtered.parquet
+
+# Filter fragments using metrics and quality threshold
+gatac filter fragments.parquet --metrics metrics.csv --filter "tsse_score > 5" -o fragments_filtered.parquet
+
+# Filter fragments with genome-based chromosome filtering
+gatac filter fragments.parquet -g hg38 -m 500 -o fragments_filtered.parquet
+
+# Generate tile matrix (m=min_unique_fragments)
+gatac tile fragments.parquet -g hg38 -t 500 -m 100
+
+# Generate tile matrix with quality filtering using metrics CSV
+gatac tile fragments.parquet -g hg38 --metrics metrics.csv --filter "tsse_score > 5"
+
+# Generate gene activity matrix
+gatac gene fragments.parquet -g annotations.gtf
+
+# Generate gene activity matrix with filtering
+gatac gene fragments.parquet -g annotations.gtf --metrics metrics.csv --filter "tsse_score > 5"
+
+# Generate ArchR-style distance-weighted gene activity SCORE matrix
+gatac genescore fragments.parquet -g annotations.gtf
+
+# Gene score with a custom gene model (function of distance x to the TSS)
+gatac genescore fragments.parquet -g annotations.gtf --gene-model "exp(-abs(x)/10000) + exp(-1)"
+
+# One tile matrix of several samples (each with its own barcode prefix),
+# most accessible tiles only
+gatac tile sample1.parquet sample2.parquet -g hg38 -n 500000 -o combined.h5ad
+
+# One gene matrix (or gene score matrix) of several samples
+gatac gene sample1.parquet sample2.parquet -g annotations.gtf -o genes.h5ad
+gatac genescore sample1.parquet sample2.parquet -g annotations.gtf -o gene_scores.h5ad
+
+# Merge h5ad files (file-by-file)
+gatac combine sample1.h5ad sample2.h5ad -o combined.h5ad
+```
+
+## Python API
+
+```python
+import gatac as ga
+
+# Convert to parquet
+ga.io.make_parquet("fragments.tsv.gz")
+
+# Name the sample's cells sample1_<barcode>, in place (footer only)
+ga.io.set_barcode_prefix("sample1.parquet", "sample1_")
+
+# Compute metrics
+metrics = ga.pp.compute_metrics("fragments.parquet", "annotations.gtf")
+
+# Create tile matrix (pre-filtered by unique fragments)
+adata = ga.pp.make_tile_matrix(
+    "fragments.parquet",
+    chrom_sizes="hg38",
+    min_fragments_per_cell=500,
+)
+
+# Create tile matrix using pre-computed metrics for filtering
+# metrics can be a path to a CSV or a cuDF DataFrame
+adata = ga.pp.make_tile_matrix("fragments.parquet", chrom_sizes="hg38", metrics=metrics, filter_query="tsse_score > 5")
+
+# Create gene activity matrix
+adata_gene = ga.pp.make_gene_matrix(
+    "fragments.parquet", gene_anno="annotations.gtf", upstream=2000, include_gene_body=True
+)
+
+# Create gene activity matrix with filtering
+adata_gene = ga.pp.make_gene_matrix(
+    "fragments.parquet", gene_anno="annotations.gtf", metrics=metrics, filter_query="tsse_score > 5"
+)
+
+# Create ArchR-style distance-weighted gene activity SCORE matrix
+# (faithful GPU port of ArchR addGeneScoreMatrix; defaults match ArchR)
+adata_score = ga.pp.make_gene_score_matrix(
+    "fragments.parquet",
+    gene_anno="annotations.gtf",  # GTF/GFF, or CSV: symbol,seqnames,start,end,strand
+    gene_model="exp(-abs(x)/5000) + exp(-1)",
+    tile_size=500,
+    extend_upstream=(1000, 100000),
+    extend_downstream=(1000, 100000),
+    use_gene_boundaries=True,
+    scale_to=10000,
+)
+
+# Filter fragments by minimum fragment count
+ga.pp.filter_fragments("fragments.parquet", min_fragments_per_cell=500)
+
+# Filter fragments using metrics with quality threshold
+ga.pp.filter_fragments("fragments.parquet", metrics=metrics, filter_query="tsse_score > 5")
+
+# Filter multiple files with genome-based chromosome filtering
+ga.pp.filter_fragments(
+    ["sample1.parquet", "sample2.parquet"],
+    metrics=metrics,
+    filter_query="tsse_score > 5 and n_unique > 1000",
+    chrom_sizes="hg38",
+)
+
+# Select features (single AnnData)
+ga.pp.select_features(adata, n_features=50000)
+
+# One tile matrix of several samples, most accessible tiles only
+ga.pp.make_tile_matrix(
+    ["sample1.parquet", "sample2.parquet"], chrom_sizes="hg38", n_features=500000, output_path="combined.h5ad"
+)
+
+# One gene matrix of several samples, written as it is built
+ga.pp.make_gene_matrix(["sample1.parquet", "sample2.parquet"], gene_anno="annotations.gtf", output_path="genes.h5ad")
+
+# Merge multiple AnnData files
+ga.pp.combine(input_paths=["sample1.h5ad", "sample2.h5ad"], output_path="merged.h5ad")
+```

gatac-0.1.0/README.md

@@ -0,0 +1,175 @@
+[![CI-Pass](https://github.com/scverse/gatac/actions/workflows/test-gpu.yml/badge.svg)](https://github.com/scverse/gatac/actions/workflows/test-gpu.yml)
+[![codecov](https://codecov.io/gh/scverse/gatac/graph/badge.svg?token=YMSDUHQRBB)](https://codecov.io/gh/scverse/gatac)
+
+# GATAC: GPU-Accelerated scATACseq Analysis
+
+GATAC is a GPU-accelerated toolkit for end-to-end ATAC-seq data processing.
+Starting from raw fragment files, it produces analysis-ready sparse matrices
+(tile, peak, and gene activity) that integrate directly with the
+[scverse](https://scverse.org) ecosystem — AnnData, Scanpy, and SnapATAC2.
+Computations are offloaded to the GPU via [RAPIDS cuDF](https://rapids.ai),
+[CuPy](https://cupy.dev), and [cuML](https://docs.rapids.ai/api/cuml/stable/),
+delivering 10–50× speedups over CPU-only workflows on typical single-cell
+datasets.
+
+GATAC workflow takes advantage of [Apache Parquet](https://parquet.apache.org) file format. Parquet's columnar layout and
+built-in compression make it an ideal staging format for GPU-based pipelines:
+columns are read independently, so only the genomic coordinates actually needed
+for a given operation are transferred to device memory. RAPIDS cuDF can read
+Parquet directly into GPU memory with zero CPU round-trips, enabling streaming
+aggregation over datasets that far exceed the size of available GPU RAM.
+
+## Installation
+
+GATAC needs Linux and an NVIDIA GPU. Install it with the extra of your CUDA
+version (`nvidia-smi` reports it), which installs RAPIDS and CuPy:
+
+```bash
+pip install 'gatac[rapids-cu12]'   # or 'gatac[rapids-cu13]'
+```
+
+From a clone of this repository: `uv sync --extra rapids-cu12`. See the
+[installation guide](https://gatac.readthedocs.io/en/latest/installation.html)
+for the optional extras and conda.
+
+## CLI Usage
+
+```bash
+# Convert TSV.GZ to Parquet
+gatac convert fragments.tsv.gz
+
+# Several samples: name each sample's cells by sample (sample1_<barcode>),
+# so that they stay distinct in a combined matrix. {sample} is written as is:
+# gatac fills it in for each file (samples/s1.tsv.gz -> s1_, ...)
+gatac convert "samples/*.tsv.gz" --output-dir parquets/ --barcode-prefix "{sample}_"
+
+# Cell Ranger outputs, all named atac_fragments.tsv.gz: prefix the files too
+# ({sample} is then the run directory: runs/A/outs/... -> A_)
+gatac convert "runs/*/outs/atac_fragments.tsv.gz" --output-dir parquets/ \
+    --file-prefix "{sample}_" --barcode-prefix "{sample}_"
+
+# Set (or change) the barcode prefix of a converted file, in place: only the
+# file footer is rewritten, in milliseconds
+gatac rename sample1.parquet --barcode-prefix sample1_
+
+# Compute quality metrics (TSSe, etc.)
+gatac metrics fragments.parquet -g annotations.gtf -o fragments_metrics.csv
+
+# Compute quality metrics (TSSe, etc.)
+gatac metrics fragments.parquet -g annotations.gtf --batch-size 64
+
+# Filter fragments by minimum fragment count
+gatac filter fragments.parquet -m 500 -o fragments_filtered.parquet
+
+# Filter fragments using metrics and quality threshold
+gatac filter fragments.parquet --metrics metrics.csv --filter "tsse_score > 5" -o fragments_filtered.parquet
+
+# Filter fragments with genome-based chromosome filtering
+gatac filter fragments.parquet -g hg38 -m 500 -o fragments_filtered.parquet
+
+# Generate tile matrix (m=min_unique_fragments)
+gatac tile fragments.parquet -g hg38 -t 500 -m 100
+
+# Generate tile matrix with quality filtering using metrics CSV
+gatac tile fragments.parquet -g hg38 --metrics metrics.csv --filter "tsse_score > 5"
+
+# Generate gene activity matrix
+gatac gene fragments.parquet -g annotations.gtf
+
+# Generate gene activity matrix with filtering
+gatac gene fragments.parquet -g annotations.gtf --metrics metrics.csv --filter "tsse_score > 5"
+
+# Generate ArchR-style distance-weighted gene activity SCORE matrix
+gatac genescore fragments.parquet -g annotations.gtf
+
+# Gene score with a custom gene model (function of distance x to the TSS)
+gatac genescore fragments.parquet -g annotations.gtf --gene-model "exp(-abs(x)/10000) + exp(-1)"
+
+# One tile matrix of several samples (each with its own barcode prefix),
+# most accessible tiles only
+gatac tile sample1.parquet sample2.parquet -g hg38 -n 500000 -o combined.h5ad
+
+# One gene matrix (or gene score matrix) of several samples
+gatac gene sample1.parquet sample2.parquet -g annotations.gtf -o genes.h5ad
+gatac genescore sample1.parquet sample2.parquet -g annotations.gtf -o gene_scores.h5ad
+
+# Merge h5ad files (file-by-file)
+gatac combine sample1.h5ad sample2.h5ad -o combined.h5ad
+```
+
+## Python API
+
+```python
+import gatac as ga
+
+# Convert to parquet
+ga.io.make_parquet("fragments.tsv.gz")
+
+# Name the sample's cells sample1_<barcode>, in place (footer only)
+ga.io.set_barcode_prefix("sample1.parquet", "sample1_")
+
+# Compute metrics
+metrics = ga.pp.compute_metrics("fragments.parquet", "annotations.gtf")
+
+# Create tile matrix (pre-filtered by unique fragments)
+adata = ga.pp.make_tile_matrix(
+    "fragments.parquet",
+    chrom_sizes="hg38",
+    min_fragments_per_cell=500,
+)
+
+# Create tile matrix using pre-computed metrics for filtering
+# metrics can be a path to a CSV or a cuDF DataFrame
+adata = ga.pp.make_tile_matrix("fragments.parquet", chrom_sizes="hg38", metrics=metrics, filter_query="tsse_score > 5")
+
+# Create gene activity matrix
+adata_gene = ga.pp.make_gene_matrix(
+    "fragments.parquet", gene_anno="annotations.gtf", upstream=2000, include_gene_body=True
+)
+
+# Create gene activity matrix with filtering
+adata_gene = ga.pp.make_gene_matrix(
+    "fragments.parquet", gene_anno="annotations.gtf", metrics=metrics, filter_query="tsse_score > 5"
+)
+
+# Create ArchR-style distance-weighted gene activity SCORE matrix
+# (faithful GPU port of ArchR addGeneScoreMatrix; defaults match ArchR)
+adata_score = ga.pp.make_gene_score_matrix(
+    "fragments.parquet",
+    gene_anno="annotations.gtf",  # GTF/GFF, or CSV: symbol,seqnames,start,end,strand
+    gene_model="exp(-abs(x)/5000) + exp(-1)",
+    tile_size=500,
+    extend_upstream=(1000, 100000),
+    extend_downstream=(1000, 100000),
+    use_gene_boundaries=True,
+    scale_to=10000,
+)
+
+# Filter fragments by minimum fragment count
+ga.pp.filter_fragments("fragments.parquet", min_fragments_per_cell=500)
+
+# Filter fragments using metrics with quality threshold
+ga.pp.filter_fragments("fragments.parquet", metrics=metrics, filter_query="tsse_score > 5")
+
+# Filter multiple files with genome-based chromosome filtering
+ga.pp.filter_fragments(
+    ["sample1.parquet", "sample2.parquet"],
+    metrics=metrics,
+    filter_query="tsse_score > 5 and n_unique > 1000",
+    chrom_sizes="hg38",
+)
+
+# Select features (single AnnData)
+ga.pp.select_features(adata, n_features=50000)
+
+# One tile matrix of several samples, most accessible tiles only
+ga.pp.make_tile_matrix(
+    ["sample1.parquet", "sample2.parquet"], chrom_sizes="hg38", n_features=500000, output_path="combined.h5ad"
+)
+
+# One gene matrix of several samples, written as it is built
+ga.pp.make_gene_matrix(["sample1.parquet", "sample2.parquet"], gene_anno="annotations.gtf", output_path="genes.h5ad")
+
+# Merge multiple AnnData files
+ga.pp.combine(input_paths=["sample1.h5ad", "sample2.h5ad"], output_path="merged.h5ad")
+```

gatac-0.1.0/gatac/__init__.py

@@ -0,0 +1,128 @@
+"""
+GATAC - GPU-accelerated ATAC-seq processing toolkit.
+
+Public API:
+    - io: Fragment files (reading, writing, conversion)
+    - pp: Preprocessing functions
+    - dr: Dimensionality reduction
+    - peak: Peak calling and marker peaks
+    - motif: Motif enrichment and chromVAR
+    - tobias: TOBIAS footprinting and differential TF binding
+    - pl: Plotting
+    - gpu: GPU helpers for code built on GATAC
+
+Installed extensions (packages with a ``gatac.ext`` entry point) are reached
+as ``gatac.<name>``, imported on first use; see :func:`extensions`.
+"""
+
+import importlib
+import logging
+import os
+from importlib.metadata import EntryPoint, entry_points, version
+from typing import TYPE_CHECKING
+
+# libcudf means to default KvikIO to POSIX reads, but opens the first file
+# before applying that, so each process probes cuFile/GPUDirect Storage once
+# (seconds on nodes without it). Apply libcudf's intended default up front.
+os.environ.setdefault("KVIKIO_COMPAT_MODE", "ON")
+# KvikIO 26.10 writes files with direct I/O by default, which fails with an
+# illegal memory access on some systems (WSL2); cuDF's to_csv / to_parquet go
+# through it. Writing through the page cache, as before 26.10, works everywhere.
+os.environ.setdefault("KVIKIO_AUTO_DIRECT_IO_WRITE", "OFF")
+
+# The submodules are imported on first use (gatac.pp, `from gatac import pp`):
+# `import gatac` is quick, and the CLI parses its arguments and shows --help
+# without RAPIDS. Each checks first that RAPIDS is installed (gatac._rapids).
+_SUBMODULES = ("io", "pp", "dr", "peak", "motif", "tobias", "pl", "gpu")
+
+if TYPE_CHECKING:
+    from . import dr, gpu, io, motif, peak, pl, pp, tobias  # noqa: F401
+
+__version__ = version("gatac")
+__all__ = ["io", "pp", "dr", "peak", "motif", "tobias", "pl", "gpu", "extensions", "set_verbosity"]
+
+
+# ---------------------------------------------------------------------------
+# Extensions
+# ---------------------------------------------------------------------------
+# A package extends GATAC by declaring an entry point in the "gatac.ext"
+# group, e.g. in its pyproject.toml:
+#
+#     [project.entry-points."gatac.ext"]
+#     chromafold = "gatac_chromafold"
+#
+# and ``gatac.chromafold`` then imports gatac_chromafold on first access.
+# Core names always win: an extension cannot replace gatac.io, gatac.pp, ...
+
+
+def extensions() -> dict[str, EntryPoint]:
+    """
+    Installed GATAC extensions, by the name they are reached at (``gatac.<name>``).
+
+    Examples
+    --------
+    >>> import gatac as ga
+    >>> ga.extensions()
+    {'chromafold': EntryPoint(name='chromafold', value='gatac_chromafold', group='gatac.ext')}
+    """
+    return {ep.name: ep for ep in entry_points(group="gatac.ext")}
+
+
+def __getattr__(name: str):
+    if name in _SUBMODULES:
+        return importlib.import_module(f".{name}", __name__)
+    ep = extensions().get(name) if not name.startswith("_") else None
+    if ep is None:
+        raise AttributeError(f"module 'gatac' has no attribute {name!r}")
+    module = ep.load()
+    globals()[name] = module
+    return module
+
+
+def __dir__() -> list[str]:
+    return sorted(set(globals()) | set(_SUBMODULES) | set(extensions()))
+
+
+# ---------------------------------------------------------------------------
+# Package-level logging
+# ---------------------------------------------------------------------------
+# GATAC's INFO messages are shown by default: on stderr while logging is not
+# configured, and through the application's own handlers once it is (root
+# logger handlers, e.g. logging.basicConfig or pytest's caplog), so they are
+# never printed twice. gatac.set_verbosity("WARNING") silences them.
+
+
+class _DefaultHandler(logging.StreamHandler):
+    """GATAC's messages on stderr, while the root logger has no handler of its own."""
+
+    def emit(self, record: logging.LogRecord) -> None:
+        if not logging.getLogger().handlers:
+            super().emit(record)
+
+
+_logger = logging.getLogger("gatac")
+_logger.setLevel(logging.INFO)
+_handler = _DefaultHandler()
+_handler.setFormatter(logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s", datefmt="%H:%M:%S"))
+_logger.addHandler(_handler)
+
+
+def set_verbosity(level: str | int) -> None:
+    """
+    Set the logging verbosity for all GATAC submodules.
+
+    Parameters
+    ----------
+    level
+        A standard logging level name (``"DEBUG"``, ``"INFO"``,
+        ``"WARNING"``, ``"ERROR"``) or the corresponding integer constant.
+
+    Examples
+    --------
+    >>> import gatac
+    >>> gatac.set_verbosity("DEBUG")   # show all messages
+    >>> gatac.set_verbosity("WARNING") # silence info messages
+    """
+    if isinstance(level, str):
+        level = getattr(logging, level.upper())
+    logging.getLogger("gatac").setLevel(level)

gatac-0.1.0/gatac/_files.py

@@ -0,0 +1,32 @@
+"""Output files that are only replaced by complete ones."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Iterator
+from contextlib import contextmanager
+from pathlib import Path
+
+
+@contextmanager
+def replacing(output_path: str | Path) -> Iterator[Path]:
+    """
+    A temporary path next to ``output_path``, moved onto it when the block succeeds.
+
+    On an error the temporary file is removed and ``output_path``, if it
+    exists, is left as it was: a reader never sees a partial output.
+    """
+    output_path = Path(output_path)
+    # hidden, per process, and with the output's suffix for writers that check it
+    tmp_path = output_path.with_name(f".{output_path.name}.{os.getpid()}.tmp{output_path.suffix}")
+    try:
+        yield tmp_path
+        os.replace(tmp_path, output_path)
+    finally:
+        tmp_path.unlink(missing_ok=True)
+
+
+def write_h5ad(adata, output_path: str | Path) -> None:
+    """``adata.write_h5ad(output_path)``, replacing ``output_path`` only once the file is complete."""
+    with replacing(output_path) as tmp_path:
+        adata.write_h5ad(str(tmp_path))

gatac-0.1.0/gatac/_progress.py

@@ -0,0 +1,33 @@
+"""GATAC's progress bars: shown in a terminal or a notebook, not in logs."""
+
+from __future__ import annotations
+
+import os
+import sys
+
+
+def show_progress() -> bool:
+    """
+    Whether progress bars are shown: when stderr is a terminal or in a
+    Jupyter kernel, so that pipelines (e.g. Snakemake) keep clean logs, and
+    never with ``TQDM_DISABLE`` set.
+    """
+    if os.environ.get("TQDM_DISABLE", "").lower() in ("1", "true", "yes"):
+        return False
+    if sys.stderr is not None and sys.stderr.isatty():
+        return True
+    ipython = sys.modules.get("IPython")
+    shell = ipython.get_ipython() if ipython is not None else None
+    return getattr(shell, "kernel", None) is not None
+
+
+def tqdm(*args, disable: bool = False, **kwargs):
+    """:class:`tqdm.auto.tqdm`, disabled unless :func:`show_progress`."""
+    from tqdm.auto import tqdm as _tqdm
+
+    return _tqdm(*args, disable=disable or not show_progress(), **kwargs)
+
+
+def trange(*args, **kwargs):
+    """``tqdm(range(*args), **kwargs)``."""
+    return tqdm(range(*args), **kwargs)

gatac-0.1.0/gatac/_rapids.py

@@ -0,0 +1,22 @@
+"""The check, first in every GPU module of GATAC, that RAPIDS is installed."""
+
+INSTALL_HINT = (
+    "With pip, install the extra matching the CUDA version nvidia-smi reports: "
+    "pip install 'gatac[rapids-cu12]' or 'gatac[rapids-cu13]'. "
+    "With conda, install RAPIDS from the rapidsai channel: "
+    "https://gatac.readthedocs.io/en/latest/installation.html"
+)
+
+
+def require() -> None:
+    """
+    Import cuDF and CuPy, or say how to install them.
+
+    ``pip install gatac`` without a RAPIDS extra installs no RAPIDS; this tells
+    how to fix it instead of failing on ``import cudf`` deep inside GATAC.
+    """
+    try:
+        import cudf  # noqa: F401
+        import cupy  # noqa: F401
+    except ModuleNotFoundError as e:
+        raise ImportError(f"GATAC runs on the GPU through RAPIDS, which is missing ({e}). {INSTALL_HINT}") from e