polyform-lattice 0.1.0__tar.gz

polyform_lattice-0.1.0/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to this project are documented here. This project adheres
+to [Semantic Versioning](https://semver.org/).
+
+## [0.1.0] — 2026-07-13
+
+### Added
+- First packaged release of PolyForm.
+- `polyform.run_support_mode` — global support-mode structural metrics on the
+  choice-free modal lattice (state access, grade distributions, fibre refinement).
+- `polyform.run_weight_mode` — demonstration occupancy metrics on real observed
+  proteoform supports.
+- `polyform.run_topology` — tissue-resolved Hamming-1 support topology on a
+  top-down human atlas (empirical + k=0-anchored), including accession-level
+  sharing and lattice heatmaps.
+- `polyform.core` — pure, importable primitives (PTM parsing, FASTA reading,
+  Hamming topology, information measures) copied verbatim from the manuscript
+  analysis scripts.
+- `polyform` command-line interface with `support`, `weight`, and `topology`
+  subcommands.
+
+### Notes
+- The computational bodies of the original manuscript scripts (in `manuscript/`)
+  are preserved unchanged as the provenance record. The packaged functions were
+  validated to reproduce their reference outputs exactly.

polyform_lattice-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 James N. Cobley
+
+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.

polyform_lattice-0.1.0/PKG-INFO

@@ -0,0 +1,172 @@
+Metadata-Version: 2.4
+Name: polyform-lattice
+Version: 0.1.0
+Summary: Structured analysis of proteoform distributions on finite, bounded, k-graded modal lattices.
+Project-URL: Homepage, https://github.com/JamesCobley/PolyForm
+Project-URL: Repository, https://github.com/JamesCobley/PolyForm
+Project-URL: Issues, https://github.com/JamesCobley/PolyForm/issues
+Author: James N. Cobley
+License: MIT License
+        
+        Copyright (c) 2026 James N. Cobley
+        
+        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.
+License-File: LICENSE
+Keywords: PTM,hamming,mass-spectrometry,modal-lattice,occupancy,proteoform,proteomics,top-down,topology
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.9
+Requires-Dist: matplotlib>=3.6
+Requires-Dist: numpy>=1.23
+Requires-Dist: openpyxl>=3.0
+Requires-Dist: pandas>=1.5
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# PolyForm
+
+PolyForm is a Python package for structured analysis of proteoform
+distributions. It maps measured proteoform catalogues onto finite, bounded,
+*k*-graded modal lattices and computes structure-derived metrics including
+state identity, occupancy, grade spread, support topology, native clustering,
+principal occupied components, and statistical surprise.
+
+## Install
+
+```bash
+pip install polyform-lattice
+```
+
+> The **import** name is `polyform`; the **PyPI distribution** name is
+> `polyform-lattice` (the plain name `polyform` was already taken by an
+> unrelated project). So you `pip install polyform-lattice` but `import polyform`.
+
+From source (for development):
+
+```bash
+git clone https://github.com/JamesCobley/PolyForm.git
+cd PolyForm
+pip install -e .
+```
+
+## Usage
+
+### Python API
+
+Each analysis is a single call that returns a dict of pandas DataFrames and,
+by default, writes CSVs and figures to an output directory.
+
+```python
+import polyform
+
+# Global support-mode structural metrics on the choice-free modal lattice
+support = polyform.run_support_mode(csv="proteoforms.csv", outdir="out_support")
+support["global"]           # one-row global summary
+support["protein_metrics"]  # protein-level structural metrics
+support["grade"]            # protein-by-grade metrics
+
+# Demonstration occupancy metrics on real observed supports
+weight = polyform.run_weight_mode(csv="proteoforms.csv", outdir="out_weight")
+weight["selected"]          # proteins selected for demonstration
+weight["metrics"]           # occupancy-dependent metrics
+
+# Tissue-resolved Hamming-1 support topology on a top-down atlas
+topology = polyform.run_topology(xlsx="atlas.xlsx", outdir="out_topology")
+topology["tissue_summary"]
+topology["components"]
+```
+
+Set `make_figures=False` to skip figure rendering (faster; CSVs still written).
+
+### Command line
+
+```bash
+polyform support   --csv proteoforms.csv --outdir out_support
+polyform weight    --csv proteoforms.csv --outdir out_weight
+polyform topology  --xlsx atlas.xlsx     --outdir out_topology
+
+polyform support --help      # per-command options
+polyform --version
+```
+
+### Core primitives
+
+The lattice/topology/information primitives are importable directly:
+
+```python
+from polyform.core import (
+    parse_ptms, read_fasta, log10_comb, hamming_distance_state,
+    connected_components_for_states, shannon_entropy, normalized_entropy,
+)
+```
+
+## Inputs
+
+- **Support / weight modes** expect a proteoform catalogue CSV with at least
+  `Entry Accession` and `PTMs` columns; protein lengths are resolved from an
+  `Isoform Sequence` column or an optional `--fasta`. PTM strings use the
+  `RESID:<code>@<position>` form, `|`-separated.
+- **Topology mode** expects the multi-tissue top-down atlas spreadsheet
+  (`--sheet`, default `All_Tissues`).
+
+## Outputs
+
+Each mode writes a set of `.csv` tables plus publication `.png`/`.pdf` figures
+into its `--outdir`. See each function's docstring for the exact file list.
+
+## Reproducibility
+
+The original manuscript analysis scripts are preserved unchanged under
+[`manuscript/`](manuscript/) as the provenance record. The packaged `run_*`
+functions wrap those exact computational bodies (only parameterising
+configuration and routing outputs) and were validated to reproduce the
+manuscript reference outputs.
+
+## Releasing (maintainers)
+
+Releases publish to PyPI via **Trusted Publishing** (OIDC — no API tokens).
+One-time setup: on PyPI, add a trusted publisher for the project pointing at
+this repo's `publish.yml` workflow and a `pypi` environment.
+
+To cut a release:
+
+```bash
+# bump version in pyproject.toml and src/polyform/__init__.py, update CHANGELOG.md
+git commit -am "Release v0.1.0"
+git tag v0.1.0
+git push origin main --tags
+```
+
+Pushing the tag triggers `.github/workflows/publish.yml`, which builds the
+sdist + wheel, runs `twine check`, and publishes to PyPI.
+
+## License
+
+MIT © 2026 James N. Cobley

polyform_lattice-0.1.0/README.md

@@ -0,0 +1,120 @@
+# PolyForm
+
+PolyForm is a Python package for structured analysis of proteoform
+distributions. It maps measured proteoform catalogues onto finite, bounded,
+*k*-graded modal lattices and computes structure-derived metrics including
+state identity, occupancy, grade spread, support topology, native clustering,
+principal occupied components, and statistical surprise.
+
+## Install
+
+```bash
+pip install polyform-lattice
+```
+
+> The **import** name is `polyform`; the **PyPI distribution** name is
+> `polyform-lattice` (the plain name `polyform` was already taken by an
+> unrelated project). So you `pip install polyform-lattice` but `import polyform`.
+
+From source (for development):
+
+```bash
+git clone https://github.com/JamesCobley/PolyForm.git
+cd PolyForm
+pip install -e .
+```
+
+## Usage
+
+### Python API
+
+Each analysis is a single call that returns a dict of pandas DataFrames and,
+by default, writes CSVs and figures to an output directory.
+
+```python
+import polyform
+
+# Global support-mode structural metrics on the choice-free modal lattice
+support = polyform.run_support_mode(csv="proteoforms.csv", outdir="out_support")
+support["global"]           # one-row global summary
+support["protein_metrics"]  # protein-level structural metrics
+support["grade"]            # protein-by-grade metrics
+
+# Demonstration occupancy metrics on real observed supports
+weight = polyform.run_weight_mode(csv="proteoforms.csv", outdir="out_weight")
+weight["selected"]          # proteins selected for demonstration
+weight["metrics"]           # occupancy-dependent metrics
+
+# Tissue-resolved Hamming-1 support topology on a top-down atlas
+topology = polyform.run_topology(xlsx="atlas.xlsx", outdir="out_topology")
+topology["tissue_summary"]
+topology["components"]
+```
+
+Set `make_figures=False` to skip figure rendering (faster; CSVs still written).
+
+### Command line
+
+```bash
+polyform support   --csv proteoforms.csv --outdir out_support
+polyform weight    --csv proteoforms.csv --outdir out_weight
+polyform topology  --xlsx atlas.xlsx     --outdir out_topology
+
+polyform support --help      # per-command options
+polyform --version
+```
+
+### Core primitives
+
+The lattice/topology/information primitives are importable directly:
+
+```python
+from polyform.core import (
+    parse_ptms, read_fasta, log10_comb, hamming_distance_state,
+    connected_components_for_states, shannon_entropy, normalized_entropy,
+)
+```
+
+## Inputs
+
+- **Support / weight modes** expect a proteoform catalogue CSV with at least
+  `Entry Accession` and `PTMs` columns; protein lengths are resolved from an
+  `Isoform Sequence` column or an optional `--fasta`. PTM strings use the
+  `RESID:<code>@<position>` form, `|`-separated.
+- **Topology mode** expects the multi-tissue top-down atlas spreadsheet
+  (`--sheet`, default `All_Tissues`).
+
+## Outputs
+
+Each mode writes a set of `.csv` tables plus publication `.png`/`.pdf` figures
+into its `--outdir`. See each function's docstring for the exact file list.
+
+## Reproducibility
+
+The original manuscript analysis scripts are preserved unchanged under
+[`manuscript/`](manuscript/) as the provenance record. The packaged `run_*`
+functions wrap those exact computational bodies (only parameterising
+configuration and routing outputs) and were validated to reproduce the
+manuscript reference outputs.
+
+## Releasing (maintainers)
+
+Releases publish to PyPI via **Trusted Publishing** (OIDC — no API tokens).
+One-time setup: on PyPI, add a trusted publisher for the project pointing at
+this repo's `publish.yml` workflow and a `pypi` environment.
+
+To cut a release:
+
+```bash
+# bump version in pyproject.toml and src/polyform/__init__.py, update CHANGELOG.md
+git commit -am "Release v0.1.0"
+git tag v0.1.0
+git push origin main --tags
+```
+
+Pushing the tag triggers `.github/workflows/publish.yml`, which builds the
+sdist + wheel, runs `twine check`, and publishes to PyPI.
+
+## License
+
+MIT © 2026 James N. Cobley

polyform_lattice-0.1.0/pyproject.toml

@@ -0,0 +1,63 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+# NOTE: the PyPI *distribution* name is `polyform-lattice` because the plain
+# name `polyform` is already taken by an unrelated project. The *import* name
+# is still `polyform` (i.e. `import polyform`). To change the distribution
+# name, edit the single `name` field below.
+name = "polyform-lattice"
+version = "0.1.0"
+description = "Structured analysis of proteoform distributions on finite, bounded, k-graded modal lattices."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { file = "LICENSE" }
+authors = [{ name = "James N. Cobley" }]
+keywords = [
+    "proteoform", "proteomics", "modal-lattice", "PTM", "top-down",
+    "hamming", "topology", "occupancy", "mass-spectrometry",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+]
+dependencies = [
+    "numpy>=1.23",
+    "pandas>=1.5",
+    "matplotlib>=3.6",
+    "openpyxl>=3.0",
+]
+
+[project.optional-dependencies]
+dev = ["build", "twine", "pytest"]
+
+[project.urls]
+Homepage = "https://github.com/JamesCobley/PolyForm"
+Repository = "https://github.com/JamesCobley/PolyForm"
+Issues = "https://github.com/JamesCobley/PolyForm/issues"
+
+[project.scripts]
+polyform = "polyform.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/polyform"]
+
+[tool.hatch.build.targets.sdist]
+# keep the distributed source archive lean: ship the package + docs only,
+# not the multi-megabyte manuscript data.
+include = [
+    "src/polyform",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "pyproject.toml",
+]

