pubmatrixpython 0.2.0__tar.gz

pubmatrixpython-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,42 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+      - name: Build sdist and wheel
+        run: uv build
+      - name: Store distribution packages
+        uses: actions/upload-artifact@v5
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish-to-pypi:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/pubmatrixpython
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v6
+        with:
+          name: python-package-distributions
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

pubmatrixpython-0.2.0/.gitignore

@@ -0,0 +1,26 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Jupyter
+.ipynb_checkpoints/
+
+# Environment
+.env
+
+# uv lock file
+uv.lock
+
+# dev / local-only notebooks
+dev/
+
+# Status bank files
+CLAUDE*.md
+.claude/

pubmatrixpython-0.2.0/.python-version

@@ -0,0 +1 @@
+3.13

pubmatrixpython-0.2.0/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+## [0.2.0] — 2026-06-03
+
+- `n_workers` parameter for concurrent NCBI queries (respects rate limits automatically)
+- `cache_dir` parameter to cache query results to disk and skip redundant requests
+- `timeout` parameter exposed on `pubmatrix()` (was hardcoded at 30 s)
+- `plot_pubmatrix_heatmap()` now returns `(fig, ax)` tuple instead of `ax` alone
+- Added `show` parameter to `plot_pubmatrix_heatmap()`; `plt.show()` no longer called automatically
+- Replaced `print()` with `logging` throughout — output can now be suppressed or redirected
+- Narrowed exception handling in `_fetch_count()` to `requests.RequestException`
+- Fixed float-unsafe clustering check (`np.allclose` instead of `==`)
+- `n_tries` and `n_workers` now validated with clear error messages
+- `odfpy` moved to optional extra: `pip install pubmatrixpython[ods]`
+- Requires Python ≥ 3.10 (relaxed from 3.13)
+- Full test suite: 60 tests covering core queries, XML parsing, caching, retry logic, and heatmap rendering
+
+## [0.1.0] — 2026-03-28
+
+Initial release. Python port of [PubMatrixR](https://github.com/ToledoEM/PubMatrixR-v2).
+
+- `pubmatrix()` — pairwise PubMed/PMC co-occurrence queries with progress bar
+- `pubmatrix_from_file()` — load term lists from a plain-text file
+- `plot_pubmatrix_heatmap()` — heatmap with optional clustering, custom colours, PNG export
+- `pubmatrix_heatmap()` — quick wrapper with defaults
+- Date range filtering via `daterange`
+- CSV and ODS export with PubMed hyperlinks
+- NCBI API key support for higher rate limits

pubmatrixpython-0.2.0/LICENSE

@@ -0,0 +1,2 @@
+YEAR: 2026
+COPYRIGHT HOLDER: Enrique Toledo

pubmatrixpython-0.2.0/LICENSE.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2026 Enrique Toledo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pubmatrixpython-0.2.0/PKG-INFO

@@ -0,0 +1,300 @@
+Metadata-Version: 2.4
+Name: pubmatrixpython
+Version: 0.2.0
+Summary: Python port of PubMatrixR — systematic literature co-occurrence analysis via NCBI PubMed
+Project-URL: Homepage, https://toledoem.github.io/pubmatrixp/
+Project-URL: Repository, https://github.com/ToledoEM/PubMatrixPython
+Project-URL: Changelog, https://github.com/ToledoEM/PubMatrixPython/blob/main/CHANGELOG.md
+Author-email: Enrique Toledo <enriquetoledo@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+License-File: LICENSE.md
+Keywords: bioinformatics,co-occurrence,literature-mining,ncbi,pubmed
+Classifier: Development Status :: 4 - Beta
+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
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.10
+Requires-Dist: matplotlib<4,>=3.10
+Requires-Dist: pandas<4,>=2.0
+Requires-Dist: requests<3,>=2.33
+Requires-Dist: scipy<2,>=1.10
+Requires-Dist: seaborn<1,>=0.13
+Requires-Dist: tqdm<5,>=4.60
+Provides-Extra: ods
+Requires-Dist: odfpy>=1.4.1; extra == 'ods'
+Description-Content-Type: text/markdown
+
+# PubMatrixPython v0.2
+
+<img src="https://toledoem.github.io/img/LogoPubmatrixP.png" align="right" width="150"/>
+
+![Python](https://img.shields.io/badge/python-3.10%2B-blue)
+![Tests](https://img.shields.io/badge/tests-60%20passed-brightgreen)
+![License](https://img.shields.io/badge/license-MIT-green)
+
+Python port of the [PubMatrixR](https://github.com/ToledoEM/PubMatrixR-v2) R package.
+
+For every pair of search terms `(A, B)`, it counts how many PubMed or PMC publications mention both. Good for mapping relationships between genes, diseases, and pathways across the literature.
+
+Based on: Becker et al. (2003) *PubMatrix: a tool for multiplex literature mining*. BMC Bioinformatics 4:61. https://doi.org/10.1186/1471-2105-4-61
+
+---
+
+## Key features
+
+- **Pairwise literature search** — automatically searches every combination of terms from two lists
+- **PubMed or PMC** — query MEDLINE abstracts or PMC full text via NCBI E-utilities
+- **Heatmap visualisation** — overlap-percentage heatmaps with optional hierarchical clustering
+- **Export to CSV or ODS** — results include clickable hyperlinks to the matching PubMed search
+- **Date filtering** — restrict searches to a publication year range
+- **Flexible input** — pass term lists directly, or load them from a text file
+- **Concurrency** — `n_workers` for parallel queries, respecting NCBI rate limits
+- **Disk caching** — `cache_dir` persists query results between runs
+- **Progress tracking** — built-in progress bar for long searches
+
+## Use cases
+
+- **Gene–disease association studies** — explore literature connections between genes and diseases
+- **Pathway analysis** — investigate co-occurrence of genes within or across biological pathways
+- **Drug–target research** — analyse relationships between compounds and potential targets
+- **Systematic literature reviews** — quantify research coverage across multiple topics
+- **Knowledge gap identification** — find under-researched combinations of terms
+- **Bibliometric analysis** — measure research activity in a domain over time
+
+---
+
+## Setup
+
+Requires [uv](https://docs.astral.sh/uv/). Install it with:
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+Clone and install dependencies:
+
+```bash
+git clone <repo-url>
+cd PubMatrixPython
+uv sync --all-groups
+```
+
+---
+
+## Running the notebooks
+
+All `uv` commands must be run from the **project root** (`PubMatrixPython/`), where `pyproject.toml` lives.
+
+```bash
+cd /path/to/PubMatrixPython
+uv run jupyter lab
+```
+
+Then open any notebook from the `notebooks/` folder in the browser.
+
+| Notebook | What it covers |
+|----------|---------------|
+| `01_pubmatrix.ipynb` | Basic queries, date filtering, PMC database, file input, CSV export, heatmap visualisation |
+| `02_example_wnt.ipynb` | Full worked example: WNT genes × obesity genes |
+
+---
+
+## Quick start (script or REPL)
+
+### Interactive REPL
+
+```bash
+uv run python
+```
+
+```python
+from pubmatrix import pubmatrix, plot_pubmatrix_heatmap
+
+A = ["WNT1", "WNT2", "CTNNB1"]
+B = ["obesity", "diabetes", "cancer"]
+
+result = pubmatrix(A=A, B=B)
+print(result)
+
+plot_pubmatrix_heatmap(result, title="WNT × Disease")
+```
+
+### Running a script
+
+Create a file `my_analysis.py`:
+
+```python
+from pubmatrix import pubmatrix, plot_pubmatrix_heatmap
+
+A = ["WNT1", "WNT2", "WNT3A", "WNT5A", "CTNNB1"]
+B = ["obesity", "diabetes", "cancer", "inflammation"]
+
+result = pubmatrix(
+    A=A,
+    B=B,
+    database="pubmed",
+    daterange=[2010, 2024],   # optional date filter
+    outfile="results",
+    export_format="csv",      # saves results_result.csv with PubMed hyperlinks
+)
+
+print(result)
+
+plot_pubmatrix_heatmap(
+    result,
+    title="WNT Genes × Disease",
+    filename="heatmap.png",   # saves to file instead of displaying
+)
+```
+
+Run it with:
+
+```bash
+uv run python my_analysis.py
+```
+
+### Loading terms from a file
+
+Create `terms.txt`:
+
+```
+WNT1
+WNT2
+CTNNB1
+#
+obesity
+diabetes
+cancer
+```
+
+```python
+from pubmatrix import pubmatrix_from_file
+
+result = pubmatrix_from_file("terms.txt")
+print(result)
+```
+
+```bash
+uv run python my_analysis.py
+```
+
+---
+
+## API reference
+
+### `pubmatrix(A, B, ...)`
+
+Query PubMed and return a `pandas.DataFrame` (rows = B, cols = A).
+
+```python
+pubmatrix(
+    A,                    # list of str — column terms
+    B,                    # list of str — row terms
+    api_key=None,         # NCBI API key (10 req/s vs 3 req/s default)
+    database="pubmed",    # "pubmed" or "pmc"
+    daterange=None,       # e.g. [2015, 2024]
+    outfile=None,         # base filename for export
+    export_format=None,   # None | "csv" | "ods"
+    n_tries=2,            # retries on network failure
+    n_workers=1,          # parallel workers for concurrent queries
+    timeout=30,           # HTTP request timeout in seconds
+    cache_dir=None,       # directory to cache query results on disk
+)
+```
+
+### `pubmatrix_from_file(filepath, ...)`
+
+Load terms from a plain-text file and run `pubmatrix()`.
+
+File format:
+```
+WNT1
+WNT2
+#
+obesity
+diabetes
+```
+
+```python
+result = pubmatrix_from_file("terms.txt", database="pubmed")
+```
+
+### `plot_pubmatrix_heatmap(matrix, ...)`
+
+Heatmap of overlap percentages with optional hierarchical clustering. Returns `(fig, ax)`.
+
+```python
+fig, ax = plot_pubmatrix_heatmap(
+    matrix,                                        # DataFrame from pubmatrix()
+    title="PubMatrix Co-occurrence Heatmap",
+    cluster_rows=True,
+    cluster_cols=True,
+    show_numbers=True,
+    color_palette=None,                            # list of hex colours
+    filename=None,                                 # save to PNG if set
+    width=10, height=8,
+    scale_font=True,
+    show=False,                                    # call plt.show() after plotting
+)
+```
+
+### `pubmatrix_heatmap(matrix, title=...)`
+
+Quick wrapper around `plot_pubmatrix_heatmap()` with all defaults. Returns `(fig, ax)`.
+
+---
+
+## Output files
+
+When `outfile` and `export_format` are set, results are written to
+`{outfile}_result.{extension}` (`.csv` or `.ods`). Each cell contains the
+publication count and a hyperlink to the matching PubMed search. Row names
+come from `B`, column names from `A`.
+
+ODS export requires the optional `odfpy` dependency:
+
+```bash
+pip install pubmatrixpython[ods]
+```
+
+---
+
+## NCBI API key
+
+Without a key: 3 requests/second. With a key: 10 requests/second.
+Get one at https://account.ncbi.nlm.nih.gov/
+
+```python
+result = pubmatrix(A=A, B=B, api_key="YOUR_KEY_HERE")
+```
+
+---
+
+## More documentation
+
+- [Performance notes](docs/performance.md) — rate limits, caching, concurrency
+- [Troubleshooting](docs/troubleshooting.md) — empty results, rate limiting, slow searches
+- [Full reference notebook](https://toledoem.github.io/pubmatrixp/) — every parameter and feature, with output
+
+---
+
+## License & citation
+
+This project is licensed under the MIT License — see [`LICENSE.md`](LICENSE.md).
+
+If you use PubMatrixPython in your research, please cite:
+
+> Becker KG, Hosack DA, Dennis G Jr, Lempicki RA, Bright TJ, Cheadle C, Engel J.
+> *PubMatrix: a tool for multiplex literature mining.*
+> BMC Bioinformatics. 2003 Dec 10;4:61. https://doi.org/10.1186/1471-2105-4-61
+
+**Developers:**
+- Tyler Laird (Author, original PubMatrixR)
+- Enrique Toledo (Author, maintainer)

pubmatrixpython-0.2.0/README.md

@@ -0,0 +1,267 @@
+# PubMatrixPython v0.2
+
+<img src="https://toledoem.github.io/img/LogoPubmatrixP.png" align="right" width="150"/>
+
+![Python](https://img.shields.io/badge/python-3.10%2B-blue)
+![Tests](https://img.shields.io/badge/tests-60%20passed-brightgreen)
+![License](https://img.shields.io/badge/license-MIT-green)
+
+Python port of the [PubMatrixR](https://github.com/ToledoEM/PubMatrixR-v2) R package.
+
+For every pair of search terms `(A, B)`, it counts how many PubMed or PMC publications mention both. Good for mapping relationships between genes, diseases, and pathways across the literature.
+
+Based on: Becker et al. (2003) *PubMatrix: a tool for multiplex literature mining*. BMC Bioinformatics 4:61. https://doi.org/10.1186/1471-2105-4-61
+
+---
+
+## Key features
+
+- **Pairwise literature search** — automatically searches every combination of terms from two lists
+- **PubMed or PMC** — query MEDLINE abstracts or PMC full text via NCBI E-utilities
+- **Heatmap visualisation** — overlap-percentage heatmaps with optional hierarchical clustering
+- **Export to CSV or ODS** — results include clickable hyperlinks to the matching PubMed search
+- **Date filtering** — restrict searches to a publication year range
+- **Flexible input** — pass term lists directly, or load them from a text file
+- **Concurrency** — `n_workers` for parallel queries, respecting NCBI rate limits
+- **Disk caching** — `cache_dir` persists query results between runs
+- **Progress tracking** — built-in progress bar for long searches
+
+## Use cases
+
+- **Gene–disease association studies** — explore literature connections between genes and diseases
+- **Pathway analysis** — investigate co-occurrence of genes within or across biological pathways
+- **Drug–target research** — analyse relationships between compounds and potential targets
+- **Systematic literature reviews** — quantify research coverage across multiple topics
+- **Knowledge gap identification** — find under-researched combinations of terms
+- **Bibliometric analysis** — measure research activity in a domain over time
+
+---
+
+## Setup
+
+Requires [uv](https://docs.astral.sh/uv/). Install it with:
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+Clone and install dependencies:
+
+```bash
+git clone <repo-url>
+cd PubMatrixPython
+uv sync --all-groups
+```
+
+---
+
+## Running the notebooks
+
+All `uv` commands must be run from the **project root** (`PubMatrixPython/`), where `pyproject.toml` lives.
+
+```bash
+cd /path/to/PubMatrixPython
+uv run jupyter lab
+```
+
+Then open any notebook from the `notebooks/` folder in the browser.
+
+| Notebook | What it covers |
+|----------|---------------|
+| `01_pubmatrix.ipynb` | Basic queries, date filtering, PMC database, file input, CSV export, heatmap visualisation |
+| `02_example_wnt.ipynb` | Full worked example: WNT genes × obesity genes |
+
+---
+
+## Quick start (script or REPL)
+
+### Interactive REPL
+
+```bash
+uv run python
+```
+
+```python
+from pubmatrix import pubmatrix, plot_pubmatrix_heatmap
+
+A = ["WNT1", "WNT2", "CTNNB1"]
+B = ["obesity", "diabetes", "cancer"]
+
+result = pubmatrix(A=A, B=B)
+print(result)
+
+plot_pubmatrix_heatmap(result, title="WNT × Disease")
+```
+
+### Running a script
+
+Create a file `my_analysis.py`:
+
+```python
+from pubmatrix import pubmatrix, plot_pubmatrix_heatmap
+
+A = ["WNT1", "WNT2", "WNT3A", "WNT5A", "CTNNB1"]
+B = ["obesity", "diabetes", "cancer", "inflammation"]
+
+result = pubmatrix(
+    A=A,
+    B=B,
+    database="pubmed",
+    daterange=[2010, 2024],   # optional date filter
+    outfile="results",
+    export_format="csv",      # saves results_result.csv with PubMed hyperlinks
+)
+
+print(result)
+
+plot_pubmatrix_heatmap(
+    result,
+    title="WNT Genes × Disease",
+    filename="heatmap.png",   # saves to file instead of displaying
+)
+```
+
+Run it with:
+
+```bash
+uv run python my_analysis.py
+```
+
+### Loading terms from a file
+
+Create `terms.txt`:
+
+```
+WNT1
+WNT2
+CTNNB1
+#
+obesity
+diabetes
+cancer
+```
+
+```python
+from pubmatrix import pubmatrix_from_file
+
+result = pubmatrix_from_file("terms.txt")
+print(result)
+```
+
+```bash
+uv run python my_analysis.py
+```
+
+---
+
+## API reference
+
+### `pubmatrix(A, B, ...)`
+
+Query PubMed and return a `pandas.DataFrame` (rows = B, cols = A).
+
+```python
+pubmatrix(
+    A,                    # list of str — column terms
+    B,                    # list of str — row terms
+    api_key=None,         # NCBI API key (10 req/s vs 3 req/s default)
+    database="pubmed",    # "pubmed" or "pmc"
+    daterange=None,       # e.g. [2015, 2024]
+    outfile=None,         # base filename for export
+    export_format=None,   # None | "csv" | "ods"
+    n_tries=2,            # retries on network failure
+    n_workers=1,          # parallel workers for concurrent queries
+    timeout=30,           # HTTP request timeout in seconds
+    cache_dir=None,       # directory to cache query results on disk
+)
+```
+
+### `pubmatrix_from_file(filepath, ...)`
+
+Load terms from a plain-text file and run `pubmatrix()`.
+
+File format:
+```
+WNT1
+WNT2
+#
+obesity
+diabetes
+```
+
+```python
+result = pubmatrix_from_file("terms.txt", database="pubmed")
+```
+
+### `plot_pubmatrix_heatmap(matrix, ...)`
+
+Heatmap of overlap percentages with optional hierarchical clustering. Returns `(fig, ax)`.
+
+```python
+fig, ax = plot_pubmatrix_heatmap(
+    matrix,                                        # DataFrame from pubmatrix()
+    title="PubMatrix Co-occurrence Heatmap",
+    cluster_rows=True,
+    cluster_cols=True,
+    show_numbers=True,
+    color_palette=None,                            # list of hex colours
+    filename=None,                                 # save to PNG if set
+    width=10, height=8,
+    scale_font=True,
+    show=False,                                    # call plt.show() after plotting
+)
+```
+
+### `pubmatrix_heatmap(matrix, title=...)`
+
+Quick wrapper around `plot_pubmatrix_heatmap()` with all defaults. Returns `(fig, ax)`.
+
+---
+
+## Output files
+
+When `outfile` and `export_format` are set, results are written to
+`{outfile}_result.{extension}` (`.csv` or `.ods`). Each cell contains the
+publication count and a hyperlink to the matching PubMed search. Row names
+come from `B`, column names from `A`.
+
+ODS export requires the optional `odfpy` dependency:
+
+```bash
+pip install pubmatrixpython[ods]
+```
+
+---
+
+## NCBI API key
+
+Without a key: 3 requests/second. With a key: 10 requests/second.
+Get one at https://account.ncbi.nlm.nih.gov/
+
+```python
+result = pubmatrix(A=A, B=B, api_key="YOUR_KEY_HERE")
+```
+
+---
+
+## More documentation
+
+- [Performance notes](docs/performance.md) — rate limits, caching, concurrency
+- [Troubleshooting](docs/troubleshooting.md) — empty results, rate limiting, slow searches
+- [Full reference notebook](https://toledoem.github.io/pubmatrixp/) — every parameter and feature, with output
+
+---
+
+## License & citation
+
+This project is licensed under the MIT License — see [`LICENSE.md`](LICENSE.md).
+
+If you use PubMatrixPython in your research, please cite:
+
+> Becker KG, Hosack DA, Dennis G Jr, Lempicki RA, Bright TJ, Cheadle C, Engel J.
+> *PubMatrix: a tool for multiplex literature mining.*
+> BMC Bioinformatics. 2003 Dec 10;4:61. https://doi.org/10.1186/1471-2105-4-61
+
+**Developers:**
+- Tyler Laird (Author, original PubMatrixR)
+- Enrique Toledo (Author, maintainer)