evoseq 0.1.0__tar.gz

evoseq-0.1.0/LICENSE

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

evoseq-0.1.0/PKG-INFO

@@ -0,0 +1,230 @@
+Metadata-Version: 2.4
+Name: evoseq
+Version: 0.1.0
+Summary: Genome analysis toolkit powered by Evo
+Author: Hideaki Mizoue
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/mizomizo1/EvoSeq
+Project-URL: Repository, https://github.com/mizomizo1/EvoSeq
+Project-URL: Issues, https://github.com/mizomizo1/EvoSeq/issues
+Keywords: bioinformatics,genomics,evo2,variant-scoring
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+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: pandas>=2.2
+Requires-Dist: numpy>=2.0
+Requires-Dist: biopython>=1.85
+Requires-Dist: tqdm>=4.66
+Provides-Extra: evo2
+Requires-Dist: evo2; extra == "evo2"
+Requires-Dist: torch; extra == "evo2"
+Dynamic: license-file
+
+# EvoSeq
+
+EvoSeq is a small Colab-friendly toolkit for preparing paired reference/mutant
+FASTA files and scoring variants with Evo2.
+
+It is designed for the common research workflow where positive datasets have a
+`manifest.tsv`, negative datasets may only have paired FASTA files, and the same
+Evo2 model should stay loaded once per Colab runtime.
+
+## Install
+
+For local testing from this repository:
+
+```bash
+pip install -e .
+```
+
+For Evo2 scoring dependencies:
+
+```bash
+pip install -e ".[evo2]"
+```
+
+In Google Colab, Evo2 often needs a runtime-specific install. Use this before
+scoring:
+
+```bash
+pip uninstall -y torchvision
+pip install -q torch==2.7.1 --index-url https://download.pytorch.org/whl/cu128
+pip install -q flash-attn==2.8.0.post2 --no-build-isolation
+pip install -q evo2
+pip install -e .
+```
+
+After a GitHub Release is tagged, users can install a specific version directly:
+
+```bash
+pip install "git+https://github.com/mizomizo1/EvoSeq.git@v0.1.0"
+```
+
+For Evo2 scoring in Colab, install Evo2 and GPU dependencies in the runtime that
+matches your model. The preprocessing step only needs the base dependencies.
+
+## Debug / Test
+
+Run the local workflow tests without Evo2, torch, or flash-attn:
+
+```bash
+python -m unittest discover -s tests -v
+```
+
+These tests cover preprocessing, folder discovery, score-table export with a
+fake scorer, and the missing Evo2 dependency message. Real Evo2 scoring still
+requires a Colab GPU runtime with `torch`, `flash-attn`, and `evo2` installed.
+
+## Quick Start: Preprocessing Files
+
+Put files anywhere, for example in `test/`, and pass the files directly:
+
+```python
+from evoseq.preprocess import preprocess_files
+
+evo_df, paths = preprocess_files(
+    reference_fasta_path="test/evo2_reference.fasta",
+    mutant_fasta_path="test/evo2_mutant.fasta",
+    manifest_path="auto",
+)
+```
+
+By default, outputs are written next to the input files:
+`test/evoseq_preprocess_output/`.
+
+You can also be explicit:
+
+```python
+evo_df, paths = preprocess_files(
+    reference_fasta_path="test/evo2_reference.fasta",
+    mutant_fasta_path="test/evo2_mutant.fasta",
+    output_dir="outputs/preprocessing",
+)
+```
+
+Outputs include:
+
+- `evo2_pairs.tsv`: one row per variant with `ref_seq` and `mut_seq`
+- `evo2_reference.fa`
+- `evo2_mutant.fa`
+- `evo2_all.fa`
+- `preprocessing_report.tsv`
+
+`manifest.tsv` is optional. When present, metadata are merged by `record_id`.
+When absent, metadata are inferred from FASTA IDs when possible.
+
+## Quick Start: Preprocessing a Folder
+
+If your folder contains paired FASTA files, EvoSeq can discover them:
+
+```python
+from evoseq.preprocess import preprocess_folder
+
+evo_df, paths = preprocess_folder("test")
+```
+
+## Quick Start: Evo2 Scoring
+
+```python
+from evoseq.scoring import score_pairs_file
+
+result_df, result_paths = score_pairs_file(
+    pairs_path="test/evoseq_preprocess_output/evo2_pairs.tsv",
+    model_name="evo2_7b",
+    batch_size=8,
+)
+```
+
+By default, outputs are written next to the pair table:
+`test/evoseq_preprocess_output/evoseq_scoring_output/`.
+
+Use `output_dir="outputs/scoring"` if you want a project-level result folder.
+
+- `evo2_variant_scores_unique.tsv`
+- `evo2_variant_scores_manifest.tsv` when a manifest is available
+- `environment_info.tsv`
+- `scoring_report.tsv`
+
+Reference sequences are scored once per unique sequence and reused. This is
+useful when many variants share the same reference window.
+
+## Model Handling
+
+EvoSeq caches the loaded Evo2 model inside the Python process:
+
+```python
+from evoseq.scoring import Evo2Scorer
+
+scorer = Evo2Scorer(model_name="evo2_7b", device="cuda:0")
+scores = scorer.score_sequences(["ACGTACGT"])
+```
+
+Calling another scoring function with the same model reuses it. Attempting to
+load a different Evo2 model in the same runtime raises an explicit error by
+default, because loading multiple large models often exhausts Colab GPU memory.
+Restart the runtime when switching from 7B to 20B.
+
+Common model names:
+
+- `evo2_7b`
+- `evo2_7b_base`
+- `evo2_20b`
+
+For local model weights:
+
+```python
+score_evo2_pairs(
+    base_dir=".",
+    model_name="evo2_20b",
+    local_path="/content/drive/MyDrive/Models/evo2_20b.pt",
+)
+```
+
+## TOML Config
+
+Copy `evoseq.example.toml`, edit the input paths/model, and run:
+
+```python
+from evoseq import run_from_config
+
+outputs = run_from_config("evoseq.example.toml")
+```
+
+or:
+
+```bash
+evoseq-run evoseq.example.toml
+```
+
+## Per-Base Log-Probabilities
+
+```python
+from evoseq.scoring import export_perbase_logprobs
+
+path = export_perbase_logprobs(
+    fasta_path="test/representative_perbase.fasta",
+    model_name="evo2_7b",
+    center=4096,
+    half_window=320,
+)
+```
+
+By default, this writes `test/evoseq_perbase_output/perbase_logprobs.tsv`.
+
+## Reproducibility
+
+EvoSeq writes small TSV reports for methods sections and reruns:
+
+- input paths and output paths
+- number of variants and unique reference sequences
+- model name, batch size, device, elapsed time
+- Python, PyTorch, CUDA, GPU, NumPy, pandas, Biopython, and Evo2 versions
+
+These files are meant to be saved with each analysis directory.

