profact 0.1.0__py3-none-any.whl

profact/cli.py

@@ -0,0 +1,209 @@
+import argparse
+import sys
+from pathlib import Path
+from .parser import read_fasta, validate_record, FastaParseError
+from .duplicates import analyze_duplicates
+from .compare import compare_files
+from .stats import analyze_stats
+from .reporter import (
+    stats_to_text,
+    stats_to_tsv,
+    stats_to_json,
+    stats_to_html,
+    format_validation_report,
+    build_full_report_data,
+    full_report_to_text,
+    full_report_to_tsv,
+    full_report_to_json,
+    full_report_to_html,
+    format_duplicates_report,
+    format_compare_report,
+)
+
+
+def write_output(output_str, output_file):
+    if output_file:
+        output_path = Path(output_file)
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        output_path.write_text(output_str)
+    else:
+        print(output_str)
+
+
+
+def cmd_validate(args):
+    file_path = args.fasta_file
+    output_format = args.format
+    output_file = args.output
+
+    try:
+        records = list(read_fasta(file_path))
+    except FileNotFoundError as e:
+        print(f"ERROR: {e}", file=sys.stderr)
+        sys.exit(2)
+    except FastaParseError as e:
+        print(f"ERROR: Invalid FASTA format: {e}", file=sys.stderr)
+        sys.exit(2)
+    except Exception as e:
+        print(f"ERROR: {e}", file=sys.stderr)
+        sys.exit(2)
+
+    validated = []
+    for rec in records:
+        res = validate_record(rec)
+        validated.append(
+            {
+                "id": rec.id,
+                "description": rec.description,
+                "sequence_length": len(rec.sequence),
+                "valid": res["valid"],
+                "errors": res["errors"],
+                "warnings": res["warnings"],
+                "has_x": res["has_x"],
+                "has_stop": res["has_stop"],
+                "is_empty": res["is_empty"],
+                "invalid_chars": sorted(res["invalid_chars"]),
+                "non_standard": sorted(res["non_standard"]),
+            }
+        )
+
+    total = len(validated)
+    valid_count = sum(1 for v in validated if v["valid"])
+    invalid_count = total - valid_count
+    records_with_x = sum(1 for v in validated if v["has_x"])
+    records_with_stop = sum(1 for v in validated if v["has_stop"])
+    empty_records = sum(1 for v in validated if v["is_empty"])
+
+    summary = {
+        "total_records": total,
+        "valid_records": valid_count,
+        "invalid_records": invalid_count,
+        "records_with_X": records_with_x,
+        "records_with_stop": records_with_stop,
+        "empty_records": empty_records,
+    }
+
+    # Use the reporter function
+    output_str = format_validation_report(file_path, validated, summary, output_format)
+
+    write_output(output_str, output_file)
+    sys.exit(0 if invalid_count == 0 else 1)
+
+
+def cmd_duplicates(args):
+    try:
+        data = analyze_duplicates(args.fasta_file)
+    except (FileNotFoundError, FastaParseError) as e:
+        print(f"ERROR: {e}", file=sys.stderr)
+        sys.exit(2)
+
+    output_str = format_duplicates_report(data, args.fasta_file, args.format)
+
+    write_output(output_str, args.output)
+    sys.exit(0)
+
+
+def cmd_compare(args):
+    try:
+        data = compare_files(args.old_fasta, args.new_fasta)
+    except (FileNotFoundError, FastaParseError) as e:
+        print(f"ERROR: {e}", file=sys.stderr)
+        sys.exit(2)
+
+    output_str = format_compare_report(data, args.format)
+
+    write_output(output_str, args.output)
+    has_changes = any(
+        [
+            data["summary"]["added_count"],
+            data["summary"]["removed_count"],
+            data["summary"]["changed_sequence_count"],
+            data["summary"]["added_duplicate_cluster_count"],
+            data["summary"]["removed_duplicate_cluster_count"],
+            data["summary"]["changed_duplicate_cluster_count"],
+        ]
+    )
+    sys.exit(1 if has_changes else 0)
+
+
+def cmd_stats(args):
+    try:
+        data = analyze_stats(args.fasta_file)
+    except (FileNotFoundError, FastaParseError) as e:
+        print(f"ERROR: {e}", file=sys.stderr)
+        sys.exit(2)
+
+    if args.format == "json":
+        output_str = stats_to_json(data)
+    elif args.format == "tsv":
+        output_str = stats_to_tsv(data)
+    elif args.format == "html":
+        output_str = stats_to_html(data)
+    else:
+        output_str = stats_to_text(data)
+
+    write_output(output_str, args.output)
+    sys.exit(0)
+
+
+def cmd_report(args):
+    try:
+        data = build_full_report_data(args.fasta_file)
+    except (FileNotFoundError, FastaParseError) as e:
+        print(f"ERROR: {e}", file=sys.stderr)
+        sys.exit(2)
+
+    if args.format == "json":
+        output_str = full_report_to_json(data)
+    elif args.format == "tsv":
+        output_str = full_report_to_tsv(data)
+    elif args.format == "html":
+        output_str = full_report_to_html(data)
+    else:
+        output_str = full_report_to_text(data)
+
+    write_output(output_str, args.output)
+    sys.exit(0)
+
+
+def main():
+    parser = argparse.ArgumentParser(prog="profact", description="Protein FASTA analysis tool")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    val_parser = subparsers.add_parser("validate", help="Validate protein FASTA records")
+    val_parser.add_argument("-i", "--input", dest="fasta_file", required=True, help="Input FASTA file (.fa, .fasta, .faa, .gz)")
+    val_parser.add_argument("-fmt", "--format", choices=["text", "json", "tsv"], default="text", help="Output format")
+    val_parser.add_argument("-o", "--output", help="Output file (default: stdout)")
+    val_parser.set_defaults(func=cmd_validate)
+
+    dup_parser = subparsers.add_parser("duplicates", help="Detect duplicate IDs and identical sequences")
+    dup_parser.add_argument("-i", "--input", dest="fasta_file", required=True, help="Input FASTA file (.fa, .fasta, .faa, .gz)")
+    dup_parser.add_argument("-fmt", "--format", choices=["text", "json", "tsv"], default="text", help="Output format")
+    dup_parser.add_argument("-o", "--output", help="Output file (default: stdout)")
+    dup_parser.set_defaults(func=cmd_duplicates)
+
+    cmp_parser = subparsers.add_parser("compare", help="Compare two protein FASTA files")
+    cmp_parser.add_argument("-f1", "--file_1", metavar="FILE_1", dest="old_fasta", required=True, help="First FASTA file")
+    cmp_parser.add_argument("-f2", "--file_2", metavar="FILE_2", dest="new_fasta", required=True, help="Second FASTA file")
+    cmp_parser.add_argument("-fmt", "--format", choices=["text", "json", "tsv"], default="text", help="Output format")
+    cmp_parser.add_argument("-o", "--output", help="Output file (default: stdout)")
+    cmp_parser.set_defaults(func=cmd_compare)
+
+    stats_parser = subparsers.add_parser("stats", help="Compute protein FASTA statistics")
+    stats_parser.add_argument("-i", "--input", dest="fasta_file", required=True, help="Input FASTA file (.fa, .fasta, .faa, .gz)")
+    stats_parser.add_argument("-fmt", "--format", choices=["text", "json", "tsv", "html"], default="text", help="Output format")
+    stats_parser.add_argument("-o", "--output", help="Output file (default: stdout)")
+    stats_parser.set_defaults(func=cmd_stats)
+
+    report_parser = subparsers.add_parser("report", help="Generate full protein FASTA report")
+    report_parser.add_argument("-i", "--input", dest="fasta_file", required=True, help="Input FASTA file (.fa, .fasta, .faa, .gz)")
+    report_parser.add_argument("-fmt", "--format", choices=["text", "json", "tsv", "html"], default="text", help="Output format")
+    report_parser.add_argument("-o", "--output", help="Output file (default: stdout)")
+    report_parser.set_defaults(func=cmd_report)
+
+    args = parser.parse_args()
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()

