profact 0.1.0__tar.gz

profact-0.1.0/LICENSE

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

profact-0.1.0/PKG-INFO

@@ -0,0 +1,184 @@
+Metadata-Version: 2.4
+Name: profact
+Version: 0.1.0
+Summary: Protein FASTA analysis and comparison tool
+Author: Wojciech Laskowski, Wojciech Moryl, Karolina Winczewska
+License-Expression: MIT
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Dynamic: license-file
+
+# ProFACT - Protein FASTA Analysis and Comparison Tool
+
+> A pip-installable Python CLI for protein FASTA quality control, duplicate detection and dataset comparison.
+
+## Overview
+
+Bioinformatics workflows often use protein FASTA files after downloading data from UniProt, Swiss-Prot, RefSeq or Ensembl/NCBI, filtering protein datasets, or running protein prediction pipelines. Checking quality and comparing two FASTA datasets often requires separate shell commands or custom scripts.
+
+ProFACT combines common protein FASTA quality-control tasks into one small, testable Python CLI tool.
+
+---
+
+## Features
+
+- Plain and gzipped protein FASTA support (`.fa`, `.fasta`, `.faa`, `.fa.gz`, `.fasta.gz`, `.faa.gz`)
+- Protein-specific statistics: length distribution, N50 and amino acid composition
+- Quality checks: `X`, `*`, invalid amino acid characters and empty records
+- Duplicate detection: repeated IDs and identical sequences under different IDs
+- Exact duplicate clustering
+- Comparison of two protein FASTA files:
+  - added IDs
+  - removed IDs
+  - changed sequences
+  - changed sequence lengths
+  - changed duplicate clusters
+- Output formats: text, TSV and JSON for all commands; HTML for statistics and full reports
+- Pure Python, no heavy bioinformatics dependencies
+- Local installation via `pip install -e .`
+
+---
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+For running tests:
+
+```bash
+pip install -e ".[test]"
+python3 -m pytest -q
+```
+
+---
+
+## Quick Start With Included Data
+
+The repository includes two sample UniProt proteome FASTA files in `data/`.
+
+To run tests and generate all example outputs:
+
+```bash
+bash scripts/run_examples.sh
+```
+
+This writes text, TSV, JSON and HTML outputs to `output/`.
+
+You can also run selected analyses manually:
+
+```bash
+python3 -m profact.cli stats \
+  -i data/uniprotkb_proteome_UP000000625_2026_06_06.fasta \
+  -fmt html \
+  -o output/stats_UP000000625.html
+
+python3 -m profact.cli report \
+  -i data/uniprotkb_proteome_UP000000625_2026_06_06.fasta \
+  -fmt html \
+  -o output/report_UP000000625.html
+
+python3 -m profact.cli compare \
+  -f1 data/uniprotkb_proteome_UP000000625_2026_06_06.fasta \
+  -f2 data/uniprotkb_proteome_UP000001570_2026_06_06.fasta \
+  -fmt json \
+  -o output/compare_UP000000625_vs_UP000001570.json
+```
+
+---
+
+## Usage
+
+```bash
+# Inspect a protein FASTA file
+profact stats -i swissprot_subset.fasta
+
+# Export statistics as JSON
+profact stats -i swissprot_subset.fasta -fmt json -o output/stats.json
+
+# Validate protein records
+profact validate -i proteins.fasta.gz
+
+# Detect identical protein sequences
+profact duplicates -i proteins.fasta
+
+# Compare raw and filtered protein datasets
+profact compare -f1 raw_proteins.fasta -f2 filtered_proteins.fasta
+
+# Export comparison as JSON
+profact compare -f1 old_uniprot.fasta -f2 new_uniprot.fasta -fmt json -o output/compare.json
+
+# Generate a full HTML report
+profact report -i proteins.fasta -fmt html -o output/report.html
+
+# Generate a full text report
+profact report -i proteins.fasta
+```
+
+Generated files can be kept in `output/`, for example:
+
+```bash
+profact stats -i data/proteins.fasta -fmt json -o output/stats.json
+profact validate -i data/proteins.fasta -fmt tsv -o output/validation.tsv
+profact compare -f1 data/old.fasta -f2 data/new.fasta -fmt json -o output/compare.json
+```
+
+The `validate` command exits with status code `1` when invalid records are found.
+The `compare` command exits with status code `1` when the two files differ.
+In both cases this is expected behavior and reports are still written to `output/`.
+
+---
+
+## Project Structure
+
+```text
+profact/      Python package and CLI implementation
+tests/        Automated tests
+data/         Sample FASTA datasets
+output/       Generated reports and command outputs
+scripts/      Helper scripts for reproducible example runs
+```
+
+---
+
+## What We Implemented
+
+We created ProFACT as a new bioinformatics-related Python CLI project for protein FASTA quality control and comparison.
+
+The implementation includes FASTA parsing, validation, sequence statistics, duplicate detection, pairwise dataset comparison, report generation, automated tests, sample FASTA datasets and a reproducible example script.
+
+The tool was needed because common FASTA quality checks are often done with separate commands or custom scripts. ProFACT provides these checks in one consistent package.
+
+---
+
+## Scope and Limitations
+
+ProFACT works with **protein FASTA files**, not FASTQ files, raw sequencing reads or nucleotide QC.
+
+The first version is intended for small and medium protein datasets, such as custom FASTA files, proteomes, Swiss-Prot subsets or filtered UniProt downloads. Very large databases such as full UniProt or NCBI NR are outside the main scope of the first version.
+
+The comparison is based on sequence IDs and exact sequence content. ProFACT does not perform BLAST searches, multiple sequence alignment or similarity-based clustering. Duplicate clustering means exact grouping of identical protein sequences.
+
+The `report` command generates a combined report for one FASTA file. Pairwise dataset comparison is handled separately by the `compare` command.
+
+---
+
+## Similar Tools
+
+Similar tools already exist, including `seqkit`, `pyfastx`, BioPython and FastQC. ProFACT does not aim to replace them or introduce a new bioinformatics algorithm.
+
+Its value is integration: it combines common protein FASTA checks into one small, focused and testable CLI with structured outputs and automated tests.
+
+---
+
+## Team Members
+
+| Name | GitHub |
+|------|--------|
+| Wojciech Laskowski | [@wlaskowski](https://github.com/wlaskowski) |
+| Wojciech Moryl | [@wojciech-moryl](https://github.com/Fair0n) |
+| Karolina Winczewska | [@KarolinaWinczewska](https://github.com/KaWinczewska) |

profact-0.1.0/README.md

@@ -0,0 +1,171 @@
+# ProFACT - Protein FASTA Analysis and Comparison Tool
+
+> A pip-installable Python CLI for protein FASTA quality control, duplicate detection and dataset comparison.
+
+## Overview
+
+Bioinformatics workflows often use protein FASTA files after downloading data from UniProt, Swiss-Prot, RefSeq or Ensembl/NCBI, filtering protein datasets, or running protein prediction pipelines. Checking quality and comparing two FASTA datasets often requires separate shell commands or custom scripts.
+
+ProFACT combines common protein FASTA quality-control tasks into one small, testable Python CLI tool.
+
+---
+
+## Features
+
+- Plain and gzipped protein FASTA support (`.fa`, `.fasta`, `.faa`, `.fa.gz`, `.fasta.gz`, `.faa.gz`)
+- Protein-specific statistics: length distribution, N50 and amino acid composition
+- Quality checks: `X`, `*`, invalid amino acid characters and empty records
+- Duplicate detection: repeated IDs and identical sequences under different IDs
+- Exact duplicate clustering
+- Comparison of two protein FASTA files:
+  - added IDs
+  - removed IDs
+  - changed sequences
+  - changed sequence lengths
+  - changed duplicate clusters
+- Output formats: text, TSV and JSON for all commands; HTML for statistics and full reports
+- Pure Python, no heavy bioinformatics dependencies
+- Local installation via `pip install -e .`
+
+---
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+For running tests:
+
+```bash
+pip install -e ".[test]"
+python3 -m pytest -q
+```
+
+---
+
+## Quick Start With Included Data
+
+The repository includes two sample UniProt proteome FASTA files in `data/`.
+
+To run tests and generate all example outputs:
+
+```bash
+bash scripts/run_examples.sh
+```
+
+This writes text, TSV, JSON and HTML outputs to `output/`.
+
+You can also run selected analyses manually:
+
+```bash
+python3 -m profact.cli stats \
+  -i data/uniprotkb_proteome_UP000000625_2026_06_06.fasta \
+  -fmt html \
+  -o output/stats_UP000000625.html
+
+python3 -m profact.cli report \
+  -i data/uniprotkb_proteome_UP000000625_2026_06_06.fasta \
+  -fmt html \
+  -o output/report_UP000000625.html
+
+python3 -m profact.cli compare \
+  -f1 data/uniprotkb_proteome_UP000000625_2026_06_06.fasta \
+  -f2 data/uniprotkb_proteome_UP000001570_2026_06_06.fasta \
+  -fmt json \
+  -o output/compare_UP000000625_vs_UP000001570.json
+```
+
+---
+
+## Usage
+
+```bash
+# Inspect a protein FASTA file
+profact stats -i swissprot_subset.fasta
+
+# Export statistics as JSON
+profact stats -i swissprot_subset.fasta -fmt json -o output/stats.json
+
+# Validate protein records
+profact validate -i proteins.fasta.gz
+
+# Detect identical protein sequences
+profact duplicates -i proteins.fasta
+
+# Compare raw and filtered protein datasets
+profact compare -f1 raw_proteins.fasta -f2 filtered_proteins.fasta
+
+# Export comparison as JSON
+profact compare -f1 old_uniprot.fasta -f2 new_uniprot.fasta -fmt json -o output/compare.json
+
+# Generate a full HTML report
+profact report -i proteins.fasta -fmt html -o output/report.html
+
+# Generate a full text report
+profact report -i proteins.fasta
+```
+
+Generated files can be kept in `output/`, for example:
+
+```bash
+profact stats -i data/proteins.fasta -fmt json -o output/stats.json
+profact validate -i data/proteins.fasta -fmt tsv -o output/validation.tsv
+profact compare -f1 data/old.fasta -f2 data/new.fasta -fmt json -o output/compare.json
+```
+
+The `validate` command exits with status code `1` when invalid records are found.
+The `compare` command exits with status code `1` when the two files differ.
+In both cases this is expected behavior and reports are still written to `output/`.
+
+---
+
+## Project Structure
+
+```text
+profact/      Python package and CLI implementation
+tests/        Automated tests
+data/         Sample FASTA datasets
+output/       Generated reports and command outputs
+scripts/      Helper scripts for reproducible example runs
+```
+
+---
+
+## What We Implemented
+
+We created ProFACT as a new bioinformatics-related Python CLI project for protein FASTA quality control and comparison.
+
+The implementation includes FASTA parsing, validation, sequence statistics, duplicate detection, pairwise dataset comparison, report generation, automated tests, sample FASTA datasets and a reproducible example script.
+
+The tool was needed because common FASTA quality checks are often done with separate commands or custom scripts. ProFACT provides these checks in one consistent package.
+
+---
+
+## Scope and Limitations
+
+ProFACT works with **protein FASTA files**, not FASTQ files, raw sequencing reads or nucleotide QC.
+
+The first version is intended for small and medium protein datasets, such as custom FASTA files, proteomes, Swiss-Prot subsets or filtered UniProt downloads. Very large databases such as full UniProt or NCBI NR are outside the main scope of the first version.
+
+The comparison is based on sequence IDs and exact sequence content. ProFACT does not perform BLAST searches, multiple sequence alignment or similarity-based clustering. Duplicate clustering means exact grouping of identical protein sequences.
+
+The `report` command generates a combined report for one FASTA file. Pairwise dataset comparison is handled separately by the `compare` command.
+
+---
+
+## Similar Tools
+
+Similar tools already exist, including `seqkit`, `pyfastx`, BioPython and FastQC. ProFACT does not aim to replace them or introduce a new bioinformatics algorithm.
+
+Its value is integration: it combines common protein FASTA checks into one small, focused and testable CLI with structured outputs and automated tests.
+
+---
+
+## Team Members
+
+| Name | GitHub |
+|------|--------|
+| Wojciech Laskowski | [@wlaskowski](https://github.com/wlaskowski) |
+| Wojciech Moryl | [@wojciech-moryl](https://github.com/Fair0n) |
+| Karolina Winczewska | [@KarolinaWinczewska](https://github.com/KaWinczewska) |

profact-0.1.0/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()