pycmplot 0.3.1__tar.gz → 0.4.0__tar.gz

{pycmplot-0.3.1 → pycmplot-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pycmplot
-Version: 0.3.1
+Version: 0.4.0
 Summary: Multi-track circular and linear Manhattan plot generation for GWAS summary statistics
 Author: Kevin Esoh
 Author-email: Kevin Esoh <kesohku1@jh.edu>
@@ -44,7 +44,7 @@ Dynamic: license-file
 </div>
 
 <p align="center">
-  <img width="600" height="400" src="docs/pycmplot-logo-circular.png">
+  <img width="600" height="400" src="https://github.com/esohkevin/pycmplot/blob/main/docs/pycmplot-logo-circular.png">
 </p>
 
 
@@ -67,6 +67,10 @@ Dynamic: license-file
     - [Trim insignificant variants for faster plotting](#trim-insignificant-variants-for-faster-plotting)
     - [Genome build conversion (liftover)](#genome-build-conversion-liftover)
     - [Nearest-gene annotation for GWAS lead SNPs](#nearest-gene-annotation-for-gwas-lead-snps)
+    - [Caching & warm resume](#caching--warm-resume)
+    - [User-editable hits overlay](#user-editable-hits-overlay)
+    - [Per-locus highlight colours & custom legend](#per-locus-highlight-colours--custom-legend)
+    - [Multi-panel canvas](#multi-panel-canvas)
 3. [Application](#application)
 4. [Tip](#tip)
 5. [Installation](#installation)
@@ -179,6 +183,46 @@ for gene annotation. Also included are UCSC chain files for coordinate conversio
     ``Homo_sapiens.GRCh37.geneinfo.tsv.gz``.
 
 
+### Caching & warm resume
+Loading is the expensive step (I/O + trim + liftover + lead extraction), so
+pycmplot ships a per-track cache keyed on `SHA-256(raw_file_sha256 + version + Stage-1 params)`.
+Warm re-runs of the same `(files, parameters)` combination complete in
+milliseconds; changing any parameter transparently invalidates only the
+affected tracks and regenerates them. Enable with `--cache` (CLI) or
+`cache=True` (Python API); use `--clear_cache` to wipe the tree.
+
+```bash
+pycmplot --sum_stats hb.tsv,mcv.tsv --labels Hb,MCV \
+         --logp --highlight --cache --cache_dir ./.pycmplot
+```
+
+### User-editable hits overlay
+When caching is on, the auto-generated hits table is written to a
+group-scoped TSV at `<cache_dir>/annotations/hits.<group_key>.tsv`
+that you're *expected to hand-edit*. Rows added or changed there feed
+straight back into the next plot — no re-plumbing required. Each row
+carries `source` (`auto` vs `user`), `highlight_color`, and `category`
+columns; user edits are inherited across cache regenerations by
+`(CHR, POS)` lookup, so re-running with a new parameter never loses
+your annotations.
+
+### Per-locus highlight colours & custom legend
+Set the `highlight_color` column on any row of the hits overlay to a
+matplotlib-parseable colour (name, `#rrggbb`, or an RGB tuple) to give
+that locus its own highlight colour; leave `auto` to fall back to the
+plot-wide `--highlight_color`. Set the `category` column
+(e.g. `novel`, `replicated`, `MHC`) to group loci in a
+**"Highlighted Categories"** legend that both the linear and circular
+plotters render automatically. If nothing is edited, no legend is
+added — the pre-feature layout is preserved.
+
+### Multi-panel canvas
+Place multiple *groups* of sumstats on the same figure by passing an
+explicit matplotlib `Axes` or `SubFigure` via `ax=` to the plotter.
+Cache files and hits overlays are group-scoped, so two panels with
+different sumstats never clobber each other's artefacts.
+
+
 ## Application
 A potential useful application is **comparative visualization** of results from multiple imputation panels, 
 multiple populations, or multiple traits to observe shared genetic architecture.
@@ -305,6 +349,16 @@ pycmplot \
 | `-st, --sort_track` | Sort tracks by `label` or `chrom_len` | input order |
 | `-od, --output_dir` | Output directory | `.` |
 | `-of, --output_format` | Output format (`png`, `pdf`, `svg`, `jpg`) | `png` |
+| `--cache` | Enable per-track cache + user-editable hits overlay | off |
+| `--cache_dir` | Where to store cache artefacts | `./.pycmplot` |
+| `--no_resume` | Regenerate but still write fresh cache entries | resume on |
+| `--clear_cache` | Delete the cache tree and exit | off |
+| `-V, --version` | Print version and exit | — |
+
+> **QQ note (0.4.0+):** the loader no longer materialises the full sorted
+> p-value array by default. `-qq/--qq_plot` sets `compute_pvals=True`
+> automatically on the CLI; Python-API callers must pass it explicitly
+> to feed `bundle['pvals']` into a QQ plotter.
 
 Run `pycmplot -h` for the full option list.
 
@@ -314,6 +368,12 @@ Run `pycmplot -h` for the full option list.
 
 A demonstration of how to use the python API is provided in this notebook: https://github.com/esohkevin/pycmplot/blob/main/pycmplot_python_api.ipynb
 
+For an end-to-end walkthrough of every feature (caching, hits overlay,
+per-locus colours & categories, multi-panel canvas, mixed-build
+liftover, QQ opt-in), see the
+[Tutorial](https://pycmplot.readthedocs.io/en/latest/tutorial.html)
+page in the docs.
+
 
 ---
 

{pycmplot-0.3.1 → pycmplot-0.4.0}/README.md

@@ -5,7 +5,7 @@
 </div>
 
 <p align="center">
-  <img width="600" height="400" src="docs/pycmplot-logo-circular.png">
+  <img width="600" height="400" src="https://github.com/esohkevin/pycmplot/blob/main/docs/pycmplot-logo-circular.png">
 </p>
 
 
@@ -28,6 +28,10 @@
     - [Trim insignificant variants for faster plotting](#trim-insignificant-variants-for-faster-plotting)
     - [Genome build conversion (liftover)](#genome-build-conversion-liftover)
     - [Nearest-gene annotation for GWAS lead SNPs](#nearest-gene-annotation-for-gwas-lead-snps)
+    - [Caching & warm resume](#caching--warm-resume)
+    - [User-editable hits overlay](#user-editable-hits-overlay)
+    - [Per-locus highlight colours & custom legend](#per-locus-highlight-colours--custom-legend)
+    - [Multi-panel canvas](#multi-panel-canvas)
 3. [Application](#application)
 4. [Tip](#tip)
 5. [Installation](#installation)
@@ -140,6 +144,46 @@ for gene annotation. Also included are UCSC chain files for coordinate conversio
     ``Homo_sapiens.GRCh37.geneinfo.tsv.gz``.
 
 
+### Caching & warm resume
+Loading is the expensive step (I/O + trim + liftover + lead extraction), so
+pycmplot ships a per-track cache keyed on `SHA-256(raw_file_sha256 + version + Stage-1 params)`.
+Warm re-runs of the same `(files, parameters)` combination complete in
+milliseconds; changing any parameter transparently invalidates only the
+affected tracks and regenerates them. Enable with `--cache` (CLI) or
+`cache=True` (Python API); use `--clear_cache` to wipe the tree.
+
+```bash
+pycmplot --sum_stats hb.tsv,mcv.tsv --labels Hb,MCV \
+         --logp --highlight --cache --cache_dir ./.pycmplot
+```
+
+### User-editable hits overlay
+When caching is on, the auto-generated hits table is written to a
+group-scoped TSV at `<cache_dir>/annotations/hits.<group_key>.tsv`
+that you're *expected to hand-edit*. Rows added or changed there feed
+straight back into the next plot — no re-plumbing required. Each row
+carries `source` (`auto` vs `user`), `highlight_color`, and `category`
+columns; user edits are inherited across cache regenerations by
+`(CHR, POS)` lookup, so re-running with a new parameter never loses
+your annotations.
+
+### Per-locus highlight colours & custom legend
+Set the `highlight_color` column on any row of the hits overlay to a
+matplotlib-parseable colour (name, `#rrggbb`, or an RGB tuple) to give
+that locus its own highlight colour; leave `auto` to fall back to the
+plot-wide `--highlight_color`. Set the `category` column
+(e.g. `novel`, `replicated`, `MHC`) to group loci in a
+**"Highlighted Categories"** legend that both the linear and circular
+plotters render automatically. If nothing is edited, no legend is
+added — the pre-feature layout is preserved.
+
+### Multi-panel canvas
+Place multiple *groups* of sumstats on the same figure by passing an
+explicit matplotlib `Axes` or `SubFigure` via `ax=` to the plotter.
+Cache files and hits overlays are group-scoped, so two panels with
+different sumstats never clobber each other's artefacts.
+
+
 ## Application
 A potential useful application is **comparative visualization** of results from multiple imputation panels, 
 multiple populations, or multiple traits to observe shared genetic architecture.
@@ -266,6 +310,16 @@ pycmplot \
 | `-st, --sort_track` | Sort tracks by `label` or `chrom_len` | input order |
 | `-od, --output_dir` | Output directory | `.` |
 | `-of, --output_format` | Output format (`png`, `pdf`, `svg`, `jpg`) | `png` |
+| `--cache` | Enable per-track cache + user-editable hits overlay | off |
+| `--cache_dir` | Where to store cache artefacts | `./.pycmplot` |
+| `--no_resume` | Regenerate but still write fresh cache entries | resume on |
+| `--clear_cache` | Delete the cache tree and exit | off |
+| `-V, --version` | Print version and exit | — |
+
+> **QQ note (0.4.0+):** the loader no longer materialises the full sorted
+> p-value array by default. `-qq/--qq_plot` sets `compute_pvals=True`
+> automatically on the CLI; Python-API callers must pass it explicitly
+> to feed `bundle['pvals']` into a QQ plotter.
 
 Run `pycmplot -h` for the full option list.
 
@@ -275,6 +329,12 @@ Run `pycmplot -h` for the full option list.
 
 A demonstration of how to use the python API is provided in this notebook: https://github.com/esohkevin/pycmplot/blob/main/pycmplot_python_api.ipynb
 
+For an end-to-end walkthrough of every feature (caching, hits overlay,
+per-locus colours & categories, multi-panel canvas, mixed-build
+liftover, QQ opt-in), see the
+[Tutorial](https://pycmplot.readthedocs.io/en/latest/tutorial.html)
+page in the docs.
+
 
 ---
 

pycmplot-0.4.0/docs-bak/conf.py

@@ -0,0 +1,90 @@
+# Configuration file for the Sphinx documentation builder.
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+import os
+import sys
+
+# -- Path setup ---------------------------------------------------------------
+# Allow Sphinx to find the pycmplot package (needed for autodoc)
+sys.path.insert(0, os.path.abspath(".."))
+
+# -- Project information -------------------------------------------------------
+project = "pycmplot"
+copyright = "2026, Kevin Esoh"
+author = "Kevin Esoh"
+release = "0.3.1"  # update to match PyPI version
+
+# -- General configuration -----------------------------------------------------
+extensions = [
+    "sphinx.ext.autodoc",       # auto-generate docs from docstrings
+    "sphinx.ext.autosummary",   # summary tables for modules/classes
+    "sphinx.ext.napoleon",      # NumPy / Google docstring styles
+    "sphinx.ext.viewcode",      # [source] links in API docs
+    "sphinx.ext.intersphinx",   # cross-links to numpy, pandas, matplotlib docs
+    "numpydoc",                 # richer NumPy-style rendering
+    "nbsphinx",                 # embed Jupyter notebooks
+    "sphinx_copybutton",        # copy-button on code blocks
+    "myst_parser",              # allow Markdown (.md) pages alongside .rst
+]
+
+# Napoleon settings (NumPy docstring style)
+napoleon_google_docstring = False
+napoleon_numpy_docstring = True
+napoleon_include_init_with_doc = True
+napoleon_include_private_with_doc = False
+napoleon_use_param = True
+napoleon_use_rtype = True
+
+# numpydoc settings
+numpydoc_show_class_members = False
+
+# Autosummary: auto-generate stub files
+autosummary_generate = True
+autodoc_default_options = {
+    "members": True,
+    "undoc-members": False,
+    "show-inheritance": True,
+}
+
+# Intersphinx: link to external package docs
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "numpy": ("https://numpy.org/doc/stable", None),
+    "pandas": ("https://pandas.pydata.org/docs", None),
+    "matplotlib": ("https://matplotlib.org/stable", None),
+}
+
+# nbsphinx: do not re-execute notebooks during docs build
+nbsphinx_execute = "never"
+
+# Source file suffixes
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".md": "markdown",
+}
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "**.ipynb_checkpoints"]
+
+# -- Options for HTML output ---------------------------------------------------
+html_theme = "sphinx_rtd_theme"
+html_theme_options = {
+    "logo_only": False,
+    "prev_next_buttons_location": "bottom",
+    "style_nav_header_background": "#2980B9",
+    "collapse_navigation": False,
+    "sticky_navigation": True,
+    "navigation_depth": 4,
+    "includehidden": True,
+    "titles_only": False,
+}
+
+html_static_path = ["_static"]
+html_css_files = ["custom.css"]
+
+# Optional: path to logo image (add docs/_static/logo.png if you have one)
+# html_logo = "_static/logo.png"
+
+html_show_sourcelink = True
+html_show_sphinx = True
+html_show_copyright = True

pycmplot-0.4.0/pycmplot/__init__.py

@@ -0,0 +1,50 @@
+"""
+pycmplot
+========
+Multi-track circular and linear Manhattan plot generation for GWAS summary statistics.
+
+Quickstart
+----------
+Command-line::
+
+    pycmplot -s file1.gz,file2.gz -l HbF,MCV --logp --mode lm
+
+Python API::
+
+    from pycmplot.io import prep_pycmplot_input_info, get_sumstats_and_merged_sector_list
+    from pycmplot.plotting import plot_linear, plot_circular, plot_qq_single, plot_qq_separate, plot_qq_overlay, plot_qq_combined
+    from pycmplot.stats import get_lead_snps
+    from pycmplot.annotation import get_hits_summary_table
+
+Public surface
+--------------
+"""
+
+from pycmplot.plotting.linear import plot_linear
+from pycmplot.plotting.circular import plot_circular, compute_track_radii_dict
+from pycmplot.plotting.qq import plot_qq_single, plot_qq_separate, plot_qq_overlay, plot_qq_combined
+from pycmplot.stats import get_lead_snps, get_highlight_snps
+from pycmplot.io import prep_pycmplot_input_info, get_sumstats_and_merged_sector_list
+from pycmplot.annotation import get_hits_summary_table
+from pycmplot.constants import hg38_chr_lengths, BIOTYPE_WEIGHTS
+from pycmplot.resources import ResourceConfig
+
+__all__ = [
+    "plot_linear",
+    "plot_circular",
+    "plot_qq_single",
+    "plot_qq_separate",
+    "plot_qq_overlay",
+    "plot_qq_combined",
+    "compute_track_radii_dict",
+    "get_lead_snps",
+    "get_highlight_snps",
+    "prep_pycmplot_input_info",
+    "get_sumstats_and_merged_sector_list",
+    "get_hits_summary_table",
+    "hg38_chr_lengths",
+    "BIOTYPE_WEIGHTS",
+    "ResourceConfig",
+]
+
+__version__ = "0.4.0"

pycmplot-0.4.0/pycmplot/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for ``python -m pycmplot`` invocation."""
+
+from pycmplot._core import main
+
+if __name__ == "__main__":
+    main()