profact/compare.py

@@ -0,0 +1,128 @@
+"""Comparison of two protein FASTA files."""
+from collections import defaultdict
+from typing import Dict, Iterable, List, Any, Tuple
+
+from .parser import FastaRecord, read_fasta
+from .duplicates import duplicate_summary
+
+
+def records_by_id(records: Iterable[FastaRecord]) -> Dict[str, FastaRecord]:
+    """
+    Build an ID -> record mapping.
+
+    If the same ID appears multiple times, the last record wins. Duplicate IDs
+    are still reported separately by duplicate_summary().
+    """
+    return {record.id: record for record in records}
+
+
+def sequence_cluster_signature(records: Iterable[FastaRecord]) -> Dict[str, Tuple[str, ...]]:
+    """Return exact sequence -> tuple(sorted IDs) for all duplicated sequences."""
+    by_sequence = defaultdict(list)
+    for record in records:
+        by_sequence[record.sequence].append(record.id)
+    return {
+        sequence: tuple(sorted(ids))
+        for sequence, ids in by_sequence.items()
+        if len(ids) > 1
+    }
+
+
+def compare_duplicate_clusters(
+    old_records: Iterable[FastaRecord],
+    new_records: Iterable[FastaRecord],
+) -> Dict[str, Any]:
+    """Detect exact duplicate sequence clusters added, removed or changed."""
+    old_sig = sequence_cluster_signature(old_records)
+    new_sig = sequence_cluster_signature(new_records)
+
+    old_sequences = set(old_sig)
+    new_sequences = set(new_sig)
+    common_sequences = old_sequences & new_sequences
+
+    changed = []
+    for sequence in sorted(common_sequences):
+        if old_sig[sequence] != new_sig[sequence]:
+            old_ids = set(old_sig[sequence])
+            new_ids = set(new_sig[sequence])
+            changed.append({
+                "sequence": sequence,
+                "length": len(sequence),
+                "old_ids": list(old_sig[sequence]),
+                "new_ids": list(new_sig[sequence]),
+                "added_ids": sorted(new_ids - old_ids),
+                "removed_ids": sorted(old_ids - new_ids),
+            })
+
+    return {
+        "added_clusters": [
+            {"sequence": seq, "length": len(seq), "ids": list(new_sig[seq])}
+            for seq in sorted(new_sequences - old_sequences)
+        ],
+        "removed_clusters": [
+            {"sequence": seq, "length": len(seq), "ids": list(old_sig[seq])}
+            for seq in sorted(old_sequences - new_sequences)
+        ],
+        "changed_clusters": changed,
+    }
+
+
+def compare_records(old_records: Iterable[FastaRecord], new_records: Iterable[FastaRecord]) -> Dict[str, Any]:
+    """Compare two FASTA record collections by ID and exact sequence content."""
+    old_list = list(old_records)
+    new_list = list(new_records)
+    old_by_id = records_by_id(old_list)
+    new_by_id = records_by_id(new_list)
+
+    old_ids = set(old_by_id)
+    new_ids = set(new_by_id)
+    common_ids = old_ids & new_ids
+
+    changed_sequences = []
+    changed_lengths = []
+    for seq_id in sorted(common_ids):
+        old_seq = old_by_id[seq_id].sequence
+        new_seq = new_by_id[seq_id].sequence
+        if old_seq != new_seq:
+            item = {
+                "id": seq_id,
+                "old_length": len(old_seq),
+                "new_length": len(new_seq),
+            }
+            changed_sequences.append(item)
+            if len(old_seq) != len(new_seq):
+                changed_lengths.append(item)
+
+    duplicate_changes = compare_duplicate_clusters(old_list, new_list)
+
+    return {
+        "summary": {
+            "old_total_records": len(old_list),
+            "new_total_records": len(new_list),
+            "added_count": len(new_ids - old_ids),
+            "removed_count": len(old_ids - new_ids),
+            "changed_sequence_count": len(changed_sequences),
+            "changed_length_count": len(changed_lengths),
+            "added_duplicate_cluster_count": len(duplicate_changes["added_clusters"]),
+            "removed_duplicate_cluster_count": len(duplicate_changes["removed_clusters"]),
+            "changed_duplicate_cluster_count": len(duplicate_changes["changed_clusters"]),
+        },
+        "added_ids": [
+            {"id": seq_id, "new_length": len(new_by_id[seq_id].sequence)}
+            for seq_id in sorted(new_ids - old_ids)
+        ],
+        "removed_ids": [
+            {"id": seq_id, "old_length": len(old_by_id[seq_id].sequence)}
+            for seq_id in sorted(old_ids - new_ids)
+        ],
+        "changed_sequences": changed_sequences,
+        "changed_lengths": changed_lengths,
+        "old_duplicates": duplicate_summary(old_list),
+        "new_duplicates": duplicate_summary(new_list),
+        "duplicate_cluster_changes": duplicate_changes,
+    }
+
+
+def compare_files(old_file: str, new_file: str) -> Dict[str, Any]:
+    """Read and compare two FASTA files."""
+    return compare_records(read_fasta(old_file), read_fasta(new_file))

