clustrX 1.0.0__tar.gz

clustrx-1.0.0/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: clustrX
+Version: 1.0.0
+Summary: clustrX: Highly Robust and Sensitive Protein Clustering Using Similarity Networks and Leiden Community Detection
+Author-email: Mario Benítez-Prián <mario.benitezprian@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/mario-benitez-prian/clustrX
+Project-URL: Repository, https://github.com/mario-benitez-prian/clustrX
+Project-URL: Bug Tracker, https://github.com/mario-benitez-prian/clustrX/issues
+Keywords: bioinformatics,clustering,blast,hmmer,sequences,graphs,protein-families,similarity-search,sequence-clustering
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: polars>=0.19.0
+Requires-Dist: igraph>=0.10.0
+Requires-Dist: numpy>=1.20.0
+Requires-Dist: psutil>=5.8.0
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+
+# clustrX: Highly Robust and Sensitive Protein Clustering
+
+[![Version](https://img.shields.io/badge/version-1.0.0-blue.svg)](https://pypi.org/project/clustrX/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+
+**clustrX** is a high-performance framework designed to transform sequence similarity search results into biologically coherent protein families. By modeling homology as a weighted mathematical network and applying the **Leiden community detection algorithm**, `clustrX` provides a sensitive and robust solution for clustering sequences, especially in complex scenarios involving remote homology and short peptides.
+
+---
+
+## 🚀 Key Features
+
+*   **Leiden Community Detection**: Beyond simple links, `clustrX` identifies densely connected communities, ensuring high internal cohesion and preventing artificial family merging (e.g., due to domain bridges).
+*   **Agnostic Input**: Works with results from **BLAST**, **Diamond**, **MMseqs2**, and **HMMER**. Or others using the custom input option.
+*   **Dynamic Coverage Filter**: Our recommended approach to handle sequences of varying lengths to obtain the most reliable and biologically sound results.
+*   **Ultra-Fast Performance**: Powered by `Polars` (Rust-based) for data processing and `igraph` (C-based) for network analysis.
+*   **Integrated Workflow**: From similarity hits to Multiple Sequence Alignments (MSAs) in a single command.
+
+---
+
+## 📦 Installation
+
+You can install `clustrX` using two main methods. Note the difference in dependency management:
+
+### Option A: Via Conda (Recommended)
+This is the easiest way as it automatically installs all external dependencies, including **MAFFT** for alignments.
+```bash
+conda install -c bioconda clustrx
+```
+
+### Option B: Via Pip (Using a Virtual Environment)
+To avoid conflicts with other packages and ensure the `clustrx` command is correctly recognized by your system (avoiding PATH issues), we highly recommend using a virtual environment:
+
+1.  **Create a new environment**:
+    ```bash
+    python -m venv clustrx_env
+    ```
+2.  **Activate it**:
+    *   **Windows**: `clustrx_env\Scripts\activate`
+    *   **Linux/macOS**: `source clustrx_env/bin/activate`
+3.  **Install**:
+    ```bash
+    pip install clustrX
+    ```
+
+> [!TIP]
+> **If the `clustrx` command is not recognized** after installation (common on Windows), it is likely because the installation directory is not in your system's PATH. You can either add it manually or use the following foolproof method:
+> `python -m clustrx [arguments]`
+
+*Note: If you use Pip, remember that you must **install MAFFT manually** on your system if you plan to use the `--mafft` option.*
+
+---
+
+## ⚙️ Input Formats & Requirements
+
+`clustrX` is designed to be a post-processing layer. It requires two main inputs:
+1.  **Similarity Hits**: A tabular file (BLAST-like or HMMER).
+2.  **Sequences**: A FASTA file containing the sequences referenced in the hits.
+
+### Using BLAST
+`clustrX` works natively with the default tabular output of BLAST (`-outfmt 6`).
+```bash
+blastp -query sequences.fasta -db database -out hits.tsv -outfmt 6
+```
+
+### Using Diamond or MMseqs2
+If you use these tools, you **must** ensure the output is in **BLAST tabular format (outfmt 6)**:
+
+*   **Diamond**:
+    ```bash
+    diamond blastp -q query.fasta -d db.dmnd -o hits.tsv --outfmt 6
+    ```
+*   **MMseqs2**:
+    ```bash
+    mmseqs easy-search query.fasta target.fasta hits.tsv tmp --format-mode 0
+    ```
+
+### Using HMMER
+HMMER outputs require specific flags depending on the filtering level you need:
+
+*   **`domtblout` (Recommended)**: Use the `--domtblout` flag in `hmmsearch` or `phmmer`. This format provides alignment coordinates, which are **required** for using the **Dynamic Coverage** filter.
+    ```bash
+    hmmsearch --domtblout hits.domtblout profile.hmm database.fasta
+    ```
+*   **`tblout`**: Use the `--tblout` flag. Note that this format lacks coordinate information; therefore, **Dynamic Coverage cannot be applied** (only E-value and Bitscore filters will be used).
+    ```bash
+    hmmsearch --tblout hits.tblout profile.hmm database.fasta
+    ```
+
+---
+
+## 🧬 The Power of Dynamic Coverage
+
+We strongly recommend using the **Dynamic Coverage** mode (`--coverage dynamic`) for most scientific applications. For more information about this, please, read the paper.
+
+Standard clustering methods often use fixed thresholds that fail to resolve relationships between sequences of very different sizes. Our dynamic filter uses a **hyperbolic decay function** (calibrated with a 50-residue scale factor) that:
+1.  Increases stringency for **short peptides** (up to 0.8 coverage) to filter out statistical noise.
+2.  Gradually relaxes for **larger proteins** (down to 0.4 coverage) to maximize sensitivity in detecting remote homology.
+
+---
+
+## 🛠️ Workflow & Usage
+
+The `clustrX` pipeline follows a clear 3-step logic:
+
+1.  **Filter**: Hits are filtered based on E-value, Bitscore, and (recommended) Dynamic Coverage.
+2.  **Cluster**: A similarity network is built where edges are weighted by Bitscore, then partitioned using Leiden algorithm.
+3.  **Output**: Results are exported. **Note: Fasta generation and alignments are optional.**
+
+### Example: Recommended Scientific Run
+```bash
+clustrx -i hits.tsv -f sequences.fasta --coverage dynamic --write-fasta --mafft --outdir results_full
+```
+*   `--write-fasta`: (Optional) Creates a FASTA file for each generated cluster.
+*   `--mafft`: (Optional) Automatically performs Multiple Sequence Alignment for each cluster.
+
+---
+
+## 💡 Use Cases
+
+*   **Protein Family Discovery**: Organizing large proteomes into evolutionarily related groups.
+*   **Short Peptide Classification**: Specifically tuned for the discovery of **Antimicrobial Peptides (AMPs)**, toxins, signaling peptides or others.
+*   **Remote Homology Exploration**: Identifying relationships in the "twilight zone" (identity < 30%) where traditional greedy methods fragment families.
+*   **Domain-Aware Clustering**: Using HMMER `domtblout` inputs to cluster sequences based on specific functional domains.
+
+---
+
+## 📝 Citation
+If you use **clustrX** in your research, please cite:
+> Benítez-Prián, M. & San Mauro, D. (2026). clustrX: Highly Robust and Sensitive Protein Clustering Using Similarity Networks and Leiden Community Detection.
+
+## 👤 Authors
+**Mario Benítez-Prián** & **Diego San Mauro**
+
+Contact: [mario.benitezprian@gmail.com](mailto:mario.benitezprian@gmail.com) | [GitHub](https://github.com/mario-benitez-prian)

clustrx-1.0.0/README.md

@@ -0,0 +1,135 @@
+# clustrX: Highly Robust and Sensitive Protein Clustering
+
+[![Version](https://img.shields.io/badge/version-1.0.0-blue.svg)](https://pypi.org/project/clustrX/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+
+**clustrX** is a high-performance framework designed to transform sequence similarity search results into biologically coherent protein families. By modeling homology as a weighted mathematical network and applying the **Leiden community detection algorithm**, `clustrX` provides a sensitive and robust solution for clustering sequences, especially in complex scenarios involving remote homology and short peptides.
+
+---
+
+## 🚀 Key Features
+
+*   **Leiden Community Detection**: Beyond simple links, `clustrX` identifies densely connected communities, ensuring high internal cohesion and preventing artificial family merging (e.g., due to domain bridges).
+*   **Agnostic Input**: Works with results from **BLAST**, **Diamond**, **MMseqs2**, and **HMMER**. Or others using the custom input option.
+*   **Dynamic Coverage Filter**: Our recommended approach to handle sequences of varying lengths to obtain the most reliable and biologically sound results.
+*   **Ultra-Fast Performance**: Powered by `Polars` (Rust-based) for data processing and `igraph` (C-based) for network analysis.
+*   **Integrated Workflow**: From similarity hits to Multiple Sequence Alignments (MSAs) in a single command.
+
+---
+
+## 📦 Installation
+
+You can install `clustrX` using two main methods. Note the difference in dependency management:
+
+### Option A: Via Conda (Recommended)
+This is the easiest way as it automatically installs all external dependencies, including **MAFFT** for alignments.
+```bash
+conda install -c bioconda clustrx
+```
+
+### Option B: Via Pip (Using a Virtual Environment)
+To avoid conflicts with other packages and ensure the `clustrx` command is correctly recognized by your system (avoiding PATH issues), we highly recommend using a virtual environment:
+
+1.  **Create a new environment**:
+    ```bash
+    python -m venv clustrx_env
+    ```
+2.  **Activate it**:
+    *   **Windows**: `clustrx_env\Scripts\activate`
+    *   **Linux/macOS**: `source clustrx_env/bin/activate`
+3.  **Install**:
+    ```bash
+    pip install clustrX
+    ```
+
+> [!TIP]
+> **If the `clustrx` command is not recognized** after installation (common on Windows), it is likely because the installation directory is not in your system's PATH. You can either add it manually or use the following foolproof method:
+> `python -m clustrx [arguments]`
+
+*Note: If you use Pip, remember that you must **install MAFFT manually** on your system if you plan to use the `--mafft` option.*
+
+---
+
+## ⚙️ Input Formats & Requirements
+
+`clustrX` is designed to be a post-processing layer. It requires two main inputs:
+1.  **Similarity Hits**: A tabular file (BLAST-like or HMMER).
+2.  **Sequences**: A FASTA file containing the sequences referenced in the hits.
+
+### Using BLAST
+`clustrX` works natively with the default tabular output of BLAST (`-outfmt 6`).
+```bash
+blastp -query sequences.fasta -db database -out hits.tsv -outfmt 6
+```
+
+### Using Diamond or MMseqs2
+If you use these tools, you **must** ensure the output is in **BLAST tabular format (outfmt 6)**:
+
+*   **Diamond**:
+    ```bash
+    diamond blastp -q query.fasta -d db.dmnd -o hits.tsv --outfmt 6
+    ```
+*   **MMseqs2**:
+    ```bash
+    mmseqs easy-search query.fasta target.fasta hits.tsv tmp --format-mode 0
+    ```
+
+### Using HMMER
+HMMER outputs require specific flags depending on the filtering level you need:
+
+*   **`domtblout` (Recommended)**: Use the `--domtblout` flag in `hmmsearch` or `phmmer`. This format provides alignment coordinates, which are **required** for using the **Dynamic Coverage** filter.
+    ```bash
+    hmmsearch --domtblout hits.domtblout profile.hmm database.fasta
+    ```
+*   **`tblout`**: Use the `--tblout` flag. Note that this format lacks coordinate information; therefore, **Dynamic Coverage cannot be applied** (only E-value and Bitscore filters will be used).
+    ```bash
+    hmmsearch --tblout hits.tblout profile.hmm database.fasta
+    ```
+
+---
+
+## 🧬 The Power of Dynamic Coverage
+
+We strongly recommend using the **Dynamic Coverage** mode (`--coverage dynamic`) for most scientific applications. For more information about this, please, read the paper.
+
+Standard clustering methods often use fixed thresholds that fail to resolve relationships between sequences of very different sizes. Our dynamic filter uses a **hyperbolic decay function** (calibrated with a 50-residue scale factor) that:
+1.  Increases stringency for **short peptides** (up to 0.8 coverage) to filter out statistical noise.
+2.  Gradually relaxes for **larger proteins** (down to 0.4 coverage) to maximize sensitivity in detecting remote homology.
+
+---
+
+## 🛠️ Workflow & Usage
+
+The `clustrX` pipeline follows a clear 3-step logic:
+
+1.  **Filter**: Hits are filtered based on E-value, Bitscore, and (recommended) Dynamic Coverage.
+2.  **Cluster**: A similarity network is built where edges are weighted by Bitscore, then partitioned using Leiden algorithm.
+3.  **Output**: Results are exported. **Note: Fasta generation and alignments are optional.**
+
+### Example: Recommended Scientific Run
+```bash
+clustrx -i hits.tsv -f sequences.fasta --coverage dynamic --write-fasta --mafft --outdir results_full
+```
+*   `--write-fasta`: (Optional) Creates a FASTA file for each generated cluster.
+*   `--mafft`: (Optional) Automatically performs Multiple Sequence Alignment for each cluster.
+
+---
+
+## 💡 Use Cases
+
+*   **Protein Family Discovery**: Organizing large proteomes into evolutionarily related groups.
+*   **Short Peptide Classification**: Specifically tuned for the discovery of **Antimicrobial Peptides (AMPs)**, toxins, signaling peptides or others.
+*   **Remote Homology Exploration**: Identifying relationships in the "twilight zone" (identity < 30%) where traditional greedy methods fragment families.
+*   **Domain-Aware Clustering**: Using HMMER `domtblout` inputs to cluster sequences based on specific functional domains.
+
+---
+
+## 📝 Citation
+If you use **clustrX** in your research, please cite:
+> Benítez-Prián, M. & San Mauro, D. (2026). clustrX: Highly Robust and Sensitive Protein Clustering Using Similarity Networks and Leiden Community Detection.
+
+## 👤 Authors
+**Mario Benítez-Prián** & **Diego San Mauro**
+
+Contact: [mario.benitezprian@gmail.com](mailto:mario.benitezprian@gmail.com) | [GitHub](https://github.com/mario-benitez-prian)

clustrx-1.0.0/clustrX.egg-info/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: clustrX
+Version: 1.0.0
+Summary: clustrX: Highly Robust and Sensitive Protein Clustering Using Similarity Networks and Leiden Community Detection
+Author-email: Mario Benítez-Prián <mario.benitezprian@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/mario-benitez-prian/clustrX
+Project-URL: Repository, https://github.com/mario-benitez-prian/clustrX
+Project-URL: Bug Tracker, https://github.com/mario-benitez-prian/clustrX/issues
+Keywords: bioinformatics,clustering,blast,hmmer,sequences,graphs,protein-families,similarity-search,sequence-clustering
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: polars>=0.19.0
+Requires-Dist: igraph>=0.10.0
+Requires-Dist: numpy>=1.20.0
+Requires-Dist: psutil>=5.8.0
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+
+# clustrX: Highly Robust and Sensitive Protein Clustering
+
+[![Version](https://img.shields.io/badge/version-1.0.0-blue.svg)](https://pypi.org/project/clustrX/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+
+**clustrX** is a high-performance framework designed to transform sequence similarity search results into biologically coherent protein families. By modeling homology as a weighted mathematical network and applying the **Leiden community detection algorithm**, `clustrX` provides a sensitive and robust solution for clustering sequences, especially in complex scenarios involving remote homology and short peptides.
+
+---
+
+## 🚀 Key Features
+
+*   **Leiden Community Detection**: Beyond simple links, `clustrX` identifies densely connected communities, ensuring high internal cohesion and preventing artificial family merging (e.g., due to domain bridges).
+*   **Agnostic Input**: Works with results from **BLAST**, **Diamond**, **MMseqs2**, and **HMMER**. Or others using the custom input option.
+*   **Dynamic Coverage Filter**: Our recommended approach to handle sequences of varying lengths to obtain the most reliable and biologically sound results.
+*   **Ultra-Fast Performance**: Powered by `Polars` (Rust-based) for data processing and `igraph` (C-based) for network analysis.
+*   **Integrated Workflow**: From similarity hits to Multiple Sequence Alignments (MSAs) in a single command.
+
+---
+
+## 📦 Installation
+
+You can install `clustrX` using two main methods. Note the difference in dependency management:
+
+### Option A: Via Conda (Recommended)
+This is the easiest way as it automatically installs all external dependencies, including **MAFFT** for alignments.
+```bash
+conda install -c bioconda clustrx
+```
+
+### Option B: Via Pip (Using a Virtual Environment)
+To avoid conflicts with other packages and ensure the `clustrx` command is correctly recognized by your system (avoiding PATH issues), we highly recommend using a virtual environment:
+
+1.  **Create a new environment**:
+    ```bash
+    python -m venv clustrx_env
+    ```
+2.  **Activate it**:
+    *   **Windows**: `clustrx_env\Scripts\activate`
+    *   **Linux/macOS**: `source clustrx_env/bin/activate`
+3.  **Install**:
+    ```bash
+    pip install clustrX
+    ```
+
+> [!TIP]
+> **If the `clustrx` command is not recognized** after installation (common on Windows), it is likely because the installation directory is not in your system's PATH. You can either add it manually or use the following foolproof method:
+> `python -m clustrx [arguments]`
+
+*Note: If you use Pip, remember that you must **install MAFFT manually** on your system if you plan to use the `--mafft` option.*
+
+---
+
+## ⚙️ Input Formats & Requirements
+
+`clustrX` is designed to be a post-processing layer. It requires two main inputs:
+1.  **Similarity Hits**: A tabular file (BLAST-like or HMMER).
+2.  **Sequences**: A FASTA file containing the sequences referenced in the hits.
+
+### Using BLAST
+`clustrX` works natively with the default tabular output of BLAST (`-outfmt 6`).
+```bash
+blastp -query sequences.fasta -db database -out hits.tsv -outfmt 6
+```
+
+### Using Diamond or MMseqs2
+If you use these tools, you **must** ensure the output is in **BLAST tabular format (outfmt 6)**:
+
+*   **Diamond**:
+    ```bash
+    diamond blastp -q query.fasta -d db.dmnd -o hits.tsv --outfmt 6
+    ```
+*   **MMseqs2**:
+    ```bash
+    mmseqs easy-search query.fasta target.fasta hits.tsv tmp --format-mode 0
+    ```
+
+### Using HMMER
+HMMER outputs require specific flags depending on the filtering level you need:
+
+*   **`domtblout` (Recommended)**: Use the `--domtblout` flag in `hmmsearch` or `phmmer`. This format provides alignment coordinates, which are **required** for using the **Dynamic Coverage** filter.
+    ```bash
+    hmmsearch --domtblout hits.domtblout profile.hmm database.fasta
+    ```
+*   **`tblout`**: Use the `--tblout` flag. Note that this format lacks coordinate information; therefore, **Dynamic Coverage cannot be applied** (only E-value and Bitscore filters will be used).
+    ```bash
+    hmmsearch --tblout hits.tblout profile.hmm database.fasta
+    ```
+
+---
+
+## 🧬 The Power of Dynamic Coverage
+
+We strongly recommend using the **Dynamic Coverage** mode (`--coverage dynamic`) for most scientific applications. For more information about this, please, read the paper.
+
+Standard clustering methods often use fixed thresholds that fail to resolve relationships between sequences of very different sizes. Our dynamic filter uses a **hyperbolic decay function** (calibrated with a 50-residue scale factor) that:
+1.  Increases stringency for **short peptides** (up to 0.8 coverage) to filter out statistical noise.
+2.  Gradually relaxes for **larger proteins** (down to 0.4 coverage) to maximize sensitivity in detecting remote homology.
+
+---
+
+## 🛠️ Workflow & Usage
+
+The `clustrX` pipeline follows a clear 3-step logic:
+
+1.  **Filter**: Hits are filtered based on E-value, Bitscore, and (recommended) Dynamic Coverage.
+2.  **Cluster**: A similarity network is built where edges are weighted by Bitscore, then partitioned using Leiden algorithm.
+3.  **Output**: Results are exported. **Note: Fasta generation and alignments are optional.**
+
+### Example: Recommended Scientific Run
+```bash
+clustrx -i hits.tsv -f sequences.fasta --coverage dynamic --write-fasta --mafft --outdir results_full
+```
+*   `--write-fasta`: (Optional) Creates a FASTA file for each generated cluster.
+*   `--mafft`: (Optional) Automatically performs Multiple Sequence Alignment for each cluster.
+
+---
+
+## 💡 Use Cases
+
+*   **Protein Family Discovery**: Organizing large proteomes into evolutionarily related groups.
+*   **Short Peptide Classification**: Specifically tuned for the discovery of **Antimicrobial Peptides (AMPs)**, toxins, signaling peptides or others.
+*   **Remote Homology Exploration**: Identifying relationships in the "twilight zone" (identity < 30%) where traditional greedy methods fragment families.
+*   **Domain-Aware Clustering**: Using HMMER `domtblout` inputs to cluster sequences based on specific functional domains.
+
+---
+
+## 📝 Citation
+If you use **clustrX** in your research, please cite:
+> Benítez-Prián, M. & San Mauro, D. (2026). clustrX: Highly Robust and Sensitive Protein Clustering Using Similarity Networks and Leiden Community Detection.
+
+## 👤 Authors
+**Mario Benítez-Prián** & **Diego San Mauro**
+
+Contact: [mario.benitezprian@gmail.com](mailto:mario.benitezprian@gmail.com) | [GitHub](https://github.com/mario-benitez-prian)

clustrx-1.0.0/clustrX.egg-info/SOURCES.txt

@@ -0,0 +1,19 @@
+README.md
+pyproject.toml
+clustrX.egg-info/PKG-INFO
+clustrX.egg-info/SOURCES.txt
+clustrX.egg-info/dependency_links.txt
+clustrX.egg-info/entry_points.txt
+clustrX.egg-info/requires.txt
+clustrX.egg-info/top_level.txt
+clustrx/__init__.py
+clustrx/__main__.py
+clustrx/cli.py
+clustrx/clustrx.py
+tests/test_clustrx_logic.py
+tests/test_custom_format.py
+tests/test_filtering.py
+tests/test_hmmer_format.py
+tests/test_integration.py
+tests/test_scientific_rigor.py
+tests/test_validation.py

clustrx-1.0.0/clustrX.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

clustrx-1.0.0/clustrX.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+clustrx = clustrx.cli:main

clustrx-1.0.0/clustrX.egg-info/requires.txt

@@ -0,0 +1,7 @@
+polars>=0.19.0
+igraph>=0.10.0
+numpy>=1.20.0
+psutil>=5.8.0
+
+[test]
+pytest>=7.0

clustrx-1.0.0/clustrX.egg-info/top_level.txt

@@ -0,0 +1 @@
+clustrx

clustrx-1.0.0/clustrx/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    main()

clustrx-1.0.0/clustrx/cli.py

@@ -0,0 +1,140 @@
+import argparse
+import polars as pl
+from pathlib import Path
+from .clustrx import read_hits, get_fasta_info, build_clusters, write_clusters
+
+def main():
+    """
+    Main entry point for the clustRX CLI.
+    
+    This function handles:
+    1. Argument parsing (BLAST/HMMER formats, filters, clustering parameters).
+    2. Sequence discovery and indexing from FASTA headers (Selective I/O).
+    3. Edge processing and graph-based clustering (Leiden algorithm).
+    4. Output generation (FASTA files and optional MSAs).
+    """
+    parser = argparse.ArgumentParser(
+        description=(
+        "clustRX: Robust and Sensitive Sequence Clustering using Similarity Networks and Leiden Community Detection\n\n"
+        "A decoupled clustering framework supporting BLAST, DIAMOND, HMMER, and MMseqs2 outputs.\n"
+        "Features Adaptive Dynamic Coverage filtering and high-speed parsing via Polars & igraph.\n\n"
+        "Authors: Mario Benítez-Prián and Diego San Mauro | Please cite clustrX if used in your research.\n"
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter
+    )
+    parser.add_argument("-i", "--input", required=True, help="Input hits file (BLAST tabular or HMMER tblout)")
+    parser.add_argument("-o", "--outdir", default="clustrx_output", help="Output directory")
+    parser.add_argument("-c", "--coverage", help="Alignment coverage filter (0.0-1.0 or 'dynamic'). Percentage of the longest sequence covered by the alignment.")
+    parser.add_argument("-fmt", "--format", choices=["blast", "hmmer", "domhmmer", "tblhmmer", "mmseqs", "custom"], help="Input format (optional, auto-detected if not provided)")
+    parser.add_argument("-f", "--fasta", required=True, help="FASTA file with all sequences")
+    parser.add_argument("-min", "--min-cluster-size", type=int, default=2, help="Minimum cluster size to output (default=2).")
+    parser.add_argument("-e", "--evalue", type=float, help="E-value threshold for filtering hits (default: no filter)")
+    parser.add_argument("-b", "--bitscore", type=float, help="Bitscore threshold for filtering hits (default: no filter)")
+    parser.add_argument("-pi", "--pidentity", type=float, help="Minimum percentage identity (0-100) (default: no filter)")
+    parser.add_argument("--id-override", type=float, default=90.0, help="Identity threshold to override coverage filter (default: 90.0).")
+    parser.add_argument("--seed", type=int, help="Seed for reproducibility (default: None)")
+    parser.add_argument("--resolution", type=float, default=1.0, help="Resolution parameter for Leiden algorithm (default: 1.0)")
+    parser.add_argument("--mafft", action="store_true", help="Automatically run MAFFT on generated clusters (requires MAFFT installed)")
+    parser.add_argument("--write-fasta", action="store_true", help="Generate FASTA files and alignments for clusters (default: False).")
+    
+    # Custom format groups
+    custom_group = parser.add_argument_group('Custom Format Options', 'Specify 0-indexed column numbers for custom tabular inputs (column 1 in file is column 0).')
+    custom_group.add_argument("--col-query", type=int, help="Column index for query ID")
+    custom_group.add_argument("--col-target", type=int, help="Column index for target ID")
+    custom_group.add_argument("--col-bitscore", type=int, help="Column index for alignment score (bitscore)")
+    custom_group.add_argument("--col-evalue", type=int, help="Column index for E-value")
+    custom_group.add_argument("--col-pident", type=int, help="Column index for percentage identity")
+    custom_group.add_argument("--col-length", type=int, help="Column index for alignment length (used in dynamic coverage). Query and target lengths are extracted from the fasta file.")
+    args = parser.parse_args()
+
+    if args.mafft:
+        import shutil
+        if not shutil.which("mafft"):
+            print("Error: MAFFT is not installed or not found in system PATH. Please install it (e.g., 'sudo apt install mafft' or via Bioconda) to use the --mafft flag.")
+            return
+
+    # SELECTIVE I/O: Read only names and lengths to build the index.
+    # This is extremely memory-efficient and fast.
+    names, lengths = get_fasta_info(args.fasta)
+    
+    # PERFORMANCE HACK: Use Polars Enum for O(1) string matching.
+    # This maps sequence names to internal IDs for fast hit lookups.
+    name_enum = pl.Enum(names)
+    
+    # Create the ID mapping and lengths DataFrames for Polars
+    mapping_df = pl.DataFrame({
+        "name": names,
+        "id": list(range(len(names)))
+    }).with_columns([
+        pl.col("name").cast(name_enum),
+        pl.col("id").cast(pl.Int32)
+    ])
+    
+    lengths_df = pl.DataFrame({
+        'name': names,
+        'len': [lengths.get(n, 0) for n in names]
+    }).with_columns([
+        pl.col('name').cast(name_enum),
+        pl.col('len').cast(pl.Int32)
+    ])
+    
+    # Process coverage arg
+    cov_val = None
+    if args.coverage:
+        if args.coverage.lower() == 'dynamic':
+            cov_val = 'dynamic'
+        else:
+            try:
+                cov_val = float(args.coverage)
+            except ValueError:
+                print(f"Error: coverage must be a float or 'dynamic'. Got '{args.coverage}'")
+                return
+
+    # Process custom cols
+    custom_cols = {}
+    if args.col_query is not None: custom_cols['q'] = args.col_query
+    if args.col_target is not None: custom_cols['t'] = args.col_target
+    if args.col_bitscore is not None: custom_cols['bitscore'] = args.col_bitscore
+    if args.col_evalue is not None: custom_cols['evalue'] = args.col_evalue
+    if args.col_pident is not None: custom_cols['pident'] = args.col_pident
+    if args.col_length is not None: custom_cols['length'] = args.col_length
+    
+    input_format = args.format
+    if custom_cols and input_format is None:
+        input_format = 'custom'
+
+    # Call read_hits with mapping and lengths
+    u_v, weights, v_list = read_hits(
+        args.input, format=input_format, evalue=args.evalue, bitscore=args.bitscore, 
+        pident=args.pidentity, coverage=cov_val,
+        mapping_df=mapping_df, lengths_df=lengths_df,
+        pident_override=args.id_override,
+        custom_cols=custom_cols if input_format == 'custom' else None
+    )
+
+    # Build clusters
+    components = build_clusters(
+        (u_v, weights, v_list), 
+        min_size=args.min_cluster_size, 
+        seed=args.seed,
+        resolution=args.resolution
+    )
+
+    # OUTPUT PHASE: Write clusters to disk.
+    # Only load the FULL sequences (ATGCs) here if requested or needed for MAFFT.
+    if args.write_fasta or args.mafft:
+        from .clustrx import read_fasta
+        sequences = read_fasta(args.fasta)
+    else:
+        sequences = None
+    
+    out_clusters = Path(args.outdir) / "clusters"
+    out_fastas = Path(args.outdir) / "fasta_files"
+    out_alignments = Path(args.outdir) / "alignments" if args.mafft else None
+    
+    write_clusters(components, sequences, out_clusters, out_fastas, out_alignments)
+
+    print(f"Done. {len(components)} clusters written to {args.outdir}/")
+
+if __name__ == "__main__":
+    main()