polyform_lattice-0.1.0/src/polyform/__init__.py

@@ -0,0 +1,49 @@
+name: Publish to PyPI
+
+# Publishes on every pushed tag that looks like a version, e.g. v0.1.0
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+
+      - name: Check metadata
+        run: |
+          python -m pip install --upgrade twine
+          python -m twine check dist/*
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write   # required for Trusted Publishing (OIDC); no API token needed
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1

polyform_lattice-0.1.0/src/polyform/cli.py

@@ -0,0 +1,107 @@
+"""
+Command-line interface for PolyForm.
+
+    polyform support   --csv proteoforms.csv       --outdir out_support
+    polyform weight    --csv proteoforms.csv       --outdir out_weight
+    polyform topology  --xlsx atlas.xlsx           --outdir out_topology
+
+Each subcommand runs the corresponding analysis, writes CSVs (and, unless
+``--no-figures`` is passed, figures) to ``--outdir``, and prints a short
+summary of the result tables.
+"""
+import argparse
+import sys
+
+from . import __version__
+
+
+def _summarise(results):
+    for key, df in results.items():
+        try:
+            print(f"  {key:28s} {len(df):>8d} rows x {len(df.columns):>3d} cols")
+        except Exception:
+            print(f"  {key:28s} {type(df).__name__}")
+
+
+def main(argv=None):
+    argv = list(sys.argv[1:] if argv is None else argv)
+
+    parser = argparse.ArgumentParser(
+        prog="polyform",
+        description="Structured analysis of proteoform distributions on modal lattices.",
+    )
+    parser.add_argument("--version", action="version",
+                        version=f"polyform {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    # support --------------------------------------------------------------
+    p_sup = sub.add_parser("support", help="global support-mode structural metrics")
+    p_sup.add_argument("--csv", default="proteoforms.csv",
+                       help="proteoform catalogue CSV (default: proteoforms.csv)")
+    p_sup.add_argument("--fasta", default=None,
+                       help="optional UniProt FASTA to resolve lengths")
+    p_sup.add_argument("--pos-base", type=int, default=0,
+                       help="set to 1 if RESID positions are 1-based")
+    p_sup.add_argument("--outdir", default="polyform_support_outputs")
+    p_sup.add_argument("--dpi", type=int, default=300)
+    p_sup.add_argument("--no-figures", action="store_true")
+
+    # weight ---------------------------------------------------------------
+    p_w = sub.add_parser("weight", help="demonstration occupancy metrics")
+    p_w.add_argument("--csv", default="proteoforms.csv")
+    p_w.add_argument("--fasta", default=None)
+    p_w.add_argument("--pos-base", type=int, default=0)
+    p_w.add_argument("--outdir", default="polyform_02_demo_occupancy_outputs")
+    p_w.add_argument("--select-n", type=int, default=8)
+    p_w.add_argument("--min-states", type=int, default=5)
+    p_w.add_argument("--min-delta-k", type=int, default=3)
+    p_w.add_argument("--dpi", type=int, default=300)
+    p_w.add_argument("--seed", type=int, default=7)
+    p_w.add_argument("--no-figures", action="store_true")
+
+    # topology -------------------------------------------------------------
+    p_t = sub.add_parser("topology", help="tissue-resolved support topology")
+    p_t.add_argument("--xlsx", default="pr2c00034_si_002 (1).xlsx",
+                     help="multi-tissue atlas spreadsheet")
+    p_t.add_argument("--outdir", default="polyform_03_tissue_support_topology_outputs")
+    p_t.add_argument("--sheet", default="All_Tissues")
+    p_t.add_argument("--no-group-by-sequence", action="store_true")
+    p_t.add_argument("--no-k0-anchor", action="store_true")
+    p_t.add_argument("--dpi", type=int, default=300)
+    p_t.add_argument("--seed", type=int, default=7)
+    p_t.add_argument("--no-figures", action="store_true")
+
+    args = parser.parse_args(argv)
+
+    if args.command == "support":
+        from .support_mode import run_support_mode
+        results = run_support_mode(
+            csv=args.csv, fasta_path=args.fasta, pos_base=args.pos_base,
+            outdir=args.outdir, make_figures=not args.no_figures, dpi=args.dpi,
+        )
+    elif args.command == "weight":
+        from .weight_mode import run_weight_mode
+        results = run_weight_mode(
+            csv=args.csv, fasta_path=args.fasta, pos_base=args.pos_base,
+            outdir=args.outdir, select_n=args.select_n, min_states=args.min_states,
+            min_delta_k=args.min_delta_k, make_figures=not args.no_figures,
+            dpi=args.dpi, random_seed=args.seed,
+        )
+    elif args.command == "topology":
+        from .topology import run_topology
+        results = run_topology(
+            xlsx=args.xlsx, outdir=args.outdir, sheet_name=args.sheet,
+            group_by_sequence=not args.no_group_by_sequence,
+            add_k0_anchor=not args.no_k0_anchor,
+            make_figures=not args.no_figures, dpi=args.dpi, random_seed=args.seed,
+        )
+    else:  # pragma: no cover
+        parser.error(f"unknown command {args.command!r}")
+
+    print(f"\nResult tables (written to {args.outdir}):")
+    _summarise(results)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())