SequenceDot 0.2.0__py3-none-any.whl

seqdot/__init__.py

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

seqdot/alphabet.py

@@ -0,0 +1,5 @@
+DNA = set("ACGTN")
+
+RNA = set("ACGUN")
+
+AA = set("ABCDEFGHIKLMNPQRSTVWXYZ")

seqdot/batch.py

@@ -0,0 +1,199 @@
+import typer
+import itertools
+
+from itertools import combinations
+from concurrent.futures import ProcessPoolExecutor, as_completed
+
+from tqdm import tqdm
+
+from seqdot.compare import compare_sequences, ensure_index
+from seqdot.utils import make_output_filename
+
+
+def generate_pairs(sequences, include_self=False):
+    """
+    Generate sequence comparison pairs.
+
+    Parameters
+    ----------
+    sequences : list
+        List of sequence dictionaries.
+
+    include_self : bool
+        Include comparisons of sequences against themselves.
+
+    Returns
+    -------
+    list
+        List of sequence pairs.
+    """
+
+    if include_self:
+
+        pairs = []
+
+        for i, seq1 in enumerate(sequences):
+            for seq2 in sequences[i:]:
+                pairs.append((seq1, seq2))
+
+        return pairs
+
+    else:
+
+        return list(
+            combinations(sequences, 2)
+        )
+
+
+def format_pair_name(seq1, seq2, max_length=20):
+    """
+    Format sequence names for the progress bar.
+    """
+
+    def shorten(name):
+        if len(name) <= max_length:
+            return name
+
+        return name[: max_length - 3] + "..."
+
+    return (
+        f"{shorten(seq1['name'])} vs "
+        f"{shorten(seq2['name'])}"
+    )
+
+def compare_pair(
+    seq1,
+    seq2,
+    kmer,
+    strand,
+    output_dir,
+    point_size,
+):
+    """
+    Compare a single pair of sequences.
+    """
+
+    output_file = make_output_filename(
+        seq1["name"],
+        seq2["name"]
+    )
+
+    output_file = output_dir / output_file
+
+    matches = compare_sequences(
+        seq1,
+        seq2,
+        kmer,
+        strand,
+        str(output_file),
+        point_size
+    )
+
+    return {
+        "seq1": seq1["name"],
+        "seq2": seq2["name"],
+        "matches": matches
+    }
+
+
+def run_all_vs_all(
+    sequences,
+    kmer,
+    strand,
+    output_dir,
+    point_size=1,
+    include_self=False,
+    silent=False,
+    threads=1,
+    thread_mode="auto"
+):
+    """
+    Run all-vs-all sequence comparisons.
+    """
+
+    pairs = generate_pairs(
+        sequences,
+        include_self
+    )
+    
+    for seq in sequences:
+
+        ensure_index(
+            seq,
+            kmer
+        )
+
+    if not silent:
+
+        typer.echo("SequenceDot batch comparison")
+        typer.echo("-" * 50)
+
+        typer.echo(f"Found sequences      : {len(sequences)}")
+        typer.echo(f"Comparison mode      : all-vs-all")
+        typer.echo(f"Include self         : {'yes' if include_self else 'no'}")
+        typer.echo(f"Total comparisons    : {len(pairs)}")
+        typer.echo(f"CPU threads          : {threads} ({thread_mode})")
+
+        typer.echo("-" * 50)
+        typer.echo()
+
+    results = []
+
+    with ProcessPoolExecutor(
+        max_workers=threads
+    ) as executor:
+    
+        future_to_pair = {}
+
+        for seq1, seq2 in pairs:
+
+            future = executor.submit(
+                compare_pair,
+                seq1,
+                seq2,
+                kmer,
+                strand,
+                output_dir,
+                point_size
+            )
+
+            future_to_pair[future] = (seq1, seq2)
+
+        if not silent:
+
+            with tqdm(
+                total=len(future_to_pair),
+                desc="Comparisons",
+                unit="comparison"
+            ) as pbar:
+                
+                for future in as_completed(future_to_pair):
+
+                    seq1, seq2 = future_to_pair[future]
+
+                    pbar.set_postfix_str(
+                        format_pair_name(seq1, seq2)
+                    )
+
+                    results.append(
+                        future.result()
+                    )
+
+                    pbar.update(1)
+
+        else:
+            
+            for future in as_completed(future_to_pair):
+
+                results.append(
+                    future.result()
+                )
+    
+    if not silent:
+
+        typer.echo()
+        typer.echo("✔ Batch comparison completed")
+        typer.echo(f"Number of dotplots created: {len(results)}")
+        typer.echo(f"Plots written to: {output_dir}")
+
+    return results

seqdot/cli.py

