CodonAdaptPy 1.0.0__py3-none-any.whl

codonadaptpy/cli.py

@@ -0,0 +1,409 @@
+"""
+CodonAdaptPy Command-Line Interface
+
+This module exposes standalone subcommands for complete sequence analysis,
+multi-host comparison, reference construction/cataloging, and constrained
+optimization or deoptimization. It also exposes MAFFT/trimAL/IQ-TREE/FastTree
+phylogenetics with ETE3-backed static tree and temporal-diagnostic figures.
+CLI workflows call the same class-based API
+used by Python callers and write reproducible, structured output directories.
+
+Commands:
+    - analyze: Analyze one sequence or a batch input file.
+    - compare: Compare sequences against multiple host reference profiles.
+    - optimize: Generate ranked synonymous sequence candidates.
+    - phylogeny: Align sequences, infer an ML tree, and optionally time-scale it.
+    - reference: Build, inspect, list, or validate codon reference profiles.
+
+Functions:
+    - build_parser: Construct the documented argument parser.
+    - main: Execute the requested subcommand and return a process status.
+
+:Created: July 20, 2026
+:Updated: July 20, 2026
+:Author: Naveen Duhan
+:Version: 1.0.0
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import shlex
+import sys
+from dataclasses import asdict
+from pathlib import Path
+
+from .__version__ import __author__, __version__
+from .aggregation import CDSAggregator
+from .analyzer import AnalysisConfig, analyzer_from_reference_files
+from .exceptions import CodonAdaptPyError
+from .models import AnalysisResult, ValidationConfig
+from .optimizer import CodonOptimizer, OptimizationConfig
+from .parsers import SequenceParser
+from .phylo_visualization import ETE3TreePlotter
+from .phylogenetics import PhylogeneticAnalyzer, TemporalAnalyzer
+from .references import ReferenceManager
+from .reporting import ReportGenerator
+from .visualization import PlotManager
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Construct the top-level parser and all standalone subcommands."""
+
+    parser = argparse.ArgumentParser(
+        prog="codonadaptpy",
+        description="Codon usage, host adaptation, evolutionary analysis, and synonymous sequence design.",
+    )
+    parser.add_argument("--version", action="version", version=f"CodonAdaptPy {__version__} ({__author__})")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    analyze = subparsers.add_parser("analyze", help="Analyze a sequence or supported batch file.")
+    _add_analysis_arguments(analyze)
+    analyze.set_defaults(handler=_run_analyze)
+
+    compare = subparsers.add_parser("compare", help="Compare sequences with multiple host references.")
+    _add_analysis_arguments(compare)
+    compare.set_defaults(handler=_run_analyze)
+
+    phylogeny = subparsers.add_parser("phylogeny", help="Infer and visualize a maximum-likelihood phylogeny.")
+    phylogeny.add_argument("input", help="Input FASTA or supported sequence file.")
+    phylogeny.add_argument("--format", choices=("fasta", "genbank", "csv", "tsv", "zip"))
+    phylogeny.add_argument("--metadata", help="CSV/TSV metadata joined by identifier.")
+    phylogeny.add_argument("--metadata-id-column", default="identifier")
+    phylogeny.add_argument("--group-key", default="group", help="Metadata field used to color tips.")
+    phylogeny.add_argument("--date-key", help="Metadata field containing decimal sampling years.")
+    phylogeny.add_argument("--temporal", action="store_true", help="Run deterministic temporal diagnostics.")
+    phylogeny.add_argument("--output", "-o", default="codonadaptpy_phylogeny")
+    phylogeny.add_argument("--tree-method", choices=("iqtree", "fasttree"), default="iqtree")
+    phylogeny.add_argument("--align-method", choices=("auto", "linsi", "einsi", "fftnsi", "fftns"), default="auto")
+    phylogeny.add_argument("--model", default="MFP", help="IQ-TREE model or ModelFinder setting.")
+    phylogeny.add_argument("--bootstrap", type=int, default=1000)
+    phylogeny.add_argument("--threads", type=int, default=1)
+    phylogeny.add_argument("--no-trim", action="store_true", help="Skip trimAL alignment trimming.")
+    phylogeny.set_defaults(handler=_run_phylogeny)
+
+    optimize = subparsers.add_parser("optimize", help="Optimize or deoptimize a coding sequence.")
+    optimize.add_argument("input", help="Input FASTA path or pasted coding sequence.")
+    optimize.add_argument("--reference", required=True, help="Reference profile JSON/CSV/TSV.")
+    optimize.add_argument("--output", "-o", default="codonadaptpy_optimization", help="Output directory.")
+    optimize.add_argument("--direction", choices=("optimize", "deoptimize", "match"), default="optimize")
+    optimize.add_argument("--candidates", type=int, default=5)
+    optimize.add_argument("--iterations", type=int, default=5000)
+    optimize.add_argument("--seed", type=int, default=1)
+    optimize.add_argument("--genetic-code", type=int, default=1)
+    optimize.add_argument("--target-gc", type=float)
+    optimize.add_argument("--gc-tolerance", type=float, default=0.05)
+    optimize.add_argument("--avoid-motif", action="append", default=[])
+    optimize.add_argument("--preserve-motif", action="append", default=[])
+    optimize.add_argument("--remove-site", action="append", default=[])
+    optimize.add_argument("--add-site", action="append", default=[])
+    optimize.add_argument("--max-homopolymer", type=int, default=6)
+    optimize.add_argument("--target-cpg", type=float)
+    optimize.add_argument("--target-upa", type=float)
+    optimize.set_defaults(handler=_run_optimize)
+
+    reference = subparsers.add_parser("reference", help="Build or inspect reference profiles.")
+    reference_sub = reference.add_subparsers(dest="reference_command", required=True)
+    reference_list = reference_sub.add_parser("list", help="List bundled profiles.")
+    reference_list.set_defaults(handler=_run_reference_list)
+    reference_build = reference_sub.add_parser("build", help="Build a profile from a CDS file.")
+    reference_build.add_argument("input")
+    reference_build.add_argument("--name", required=True)
+    reference_build.add_argument("--output", "-o", required=True)
+    reference_build.add_argument("--source", default="user CDS set")
+    reference_build.add_argument("--reference-version", default="1")
+    reference_build.add_argument("--genetic-code", type=int, default=1)
+    reference_build.set_defaults(handler=_run_reference_build)
+    reference_show = reference_sub.add_parser("show", help="Validate and print a profile.")
+    reference_show.add_argument("input")
+    reference_show.set_defaults(handler=_run_reference_show)
+    return parser
+
+
+def _add_analysis_arguments(parser: argparse.ArgumentParser) -> None:
+    """Attach shared sequence-analysis options to a subcommand parser."""
+
+    parser.add_argument("input", help="FASTA, GenBank, CSV/TSV, ZIP, or pasted sequence.")
+    parser.add_argument("--format", choices=("fasta", "genbank", "csv", "tsv", "zip"))
+    parser.add_argument("--metadata", help="CSV/TSV metadata joined to sequence identifiers.")
+    parser.add_argument("--metadata-id-column", default="identifier")
+    parser.add_argument("--aggregate-by", help="Metadata field identifying isolates for genome-wide CDS pooling.")
+    parser.add_argument("--gene-key", default="gene", help="Metadata field containing gene names.")
+    parser.add_argument(
+        "--focus-gene",
+        action="append",
+        default=[],
+        help="Gene to report separately during aggregation; repeat as needed.",
+    )
+    parser.add_argument("--reference", help="Target reference profile JSON/CSV/TSV.")
+    parser.add_argument(
+        "--host", action="append", default=[], help="Host reference profile; repeat for multiple hosts."
+    )
+    parser.add_argument("--output", "-o", default="codonadaptpy_results", help="Output directory.")
+    parser.add_argument("--formats", default="json,csv,html", help="Comma-separated json,csv,tsv,xlsx,html,pdf.")
+    parser.add_argument("--plots", action="store_true", help="Write RSCU, ENC-GC3, and CAI plots as HTML.")
+    parser.add_argument("--genetic-code", type=int, default=1)
+    parser.add_argument("--frame", type=int, choices=(0, 1, 2), default=0)
+    parser.add_argument("--partial", action="store_true")
+    parser.add_argument("--no-require-start", action="store_true")
+    parser.add_argument("--no-require-stop", action="store_true")
+    parser.add_argument("--ambiguous", choices=("reject", "skip", "allow"), default="reject")
+    parser.add_argument("--window", type=int, default=30)
+    parser.add_argument("--step", type=int, default=1)
+    parser.add_argument("--simulate-cai", type=int, default=0)
+    parser.add_argument("--seed", type=int, default=1)
+    parser.add_argument(
+        "--lenient", action="store_true", help="Return invalid reports instead of stopping at validation errors."
+    )
+
+
+def _run_phylogeny(args: argparse.Namespace) -> int:
+    """Run alignment, ML inference, ETE3 plotting, and optional temporal analysis."""
+
+    parser = SequenceParser()
+    records = parser.parse(args.input, fmt=args.format)
+    if args.metadata:
+        records = parser.attach_metadata(records, args.metadata, identifier_column=args.metadata_id_column)
+    output = Path(args.output)
+    run = PhylogeneticAnalyzer().run(
+        records,
+        output / "inference",
+        name="phylogeny",
+        align_method=args.align_method,
+        tree_method=args.tree_method,
+        trim=not args.no_trim,
+        trim_required=not args.no_trim,
+        model=args.model,
+        bootstrap=args.bootstrap,
+        threads=args.threads,
+    )
+    groups = {record.identifier: str(record.metadata.get(args.group_key, "Unknown")) for record in records}
+    plotter = ETE3TreePlotter()
+    figures = output / "figures"
+    tree_figure = plotter.tree(run.tree, groups=groups, title="Maximum-likelihood phylogeny")
+    for suffix in ("png", "pdf"):
+        plotter.save(tree_figure, figures / f"phylogeny.{suffix}", dpi=600)
+    report: dict[str, object] = {"phylogeny": run.to_dict()}
+    if args.temporal:
+        if not args.date_key:
+            raise ValueError("--date-key is required with --temporal.")
+        dates: dict[str, float] = {}
+        for record in records:
+            try:
+                dates[record.identifier] = float(record.metadata[args.date_key])
+            except (KeyError, TypeError, ValueError):
+                continue
+        temporal = TemporalAnalyzer()
+        signal = temporal.temporal_signal(run.tree, dates, optimize_root=True)
+        dated_tree = temporal.date_tree(run.tree, signal)
+        time_figure = plotter.tree(
+            dated_tree,
+            groups=groups,
+            title="Exploratory strict-clock time tree",
+            time_scaled=True,
+        )
+        signal_figure = plotter.temporal_signal(signal, groups=groups)
+        trajectory_figure = plotter.lineage_through_time(
+            {"All samples": temporal.lineage_through_time(dated_tree)}
+        )
+        for stem, figure in (
+            ("time_tree", time_figure),
+            ("temporal_signal", signal_figure),
+            ("lineage_through_time", trajectory_figure),
+        ):
+            for suffix in ("png", "pdf"):
+                plotter.save(figure, figures / f"{stem}.{suffix}", dpi=600)
+        dated_tree.write(
+            format=1,
+            features=["calendar_date", "observed_date", "fitted_date"],
+            outfile=str(output / "inference" / "phylogeny.dated.nwk"),
+        )
+        report["temporal_signal"] = signal.to_dict()
+        report["temporal_warning"] = (
+            "Root-to-tip strict-clock and LTT outputs are exploratory, deterministic estimates."
+        )
+    output.mkdir(parents=True, exist_ok=True)
+    (output / "phylogeny.json").write_text(json.dumps(report, indent=2), encoding="utf-8")
+    print(f"Phylogenetic analysis complete; results: {output}")
+    return 0
+
+
+def _run_analyze(args: argparse.Namespace) -> int:
+    """Execute analysis or multi-host comparison and write selected outputs."""
+
+    validation = ValidationConfig(
+        reading_frame=args.frame,
+        genetic_code=args.genetic_code,
+        require_start=not args.no_require_start,
+        require_stop=not args.no_require_stop,
+        ambiguous_policy=args.ambiguous,
+        allow_partial=args.partial,
+    )
+    config = AnalysisConfig(validation, args.window, args.step, args.simulate_cai, args.seed, not args.lenient)
+    analyzer = analyzer_from_reference_files(args.reference, args.host, config=config)
+    parser = SequenceParser()
+    records = parser.parse(args.input, fmt=args.format)
+    if args.metadata:
+        records = parser.attach_metadata(records, args.metadata, identifier_column=args.metadata_id_column)
+    output = Path(args.output)
+    output.mkdir(parents=True, exist_ok=True)
+    reporter = ReportGenerator()
+    formats = {item.strip().lower() for item in args.formats.split(",") if item.strip()}
+    supported = {"json", "csv", "tsv", "xlsx", "html", "pdf"}
+    unknown = formats - supported
+    if unknown:
+        raise ValueError(f"Unsupported output formats: {', '.join(sorted(unknown))}")
+
+    if args.aggregate_by:
+        isolate_results = CDSAggregator(analyzer).analyze(
+            records,
+            isolate_key=args.aggregate_by,
+            gene_key=args.gene_key,
+            focus_genes=tuple(args.focus_gene),
+        )
+        genome_results = [result.genome_result for result in isolate_results]
+        gene_results = [gene_result for result in isolate_results for gene_result in result.gene_results]
+        _write_result_set(reporter, genome_results, output / "genome_wide", formats)
+        _write_result_set(reporter, gene_results, output / "per_gene", formats)
+        for focus_gene in args.focus_gene:
+            focused = [
+                gene_result for result in isolate_results for gene_result in result.focus_gene_results[focus_gene]
+            ]
+            safe_name = "".join(
+                character if character.isalnum() or character in "-_" else "_" for character in focus_gene
+            )
+            _write_result_set(reporter, focused, output / f"focus_{safe_name}", formats)
+        (output / "aggregation.json").write_text(
+            json.dumps([result.to_dict() for result in isolate_results], indent=2, sort_keys=True) + "\n",
+            encoding="utf-8",
+        )
+        results = genome_results
+        analyzed_message = f"Aggregated {len(gene_results)} CDS(s) across {len(genome_results)} isolate(s)"
+    else:
+        if args.focus_gene:
+            raise ValueError("--focus-gene requires --aggregate-by.")
+        results = analyzer.analyze_many(records)
+        _write_result_set(reporter, results, output, formats)
+        analyzed_message = f"Analyzed {len(results)} sequence(s)"
+
+    if args.plots:
+        _write_plots(results, output / ("genome_wide" if args.aggregate_by else ""))
+    (output / "command.txt").write_text(" ".join(shlex.quote(item) for item in sys.argv) + "\n", encoding="utf-8")
+    (output / "config.json").write_text(json.dumps(asdict(config), indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    print(f"{analyzed_message}; results: {output}")
+    return 0
+
+
+def _write_result_set(
+    reporter: ReportGenerator,
+    results: list[AnalysisResult],
+    output: Path,
+    formats: set[str],
+) -> None:
+    """Write one consistently named result set in selected formats."""
+
+    output.mkdir(parents=True, exist_ok=True)
+    writers = {
+        "json": lambda: reporter.write_json(results, output / "analysis.json"),
+        "csv": lambda: reporter.write_table(results, output / "summary.csv"),
+        "tsv": lambda: reporter.write_table(results, output / "summary.tsv"),
+        "xlsx": lambda: reporter.write_excel(results, output / "analysis.xlsx"),
+        "html": lambda: reporter.write_html(results, output / "report.html"),
+        "pdf": lambda: reporter.write_pdf(results, output / "report.pdf"),
+    }
+    for output_format in sorted(formats):
+        writers[output_format]()
+
+
+def _write_plots(results: list[AnalysisResult], output: Path) -> None:
+    """Write the standard interactive plot collection for a result set."""
+
+    output.mkdir(parents=True, exist_ok=True)
+    plotter = PlotManager()
+    plotter.save(plotter.rscu_heatmap(results), output / "rscu_heatmap.html")
+    plotter.save(plotter.enc_gc3(results), output / "enc_gc3.html")
+    plotter.save(plotter.neutrality(results), output / "neutrality.html")
+    plotter.save(plotter.parity_rule_2(results), output / "parity_rule_2.html")
+    for result in results:
+        if result.sliding_windows.get("cai"):
+            plotter.save(plotter.sliding_cai(result), output / f"{result.identifier}_sliding_cai.html")
+
+
+def _run_optimize(args: argparse.Namespace) -> int:
+    """Execute constrained synonymous design for one input record."""
+
+    manager = ReferenceManager()
+    profile = manager.load(args.reference)
+    records = SequenceParser().parse(args.input)
+    if len(records) != 1:
+        raise ValueError("Optimization accepts exactly one sequence per invocation.")
+    config = OptimizationConfig(
+        direction=args.direction,
+        candidates=args.candidates,
+        iterations=args.iterations,
+        seed=args.seed,
+        target_gc=args.target_gc,
+        gc_tolerance=args.gc_tolerance,
+        avoid_motifs=tuple(args.avoid_motif),
+        preserve_motifs=tuple(args.preserve_motif),
+        remove_restriction_sites=tuple(args.remove_site),
+        add_restriction_sites=tuple(args.add_site),
+        max_homopolymer=args.max_homopolymer,
+        target_cpg=args.target_cpg,
+        target_upa=args.target_upa,
+    )
+    result = CodonOptimizer(profile.counts, genetic_code=args.genetic_code).optimize(records[0].sequence, config)
+    output = Path(args.output)
+    output.mkdir(parents=True, exist_ok=True)
+    (output / "optimization.json").write_text(
+        json.dumps(result.to_dict(), indent=2, sort_keys=True) + "\n", encoding="utf-8"
+    )
+    ReportGenerator().write_optimized_fasta(result, output / "optimized.fasta")
+    (output / "command.txt").write_text(" ".join(shlex.quote(item) for item in sys.argv) + "\n", encoding="utf-8")
+    print(f"Generated {len(result.candidates)} candidate(s); results: {output}")
+    return 0
+
+
+def _run_reference_list(args: argparse.Namespace) -> int:
+    """Print the bundled reference catalog."""
+
+    print(json.dumps(ReferenceManager().list(), indent=2))
+    return 0
+
+
+def _run_reference_build(args: argparse.Namespace) -> int:
+    """Build and persist a profile from validated CDS input."""
+
+    manager = ReferenceManager()
+    records = SequenceParser().parse(args.input)
+    profile = manager.from_sequences(
+        args.name, records, genetic_code=args.genetic_code, version=args.reference_version, source=args.source
+    )
+    manager.save(profile.name, args.output)
+    print(f"Built reference {profile.name!r} from {len(records)} sequence(s): {args.output}")
+    return 0
+
+
+def _run_reference_show(args: argparse.Namespace) -> int:
+    """Validate and display a reference profile."""
+
+    manager = ReferenceManager()
+    profile = manager.load(args.input)
+    print(json.dumps(profile.to_dict(), indent=2, sort_keys=True))
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run the CLI and convert anticipated errors to concise status messages."""
+
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        return int(args.handler(args))
+    except (CodonAdaptPyError, OSError, ValueError) as exc:
+        parser.exit(2, f"codonadaptpy: error: {exc}\n")
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())