profact/duplicates.py

@@ -0,0 +1,57 @@
+"""Duplicate detection for protein FASTA records."""
+from collections import Counter, defaultdict
+from typing import Dict, Iterable, List, Any
+
+from .parser import FastaRecord, read_fasta
+
+
+def find_duplicate_ids(records: Iterable[FastaRecord]) -> Dict[str, int]:
+    """Return IDs that occur more than once with their occurrence counts."""
+    counts = Counter(record.id for record in records)
+    return {seq_id: count for seq_id, count in counts.items() if count > 1}
+
+
+def cluster_identical_sequences(records: Iterable[FastaRecord]) -> List[Dict[str, Any]]:
+    """
+    Group records by exact sequence content.
+
+    Only clusters with at least two records are returned. IDs are sorted to keep
+    output stable in tests and CLI reports.
+    """
+    by_sequence = defaultdict(list)
+    for record in records:
+        by_sequence[record.sequence].append(record.id)
+
+    clusters = []
+    for sequence, ids in by_sequence.items():
+        if len(ids) > 1:
+            clusters.append({
+                "sequence": sequence,
+                "length": len(sequence),
+                "count": len(ids),
+                "ids": sorted(ids),
+            })
+
+    return sorted(clusters, key=lambda cluster: (cluster["length"], cluster["ids"]))
+
+
+def duplicate_summary(records: Iterable[FastaRecord]) -> Dict[str, Any]:
+    """Return duplicate-ID and identical-sequence cluster summary."""
+    materialized = list(records)
+    duplicate_ids = find_duplicate_ids(materialized)
+    clusters = cluster_identical_sequences(materialized)
+    ids_in_clusters = sorted({seq_id for cluster in clusters for seq_id in cluster["ids"]})
+
+    return {
+        "total_records": len(materialized),
+        "duplicate_id_count": len(duplicate_ids),
+        "duplicate_ids": duplicate_ids,
+        "identical_sequence_cluster_count": len(clusters),
+        "records_in_identical_sequence_clusters": len(ids_in_clusters),
+        "identical_sequence_clusters": clusters,
+    }
+
+
+def analyze_duplicates(file_path: str) -> Dict[str, Any]:
+    """Read a FASTA file and return duplicate analysis."""
+    return duplicate_summary(read_fasta(file_path))