@@ -0,0 +1,287 @@
+import typer
+import os
+
+from seqdot import __version__
+from seqdot.compare import compare_sequences
+from seqdot.fasta import read_fasta, read_multi_fasta
+from seqdot.batch import run_all_vs_all
+from seqdot.utils import make_output_filename, check_for_gaps, resolve_threads
+from seqdot.report import write_summary
+
+from pathlib import Path
+from enum import Enum
+
+class Strand(str, Enum):
+    forward = "forward"
+    reverse = "reverse"
+    both = "both"
+
+app = typer.Typer(
+    name="SequenceDot",
+    context_settings={
+        "help_option_names": ["-h", "--help"]
+    },
+    help="""
+Create k-mer-based dotplots from unaligned sequences
+
+Supports:
+- comparison of two FASTA files
+- all-vs-all comparison from a multi-sequence FASTA file
+"""
+)
+
+
+def version_callback(value: bool):
+
+    if value:
+
+        typer.echo(f"SequenceDot {__version__}")
+        raise typer.Exit()
+
+
+@app.command()
+def main(
+    sequence1: str | None = typer.Argument(
+        None,
+        help="First fasta file (.fasta, .fa, .fna, optionally .gz)"
+    ),
+    sequence2: str | None = typer.Argument(
+        None,
+        help="Second fasta file (.fasta, .fa, .fna, optionally .gz)"
+    ),
+    input_file: str | None = typer.Option(
+        None,
+        "--file",
+        help="Multiple sequence fasta file for batch comparison (.fasta, .fa, .fna, optionally .gz)"
+    ),
+    all_vs_all: bool = typer.Option(
+        False,
+        "--all-vs-all",
+        help="Compare every sequence against every other sequence in --file, default does NOT include self (add --include-self)"
+    ),
+    include_self: bool = typer.Option(
+        False,
+        "--include-self",
+        help="Include self-comparisons in all-vs-all mode"
+    ),
+    kmer: int = typer.Option(
+        11,
+        "--kmer",
+        "-k",
+        min=1,
+        max=100,
+        help="Length of k-mer used for matching (1-100)"
+    ),
+    output: str | None = typer.Option(
+        None,
+        "--output",
+        "-o",
+        help="Output file for single comparisons (.png, .pdf, .svg)"
+    ),
+    output_dir: str | None = typer.Option(
+        None,
+        "--output-dir",
+        "-d",
+        help="Directory where output files are written, specifically useful for batch mode"
+    ),
+    alphabet: str = typer.Option(
+        "DNA",
+        "--alphabet",
+        "-a",
+        help="Sequence alphabet: DNA, RNA, or AA"
+    ),
+    strand: Strand = typer.Option(
+        Strand.forward,
+        "--strand",
+        "-s",
+        help="Compare forward strand, reverse complement, or both"
+    ),
+    point_size: float = typer.Option(
+        1.0,
+        "--point-size",
+        "-p",
+        min=0.1,
+        max=100,
+        help="Size of dots in the plot (0.1-100)"
+    ),
+    silent: bool = typer.Option(
+        False,
+        "--silent",
+        "-s",
+        help="Suppress progress bar during batch processing"
+    ),
+    version: bool = typer.Option(
+        False,
+        "--version",
+        "-v",
+        callback=version_callback,
+        is_eager=True,
+        help="Show SequenceDot version and exit"
+    ),
+    threads: str = typer.Option(
+        "auto",
+        "--threads",
+        "-t",
+        help="Number of CPU workers (default: auto)"
+    )
+):
+
+
+    """
+    Generate a dotplot from two sequence files.
+    """
+    if all_vs_all:
+
+        if input_file is None:
+            raise typer.BadParameter(
+                "--all-vs-all requires --file"
+            )
+
+        sequences = read_multi_fasta(
+            input_file,
+            alphabet
+        )
+
+        shortest = min(
+            seq["length"]
+            for seq in sequences
+        )
+
+        if kmer > shortest:
+            raise typer.BadParameter(
+                f"k-mer size ({kmer}) is larger than the "
+                f"shortest sequence ({shortest} bp)."
+            )
+
+        if output_dir is None:
+            output_dir = Path("seqdot_results")
+
+        output_dir = Path(output_dir)
+
+        output_dir.mkdir(
+            parents=True,
+            exist_ok=True
+        )
+        
+        try:
+            cpu_count = os.cpu_count() or 1
+            resolved_threads, thread_mode = resolve_threads(
+                threads,
+                len(sequences)
+            )
+
+        except ValueError as e:
+            raise typer.BadParameter(str(e))
+        
+        typer.echo("\nSequenceDot batch comparison")
+        typer.echo("-" * 50)
+        
+        typer.echo(f"Found sequences   : {len(sequences)}")
+        typer.echo("Comparison mode   : all-vs-all")
+        typer.echo(f"Include self      : {'yes' if include_self else 'no'}")
+
+        n = len(sequences)
+        comparisons = (n * (n - 1) // 2)
+        if include_self:
+            comparisons += n
+        
+        typer.echo(f"Total comparisons : {comparisons}")
+
+        if thread_mode == "auto":
+            typer.echo(
+                f"CPU workers       : "
+                f"{resolved_threads} "
+                f"(auto, {cpu_count} available)"
+            )
+        else:
+            typer.echo(
+                f"CPU workers       : "
+                f"{resolved_threads} "
+                "(user)"
+            )
+        
+        typer.echo("-" * 50)
+
+        results = run_all_vs_all(
+            sequences=sequences,
+            kmer=kmer,
+            strand=strand.value,
+            output_dir=output_dir,
+            point_size=point_size,
+            include_self=include_self,
+            silent=silent,
+            threads=resolved_threads,
+            thread_mode=thread_mode
+        )
+        
+        write_summary(
+            results,
+            output_dir
+        )
+        
+        typer.echo(
+            f"Summary written to {output_dir / 'summary.tsv'}"
+        )
+
+        raise typer.Exit()
+    
+    seq1 = read_fasta(sequence1, alphabet)
+    seq2 = read_fasta(sequence2, alphabet)
+
+    shortest = min(
+        seq1["length"],
+        seq2["length"]
+    )
+    
+    for seq in [seq1, seq2]:
+
+        if check_for_gaps(seq["sequence"]):
+            typer.echo(
+                f"Warning: {seq['name']} contains gap characters (-). "
+                "SequenceDot is designed for unaligned sequences."
+            )
+    
+    if kmer > shortest:
+        raise typer.BadParameter(
+            f"k-mer size ({kmer}) is larger than the "
+            f"shortest sequence ({shortest} bp)"
+        )
+    
+    if output is None:
+        output = make_output_filename(
+            seq1["name"],
+            seq2["name"]
+        )
+    
+    if output_dir is not None:
+        output_dir = Path(output_dir)
+
+        output_dir.mkdir(
+            parents=True,
+            exist_ok=True
+        )
+
+        output = str(output_dir / output)
+
+    typer.echo(
+        f"Building k-mer index (k={kmer})..."
+    )
+
+    matches = compare_sequences(
+        seq1,
+        seq2,
+        kmer,
+        strand.value,
+        output,
+        point_size
+    )
+
+    typer.echo(
+        f"Found {matches} matching k-mers"
+    )
+
+    typer.echo("Dotplot saved")
+    
+
+if __name__ == "__main__":
+    app()

seqdot/compare.py

@@ -0,0 +1,144 @@
+from seqdot.kmer import build_kmer_index, find_kmer_matches, build_kmer_index
+from seqdot.plot import create_dotplot
+from seqdot.utils import reverse_complement
+
+
+def add_strand(matches, strand):
+    """
+    Add strand information to matching coordinates.
+
+    Converts:
+        [(x, y), (x, y)]
+
+    into:
+        [(x, y, strand), (x, y, strand)]
+    """
+
+    return [
+        (x, y, strand)
+        for x, y in matches
+    ]
+
+
+def ensure_index(sequence, kmer):
+    """
+    Build a k-mer index once and reuse it.
+    """
+
+    if (
+        "kmer_index" not in sequence
+        or sequence["kmer_index"] is None
+        or sequence.get("kmer_index_k") != kmer
+    ):
+
+        sequence["kmer_index"] = build_kmer_index(
+            sequence["sequence"],
+            kmer
+        )
+
+        sequence["kmer_index_k"] = kmer
+
+
+def compare_sequences(
+    seq1,
+    seq2,
+    kmer,
+    strand,
+    output_file,
+    point_size=1,
+):
+    """
+    Compare two sequences and create a dotplot.
+
+    Parameters
+    ----------
+    seq1 : dict
+        First sequence dictionary.
+
+    seq2 : dict
+        Second sequence dictionary.
+
+    kmer : int
+        K-mer size.
+
+    strand : str
+        "forward", "reverse", or "both".
+
+    output_file : str
+        Output filename.
+
+    point_size : float
+        Size of dots in plot.
+
+    Returns
+    -------
+    int
+        Number of matching k-mers.
+    """
+
+    matches = []
+
+    # Forward comparison
+    if strand in ["forward", "both"]:
+        
+        ensure_index(
+            seq1,
+            kmer
+        )
+
+        index = seq1["kmer_index"]
+
+        forward_matches = find_kmer_matches(
+            seq2["sequence"],
+            index,
+            kmer
+        )
+
+        matches.extend(
+            add_strand(
+                forward_matches,
+                "forward"
+            )
+        )
+
+
+    # Reverse-complement comparison
+    if strand in ["reverse", "both"]:
+
+        reverse_seq2 = reverse_complement(
+            seq2["sequence"]
+        )
+        
+        ensure_index(
+            seq1,
+            kmer
+        )
+
+        index = seq1["kmer_index"]
+
+        reverse_matches = find_kmer_matches(
+            reverse_seq2,
+            index,
+            kmer
+        )
+
+        matches.extend(
+            add_strand(
+                reverse_matches,
+                "reverse"
+            )
+        )
+    
+    create_dotplot(
+        matches,
+        seq1["length"],
+        seq2["length"],
+        kmer,
+        name1=seq1["name"],
+        name2=seq2["name"],
+        output_file=output_file,
+        point_size=point_size
+    )
+
+
+    return len(matches)