gatac 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (57) hide show
  1. gatac/__init__.py +128 -0
  2. gatac/_files.py +32 -0
  3. gatac/_progress.py +33 -0
  4. gatac/_rapids.py +22 -0
  5. gatac/_readers.py +140 -0
  6. gatac/_workers.py +31 -0
  7. gatac/cli.py +771 -0
  8. gatac/dr/__init__.py +26 -0
  9. gatac/dr/_clustering.py +573 -0
  10. gatac/dr/_gpu.py +340 -0
  11. gatac/dr/_stream.py +267 -0
  12. gatac/dr/lsi.py +2175 -0
  13. gatac/dr/spectral.py +581 -0
  14. gatac/gpu.py +78 -0
  15. gatac/io/__init__.py +22 -0
  16. gatac/io/_footer.py +187 -0
  17. gatac/io/convert.py +682 -0
  18. gatac/io/fasta.py +250 -0
  19. gatac/io/fragments.py +1027 -0
  20. gatac/io/gpu_convert.py +681 -0
  21. gatac/motif/__init__.py +40 -0
  22. gatac/motif/_bias_matching.py +244 -0
  23. gatac/motif/_gsea.py +643 -0
  24. gatac/motif/chromvar.py +1150 -0
  25. gatac/motif/motif.py +2208 -0
  26. gatac/peak/__init__.py +18 -0
  27. gatac/peak/_macs.py +836 -0
  28. gatac/peak/markers.py +529 -0
  29. gatac/peak/peaks.py +1244 -0
  30. gatac/pl/__init__.py +10 -0
  31. gatac/pl/footprint.py +139 -0
  32. gatac/pl/fragments.py +77 -0
  33. gatac/pl/metrics.py +113 -0
  34. gatac/pl/motifs.py +68 -0
  35. gatac/pp/__init__.py +45 -0
  36. gatac/pp/_combine.py +179 -0
  37. gatac/pp/_utils.py +35 -0
  38. gatac/pp/amulet.py +538 -0
  39. gatac/pp/features.py +310 -0
  40. gatac/pp/filter.py +279 -0
  41. gatac/pp/gene.py +808 -0
  42. gatac/pp/genescore.py +709 -0
  43. gatac/pp/genome.py +144 -0
  44. gatac/pp/metrics.py +335 -0
  45. gatac/pp/process.py +88 -0
  46. gatac/pp/tile.py +923 -0
  47. gatac/pp/tile_scan.py +373 -0
  48. gatac/py.typed +0 -0
  49. gatac/tobias/__init__.py +21 -0
  50. gatac/tobias/_minpack_relu.cu +528 -0
  51. gatac/tobias/bindetect.py +1521 -0
  52. gatac/tobias/footprint.py +996 -0
  53. gatac-0.1.0.dist-info/METADATA +227 -0
  54. gatac-0.1.0.dist-info/RECORD +57 -0
  55. gatac-0.1.0.dist-info/WHEEL +4 -0
  56. gatac-0.1.0.dist-info/entry_points.txt +2 -0
  57. gatac-0.1.0.dist-info/licenses/LICENSE +28 -0
