aprofiler 0.1.3

aProfiler: MSA Statistics & Visualization Toolkit

aProfiler

MSA Statistics & Visualization Toolkit

aProfiler examines Multiple Sequence Alignments (MSAs) and delivers useful statistics, publication-grade plots, codon-aware metrics (RSCU and essential amino acid summaries), embeddings, and CSV tables from a single command-line call.

---

Installation

pip install aprofiler

---

CLI Usage

aprofiler --input {alignment.fasta} --mode auto --report

CLI Help

aprofiler --help

usage: aprofiler [-h] --input INPUT [--mode {nt,aa,codon,auto}] [--no-plots]
                 [--report] [--report-format {md,html}] [--seed SEED]

aProfiler — MSA statistics & visualization.

options:
  -h, --help            show this help message and exit
  --input INPUT         Input MSA file (FASTA/A3M/ALN/etc.)
  --mode {nt,aa,codon,auto}
                        Sequence type mode (nt, aa, codon, or auto-detect).
  --no-plots            Disable plot generation (CSV only).
  --report              Generate a summary report (HTML by default).
  --report-format {md,html}
                        Report format if --report is set (default: html).
  --seed SEED           Random seed for any subsampling and UMAP embeddings.

Examples on test data

aprofiler --input .\data\test-TP53-nt.fasta
aprofiler --input .\data\test-TP53-nt.fasta --report
aprofiler --input .\data\test-TP53-nt.fasta --report --mode codon
aprofiler --input .\data\test-TP53-aa.fasta --report --report-format md
aprofiler --input .\data\test-TP53-aa.fasta --no-plots --mode aa

Modes

Mode	Description
nt	Nucleotide MSA (DNA/RNA, IUPAC tolerated)
aa	Amino acid MSA (protein residues)
codon	Coding sequence MSA analyzed at codon level (standard genetic code by default)
auto	Auto-detect between NT and AA (codon is never auto-selected and must be explicit)

Common Flags

Flag	Purpose
--input	Input MSA file (FASTA MSA, A3M, or fixed-column alignment)
--mode	nt, aa, codon, or auto
--report	Generate a summary report (.md or .html)
--report-format	md or html (default: html)
--no-plots	Skip plots, output CSV tables only
--seed	Set seed for PCA/UMAP reproducibility

---

Outputs (Saved Automatically)

All results are saved under:

./results/{alignment_name}/

CSV Tables

Output	File
Global NT or AA frequencies	*_global_freqs.csv
Per-site NT stats + entropy + GC%	*_nt_per_site.csv
PCA embeddings	*_pca_embedding.csv
UMAP embeddings	*_umap_embedding.csv
Codon usage table	*_codon_global.csv
Relative Synonymous Codon Usage (RSCU)	*_codon_rscu.csv
Amino acid usage derived from codons	*_aa_from_codons.csv
Essential vs non-essential AA summary (from codons)	*_aa_essential_summary.csv

Plots (On by default unless disabled)

Plot	Purpose
Nucleotide logo plot	Position-wise base enrichment
GC% per-site	GC landscape across MSA
Entropy per-site	Conservation skyline
AA/NT per-site heatmaps	Residue/base prevalence
PCA scatter	Sequence-space clustering
UMAP scatter	Similarity-space embedding
Pairwise identity histogram	Sequence similarity distribution
Gap fraction histogram	Alignment completeness QC
Codon usage barplot	Most frequent codons
RSCU heatmap	Synonymous codon bias by AA
Essential AA barplot	Essential vs non-essential AA trends (codon mode only)

---

Alignment Format Compatibility and Constraints

Input alignment type	Supported?	Notes
FASTA MSA	Yes	Sequences must be equal length
A3M	Yes	Lowercase letters denote inserted columns
ALN/Clustal	Yes	Must be in fixed columns or converted first
Codon FASTA	Yes	Requires explicit --mode codon
Mixed NT+AA alphabets	No	Alphabet must be uniform per file

All alignments are treated as fixed, rectangular matrices; sequences must have equal alignment length.

---

Output Guarantees

All profiling artifacts are written into results/ without overwriting unrelated files. Ambiguous input characters are tolerated but tracked, not silently discarded. Codon mode metrics are only computed when explicitly requested.

---

Example Output Directory Tree

results/
  TP53_alignment/
    TP53_global_freqs.csv             # Tables
    TP53_nt_per_site.csv
    TP53_pca_embedding.csv
    TP53_umap_embedding.csv
    TP53_report.html                  # Report in HTML format
    TP53_nt_logo.png                  # Plots
    TP53_entropy.png                 
    TP53_gc.png
    TP53_pca.png
    TP53_umap.png
    TP53_pairwise_identity.png
    TP53_gap_fraction.png
    TP53_rscu_heatmap.png
    TP53_aa_essential_bar.png

---

Scalability Notes

*Optimized for MSAs up to ~20k sequences × 10k columns on standard hardware. Larger inputs may require downsampling for logos/heatmaps

---

Testing

pip install pytest
pytest -q

Tests validate:

• equal-length enforcement
• stable fallback embedding behavior
• non-empty CSV outputs
• plot and artifact creation without crashes

---

Python API Example

from aprofiler.profiler import AlignmentProfiler

prof = AlignmentProfiler("alignment.fasta", mode="auto", out_dir="results")
prof.load_alignment()
outputs = prof.run_full_profile()
report_path = prof.generate_report(outputs, fmt="md")

print("Outputs generated:", outputs)
print("Report saved to:", report_path)

---

Citation

If you use aProfiler in a publication, please cite:

TBD

---

Contributing

Issues, discussions, and pull requests are welcome. Ensure contributions are:

• statistically useful
• plot-rich by design
• free of silent failures
• non-destructive to unrelated files
• aligned with package philosophy and constraints