FAQ

FAQ

"index already exists" — what do I do?

This is informational, not an error. prot2exon fetch caches indexes under ~/.cache/prot2exon/; on the second invocation it just prints using cached index: /path/to/yeast.idx (--force to rebuild) and prints the path. Pass --force if you actually want to rebuild from the upstream GTF.

My TSV row has cds_length_mismatch = true — bug?

Usually not. It flags cases where the sum of CDS lengths isn't a clean multiple of 3, which happens legitimately for:

• Selenoproteins (Sec) — UGA stop codon read through as selenocysteine.
• Programmed readthrough / stop-codon recoding.
• Incomplete CDS — transcripts annotated as cds_start_NF, cds_end_NF, or mRNA_end_NF.

cds_nt_remainder (1 or 2) tells you which side. The mapping is still emitted; you just lose codon-precision at the affected end.

A query has reason = no_CDS_for_protein — what's going on?

You probably passed a transcript ID for a non-coding transcript (lncRNA, processed transcript, …). There's no CDS to map onto, so the row goes to unmapped_domains.tsv. The summary's input_id_type column distinguishes ENSP / ENST queries.

How does prot2exon handle codons split across an exon boundary?

Codons that straddle two CDS exons (1+2 or 2+1 patterns) are handled correctly — the mapper tracks cds_nt_start / cds_nt_end across the exon boundary so aa coordinates round-trip cleanly. CDS exons are split only when the domain partially covers them, never on the codon boundary.

MANE Select and Ensembl canonical — where are they?

is_mane_select and is_ensembl_canonical columns are present on every TSV. They're booleans (true / false) parsed from GENCODE/Ensembl tag annotations. RefSeq GTFs don't carry MANE Select tags, so both columns are NA there.

The plot looks empty / I see no UTRs

Two common causes:

• You loaded domain_cds_segments.tsv instead of isoform_structure.tsv. The CDS table doesn't include UTR rows by design — only the full isoform table does.
• You passed --no-utr to the plotter, or unchecked Show UTRs in the interactive viewer.

The viewer shows long stretches of empty intron — fix?

Use compact mode. CLI: --compact-genomic (matplotlib) or the Compact (introns = 80 bp) radio in the interactive viewer. Long human genes (TP53 spans ~19 kb) become legible at exon resolution.

My --html plotly file is huge

That's expected — plotly bundles its full JS engine in every standalone HTML (~3 MB). If size matters, use --html-interactive instead — the interactive viewer is ~35 KB and has no JS dependency.

Can I run prot2exon on Windows?

The Python wrapper works on Windows. The C++ binary should build cleanly under MSVC 2019+ or MinGW, but is mainly tested on Linux. WSL is the path of least friction.

How do I cite prot2exon?

A formal citation will land when the accompanying manuscript is posted. Until then, please cite the repository URL.

Where do I report a bug?

Open an issue on the GitHub repo. A minimal reproducer (the GTF lines or BED row that triggers it, plus the exact CLI you ran) makes triage 10× faster.

I want to contribute — where do I start?

• Bug fixes — open a PR with a regression test in tests/run_tests.py.
• New plot styles — both matplotlib (plot.py) and the JS viewer (_interactive_html.py) are templated; copy an existing draw function and add a CLI flag.
• New input adapters — scripts/prepare_from_*.py is the conventional spot for "turn external format X into prot2exon BED".
• New genome onboarding presets — extend _resolve_url in python/prot2exon/fetch.py.