evoseq-0.1.0/README.md

@@ -0,0 +1,201 @@
+# EvoSeq
+
+EvoSeq is a small Colab-friendly toolkit for preparing paired reference/mutant
+FASTA files and scoring variants with Evo2.
+
+It is designed for the common research workflow where positive datasets have a
+`manifest.tsv`, negative datasets may only have paired FASTA files, and the same
+Evo2 model should stay loaded once per Colab runtime.
+
+## Install
+
+For local testing from this repository:
+
+```bash
+pip install -e .
+```
+
+For Evo2 scoring dependencies:
+
+```bash
+pip install -e ".[evo2]"
+```
+
+In Google Colab, Evo2 often needs a runtime-specific install. Use this before
+scoring:
+
+```bash
+pip uninstall -y torchvision
+pip install -q torch==2.7.1 --index-url https://download.pytorch.org/whl/cu128
+pip install -q flash-attn==2.8.0.post2 --no-build-isolation
+pip install -q evo2
+pip install -e .
+```
+
+After a GitHub Release is tagged, users can install a specific version directly:
+
+```bash
+pip install "git+https://github.com/mizomizo1/EvoSeq.git@v0.1.0"
+```
+
+For Evo2 scoring in Colab, install Evo2 and GPU dependencies in the runtime that
+matches your model. The preprocessing step only needs the base dependencies.
+
+## Debug / Test
+
+Run the local workflow tests without Evo2, torch, or flash-attn:
+
+```bash
+python -m unittest discover -s tests -v
+```
+
+These tests cover preprocessing, folder discovery, score-table export with a
+fake scorer, and the missing Evo2 dependency message. Real Evo2 scoring still
+requires a Colab GPU runtime with `torch`, `flash-attn`, and `evo2` installed.
+
+## Quick Start: Preprocessing Files
+
+Put files anywhere, for example in `test/`, and pass the files directly:
+
+```python
+from evoseq.preprocess import preprocess_files
+
+evo_df, paths = preprocess_files(
+    reference_fasta_path="test/evo2_reference.fasta",
+    mutant_fasta_path="test/evo2_mutant.fasta",
+    manifest_path="auto",
+)
+```
+
+By default, outputs are written next to the input files:
+`test/evoseq_preprocess_output/`.
+
+You can also be explicit:
+
+```python
+evo_df, paths = preprocess_files(
+    reference_fasta_path="test/evo2_reference.fasta",
+    mutant_fasta_path="test/evo2_mutant.fasta",
+    output_dir="outputs/preprocessing",
+)
+```
+
+Outputs include:
+
+- `evo2_pairs.tsv`: one row per variant with `ref_seq` and `mut_seq`
+- `evo2_reference.fa`
+- `evo2_mutant.fa`
+- `evo2_all.fa`
+- `preprocessing_report.tsv`
+
+`manifest.tsv` is optional. When present, metadata are merged by `record_id`.
+When absent, metadata are inferred from FASTA IDs when possible.
+
+## Quick Start: Preprocessing a Folder
+
+If your folder contains paired FASTA files, EvoSeq can discover them:
+
+```python
+from evoseq.preprocess import preprocess_folder
+
+evo_df, paths = preprocess_folder("test")
+```
+
+## Quick Start: Evo2 Scoring
+
+```python
+from evoseq.scoring import score_pairs_file
+
+result_df, result_paths = score_pairs_file(
+    pairs_path="test/evoseq_preprocess_output/evo2_pairs.tsv",
+    model_name="evo2_7b",
+    batch_size=8,
+)
+```
+
+By default, outputs are written next to the pair table:
+`test/evoseq_preprocess_output/evoseq_scoring_output/`.
+
+Use `output_dir="outputs/scoring"` if you want a project-level result folder.
+
+- `evo2_variant_scores_unique.tsv`
+- `evo2_variant_scores_manifest.tsv` when a manifest is available
+- `environment_info.tsv`
+- `scoring_report.tsv`
+
+Reference sequences are scored once per unique sequence and reused. This is
+useful when many variants share the same reference window.
+
+## Model Handling
+
+EvoSeq caches the loaded Evo2 model inside the Python process:
+
+```python
+from evoseq.scoring import Evo2Scorer
+
+scorer = Evo2Scorer(model_name="evo2_7b", device="cuda:0")
+scores = scorer.score_sequences(["ACGTACGT"])
+```
+
+Calling another scoring function with the same model reuses it. Attempting to
+load a different Evo2 model in the same runtime raises an explicit error by
+default, because loading multiple large models often exhausts Colab GPU memory.
+Restart the runtime when switching from 7B to 20B.
+
+Common model names:
+
+- `evo2_7b`
+- `evo2_7b_base`
+- `evo2_20b`
+
+For local model weights:
+
+```python
+score_evo2_pairs(
+    base_dir=".",
+    model_name="evo2_20b",
+    local_path="/content/drive/MyDrive/Models/evo2_20b.pt",
+)
+```
+
+## TOML Config
+
+Copy `evoseq.example.toml`, edit the input paths/model, and run:
+
+```python
+from evoseq import run_from_config
+
+outputs = run_from_config("evoseq.example.toml")
+```
+
+or:
+
+```bash
+evoseq-run evoseq.example.toml
+```
+
+## Per-Base Log-Probabilities
+
+```python
+from evoseq.scoring import export_perbase_logprobs
+
+path = export_perbase_logprobs(
+    fasta_path="test/representative_perbase.fasta",
+    model_name="evo2_7b",
+    center=4096,
+    half_window=320,
+)
+```
+
+By default, this writes `test/evoseq_perbase_output/perbase_logprobs.tsv`.
+
+## Reproducibility
+
+EvoSeq writes small TSV reports for methods sections and reruns:
+
+- input paths and output paths
+- number of variants and unique reference sequences
+- model name, batch size, device, elapsed time
+- Python, PyTorch, CUDA, GPU, NumPy, pandas, Biopython, and Evo2 versions
+
+These files are meant to be saved with each analysis directory.