gatac/__init__.py ADDED
@@ -0,0 +1,128 @@
1
+ """
2
+ GATAC - GPU-accelerated ATAC-seq processing toolkit.
3
+
4
+ Public API:
5
+ - io: Fragment files (reading, writing, conversion)
6
+ - pp: Preprocessing functions
7
+ - dr: Dimensionality reduction
8
+ - peak: Peak calling and marker peaks
9
+ - motif: Motif enrichment and chromVAR
10
+ - tobias: TOBIAS footprinting and differential TF binding
11
+ - pl: Plotting
12
+ - gpu: GPU helpers for code built on GATAC
13
+
14
+ Installed extensions (packages with a ``gatac.ext`` entry point) are reached
15
+ as ``gatac.<name>``, imported on first use; see :func:`extensions`.
16
+ """
17
+
18
+ import importlib
19
+ import logging
20
+ import os
21
+ from importlib.metadata import EntryPoint, entry_points, version
22
+ from typing import TYPE_CHECKING
23
+
24
+ # libcudf means to default KvikIO to POSIX reads, but opens the first file
25
+ # before applying that, so each process probes cuFile/GPUDirect Storage once
26
+ # (seconds on nodes without it). Apply libcudf's intended default up front.
27
+ os.environ.setdefault("KVIKIO_COMPAT_MODE", "ON")
28
+ # KvikIO 26.10 writes files with direct I/O by default, which fails with an
29
+ # illegal memory access on some systems (WSL2); cuDF's to_csv / to_parquet go
30
+ # through it. Writing through the page cache, as before 26.10, works everywhere.
31
+ os.environ.setdefault("KVIKIO_AUTO_DIRECT_IO_WRITE", "OFF")
32
+
33
+ # The submodules are imported on first use (gatac.pp, `from gatac import pp`):
34
+ # `import gatac` is quick, and the CLI parses its arguments and shows --help
35
+ # without RAPIDS. Each checks first that RAPIDS is installed (gatac._rapids).
36
+ _SUBMODULES = ("io", "pp", "dr", "peak", "motif", "tobias", "pl", "gpu")
37
+
38
+ if TYPE_CHECKING:
39
+ from . import dr, gpu, io, motif, peak, pl, pp, tobias # noqa: F401
40
+
41
+ __version__ = version("gatac")
42
+ __all__ = ["io", "pp", "dr", "peak", "motif", "tobias", "pl", "gpu", "extensions", "set_verbosity"]
43
+
44
+
45
+ # ---------------------------------------------------------------------------
46
+ # Extensions
47
+ # ---------------------------------------------------------------------------
48
+ # A package extends GATAC by declaring an entry point in the "gatac.ext"
49
+ # group, e.g. in its pyproject.toml:
50
+ #
51
+ # [project.entry-points."gatac.ext"]
52
+ # chromafold = "gatac_chromafold"
53
+ #
54
+ # and ``gatac.chromafold`` then imports gatac_chromafold on first access.
55
+ # Core names always win: an extension cannot replace gatac.io, gatac.pp, ...
56
+
57
+
58
+ def extensions() -> dict[str, EntryPoint]:
59
+ """
60
+ Installed GATAC extensions, by the name they are reached at (``gatac.<name>``).
61
+
62
+ Examples
63
+ --------
64
+ >>> import gatac as ga
65
+ >>> ga.extensions()
66
+ {'chromafold': EntryPoint(name='chromafold', value='gatac_chromafold', group='gatac.ext')}
67
+ """
68
+ return {ep.name: ep for ep in entry_points(group="gatac.ext")}
69
+
70
+
71
+ def __getattr__(name: str):
72
+ if name in _SUBMODULES:
73
+ return importlib.import_module(f".{name}", __name__)
74
+ ep = extensions().get(name) if not name.startswith("_") else None
75
+ if ep is None:
76
+ raise AttributeError(f"module 'gatac' has no attribute {name!r}")
77
+ module = ep.load()
78
+ globals()[name] = module
79
+ return module
80
+
81
+
82
+ def __dir__() -> list[str]:
83
+ return sorted(set(globals()) | set(_SUBMODULES) | set(extensions()))
84
+
85
+
86
+ # ---------------------------------------------------------------------------
87
+ # Package-level logging
88
+ # ---------------------------------------------------------------------------
89
+ # GATAC's INFO messages are shown by default: on stderr while logging is not
90
+ # configured, and through the application's own handlers once it is (root
91
+ # logger handlers, e.g. logging.basicConfig or pytest's caplog), so they are
92
+ # never printed twice. gatac.set_verbosity("WARNING") silences them.
93
+
94
+
95
+ class _DefaultHandler(logging.StreamHandler):
96
+ """GATAC's messages on stderr, while the root logger has no handler of its own."""
97
+
98
+ def emit(self, record: logging.LogRecord) -> None:
99
+ if not logging.getLogger().handlers:
100
+ super().emit(record)
101
+
102
+
103
+ _logger = logging.getLogger("gatac")
104
+ _logger.setLevel(logging.INFO)
105
+ _handler = _DefaultHandler()
106
+ _handler.setFormatter(logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s", datefmt="%H:%M:%S"))
107
+ _logger.addHandler(_handler)
108
+
109
+
110
+ def set_verbosity(level: str | int) -> None:
111
+ """
112
+ Set the logging verbosity for all GATAC submodules.
113
+
114
+ Parameters
115
+ ----------
116
+ level
117
+ A standard logging level name (``"DEBUG"``, ``"INFO"``,
118
+ ``"WARNING"``, ``"ERROR"``) or the corresponding integer constant.
119
+
120
+ Examples
121
+ --------
122
+ >>> import gatac
123
+ >>> gatac.set_verbosity("DEBUG") # show all messages
124
+ >>> gatac.set_verbosity("WARNING") # silence info messages
125
+ """
126
+ if isinstance(level, str):
127
+ level = getattr(logging, level.upper())
128
+ logging.getLogger("gatac").setLevel(level)
gatac/_files.py ADDED
@@ -0,0 +1,32 @@
1
+ """Output files that are only replaced by complete ones."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import os
6
+ from collections.abc import Iterator
7
+ from contextlib import contextmanager
8
+ from pathlib import Path
9
+
10
+
11
+ @contextmanager
12
+ def replacing(output_path: str | Path) -> Iterator[Path]:
13
+ """
14
+ A temporary path next to ``output_path``, moved onto it when the block succeeds.
15
+
16
+ On an error the temporary file is removed and ``output_path``, if it
17
+ exists, is left as it was: a reader never sees a partial output.
18
+ """
19
+ output_path = Path(output_path)
20
+ # hidden, per process, and with the output's suffix for writers that check it
21
+ tmp_path = output_path.with_name(f".{output_path.name}.{os.getpid()}.tmp{output_path.suffix}")
22
+ try:
23
+ yield tmp_path
24
+ os.replace(tmp_path, output_path)
25
+ finally:
26
+ tmp_path.unlink(missing_ok=True)
27
+
28
+
29
+ def write_h5ad(adata, output_path: str | Path) -> None:
30
+ """``adata.write_h5ad(output_path)``, replacing ``output_path`` only once the file is complete."""
31
+ with replacing(output_path) as tmp_path:
32
+ adata.write_h5ad(str(tmp_path))
gatac/_progress.py ADDED
@@ -0,0 +1,33 @@
1
+ """GATAC's progress bars: shown in a terminal or a notebook, not in logs."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import os
6
+ import sys
7
+
8
+
9
+ def show_progress() -> bool:
10
+ """
11
+ Whether progress bars are shown: when stderr is a terminal or in a
12
+ Jupyter kernel, so that pipelines (e.g. Snakemake) keep clean logs, and
13
+ never with ``TQDM_DISABLE`` set.
14
+ """
15
+ if os.environ.get("TQDM_DISABLE", "").lower() in ("1", "true", "yes"):
16
+ return False
17
+ if sys.stderr is not None and sys.stderr.isatty():
18
+ return True
19
+ ipython = sys.modules.get("IPython")
20
+ shell = ipython.get_ipython() if ipython is not None else None
21
+ return getattr(shell, "kernel", None) is not None
22
+
23
+
24
+ def tqdm(*args, disable: bool = False, **kwargs):
25
+ """:class:`tqdm.auto.tqdm`, disabled unless :func:`show_progress`."""
26
+ from tqdm.auto import tqdm as _tqdm
27
+
28
+ return _tqdm(*args, disable=disable or not show_progress(), **kwargs)
29
+
30
+
31
+ def trange(*args, **kwargs):
32
+ """``tqdm(range(*args), **kwargs)``."""
33
+ return tqdm(range(*args), **kwargs)
gatac/_rapids.py ADDED
@@ -0,0 +1,22 @@
1
+ """The check, first in every GPU module of GATAC, that RAPIDS is installed."""
2
+
3
+ INSTALL_HINT = (
4
+ "With pip, install the extra matching the CUDA version nvidia-smi reports: "
5
+ "pip install 'gatac[rapids-cu12]' or 'gatac[rapids-cu13]'. "
6
+ "With conda, install RAPIDS from the rapidsai channel: "
7
+ "https://gatac.readthedocs.io/en/latest/installation.html"
8
+ )
9
+
10
+
11
+ def require() -> None:
12
+ """
13
+ Import cuDF and CuPy, or say how to install them.
14
+
15
+ ``pip install gatac`` without a RAPIDS extra installs no RAPIDS; this tells
16
+ how to fix it instead of failing on ``import cudf`` deep inside GATAC.
17
+ """
18
+ try:
19
+ import cudf # noqa: F401
20
+ import cupy # noqa: F401
21
+ except ModuleNotFoundError as e:
22
+ raise ImportError(f"GATAC runs on the GPU through RAPIDS, which is missing ({e}). {INSTALL_HINT}") from e
gatac/_readers.py ADDED
@@ -0,0 +1,140 @@
1
+ """
2
+ Readers shared by every GATAC function that takes a cell metrics table, a
3
+ BED file or a gene annotation, so they all accept the same inputs and parse
4
+ them the same way.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ import logging
10
+ import os
11
+ from collections.abc import Mapping
12
+ from pathlib import Path
13
+
14
+ import cudf
15
+ import duckdb
16
+ import pandas as pd
17
+
18
+ logger = logging.getLogger(__name__)
19
+
20
+
21
+ def read_metrics(metrics, gpu: bool = False) -> pd.DataFrame | cudf.DataFrame | None:
22
+ """
23
+ Cell metrics as a DataFrame of its own (a copy of a DataFrame input).
24
+
25
+ Parameters
26
+ ----------
27
+ metrics : str, Path, pandas.DataFrame, cudf.DataFrame or None
28
+ A CSV file (as written from :func:`gatac.pp.compute_metrics`) or a
29
+ loaded table.
30
+ gpu : bool
31
+ Return a cuDF DataFrame instead of a pandas one (default False).
32
+
33
+ Returns
34
+ -------
35
+ pandas.DataFrame, cudf.DataFrame or None
36
+ None when ``metrics`` is None.
37
+
38
+ Raises
39
+ ------
40
+ FileNotFoundError
41
+ If ``metrics`` is a path that does not exist.
42
+ """
43
+ if metrics is None:
44
+ return None
45
+ if isinstance(metrics, (str, os.PathLike)):
46
+ path = Path(metrics)
47
+ if not path.exists():
48
+ raise FileNotFoundError(f"Metrics file not found: {path}")
49
+ logger.info(f"Loading cell metrics from {path}")
50
+ df = pd.read_csv(path)
51
+ elif isinstance(metrics, cudf.DataFrame):
52
+ return metrics.copy() if gpu else metrics.to_pandas()
53
+ elif isinstance(metrics, pd.DataFrame):
54
+ df = metrics.copy()
55
+ else:
56
+ raise TypeError(f"metrics must be a CSV path or a pandas or cuDF DataFrame, not {type(metrics).__name__}")
57
+ return cudf.from_pandas(df) if gpu else df
58
+
59
+
60
+ _GTF_COLUMNS = {
61
+ "chrom": "VARCHAR",
62
+ "source": "VARCHAR",
63
+ "feature": "VARCHAR",
64
+ "start": "BIGINT",
65
+ "end": "BIGINT",
66
+ "score": "VARCHAR",
67
+ "strand": "VARCHAR",
68
+ "frame": "VARCHAR",
69
+ "attribute": "VARCHAR",
70
+ }
71
+
72
+
73
+ def read_gtf(
74
+ path: str | Path,
75
+ feature: str,
76
+ attributes: Mapping[str, str] = {},
77
+ ) -> pd.DataFrame:
78
+ """
79
+ The rows of one feature type of a GTF or GFF3 file, in file order.
80
+
81
+ Parameters
82
+ ----------
83
+ path : str or Path
84
+ GTF, or GFF3 when the file name contains ``.gff``; gzipped files are
85
+ read directly.
86
+ feature : str
87
+ Value of the feature column to keep, e.g. ``"transcript"``.
88
+ attributes : dict
89
+ Output column -> attribute key, e.g. ``{"name": "gene_name"}``: the
90
+ value of ``key "value";`` (GTF) or ``key=value;`` (GFF3), null when
91
+ the key is absent.
92
+
93
+ Returns
94
+ -------
95
+ pandas.DataFrame
96
+ ``chrom``, ``start``, ``end`` (as in the file: 1-based, inclusive),
97
+ ``strand`` and the ``attributes`` columns.
98
+ """
99
+ path = Path(path)
100
+ gff3 = ".gff" in path.name.lower()
101
+
102
+ def pattern(key):
103
+ return rf"{key}=([^;]+)" if gff3 else rf'{key} "([^"]+)"'
104
+
105
+ extract = "".join(f", nullif(regexp_extract(attribute, ?, 1), '') AS \"{col}\"" for col in attributes)
106
+ columns = ", ".join(f"'{c}': '{t}'" for c, t in _GTF_COLUMNS.items())
107
+ # The columns are given: DuckDB's dialect sniffer fails on the "##" header
108
+ # lines of a GTF. GTF attribute values are quoted mid-field, so no quote
109
+ # character either.
110
+ query = f"""
111
+ SELECT chrom, start, "end", strand{extract}
112
+ FROM read_csv(?, delim='\t', header=false, comment='#', quote='', escape='',
113
+ auto_detect=false, columns={{{columns}}})
114
+ WHERE feature = ?
115
+ """
116
+ params = [pattern(k) for k in attributes.values()] + [str(path), feature]
117
+ with duckdb.connect() as con:
118
+ con.execute("SET enable_progress_bar = false")
119
+ return con.execute(query, params).df()
120
+
121
+
122
+ def read_bed(path: str | Path) -> pd.DataFrame:
123
+ """
124
+ The first three columns of a BED file: ``chrom`` (str), ``start``, ``end`` (int64).
125
+
126
+ Lines starting with ``#``, ``track`` or ``browser`` are skipped, and
127
+ chromosome names stay strings, so ``1`` matches the chromosome ``"1"``.
128
+ Gzipped files are read directly.
129
+ """
130
+ df = pd.read_csv(
131
+ path,
132
+ sep="\t",
133
+ header=None,
134
+ usecols=[0, 1, 2],
135
+ names=["chrom", "start", "end"],
136
+ comment="#",
137
+ dtype=str,
138
+ )
139
+ df = df[~df["chrom"].str.startswith(("track", "browser"))]
140
+ return df.astype({"start": "int64", "end": "int64"}).reset_index(drop=True)
gatac/_workers.py ADDED
@@ -0,0 +1,31 @@
1
+ """Default numbers of parallel workers, from the CPUs this process may use."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import os
6
+
7
+ # Files processed at once by default: more than 4 used more GPU memory without
8
+ # being faster, for the GPU import as for compute_metrics + filter_fragments.
9
+ MAX_DEFAULT_WORKERS = 4
10
+
11
+
12
+ def n_cpus() -> int:
13
+ """CPUs this process may use: a SLURM allocation, not the node's cores."""
14
+ return os.process_cpu_count() or 1
15
+
16
+
17
+ def default_workers(cap: int | None = MAX_DEFAULT_WORKERS) -> int:
18
+ """``n_cpus() - 1`` (one left for the main process), at least 1, at most ``cap``."""
19
+ n = max(1, n_cpus() - 1)
20
+ return n if cap is None else min(cap, n)
21
+
22
+
23
+ def resolve_workers(workers: int | str | None, auto: int) -> int:
24
+ """``workers`` as an int: ``"auto"`` (or None) gives ``auto``."""
25
+ if workers is None or workers == "auto":
26
+ return auto
27
+ if isinstance(workers, str):
28
+ raise ValueError(f'workers must be a positive int or "auto", not {workers!r}')
29
+ if workers < 1:
30
+ raise ValueError(f"workers must be at least 1, not {workers}")
31
+ return int(workers)