profact/parser.py

@@ -0,0 +1,139 @@
+"""FASTA parsing and validation for protein sequences."""
+import gzip
+import sys
+from pathlib import Path
+from typing import Iterator, Dict, Set, List, Tuple, Optional
+import re
+
+# Standard 20 amino acids
+STD_AA = set("ACDEFGHIKLMNPQRSTVWY")
+# Allowed with warnings
+WARN_AA = {"X", "*"}   # X = unknown, * = stop
+# Non-standard but sometimes seen (B, Z, J) – also warnings
+NON_STD = {"B", "Z", "J"}
+# All characters that are not immediately rejected
+VALID_CHARS = STD_AA | WARN_AA | NON_STD
+
+class FastaRecord:
+    __slots__ = ("id", "description", "sequence")
+    def __init__(self, id: str, description: str, sequence: str):
+        self.id = id
+        self.description = description
+        self.sequence = sequence
+
+    def __repr__(self):
+        return f"FastaRecord(id={self.id!r}, seq_len={len(self.sequence)})"
+
+class FastaParseError(Exception):
+    """Raised when FASTA format is malformed."""
+    pass
+
+def read_fasta(file_path: str) -> Iterator[FastaRecord]:
+    """
+    Yield FastaRecord objects from a FASTA file (plain or .gz).
+    Raises FastaParseError if a record header does not start with '>'.
+    """
+    path = Path(file_path)
+    if not path.exists():
+        raise FileNotFoundError(f"File not found: {file_path}")
+
+    open_func = gzip.open if path.suffix == '.gz' else open
+    mode = 'rt' if path.suffix == '.gz' else 'r'
+
+    with open_func(path, mode) as f:
+        current_id = None
+        current_desc = ""
+        current_seq_lines = []
+        line_num = 0
+
+        for line in f:
+            line_num += 1
+            line = line.rstrip('\n\r')
+            if not line:
+                continue
+            if line[0] == '>':
+                # yield previous record
+                if current_id is not None:
+                    seq = ''.join(current_seq_lines)
+                    yield FastaRecord(current_id, current_desc, seq)
+                # parse header
+                header = line[1:].strip()
+                if not header:
+                    raise FastaParseError(f"Empty header after '>' at line {line_num}")
+                parts = header.split(maxsplit=1)
+                current_id = parts[0]
+                current_desc = parts[1] if len(parts) > 1 else ""
+                current_seq_lines = []
+            else:
+                # sequence line – remove all whitespace
+                current_seq_lines.append(re.sub(r'\s+', '', line))
+
+        # last record
+        if current_id is not None:
+            seq = ''.join(current_seq_lines)
+            yield FastaRecord(current_id, current_desc, seq)
+        elif line_num == 0:
+            # empty file
+            return
+        else:
+            raise FastaParseError("File ended without a record (missing '>'?)")
+
+def validate_record(record: FastaRecord) -> Dict[str, any]:
+    """
+    Validate a single protein FASTA record.
+    Returns dict with:
+        valid (bool)
+        errors (list of str)
+        warnings (list of str)
+        has_x (bool)
+        has_stop (bool)
+        invalid_chars (set)
+        non_standard (set)
+        is_empty (bool)
+    """
+    errors = []
+    warnings = []
+    seq = record.sequence
+    has_x = 'X' in seq
+    has_stop = '*' in seq
+    is_empty = len(seq) == 0
+
+    # Find invalid characters (anything not in VALID_CHARS)
+    invalid_chars = set(seq) - VALID_CHARS
+    if invalid_chars:
+        errors.append(f"Invalid character(s): {', '.join(sorted(invalid_chars))}")
+
+    if is_empty:
+        errors.append("Empty sequence")
+
+    # Warnings
+    if has_x:
+        warnings.append("Contains unknown residue 'X'")
+    if has_stop:
+        warnings.append("Contains stop symbol '*'")
+
+    non_standard = set(seq) & NON_STD
+    if non_standard:
+        warnings.append(f"Non-standard amino acid(s): {', '.join(sorted(non_standard))} (B=Asx, Z=Glx, J=Xle)")
+
+    valid = len(errors) == 0
+
+    return {
+        "valid": valid,
+        "errors": errors,
+        "warnings": warnings,
+        "has_x": has_x,
+        "has_stop": has_stop,
+        "invalid_chars": invalid_chars,
+        "non_standard": non_standard,
+        "is_empty": is_empty,
+    }
+
+def validate_file(file_path: str) -> Tuple[List[FastaRecord], List[Dict]]:
+    """
+    Parse all records from a FASTA file and validate each.
+    Returns (records, validation_results) where validation_results[i] corresponds to records[i].
+    """
+    records = list(read_fasta(file_path))
+    results = [validate_record(rec) for rec in records]
+    return records, results