evoseq-0.1.0/evoseq/__init__.py

@@ -0,0 +1,3 @@
+from .config import load_config, run_from_config
+
+__all__ = ["load_config", "run_from_config"]

evoseq-0.1.0/evoseq/cli.py

@@ -0,0 +1,21 @@
+import argparse
+
+from .config import run_from_config
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(description="Run EvoSeq from a TOML config.")
+    parser.add_argument("config", help="Path to an EvoSeq TOML config file.")
+    args = parser.parse_args(argv)
+
+    outputs = run_from_config(args.config)
+    print("EvoSeq run completed.")
+    for key, value in outputs.items():
+        if key.endswith("_paths"):
+            print(f"{key}:")
+            for name, path in value.items():
+                print(f"  {name}: {path}")
+
+
+if __name__ == "__main__":
+    main()

evoseq-0.1.0/evoseq/config.py

@@ -0,0 +1,107 @@
+from pathlib import Path
+import tomllib
+
+from .preprocess import preprocess_files, preprocess_folder
+from .scoring import export_perbase_logprobs, score_pairs_file
+
+
+def _none_if_blank(value):
+    return None if value == "" else value
+
+
+def load_config(path):
+    with open(path, "rb") as fh:
+        return tomllib.load(fh)
+
+
+def run_from_config(path):
+    config = load_config(path)
+
+    project = config.get("project", {})
+    input_dir = project.get("input_dir", project.get("base_dir", "."))
+
+    preprocess_config = config.get("preprocess", {})
+    scoring_config = config.get("scoring", {})
+    perbase_config = config.get("perbase", {})
+
+    outputs = {}
+    if preprocess_config.get("enabled", True):
+        reference_fasta_path = _none_if_blank(preprocess_config.get("reference_fasta_path"))
+        mutant_fasta_path = _none_if_blank(preprocess_config.get("mutant_fasta_path"))
+        manifest_path = preprocess_config.get("manifest_path", "auto")
+
+        if reference_fasta_path and mutant_fasta_path:
+            evo_df, saved = preprocess_files(
+                reference_fasta_path=reference_fasta_path,
+                mutant_fasta_path=mutant_fasta_path,
+                manifest_path=manifest_path,
+                output_dir=_none_if_blank(
+                    preprocess_config.get("output_dir", preprocess_config.get("out_dir"))
+                ),
+                strict_manifest=preprocess_config.get("strict_manifest", False),
+                progress=preprocess_config.get("progress", True),
+            )
+        else:
+            evo_df, saved = preprocess_folder(
+                input_dir=input_dir,
+                output_dir=_none_if_blank(
+                    preprocess_config.get("output_dir", preprocess_config.get("out_dir"))
+                ),
+                manifest_path=manifest_path,
+                reference_fasta_path=reference_fasta_path,
+                mutant_fasta_path=mutant_fasta_path,
+                dataset_type=preprocess_config.get("dataset_type", "auto"),
+                window_size=preprocess_config.get("window_size"),
+                strict_manifest=preprocess_config.get("strict_manifest", False),
+                progress=preprocess_config.get("progress", True),
+            )
+        outputs["preprocess_df"] = evo_df
+        outputs["preprocess_paths"] = saved
+
+    if scoring_config.get("enabled", False):
+        pairs_path = (
+            _none_if_blank(scoring_config.get("pairs_path"))
+            or outputs.get("preprocess_paths", {}).get("pairs")
+        )
+        if not pairs_path:
+            raise ValueError(
+                "scoring.enabled is true, but no pairs_path was provided and "
+                "preprocessing did not produce a pair table."
+            )
+
+        result_df, paths = score_pairs_file(
+            pairs_path=pairs_path,
+            output_dir=_none_if_blank(
+                scoring_config.get("output_dir", scoring_config.get("result_dir"))
+            ),
+            manifest_path=scoring_config.get("manifest_path", "auto"),
+            model_name=scoring_config.get("model_name", "evo2_7b"),
+            device=scoring_config.get("device", "cuda:0"),
+            local_path=_none_if_blank(scoring_config.get("local_path")),
+            batch_size=scoring_config.get("batch_size", 8),
+            force_reload=scoring_config.get("force_reload", False),
+            require_recommended_gpu=scoring_config.get(
+                "require_recommended_gpu",
+                True,
+            ),
+            progress=scoring_config.get("progress", True),
+        )
+        outputs["scoring_df"] = result_df
+        outputs["scoring_paths"] = paths
+
+    if perbase_config.get("enabled", False):
+        output_path = export_perbase_logprobs(
+            fasta_path=perbase_config["fasta_path"],
+            output_path=_none_if_blank(perbase_config.get("output_path")),
+            output_dir=_none_if_blank(perbase_config.get("output_dir")),
+            model_name=perbase_config.get("model_name", "evo2_7b"),
+            device=perbase_config.get("device", "cuda:0"),
+            center=perbase_config.get("center", 4096),
+            half_window=perbase_config.get("half_window", 320),
+            local_path=_none_if_blank(perbase_config.get("local_path")),
+            progress=perbase_config.get("progress", True),
+        )
+        outputs["perbase_path"] = output_path
+
+    outputs["config_path"] = Path(path)
+    return outputs

