egt 0.1.0__tar.gz

egt-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Darrin T. Schultz
+
+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.

egt-0.1.0/PKG-INFO

@@ -0,0 +1,285 @@
+Metadata-Version: 2.4
+Name: egt
+Version: 0.1.0
+Summary: Evolutionary Genome Topology — analysis toolkit for chromosome evolution across metazoan genomes using reciprocal-best-hits data.
+Author-email: "Darrin T. Schultz" <darrin.schultz@univie.ac.at>
+License: MIT
+Project-URL: Homepage, https://github.com/conchoecia/egt
+Project-URL: Source code, https://github.com/conchoecia/egt
+Project-URL: Manuscript, https://github.com/conchoecia/egt/blob/main/docs/manuscript.md
+Project-URL: odp, https://github.com/conchoecia/odp
+Keywords: comparative genomics,chromosome evolution,ancestral linkage groups,ALG,synteny,UMAP,phylogenetics
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+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.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: scipy
+Requires-Dist: scikit-learn
+Requires-Dist: matplotlib
+Requires-Dist: networkx
+Requires-Dist: Pillow
+Requires-Dist: umap-learn[plot]
+Requires-Dist: bokeh
+Requires-Dist: ete4
+Requires-Dist: snakemake<9,>=7
+Requires-Dist: pyyaml
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pyflakes; extra == "dev"
+Dynamic: license-file
+
+# egt — Evolutionary Genome Topology
+
+`egt` is a Python / Snakemake analysis toolkit for characterizing
+chromosome evolution across metazoan genomes. It builds on reciprocal-best-hits
+data from [`odp`](https://github.com/conchoecia/odp) and provides tools for:
+
+- ALG (ancestral linkage group) fusion, dispersal, and rate analyses
+- PhyloTreeUMAP: manifold projection of per-species ALG state (MGT, MLT, and
+  one-dot-one-genome variants)
+- perspective-chromosome reconstruction with Monte Carlo support
+- branch-wise rate analyses against a calibrated tree
+- Fourier-period analysis of rate time series
+- phylogenetic subsampling, tree prep, taxonomy utilities
+
+## Getting Started
+
+```sh
+git clone https://github.com/conchoecia/egt.git
+cd egt
+python -m venv .venv && source .venv/bin/activate
+pip install -e .
+
+egt --help
+bash tests/smoke/test_cli.sh
+```
+
+Primary input is a directory of per-species RBH files produced by `odp`
+against the BCnS ALG database. From there, most analyses are a single
+`egt <subcommand>` call or a Snakefile under `workflows/`.
+
+## Quick Start
+
+### PhyloTreeUMAP — manifold projection of per-species ALG state
+
+```sh
+# 1. build per-sample distance matrices + sampledf
+egt phylotreeumap build-distances \
+    --rbh-dir /path/to/rbh_files \
+    --alg-name BCnSSimakov2022 \
+    --sampledf-out GTUMAP/sampledf.tsv \
+    --distance-dir GTUMAP/distance_matrices/
+
+# 2. index ALG locus pairs
+egt phylotreeumap algcomboix \
+    --alg-rbh /path/to/LG_db/BCnSSimakov2022/BCnSSimakov2022.rbh \
+    --output GTUMAP/alg_combo_to_ix.tsv
+
+# 3. run the UMAP + HTML plot (MGT / MLT / ODOG variants)
+egt phylotreeumap mgt-mlt-umap --help
+```
+
+### ALG fusion analysis on a calibrated tree
+
+```sh
+egt alg-fusions --help
+```
+
+### Perspective-chromosome tree mapping + Monte Carlo rates
+
+```sh
+egt perspchrom-df-to-tree --help
+```
+
+### Rate analyses, Fourier periodicity, branch stats
+
+```sh
+egt branch-stats-vs-time    --help
+egt fourier-of-rates        --help
+egt fourier-support-vs-time --help
+egt collapsed-tree          --help
+egt tree-changes            --help
+egt decay-pairwise          --help
+egt decay-many-species      --help
+```
+
+### Phylogeny preparation
+
+```sh
+egt taxids-to-newick           --help
+egt newick-to-common-ancestors --help
+```
+
+## Users' Guide
+
+`egt` is a collection of analysis scripts rather than a monolithic pipeline.
+Each script is also registered as a subcommand of the `egt` console script:
+
+```sh
+egt alg-fusions --help
+# equivalent to
+python -m egt.plot_alg_fusions --help
+```
+
+### Installation
+
+```sh
+git clone https://github.com/conchoecia/egt.git
+cd egt
+python -m venv .venv && source .venv/bin/activate
+pip install -e .
+```
+
+### Python requirements
+
+Python 3.10 or newer. `pip install -e .` pulls the deps from `pyproject.toml`:
+
+- numpy, pandas, scipy, scikit-learn, matplotlib, networkx, Pillow
+- umap-learn[plot] — UMAP + the plotting extras needed by PhyloTreeUMAP
+- bokeh — interactive HTML plots
+- ete4 — taxonomy trees and NCBI taxid handling
+- snakemake (>=7, <9)
+- pyyaml
+
+Conda equivalent:
+
+```sh
+mamba install -c conda-forge -c bioconda \
+      python=3.11 numpy pandas scipy scikit-learn matplotlib networkx pillow \
+      "umap-learn" bokeh ete4 "snakemake<9" pyyaml
+pip install --no-deps -e .
+```
+
+### Upstream tools
+
+`egt` consumes outputs of several companion tools:
+
+- [`odp`](https://github.com/conchoecia/odp) — per-species RBH files, ALG
+  databases (BCnSSimakov2022 etc.)
+- [`chrombase`](https://github.com/conchoecia/chrombase) — chromosome-scale
+  NCBI genome database builder
+- [`genbargo`](https://github.com/conchoecia/genbargo) — embargo-aware
+  assembly curation
+- [`chromsim`](https://github.com/conchoecia/chromsim) — chromosome-evolution
+  simulations
+
+### CLI overview
+
+```
+phylotreeumap             — UMAP-over-ALG-topology (MGT, MLT, ODOG subcommands)
+phylotreeumap-subsample   — subsample species phylogenetically with per-clade caps
+alg-fusions               — plot fusion events on a phylogeny (canonical v3)
+alg-dispersion            — plot ALG dispersion across species
+perspchrom-df-to-tree     — map perspective-chromosome changes onto a tree (Monte Carlo)
+decay-pairwise            — pairwise ALG-decay analysis
+decay-many-species        — cross-species ALG conservation / decay
+chrom-number-vs-changes   — chromosome count vs rearrangement-rate scatter
+branch-stats-vs-time      — branch statistics against geologic time
+branch-stats-tree         — branch statistics laid out on a tree
+branch-stats-tree-pair    — paired branch-stats tree plots
+collapsed-tree            — collapsed-tree visualization
+tree-changes              — per-branch changes on a tree
+fourier-of-rates          — Fourier analysis of chromosomal change rates
+fourier-support-vs-time   — Fourier-support-vs-time plots
+count-unique-changes      — count unique changes per branch
+defining-features         — identify clade-defining features
+defining-features-plot    — plot defining features
+defining-features-plotRBH — plot defining features on RBH dataframes
+taxids-to-newick          — build a Newick tree from NCBI taxids
+newick-to-common-ancestors — divergence-time annotation from a timetree
+algs-split-across-scaffolds — find ALGs split across scaffolds
+get-assembly-sizes        — summarize assembly sizes
+pull-entries-from-yaml    — select rows from a YAML sample list
+aggregate-filechecker     — aggregate filechecker benchmarks
+aggregate-filesizes       — aggregate file-size summaries
+join-supplementary-tables — join table fragments
+phylotreeumap-plotdfs     — PhyloTreeUMAP plotting dataframe helper
+```
+
+### Snakemake workflows
+
+Multi-stage Snakemake definitions live under `workflows/`:
+
+```
+workflows/
+├── phylotree_umap.smk
+├── phylotree_umap_subsampling.smk
+├── perspchrom_df_stats_and_mc.smk
+├── annotate_sample_df.smk
+├── sample_to_num_chromosomes.smk
+├── odol_annotate_blast.smk
+└── pipeline/
+    ├── README.md
+    ├── config.template.yaml
+    └── run.sh
+```
+
+Each workflow is standalone and parameterized via a YAML config.
+
+### Input file formats
+
+- **RBH files** (`.rbh`) — tab-separated reciprocal-best-hits output of `odp`.
+  Filenames must embed the NCBI taxid as the second hyphen-separated field,
+  e.g. `speciesname-7777-something.rbh`.
+- **Sample dataframe** (`sampledf.tsv`) — output of
+  `egt phylotreeumap build-distances`; consumed by most downstream commands.
+- **ALG database RBH** — e.g. `BCnSSimakov2022.rbh`, from `odp`'s LG_db.
+- **Newick trees** — ete4-readable. `egt taxids-to-newick` emits these.
+- **Divergence-time tables** — TSV, as accepted by
+  `egt newick-to-common-ancestors`.
+
+## Layout
+
+```
+egt/
+├── src/egt/                    — Python package
+│   ├── cli.py                  — argparse dispatcher
+│   ├── _vendor/                — vendored, frozen plotting utilities
+│   ├── legacy/                 — prior versions of plot_ALG_fusions kept for parity
+│   └── *.py                    — one module per subcommand
+├── workflows/                  — Snakemake workflows
+├── configs/                    — example configs
+├── data/                       — small bundled data
+├── tests/
+│   ├── testdb/                 — mini_hydra + mini_urchin fixtures
+│   └── smoke/test_cli.sh       — CLI smoke test
+└── docs/
+```
+
+## Related tools
+
+- [`odp`](https://github.com/conchoecia/odp)
+- [`chrombase`](https://github.com/conchoecia/chrombase)
+- [`genbargo`](https://github.com/conchoecia/genbargo)
+- [`chromsim`](https://github.com/conchoecia/chromsim)
+
+## Citing egt
+
+If you use this toolkit, please cite:
+
+> Schultz, D.T., Blümel, A., Destanović, D., Sarigol, F., Simakov, O. (2024).
+> *Topological mixing and irreversibility in animal chromosome evolution.*
+> bioRxiv. [doi:10.1101/2024.07.29.605683](https://doi.org/10.1101/2024.07.29.605683)
+
+For background on the topological framework for comparative genomics, see:
+
+> Schultz, D.T., Simakov, O. (2026).
+> *Topological Approaches in Animal Comparative Genomics.*
+> Annual Review of Animal Biosciences 14(1), 17–48.
+> [doi:10.1146/annurev-animal-030424-084541](https://doi.org/10.1146/annurev-animal-030424-084541)
+
+See also [`CITATION.cff`](CITATION.cff).
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).

egt-0.1.0/README.md

@@ -0,0 +1,245 @@
+# egt — Evolutionary Genome Topology
+
+`egt` is a Python / Snakemake analysis toolkit for characterizing
+chromosome evolution across metazoan genomes. It builds on reciprocal-best-hits
+data from [`odp`](https://github.com/conchoecia/odp) and provides tools for:
+
+- ALG (ancestral linkage group) fusion, dispersal, and rate analyses
+- PhyloTreeUMAP: manifold projection of per-species ALG state (MGT, MLT, and
+  one-dot-one-genome variants)
+- perspective-chromosome reconstruction with Monte Carlo support
+- branch-wise rate analyses against a calibrated tree
+- Fourier-period analysis of rate time series
+- phylogenetic subsampling, tree prep, taxonomy utilities
+
+## Getting Started
+
+```sh
+git clone https://github.com/conchoecia/egt.git
+cd egt
+python -m venv .venv && source .venv/bin/activate
+pip install -e .
+
+egt --help
+bash tests/smoke/test_cli.sh
+```
+
+Primary input is a directory of per-species RBH files produced by `odp`
+against the BCnS ALG database. From there, most analyses are a single
+`egt <subcommand>` call or a Snakefile under `workflows/`.
+
+## Quick Start
+
+### PhyloTreeUMAP — manifold projection of per-species ALG state
+
+```sh
+# 1. build per-sample distance matrices + sampledf
+egt phylotreeumap build-distances \
+    --rbh-dir /path/to/rbh_files \
+    --alg-name BCnSSimakov2022 \
+    --sampledf-out GTUMAP/sampledf.tsv \
+    --distance-dir GTUMAP/distance_matrices/
+
+# 2. index ALG locus pairs
+egt phylotreeumap algcomboix \
+    --alg-rbh /path/to/LG_db/BCnSSimakov2022/BCnSSimakov2022.rbh \
+    --output GTUMAP/alg_combo_to_ix.tsv
+
+# 3. run the UMAP + HTML plot (MGT / MLT / ODOG variants)
+egt phylotreeumap mgt-mlt-umap --help
+```
+
+### ALG fusion analysis on a calibrated tree
+
+```sh
+egt alg-fusions --help
+```
+
+### Perspective-chromosome tree mapping + Monte Carlo rates
+
+```sh
+egt perspchrom-df-to-tree --help
+```
+
+### Rate analyses, Fourier periodicity, branch stats
+
+```sh
+egt branch-stats-vs-time    --help
+egt fourier-of-rates        --help
+egt fourier-support-vs-time --help
+egt collapsed-tree          --help
+egt tree-changes            --help
+egt decay-pairwise          --help
+egt decay-many-species      --help
+```
+
+### Phylogeny preparation
+
+```sh
+egt taxids-to-newick           --help
+egt newick-to-common-ancestors --help
+```
+
+## Users' Guide
+
+`egt` is a collection of analysis scripts rather than a monolithic pipeline.
+Each script is also registered as a subcommand of the `egt` console script:
+
+```sh
+egt alg-fusions --help
+# equivalent to
+python -m egt.plot_alg_fusions --help
+```
+
+### Installation
+
+```sh
+git clone https://github.com/conchoecia/egt.git
+cd egt
+python -m venv .venv && source .venv/bin/activate
+pip install -e .
+```
+
+### Python requirements
+
+Python 3.10 or newer. `pip install -e .` pulls the deps from `pyproject.toml`:
+
+- numpy, pandas, scipy, scikit-learn, matplotlib, networkx, Pillow
+- umap-learn[plot] — UMAP + the plotting extras needed by PhyloTreeUMAP
+- bokeh — interactive HTML plots
+- ete4 — taxonomy trees and NCBI taxid handling
+- snakemake (>=7, <9)
+- pyyaml
+
+Conda equivalent:
+
+```sh
+mamba install -c conda-forge -c bioconda \
+      python=3.11 numpy pandas scipy scikit-learn matplotlib networkx pillow \
+      "umap-learn" bokeh ete4 "snakemake<9" pyyaml
+pip install --no-deps -e .
+```
+
+### Upstream tools
+
+`egt` consumes outputs of several companion tools:
+
+- [`odp`](https://github.com/conchoecia/odp) — per-species RBH files, ALG
+  databases (BCnSSimakov2022 etc.)
+- [`chrombase`](https://github.com/conchoecia/chrombase) — chromosome-scale
+  NCBI genome database builder
+- [`genbargo`](https://github.com/conchoecia/genbargo) — embargo-aware
+  assembly curation
+- [`chromsim`](https://github.com/conchoecia/chromsim) — chromosome-evolution
+  simulations
+
+### CLI overview
+
+```
+phylotreeumap             — UMAP-over-ALG-topology (MGT, MLT, ODOG subcommands)
+phylotreeumap-subsample   — subsample species phylogenetically with per-clade caps
+alg-fusions               — plot fusion events on a phylogeny (canonical v3)
+alg-dispersion            — plot ALG dispersion across species
+perspchrom-df-to-tree     — map perspective-chromosome changes onto a tree (Monte Carlo)
+decay-pairwise            — pairwise ALG-decay analysis
+decay-many-species        — cross-species ALG conservation / decay
+chrom-number-vs-changes   — chromosome count vs rearrangement-rate scatter
+branch-stats-vs-time      — branch statistics against geologic time
+branch-stats-tree         — branch statistics laid out on a tree
+branch-stats-tree-pair    — paired branch-stats tree plots
+collapsed-tree            — collapsed-tree visualization
+tree-changes              — per-branch changes on a tree
+fourier-of-rates          — Fourier analysis of chromosomal change rates
+fourier-support-vs-time   — Fourier-support-vs-time plots
+count-unique-changes      — count unique changes per branch
+defining-features         — identify clade-defining features
+defining-features-plot    — plot defining features
+defining-features-plotRBH — plot defining features on RBH dataframes
+taxids-to-newick          — build a Newick tree from NCBI taxids
+newick-to-common-ancestors — divergence-time annotation from a timetree
+algs-split-across-scaffolds — find ALGs split across scaffolds
+get-assembly-sizes        — summarize assembly sizes
+pull-entries-from-yaml    — select rows from a YAML sample list
+aggregate-filechecker     — aggregate filechecker benchmarks
+aggregate-filesizes       — aggregate file-size summaries
+join-supplementary-tables — join table fragments
+phylotreeumap-plotdfs     — PhyloTreeUMAP plotting dataframe helper
+```
+
+### Snakemake workflows
+
+Multi-stage Snakemake definitions live under `workflows/`:
+
+```
+workflows/
+├── phylotree_umap.smk
+├── phylotree_umap_subsampling.smk
+├── perspchrom_df_stats_and_mc.smk
+├── annotate_sample_df.smk
+├── sample_to_num_chromosomes.smk
+├── odol_annotate_blast.smk
+└── pipeline/
+    ├── README.md
+    ├── config.template.yaml
+    └── run.sh
+```
+
+Each workflow is standalone and parameterized via a YAML config.
+
+### Input file formats
+
+- **RBH files** (`.rbh`) — tab-separated reciprocal-best-hits output of `odp`.
+  Filenames must embed the NCBI taxid as the second hyphen-separated field,
+  e.g. `speciesname-7777-something.rbh`.
+- **Sample dataframe** (`sampledf.tsv`) — output of
+  `egt phylotreeumap build-distances`; consumed by most downstream commands.
+- **ALG database RBH** — e.g. `BCnSSimakov2022.rbh`, from `odp`'s LG_db.
+- **Newick trees** — ete4-readable. `egt taxids-to-newick` emits these.
+- **Divergence-time tables** — TSV, as accepted by
+  `egt newick-to-common-ancestors`.
+
+## Layout
+
+```
+egt/
+├── src/egt/                    — Python package
+│   ├── cli.py                  — argparse dispatcher
+│   ├── _vendor/                — vendored, frozen plotting utilities
+│   ├── legacy/                 — prior versions of plot_ALG_fusions kept for parity
+│   └── *.py                    — one module per subcommand
+├── workflows/                  — Snakemake workflows
+├── configs/                    — example configs
+├── data/                       — small bundled data
+├── tests/
+│   ├── testdb/                 — mini_hydra + mini_urchin fixtures
+│   └── smoke/test_cli.sh       — CLI smoke test
+└── docs/
+```
+
+## Related tools
+
+- [`odp`](https://github.com/conchoecia/odp)
+- [`chrombase`](https://github.com/conchoecia/chrombase)
+- [`genbargo`](https://github.com/conchoecia/genbargo)
+- [`chromsim`](https://github.com/conchoecia/chromsim)
+
+## Citing egt
+
+If you use this toolkit, please cite:
+
+> Schultz, D.T., Blümel, A., Destanović, D., Sarigol, F., Simakov, O. (2024).
+> *Topological mixing and irreversibility in animal chromosome evolution.*
+> bioRxiv. [doi:10.1101/2024.07.29.605683](https://doi.org/10.1101/2024.07.29.605683)
+
+For background on the topological framework for comparative genomics, see:
+
+> Schultz, D.T., Simakov, O. (2026).
+> *Topological Approaches in Animal Comparative Genomics.*
+> Annual Review of Animal Biosciences 14(1), 17–48.
+> [doi:10.1146/annurev-animal-030424-084541](https://doi.org/10.1146/annurev-animal-030424-084541)
+
+See also [`CITATION.cff`](CITATION.cff).
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).

egt-0.1.0/pyproject.toml

@@ -0,0 +1,66 @@
+[build-system]
+requires = ["setuptools>=64", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "egt"
+version = "0.1.0"
+description = "Evolutionary Genome Topology — analysis toolkit for chromosome evolution across metazoan genomes using reciprocal-best-hits data."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [
+  { name = "Darrin T. Schultz", email = "darrin.schultz@univie.ac.at" },
+]
+keywords = [
+  "comparative genomics",
+  "chromosome evolution",
+  "ancestral linkage groups",
+  "ALG",
+  "synteny",
+  "UMAP",
+  "phylogenetics",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Science/Research",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: POSIX",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Scientific/Engineering :: Bio-Informatics",
+]
+dependencies = [
+  "numpy",
+  "pandas",
+  "scipy",
+  "scikit-learn",
+  "matplotlib",
+  "networkx",
+  "Pillow",
+  "umap-learn[plot]",
+  "bokeh",
+  "ete4",
+  "snakemake>=7,<9",
+  "pyyaml",
+]
+
+[project.optional-dependencies]
+dev = ["pytest", "pyflakes"]
+
+[project.urls]
+Homepage = "https://github.com/conchoecia/egt"
+"Source code" = "https://github.com/conchoecia/egt"
+"Manuscript" = "https://github.com/conchoecia/egt/blob/main/docs/manuscript.md"
+"odp" = "https://github.com/conchoecia/odp"
+
+[project.scripts]
+egt = "egt.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+egt = ["py.typed"]

egt-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

egt-0.1.0/src/egt/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"