PythiaLabelGenerator 1.0.0__tar.gz → 1.1.1__tar.gz

{pythialabelgenerator-1.0.0 → pythialabelgenerator-1.1.1}/.github/workflows/test-label-generator.yml

@@ -39,7 +39,7 @@ jobs:
 #        uses: mxschmitt/action-tmate@v3
       - name: Run LabelGenerator tests
         run: |
-          PYTHONPATH=. pytest -svx
+          PYTHONPATH=. pytest -svx --color=yes
         shell: bash -el {0}
 
   Install-using-conda:

{pythialabelgenerator-1.0.0 → pythialabelgenerator-1.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PythiaLabelGenerator
-Version: 1.0.0
+Version: 1.1.1
 Summary: Command line tool to generate the ground-truth phylogenetic difficulty of MSAs
 Project-URL: Homepage, https://github.com/tschuelia/PythiaLabelGenerator
 Author-email: Julia Haag <info@juliaschmid.com>
@@ -18,11 +18,11 @@ Provides-Extra: test
 Requires-Dist: pytest; extra == 'test'
 Description-Content-Type: text/markdown
 
-# Pythia Difficulty Label Generator
+# Pythia Difficulty Label Generator (PyDLG)
 
 ![Label Generator GH actions CI](https://github.com/tschuelia/PythiaLabelGenerator/actions/workflows/test-label-generator.yml/badge.svg)
 
-The Pythia Difficulty Label Generator generates the ground-truth phylogenetic difficulty label for an MSA and
+PyDLG generates the ground-truth phylogenetic difficulty label for an MSA and
 corresponds to the prediction target of our difficulty prediction tool [Pythia](https://github.com/tschuelia/PyPythia).
 
 > [!CAUTION]
@@ -70,7 +70,7 @@ comprising [SARS-CoV-2 sequences](https://doi.org/10.1093/molbev/msaa314) (appro
 12 hours on a large compute cluster. Using Pythia instead, we can predict the same MSA to be very difficult in about 2.5
 minutes on a standard MacBook.
 
-Only use this tool if you need the ground-truth difficulty for a specific MSA and you are sure that Pythia is unable to
+Only use PyDLG if you need the ground-truth difficulty for a specific MSA and you are sure that Pythia is unable to
 predict the difficulty accurately.
 The only case where we observed Pythia to fail is for language MSAs, so if you are working with DNA, Protein, or
 biological morphological data, Pythia should work just fine 😉
@@ -79,7 +79,7 @@ biological morphological data, Pythia should work just fine 😉
 
 #### Requirements
 
-To use this labelling tool, you need to install
+To use PyDLG, you need to install
 
 - RAxML-NG: See [the RAxML-NG GitHub repository](https://github.com/amkozlov/raxml-ng) for installation instructions.
   Please make sure that you install a RAxML-NG version < 2.
@@ -88,7 +88,11 @@ To use this labelling tool, you need to install
 
 #### Install via conda (recommended)
 
-This package will soon be available on conda-forge :)
+You can install the package using conda:
+
+```bash
+conda install pythialabelgenerator -c conda-forge
+```
 
 #### Install using pip
 
@@ -100,7 +104,7 @@ pip install pythialabelgenerator
 
 ## Usage
 
-This label-generator is primarily a command line tool. You can call it using the `label` command, for instance, to
+PyDLG is primarily a command line tool. You can call it using the `label` command, for instance, to
 compute the difficulty for the example MSA provided in the `examples` directory run
 
 ```bash
@@ -112,7 +116,7 @@ to the console.
 The output will look something like this:
 
 ```text
-Difficulty LabelGenerator version 1.0.0 released by The Exelixis Lab
+PyDLG version 1.0.1 released by The Exelixis Lab
 Developed by: Julia Haag
 Latest version: https://github.com/tschuelia/LabelGenerator
 Questions/problems/suggestions? Please open an issue on GitHub.
@@ -147,7 +151,7 @@ Note that this `examply.phy` MSA is not the same exemplary MSA as we provide in
 For a full list of command line options, run `label -h`:
 
 ```text
-Difficulty LabelGenerator version 1.0.0 released by The Exelixis Lab
+PyDLG version 1.0.1 released by The Exelixis Lab
 Developed by: Julia Haag
 Latest version: https://github.com/tschuelia/LabelGenerator
 Questions/problems/suggestions? Please open an issue on GitHub.
@@ -183,19 +187,19 @@ difficulties, as the difficulty is based on the average pairwise RF distance bet
 
 ### Result Files
 
-Running this labelling tool will result in the following files:
+Running PyDLG will result in the following files:
 
 - `{prefix}.raxml.*`: RAxML-NG log and result files.
 - `{prefix}.iqtree.*`: IQ-TREE log and result files.
 - `{prefix}.labelGen.log`: Log file containing the output of the label generator. This is the same output as printed to
   the terminal.
+- `{prefix}.csv`: The computed ground-truth difficulty and all features required for Pythia for the given MSA.
 
 You can set the prefix of these files using the `-p` option. By default, the prefix is the name of the MSA file.
 Note that RAxML-NG and IQ-TREE refuse to overwrite existing files. If you want to redo the computations, you can use the
 `--redo` option.
 Please also specify the `--redo` option if you want to change the number of trees to infer using the `--ntrees` option
-for the same prefix. Otherwise,
-the label generator will exit with an error message.
+for the same prefix. Otherwise, PyDLG will exit with an error message.
 
 ### Input Data
 
@@ -209,7 +213,6 @@ you can do so using the `--model` option.
 
 
 ## Citation
-We will soon publish a pre-print on bioRxiv with updates on our Pythia difficulty prediction tool that will also include a
-brief description of this new labelling tool. Please cite this pre-print if you use this tool in your research.
+Please cite the following preprint if you use this tool in your research.
 
-The link to the paper will be added soon 🙂
+Haag, J. & Stamatakis, A. (2025). **Pythia 2.0: New Data, New Prediction Model, New Features.** *BioRxiv*. [https://doi.org/10.1101/2025.03.25.645182](https://doi.org/10.1101/2025.03.25.645182)

{pythialabelgenerator-1.0.0 → pythialabelgenerator-1.1.1}/README.md

@@ -1,8 +1,8 @@
-# Pythia Difficulty Label Generator
+# Pythia Difficulty Label Generator (PyDLG)
 
 ![Label Generator GH actions CI](https://github.com/tschuelia/PythiaLabelGenerator/actions/workflows/test-label-generator.yml/badge.svg)
 
-The Pythia Difficulty Label Generator generates the ground-truth phylogenetic difficulty label for an MSA and
+PyDLG generates the ground-truth phylogenetic difficulty label for an MSA and
 corresponds to the prediction target of our difficulty prediction tool [Pythia](https://github.com/tschuelia/PyPythia).
 
 > [!CAUTION]
@@ -50,7 +50,7 @@ comprising [SARS-CoV-2 sequences](https://doi.org/10.1093/molbev/msaa314) (appro
 12 hours on a large compute cluster. Using Pythia instead, we can predict the same MSA to be very difficult in about 2.5
 minutes on a standard MacBook.
 
-Only use this tool if you need the ground-truth difficulty for a specific MSA and you are sure that Pythia is unable to
+Only use PyDLG if you need the ground-truth difficulty for a specific MSA and you are sure that Pythia is unable to
 predict the difficulty accurately.
 The only case where we observed Pythia to fail is for language MSAs, so if you are working with DNA, Protein, or
 biological morphological data, Pythia should work just fine 😉
@@ -59,7 +59,7 @@ biological morphological data, Pythia should work just fine 😉
 
 #### Requirements
 
-To use this labelling tool, you need to install
+To use PyDLG, you need to install
 
 - RAxML-NG: See [the RAxML-NG GitHub repository](https://github.com/amkozlov/raxml-ng) for installation instructions.
   Please make sure that you install a RAxML-NG version < 2.
@@ -68,7 +68,11 @@ To use this labelling tool, you need to install
 
 #### Install via conda (recommended)
 
-This package will soon be available on conda-forge :)
+You can install the package using conda:
+
+```bash
+conda install pythialabelgenerator -c conda-forge
+```
 
 #### Install using pip
 
@@ -80,7 +84,7 @@ pip install pythialabelgenerator
 
 ## Usage
 
-This label-generator is primarily a command line tool. You can call it using the `label` command, for instance, to
+PyDLG is primarily a command line tool. You can call it using the `label` command, for instance, to
 compute the difficulty for the example MSA provided in the `examples` directory run
 
 ```bash
@@ -92,7 +96,7 @@ to the console.
 The output will look something like this:
 
 ```text
-Difficulty LabelGenerator version 1.0.0 released by The Exelixis Lab
+PyDLG version 1.0.1 released by The Exelixis Lab
 Developed by: Julia Haag
 Latest version: https://github.com/tschuelia/LabelGenerator
 Questions/problems/suggestions? Please open an issue on GitHub.
@@ -127,7 +131,7 @@ Note that this `examply.phy` MSA is not the same exemplary MSA as we provide in
 For a full list of command line options, run `label -h`:
 
 ```text
-Difficulty LabelGenerator version 1.0.0 released by The Exelixis Lab
+PyDLG version 1.0.1 released by The Exelixis Lab
 Developed by: Julia Haag
 Latest version: https://github.com/tschuelia/LabelGenerator
 Questions/problems/suggestions? Please open an issue on GitHub.
@@ -163,19 +167,19 @@ difficulties, as the difficulty is based on the average pairwise RF distance bet
 
 ### Result Files
 
-Running this labelling tool will result in the following files:
+Running PyDLG will result in the following files:
 
 - `{prefix}.raxml.*`: RAxML-NG log and result files.
 - `{prefix}.iqtree.*`: IQ-TREE log and result files.
 - `{prefix}.labelGen.log`: Log file containing the output of the label generator. This is the same output as printed to
   the terminal.
+- `{prefix}.csv`: The computed ground-truth difficulty and all features required for Pythia for the given MSA.
 
 You can set the prefix of these files using the `-p` option. By default, the prefix is the name of the MSA file.
 Note that RAxML-NG and IQ-TREE refuse to overwrite existing files. If you want to redo the computations, you can use the
 `--redo` option.
 Please also specify the `--redo` option if you want to change the number of trees to infer using the `--ntrees` option
-for the same prefix. Otherwise,
-the label generator will exit with an error message.
+for the same prefix. Otherwise, PyDLG will exit with an error message.
 
 ### Input Data
 
@@ -189,7 +193,6 @@ you can do so using the `--model` option.
 
 
 ## Citation
-We will soon publish a pre-print on bioRxiv with updates on our Pythia difficulty prediction tool that will also include a
-brief description of this new labelling tool. Please cite this pre-print if you use this tool in your research.
+Please cite the following preprint if you use this tool in your research.
 
-The link to the paper will be added soon 🙂
+Haag, J. & Stamatakis, A. (2025). **Pythia 2.0: New Data, New Prediction Model, New Features.** *BioRxiv*. [https://doi.org/10.1101/2025.03.25.645182](https://doi.org/10.1101/2025.03.25.645182)

{pythialabelgenerator-1.0.0 → pythialabelgenerator-1.1.1}/labelgenerator/label.py

@@ -1,7 +1,7 @@
 import pathlib
 from typing import Optional
 
-from pypythia.msa import parse_msa
+from pypythia.msa import DataType, MSA
 
 from labelgenerator.iqtree import (
     filter_plausible_trees,
@@ -92,14 +92,15 @@ def get_label(
     label = total / 5
 
     eps = 1e-9
-    assert -eps <= label <= 1 + eps, (
-        f"Label {label} is not between 0 and 1. Check the input values."
-    )
+    assert (
+        -eps <= label <= 1 + eps
+    ), f"Label {label} is not between 0 and 1. Check the input values."
 
     return label
 
 
 def compute_label(
+    msa_obj: MSA,
     msa_file: pathlib.Path,
     raxmlng: pathlib.Path,
     iqtree: pathlib.Path,
@@ -117,6 +118,7 @@ def compute_label(
 
 
     Args:
+        msa_obj (MSA): MSA object containing the input data.
         msa_file (pathlib.Path): Path to the MSA file to compute the label for. Can be either in FASTA or PHYLIP format.
         raxmlng (pathlib.Path): Path to the RAxML-NG executable.
         iqtree (pathlib.Path): Path to the IQ-TREE executable.
@@ -134,7 +136,6 @@ def compute_label(
         float: The ground truth difficulty label for the given MSA.
 
     """
-    msa_obj = parse_msa(msa_file)
     model = model or msa_obj.get_raxmlng_model()
 
     # 1. Infer 100 ML trees for the given MSA using RAxML-NG
@@ -182,6 +183,7 @@ def compute_label(
         seed=seed,
         threads=threads,
         redo=redo,
+        is_morph=msa_obj.data_type == DataType.MORPH,
     )
 
     # 4. Filter the plausible trees

{pythialabelgenerator-1.0.0 → pythialabelgenerator-1.1.1}/labelgenerator/logger.py

@@ -15,7 +15,7 @@ logger.add(sys.stderr, format="{message}")
 
 def get_header():
     return textwrap.dedent(
-        f"Difficulty LabelGenerator version {__version__} released by The Exelixis Lab\n"
+        f"PyDLG version {__version__} released by The Exelixis Lab\n"
         f"Developed by: Julia Haag\n"
         f"Latest version: https://github.com/tschuelia/LabelGenerator\n"
         f"Questions/problems/suggestions? Please open an issue on GitHub.\n",
@@ -30,3 +30,19 @@ def log_runtime_information(message, log_runtime=True):
     else:
         time_string = ""
     logger.info(f"{time_string}{message}")
+
+
+def log_runtime(total_runtime: int, runtime_name: str):
+    hours, remainder = divmod(total_runtime, 3600)
+    minutes, seconds = divmod(remainder, 60)
+
+    if hours > 0:
+        logger.info(
+            f"{runtime_name}: {int(hours):02d}:{int(minutes):02d}:{seconds:02d} hours ({round(total_runtime)} seconds)."
+        )
+    elif minutes > 0:
+        logger.info(
+            f"{runtime_name}: {int(minutes):02d}:{int(seconds):02d} minutes ({round(total_runtime)} seconds)."
+        )
+    else:
+        logger.info(f"{runtime_name}: {seconds:.2f} seconds.")

{pythialabelgenerator-1.0.0 → pythialabelgenerator-1.1.1}/labelgenerator/main.py

@@ -3,15 +3,20 @@ import pathlib
 import shutil
 import sys
 import time
+from typing import Optional
 
 from labelgenerator import __version__
 from labelgenerator.label import compute_label
 from labelgenerator.logger import (
     SCRIPT_START,
     get_header,
+    log_runtime,
     log_runtime_information,
     logger,
 )
+from pypythia.msa import parse_msa
+from pypythia.prediction import collect_features
+from pypythia.raxmlng import RAxMLNG
 
 DEFAULT_RAXMLNG_EXE = (
     pathlib.Path(shutil.which("raxml-ng")) if shutil.which("raxml-ng") else None
@@ -22,7 +27,7 @@ DEFAULT_IQTREE_EXE = (
 )
 
 
-def _parse_cli():
+def _parse_cli(arg_list: Optional[list[str]] = None):
     parser = argparse.ArgumentParser(
         description="Generate the ground truth difficulty for the given MSA."
     )
@@ -110,29 +115,49 @@ def _parse_cli():
         help="Print the version number and exit.",
     )
 
-    return parser.parse_args()
+    return parser.parse_args(arg_list)
 
 
-def main():
+def main(arg_list: Optional[list[str]] = None):
     logger.info(get_header())
-    args = _parse_cli()
+    args = _parse_cli(arg_list)
 
     msa_file = pathlib.Path(args.msa)
     prefix = pathlib.Path(args.prefix) if args.prefix else msa_file
 
     log_file = pathlib.Path(f"{prefix}.labelGen.log")
+    features_file = pathlib.Path(f"{prefix}.csv")
+
+    # If the log file and the features file already exist, remove them if the --redo flag is set
+    if args.redo:
+        log_file.unlink(missing_ok=True)
+        features_file.unlink(missing_ok=True)
+
     logger.add(log_file, format="{message}")
     log_file.write_text(get_header() + "\n")
 
     logger.info(
-        f"LabelGenerator was called at {time.strftime('%d-%b-%Y %H:%M:%S')} as follows:\n"
+        f"PyDLG was called at {time.strftime('%d-%b-%Y %H:%M:%S')} as follows:\n"
     )
     logger.info(" ".join(sys.argv))
     logger.info("")
 
     log_runtime_information("Starting label computation.")
 
+    msa_obj = parse_msa(msa_file)
+
+    if msa_obj.contains_duplicate_sequences():
+        logger.info(
+            "WARNING: The input MSA contains duplicate sequences. Consider deduplicating the MSA before running the label generator."
+        )
+
+    if msa_obj.contains_full_gap_sequences():
+        logger.info(
+            "WARNING: The input MSA contains sequences that are only gaps. Consider removing these sequences before running the label generator."
+        )
+
     difficulty = compute_label(
+        msa_obj=msa_obj,
         msa_file=msa_file,
         raxmlng=pathlib.Path(args.raxmlng),
         iqtree=pathlib.Path(args.iqtree),
@@ -145,6 +170,22 @@ def main():
         log_info=True,
     )
 
+    label_end = time.perf_counter()
+
+    log_runtime_information("Computing corresponding Pythia features.")
+
+    features = collect_features(
+        msa=msa_obj,
+        msa_file=msa_file,
+        raxmlng=RAxMLNG(pathlib.Path(args.raxmlng)),
+        log_info=False,
+        threads=args.threads,
+        seed=args.seed,
+    )
+
+    features["difficulty"] = difficulty
+    features.to_csv(features_file, index=False)
+
     script_end = time.perf_counter()
 
     logger.info("")
@@ -156,20 +197,8 @@ def main():
         )
 
     logger.info("")
-    total_runtime = script_end - SCRIPT_START
-    hours, remainder = divmod(total_runtime, 3600)
-    minutes, seconds = divmod(remainder, 60)
-
-    if hours > 0:
-        logger.info(
-            f"Total runtime: {int(hours):02d}:{int(minutes):02d}:{seconds:02d} hours ({round(total_runtime)} seconds)."
-        )
-    elif minutes > 0:
-        logger.info(
-            f"Total runtime: {int(minutes):02d}:{int(seconds):02d} minutes ({round(total_runtime)} seconds)."
-        )
-    else:
-        logger.info(f"Total runtime: {seconds:.2f} seconds.")
+    log_runtime(label_end - SCRIPT_START, "Label computation runtime")
+    log_runtime(script_end - SCRIPT_START, "Total runtime")
 
 
 if __name__ == "__main__":

{pythialabelgenerator-1.0.0 → pythialabelgenerator-1.1.1}/pyproject.toml

@@ -3,7 +3,7 @@ name = "PythiaLabelGenerator"
 description = "Command line tool to generate the ground-truth phylogenetic difficulty of MSAs"
 readme = {file = "README.md", content-type = "text/markdown"}
 authors = [{name = "Julia Haag", email = "info@juliaschmid.com"}]
-version = "1.0.0"
+version = "1.1.1"
 license = "GPL-3.0-or-later"
 classifiers = [
     "Programming Language :: Python :: 3.9",

{pythialabelgenerator-1.0.0 → pythialabelgenerator-1.1.1}/tests/test_label.py

@@ -6,6 +6,7 @@ import pytest
 from labelgenerator.label import get_label, compute_label
 from labelgenerator.logger import logger
 from pypythia.custom_types import DataType
+from pypythia.msa import parse_msa
 
 
 def test_get_label_fails_for_invalid_input():
@@ -99,6 +100,7 @@ def test_compute_label(
         prefix = pathlib.Path(tmpdir) / "test"
 
         label = compute_label(
+            msa_obj=parse_msa(msa_file),
             msa_file=msa_file,
             raxmlng=raxmlng_command,
             iqtree=iqtree_command,
@@ -123,6 +125,7 @@ def test_compute_label_with_logging(raxmlng_command, iqtree_command, data_dir):
         logger.add(logfile, format="{message}")
 
         label = compute_label(
+            msa_obj=parse_msa(msa_file),
             msa_file=msa_file,
             raxmlng=raxmlng_command,
             iqtree=iqtree_command,

pythialabelgenerator-1.1.1/tests/test_main.py

@@ -0,0 +1,127 @@
+import tempfile
+import pytest
+
+import pandas as pd
+
+from labelgenerator.main import main
+from labelgenerator import __version__
+import pathlib
+
+from pypythia.custom_types import DataType
+from pypythia.msa import parse_msa
+
+
+@pytest.mark.parametrize(
+    "data_type, expected_label",
+    [(DataType.DNA, 0.772), (DataType.AA, 0.04), (DataType.MORPH, 0.173)],
+)
+def test_main(data_type, expected_label, data_dir, raxmlng_command, iqtree_command):
+    with tempfile.TemporaryDirectory() as tmpdir:
+        # Create a temporary directory for the test
+        prefix = pathlib.Path(tmpdir) / "test"
+        seed = 42
+        n_trees = 10
+
+        logfile = prefix.with_suffix(".labelGen.log")
+        features_file = prefix.with_suffix(".csv")
+
+        msa_file = data_dir / f"{data_type.name}.phy"
+        msa_obj = parse_msa(msa_file)
+
+        args = [
+            "--msa",
+            str(msa_file),
+            "--raxmlng",
+            str(raxmlng_command),
+            "--iqtree",
+            str(iqtree_command),
+            "--seed",
+            str(seed),
+            "--prefix",
+            str(prefix),
+            "--ntrees",
+            str(n_trees),
+            "--redo",
+        ]
+
+        main(args)
+
+        # Check if all output files exist
+        expected_files = [
+            logfile,
+            features_file,
+            # RAxML-NG output files
+            prefix.with_suffix(".raxml.bestTree"),
+            prefix.with_suffix(".raxml.log"),
+            prefix.with_suffix(".raxml.mlTrees"),
+            prefix.with_suffix(".raxml.plausibleTrees"),
+            # IQ-TREE output files
+            prefix.with_suffix(".iqtree.iqtree"),
+            prefix.with_suffix(".iqtree.log"),
+        ]
+
+        for file in expected_files:
+            assert file.exists(), f"Expected file {file} does not exist."
+
+        # Check if the features csv file is correct
+        features_content = pd.read_csv(features_file)
+        assert features_content.shape[0] == 1, "Expected one row in the features file."
+        pd.testing.assert_index_equal(
+            features_content.columns,
+            pd.Index(
+                [
+                    "num_taxa",
+                    "num_sites",
+                    "num_patterns",
+                    "num_patterns/num_taxa",
+                    "num_sites/num_taxa",
+                    "num_patterns/num_sites",
+                    "proportion_gaps",
+                    "proportion_invariant",
+                    "entropy",
+                    "bollback",
+                    "pattern_entropy",
+                    "avg_rfdist_parsimony",
+                    "proportion_unique_topos_parsimony",
+                    "difficulty",
+                ]
+            ),
+        )
+
+        # Check if the label is correct
+        label = features_content["difficulty"].values[0]
+        assert label == pytest.approx(expected_label, abs=0.01)
+
+        # Check if the log file is correct and contains the expected output
+        expected_lines = [
+            f"PyDLG version {__version__} released by The Exelixis Lab",
+            "PyDLG was called at",
+            "Starting label computation.",
+            "Computing RF-Distance between ML trees.",
+            "Inferring 10 ML trees using RAxML-NG.",
+            "RF-Distance ML trees:",
+            "Unique topologies ML trees:",
+            "Running IQ-TREE statistical tests.",
+            "Computing RF-Distance between plausible ML trees.",
+            "RF-Distance plausible trees:",
+            "Unique topologies plausible trees:",
+            "Computing corresponding Pythia features.",
+            f"Ground Truth Difficulty for {msa_file}:",
+            "WARNING: The number of inferred ML trees is less than 100. The computed label may be less reliable.",
+            "Label computation runtime",
+            "Total runtime",
+        ]
+
+        if msa_obj.contains_duplicate_sequences():
+            expected_lines.append(
+                "WARNING: The input MSA contains duplicate sequences. Consider deduplicating the MSA before running the label generator."
+            )
+        if msa_obj.contains_full_gap_sequences():
+            expected_lines.append(
+                "WARNING: The input MSA contains sequences that are only gaps. Consider removing these sequences before running the label generator."
+            )
+
+        log_content = logfile.read_text()
+
+        for line in expected_lines:
+            assert line in log_content