evoseq-0.1.0/evoseq/paths.py

@@ -0,0 +1,43 @@
+from pathlib import Path
+
+
+def common_parent(paths):
+    resolved = [Path(path).expanduser().resolve().parent for path in paths if path]
+    if not resolved:
+        return Path.cwd()
+    if len(resolved) == 1:
+        return resolved[0]
+
+    import os
+
+    return Path(os.path.commonpath([str(path) for path in resolved]))
+
+
+def default_output_dir(kind, *input_paths, base_dir=None):
+    names = {
+        "preprocess": "evoseq_preprocess_output",
+        "scoring": "evoseq_scoring_output",
+        "perbase": "evoseq_perbase_output",
+    }
+    dirname = names.get(kind, f"evoseq_{kind}_output")
+
+    if base_dir:
+        return Path(base_dir) / dirname
+
+    return common_parent(input_paths) / dirname
+
+
+def ensure_output_dir(path, fallback="/content/evoseq_output"):
+    path = Path(path)
+    try:
+        path.mkdir(parents=True, exist_ok=True)
+        test_path = path / ".write_test"
+        test_path.write_text("ok")
+        test_path.unlink(missing_ok=True)
+        return path
+    except OSError as exc:
+        fallback_path = Path(fallback)
+        print(f"Warning: cannot use output directory {path} ({exc}).")
+        print(f"Using fallback output directory: {fallback_path}")
+        fallback_path.mkdir(parents=True, exist_ok=True)
+        return fallback_path

evoseq-0.1.0/evoseq/preprocess/__init__.py

@@ -0,0 +1,13 @@
+from .pipeline import (
+    prepare_evo2_input,
+    preprocess_files,
+    preprocess_folder,
+    preprocess_from_base_dir,
+)
+
+__all__ = [
+    "prepare_evo2_input",
+    "preprocess_files",
+    "preprocess_folder",
+    "preprocess_from_base_dir",
+]