phylogenie 1.0.0__tar.gz → 1.0.2__tar.gz

phylogenie-1.0.2/LICENSE.txt

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 GABRIELE MARINO
+
+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.

phylogenie-1.0.2/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.1
+Name: phylogenie
+Version: 1.0.2
+Summary: Generate phylogenetic datasets with minimal setup effort
+Author: Gabriele Marino
+Author-email: gabmarino.8601@gmail.com
+Requires-Python: >=3.10,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: joblib (>=1.4.2,<2.0.0)
+Requires-Dist: pandas (>=2.2.2,<3.0.0)
+Requires-Dist: pydantic (>=2.11.5,<3.0.0)
+Requires-Dist: pyyaml (>=6.0.2,<7.0.0)
+Requires-Dist: tqdm (>=4.66.4,<5.0.0)
+Requires-Dist: treesimulator (>=0.2.15,<0.3.0)
+Description-Content-Type: text/markdown
+
+<p align="center">
+<img src="https://raw.githubusercontent.com/gabriele-marino/phylogenie/main/logo.png" style="width:100%; height:auto;"/>
+</p>
+
+---
+
+[![TreeSimulator](https://img.shields.io/badge/Powered%20by-TreeSimulator-green?style=flat-square)](https://github.com/evolbioinfo/treesimulator)
+[![Remaster](https://img.shields.io/badge/Powered%20by-Remaster-blue?style=flat-square)](https://tgvaughan.github.io/remaster/)
+[![AliSim](https://img.shields.io/badge/Powered%20by-AliSim-orange?style=flat-square)](https://iqtree.github.io/doc/AliSim)
+
+Phylogenie is a [Python](https://www.python.org/) package designed to easily simulate phylogenetic datasets—such as trees and multiple sequence alignments (MSAs)—with minimal setup effort. Simply specify the distributions from which your parameters should be sampled, and Phylogenie will handle the rest!
+
+## ✨ Features
+
+Phylogenie comes packed with useful features, including:
+
+- **Simulate tree and multiple sequence alignment (MSA) datasets from parameter distributions** 🌳🧬  
+  Define distributions over your parameters and sample a different combination of parameters for each dataset sample.
+
+- **Automatic metadata management** 🗂️  
+  Phylogenie stores each parameter combination sampled during dataset generation in a `.csv` file.
+
+- **Generalizable configurations** 🔄  
+  Easily apply the same configuration across multiple dataset splits (e.g., train, validation, test).
+
+- **Multiprocessing support** ⚙️💻  
+  Simply specify the number of cores to use, and Phylogenie handles multiprocessing automatically.
+
+- **Pre-implemented parameterizations** 🎯  
+  Include canonical, fossilized birth-death, epidemiological, birth-death with exposed-infectious (BDEI), contact-tracing (CT), and more.
+
+- **Skyline parameter support** 🪜  
+  Support for piece-wise constant parameters.
+
+- **Arithmetic operations on parameters** 🧮  
+  Perform flexible arithmetic operations between parameters directly within the config file.
+
+- **Support for common phylogenetic simulation tools** 🛠️  
+  Compatible backends include ReMASTER, TreeSimulator, and AliSim.
+
+- **Modular and extendible architecture** 🧩  
+  Easily add new simulation backends as needed.
+
+## 📦 Installation
+Phylogenie requires [Python](https://www.python.org/) 3.10 to be installed on your system. There are several ways to install Python and managing different Python versions. One popular option is to use [pyenv](https://github.com/pyenv/pyenv).
+
+Once you have Python set up, you can install Phylogenie directly from PyPI:
+
+```bash
+pip install phylogenie
+```
+
+Or install from source:
+```bash
+git clone https://github.com/gabriele-marino/phylogenie.git
+cd phylogenie
+pip install .
+```
+
+## 🛠 Backend dependencies
+
+Phylogenie works with the following simulation backends:
+
+- **[TreeSimulator](https://github.com/evolbioinfo/treesimulator)**  
+  A [Python](https://www.python.org/) package for simulating phylogenetic trees. It is automatically installed with Phylogenie, so you can use it right away.
+
+- **[ReMASTER](https://tgvaughan.github.io/remaster/)**  
+  A [BEAST2](https://www.beast2.org/) package designed for tree simulation. To use ReMASTER as a backend, you need to install it separately.
+
+- **[AliSim](https://iqtree.github.io/doc/AliSim)**  
+  A tool for simulating multiple sequence alignments (MSAs). It is distributed with [IQ-TREE](https://iqtree.github.io/) and also requires separate installation if you wish to use it as a backend.
+
+## 🚀 Quick Start
+
+Once you have installed Phylogenie, check out the [examples](https://github.com/gabriele-marino/phylogenie/tree/main/examples) folder.  
+It includes a collection of thoroughly commented configuration files, organized as a step-by-step tutorial. These examples will help you understand how to use Phylogenie in practice and can be easily adapted to fit your own workflow.
+
+For quick start, pick your favorite config file and run Phylogenie with:
+```bash
+phylogenie examples/<config_file>.yaml
+```
+This command will create the output dataset in the folder specified inside the configuration file, including data directories and metadata files for each dataset split defined in the config.
+
+>❗ *Tip*: Can’t choose just one config file?
+You can run them all at once by pointing Phylogenie to the folder! Just use: `phylogenie examples`. In this mode, Phylogenie will automatically find all `.yaml` files in the folder you specified and run for each of them!
+
+## 📖 Documentation
+
+- The [examples](https://github.com/gabriele-marino/phylogenie/tree/main/examples) folder contains many ready-to-use, extensively commented configuration files that serve as a step-by-step tutorial to guide you through using Phylogenie. You can explore them to learn how it works or adapt them directly to your own workflows.
+- A complete user guide and API reference are under development. In the meantime, feel free to [reach out](mailto:gabmarino.8601@email.com) if you have any questions about integrating Phylogenie into your workflows.
+
+## 📄 License
+
+This project is licensed under [MIT License](https://raw.githubusercontent.com/gabriele-marino/phylogenie/main/LICENSE.txt). 
+
+## 📫 Contact
+
+For questions, bug reports, or feature requests, please, consider opening an [issue on GitHub](https://github.com/gabriele-marino/phylogenie/issues), or [contact me directly](mailto:gabmarino.8601@email.com).
+
+If you need help with the configuration files, feel free to reach out —  I am always very available and happy to assist!
+

phylogenie-1.0.2/README.md

@@ -0,0 +1,100 @@
+<p align="center">
+<img src="https://raw.githubusercontent.com/gabriele-marino/phylogenie/main/logo.png" style="width:100%; height:auto;"/>
+</p>
+
+---
+
+[![TreeSimulator](https://img.shields.io/badge/Powered%20by-TreeSimulator-green?style=flat-square)](https://github.com/evolbioinfo/treesimulator)
+[![Remaster](https://img.shields.io/badge/Powered%20by-Remaster-blue?style=flat-square)](https://tgvaughan.github.io/remaster/)
+[![AliSim](https://img.shields.io/badge/Powered%20by-AliSim-orange?style=flat-square)](https://iqtree.github.io/doc/AliSim)
+
+Phylogenie is a [Python](https://www.python.org/) package designed to easily simulate phylogenetic datasets—such as trees and multiple sequence alignments (MSAs)—with minimal setup effort. Simply specify the distributions from which your parameters should be sampled, and Phylogenie will handle the rest!
+
+## ✨ Features
+
+Phylogenie comes packed with useful features, including:
+
+- **Simulate tree and multiple sequence alignment (MSA) datasets from parameter distributions** 🌳🧬  
+  Define distributions over your parameters and sample a different combination of parameters for each dataset sample.
+
+- **Automatic metadata management** 🗂️  
+  Phylogenie stores each parameter combination sampled during dataset generation in a `.csv` file.
+
+- **Generalizable configurations** 🔄  
+  Easily apply the same configuration across multiple dataset splits (e.g., train, validation, test).
+
+- **Multiprocessing support** ⚙️💻  
+  Simply specify the number of cores to use, and Phylogenie handles multiprocessing automatically.
+
+- **Pre-implemented parameterizations** 🎯  
+  Include canonical, fossilized birth-death, epidemiological, birth-death with exposed-infectious (BDEI), contact-tracing (CT), and more.
+
+- **Skyline parameter support** 🪜  
+  Support for piece-wise constant parameters.
+
+- **Arithmetic operations on parameters** 🧮  
+  Perform flexible arithmetic operations between parameters directly within the config file.
+
+- **Support for common phylogenetic simulation tools** 🛠️  
+  Compatible backends include ReMASTER, TreeSimulator, and AliSim.
+
+- **Modular and extendible architecture** 🧩  
+  Easily add new simulation backends as needed.
+
+## 📦 Installation
+Phylogenie requires [Python](https://www.python.org/) 3.10 to be installed on your system. There are several ways to install Python and managing different Python versions. One popular option is to use [pyenv](https://github.com/pyenv/pyenv).
+
+Once you have Python set up, you can install Phylogenie directly from PyPI:
+
+```bash
+pip install phylogenie
+```
+
+Or install from source:
+```bash
+git clone https://github.com/gabriele-marino/phylogenie.git
+cd phylogenie
+pip install .
+```
+
+## 🛠 Backend dependencies
+
+Phylogenie works with the following simulation backends:
+
+- **[TreeSimulator](https://github.com/evolbioinfo/treesimulator)**  
+  A [Python](https://www.python.org/) package for simulating phylogenetic trees. It is automatically installed with Phylogenie, so you can use it right away.
+
+- **[ReMASTER](https://tgvaughan.github.io/remaster/)**  
+  A [BEAST2](https://www.beast2.org/) package designed for tree simulation. To use ReMASTER as a backend, you need to install it separately.
+
+- **[AliSim](https://iqtree.github.io/doc/AliSim)**  
+  A tool for simulating multiple sequence alignments (MSAs). It is distributed with [IQ-TREE](https://iqtree.github.io/) and also requires separate installation if you wish to use it as a backend.
+
+## 🚀 Quick Start
+
+Once you have installed Phylogenie, check out the [examples](https://github.com/gabriele-marino/phylogenie/tree/main/examples) folder.  
+It includes a collection of thoroughly commented configuration files, organized as a step-by-step tutorial. These examples will help you understand how to use Phylogenie in practice and can be easily adapted to fit your own workflow.
+
+For quick start, pick your favorite config file and run Phylogenie with:
+```bash
+phylogenie examples/<config_file>.yaml
+```
+This command will create the output dataset in the folder specified inside the configuration file, including data directories and metadata files for each dataset split defined in the config.
+
+>❗ *Tip*: Can’t choose just one config file?
+You can run them all at once by pointing Phylogenie to the folder! Just use: `phylogenie examples`. In this mode, Phylogenie will automatically find all `.yaml` files in the folder you specified and run for each of them!
+
+## 📖 Documentation
+
+- The [examples](https://github.com/gabriele-marino/phylogenie/tree/main/examples) folder contains many ready-to-use, extensively commented configuration files that serve as a step-by-step tutorial to guide you through using Phylogenie. You can explore them to learn how it works or adapt them directly to your own workflows.
+- A complete user guide and API reference are under development. In the meantime, feel free to [reach out](mailto:gabmarino.8601@email.com) if you have any questions about integrating Phylogenie into your workflows.
+
+## 📄 License
+
+This project is licensed under [MIT License](https://raw.githubusercontent.com/gabriele-marino/phylogenie/main/LICENSE.txt). 
+
+## 📫 Contact
+
+For questions, bug reports, or feature requests, please, consider opening an [issue on GitHub](https://github.com/gabriele-marino/phylogenie/issues), or [contact me directly](mailto:gabmarino.8601@email.com).
+
+If you need help with the configuration files, feel free to reach out —  I am always very available and happy to assist!

{phylogenie-1.0.0 → phylogenie-1.0.2}/phylogenie/backend/remaster/generate.py

@@ -11,7 +11,6 @@ from phylogenie.backend.remaster.reactions import (
     Reaction,
 )
 from phylogenie.skyline import skyline_parameter
-from phylogenie.utils import vectorify1D
 
 TREE_ID = "Tree"
 
@@ -75,12 +74,12 @@ def _generate_config_file(
             attrs = {
                 "spec": "PunctualReaction",
                 "value": punctual_reaction.value,
-                "times": " ".join(map(str, vectorify1D(punctual_reaction.times))),
+                "times": " ".join(map(str, punctual_reaction.times)),
             }
             if punctual_reaction.p is not None:
-                attrs["p"] = " ".join(map(str, vectorify1D(punctual_reaction.p)))
+                attrs["p"] = " ".join(map(str, punctual_reaction.p))
             if punctual_reaction.n is not None:
-                attrs["n"] = " ".join(map(str, vectorify1D(punctual_reaction.n)))
+                attrs["n"] = " ".join(map(str, punctual_reaction.n))
             trajectory.append(Element("reaction", attrs))
 
     simulate.append(trajectory)
@@ -151,6 +150,7 @@ def generate_trees(
     output_xml_file: str | None = None,
     n_simulations: int = 1,
     seed: int | None = None,
+    beast_path: str = "beast",
 ) -> None:
     if isinstance(populations, str):
         populations = [populations]
@@ -175,7 +175,7 @@ def generate_trees(
         n_simulations=n_simulations,
     )
 
-    cmd = ["beast"]
+    cmd = [beast_path]
     if seed is not None:
         cmd.extend(["-seed", str(seed)])
     cmd.append(xml_file)

{phylogenie-1.0.0 → phylogenie-1.0.2}/phylogenie/backend/remaster/reactions.py

@@ -2,9 +2,9 @@ from dataclasses import dataclass
 
 import phylogenie.typings as pgt
 from phylogenie.skyline import (
-    SkylineMatrixLike,
+    SkylineMatrixCoercible,
     SkylineParameterLike,
-    SkylineVectorLike,
+    SkylineVectorCoercible,
     skyline_matrix,
     skyline_vector,
 )
@@ -21,21 +21,21 @@ class Reaction:
 
 @dataclass
 class PunctualReaction:
-    times: pgt.OneOrManyScalars
+    times: pgt.ManyScalars
     value: str
-    p: pgt.OneOrManyScalars | None = None
-    n: pgt.OneOrMany[int] | None = None
+    p: pgt.ManyScalars | None = None
+    n: pgt.Many[int] | None = None
 
 
 def get_canonical_reactions(
     populations: str | list[str] = DEFAULT_POPULATION,
     sample_population: str = SAMPLE_POPULATION,
-    birth_rates: SkylineVectorLike = 0,
-    death_rates: SkylineVectorLike = 0,
-    sampling_rates: SkylineVectorLike = 0,
-    removal_probabilities: SkylineVectorLike = 0,
-    migration_rates: SkylineMatrixLike = 0,
-    birth_rates_among_demes: SkylineMatrixLike = 0,
+    birth_rates: SkylineVectorCoercible = 0,
+    death_rates: SkylineVectorCoercible = 0,
+    sampling_rates: SkylineVectorCoercible = 0,
+    removal_probabilities: SkylineVectorCoercible = 0,
+    migration_rates: SkylineMatrixCoercible = 0,
+    birth_rates_among_demes: SkylineMatrixCoercible = 0,
 ) -> list[Reaction]:
     if isinstance(populations, str):
         populations = [populations]
@@ -84,12 +84,12 @@ def get_canonical_reactions(
 def get_epidemiological_reactions(
     populations: str | list[str] = DEFAULT_POPULATION,
     sample_population: str = SAMPLE_POPULATION,
-    reproduction_numbers: SkylineVectorLike = 0,
-    become_uninfectious_rates: SkylineVectorLike = 0,
-    sampling_proportions: SkylineVectorLike = 0,
-    removal_probabilities: SkylineVectorLike = 0,
-    migration_rates: SkylineMatrixLike = 0,
-    reproduction_numbers_among_demes: SkylineMatrixLike = 0,
+    reproduction_numbers: SkylineVectorCoercible = 0,
+    become_uninfectious_rates: SkylineVectorCoercible = 0,
+    sampling_proportions: SkylineVectorCoercible = 0,
+    removal_probabilities: SkylineVectorCoercible = 0,
+    migration_rates: SkylineMatrixCoercible = 0,
+    reproduction_numbers_among_demes: SkylineMatrixCoercible = 0,
 ) -> list[Reaction]:
     if isinstance(populations, str):
         populations = [populations]
@@ -125,12 +125,12 @@ def get_epidemiological_reactions(
 def get_FBD_reactions(
     populations: str | list[str] = DEFAULT_POPULATION,
     sample_population: str = SAMPLE_POPULATION,
-    diversification: SkylineVectorLike = 0,
-    turnover: SkylineVectorLike = 0,
-    sampling_proportions: SkylineVectorLike = 0,
-    removal_probabilities: SkylineVectorLike = 0,
-    migration_rates: SkylineMatrixLike = 0,
-    diversification_between_types: SkylineMatrixLike = 0,
+    diversification: SkylineVectorCoercible = 0,
+    turnover: SkylineVectorCoercible = 0,
+    sampling_proportions: SkylineVectorCoercible = 0,
+    removal_probabilities: SkylineVectorCoercible = 0,
+    migration_rates: SkylineMatrixCoercible = 0,
+    diversification_between_types: SkylineMatrixCoercible = 0,
 ):
     if isinstance(populations, str):
         populations = [populations]

{phylogenie-1.0.0 → phylogenie-1.0.2}/phylogenie/backend/treesimulator.py

@@ -6,9 +6,9 @@ from treesimulator.generator import generate
 from treesimulator.mtbd_models import CTModel, Model
 
 from phylogenie.skyline import (
-    SkylineMatrixLike,
+    SkylineMatrixCoercible,
     SkylineParameterLike,
-    SkylineVectorLike,
+    SkylineVectorCoercible,
     skyline_matrix,
     skyline_parameter,
     skyline_vector,
@@ -22,10 +22,10 @@ EXPOSED_POPULATION = "E"
 @dataclass
 class TreeParams:
     populations: str | list[str] = DEFAULT_POPULATION
-    transition_rates: SkylineMatrixLike = 0
-    transmission_rates: SkylineMatrixLike = 0
-    removal_rates: SkylineVectorLike = 0
-    sampling_proportions: SkylineVectorLike = 0
+    transition_rates: SkylineMatrixCoercible = 0
+    transmission_rates: SkylineMatrixCoercible = 0
+    removal_rates: SkylineVectorCoercible = 0
+    sampling_proportions: SkylineVectorCoercible = 0
 
 
 def generate_tree(

phylogenie-1.0.2/phylogenie/core/configs.py

@@ -0,0 +1,40 @@
+import phylogenie.typings as pgt
+from phylogenie.configs import StrictBaseModel
+
+IntConfig = str | int
+ScalarConfig = str | pgt.Scalar
+ManyIntsConfig = str | list[IntConfig]
+ManyScalarsConfig = str | list[ScalarConfig]
+OneOrManyScalarsConfig = ScalarConfig | list[ScalarConfig]
+OneOrMany2DScalarsConfig = ScalarConfig | list[list[ScalarConfig]]
+
+
+class SkylineParameterValueModel(StrictBaseModel):
+    value: ManyScalarsConfig
+    change_times: ManyScalarsConfig
+
+
+SkylineParameterLikeConfig = ScalarConfig | SkylineParameterValueModel
+
+
+class SkylineVectorValueModel(StrictBaseModel):
+    value: str | list[OneOrManyScalarsConfig]
+    change_times: ManyScalarsConfig
+
+
+SkylineVectorCoercibleConfig = (
+    str | pgt.Scalar | list[SkylineParameterLikeConfig] | SkylineVectorValueModel
+)
+SkylineVectorLikeConfig = (
+    str | list[SkylineParameterLikeConfig] | SkylineVectorValueModel
+)
+
+
+class SkylineMatrixValueModel(StrictBaseModel):
+    value: str | list[OneOrMany2DScalarsConfig]
+    change_times: ManyScalarsConfig
+
+
+SkylineMatrixCoercibleConfig = (
+    str | pgt.Scalar | list[SkylineVectorLikeConfig] | SkylineMatrixValueModel
+)

{phylogenie-1.0.0 → phylogenie-1.0.2}/phylogenie/core/context/factories.py

@@ -3,18 +3,15 @@ from numpy.random import Generator
 import phylogenie.core.context.configs as cfg
 import phylogenie.typings as pgt
 from phylogenie.core.context import distributions
-from phylogenie.core.typings import Data
 
 
-def _sample_vector1D(
-    x: distributions.Scalar, N: int, rng: Generator
-) -> list[pgt.Scalar]:
+def _sample_vector1D(x: distributions.Scalar, N: int, rng: Generator) -> pgt.Vector1D:
     return [x.sample(rng) for _ in range(N)]
 
 
 def _sample_vector2D(
     x: distributions.Scalar, N: int, zero_diagonal: bool, rng: Generator
-) -> list[list[pgt.Scalar]]:
+) -> pgt.Vector2D:
     v = [_sample_vector1D(x, N, rng) for _ in range(N)]
     if zero_diagonal:
         for i in range(N):
@@ -24,12 +21,12 @@ def _sample_vector2D(
 
 def _sample_vector3D(
     x: distributions.Scalar, N: int, T: int, zero_diagonal: bool, rng: Generator
-) -> list[list[list[pgt.Scalar]]]:
+) -> pgt.Vector3D:
     return [_sample_vector2D(x, N, zero_diagonal, rng) for _ in range(T)]
 
 
-def context_factory(x: cfg.ContextConfig, rng: Generator) -> Data:
-    data: Data = {}
+def context_factory(x: cfg.ContextConfig, rng: Generator) -> pgt.Data:
+    data: pgt.Data = {}
     for key, value in x.items():
         if isinstance(value, distributions.Distribution):
             data[key] = value.sample(rng)

{phylogenie-1.0.0 → phylogenie-1.0.2}/phylogenie/core/dataset.py

@@ -7,9 +7,9 @@ import pandas as pd
 from numpy.random import Generator, default_rng
 from tqdm import tqdm
 
+import phylogenie.typings as pgt
 from phylogenie.configs import StrictBaseModel
 from phylogenie.core.context import ContextConfig, context_factory
-from phylogenie.core.typings import Data
 
 
 class DataType(str, Enum):
@@ -19,18 +19,18 @@ class DataType(str, Enum):
 
 class DatasetGenerator(ABC, StrictBaseModel):
     output_dir: str = "phylogenie-out"
+    data_dir: str = "data"
+    metadata_filename: str = "metadata.csv"
     n_samples: int | dict[str, int] = 1
-    context: ContextConfig | None = None
     n_jobs: int = -1
     seed: int | None = None
-    data_dir: str = "data"
-    metadata_filename: str = "metadata.csv"
+    context: ContextConfig | None = None
 
     @abstractmethod
-    def _generate_one(self, filename: str, rng: Generator, data: Data) -> None: ...
+    def _generate_one(self, filename: str, rng: Generator, data: pgt.Data) -> None: ...
 
     def generate_one(
-        self, filename: str, data: Data | None = None, seed: int | None = None
+        self, filename: str, data: pgt.Data | None = None, seed: int | None = None
     ) -> None:
         data = {} if data is None else data
         self._generate_one(filename=filename, rng=default_rng(seed), data=data)