PlantAI-dev/docs/msa_plot_revision_experience_2026-05-25.md

MSA Plot Revision Experience

Date: 2026-05-25

This note summarizes the MSA plot revision work so the same pattern can be reused by other image-producing stages.

Goal

The target interaction is:

1. User opens a generated result image.
2. User clicks 修订.
3. The system infers the source artifact from the current image context.
4. The dialog shows sensible defaults and editable parameters.
5. User submits and the backend redraws a new figure with traceable outputs.

For MSA plots, this means the selected image should identify the correct aligned FASTA, recommend a useful region, allow manual override, and regenerate a local MSA figure.

Coordinate Rules

MSA region plotting must distinguish two coordinate systems.

Alignment column coordinates:

alignment_col = 1, 2, 3, ...

These include gap columns. This is the coordinate system used to slice all sequences.

Reference-sequence residue coordinates:

residue_index(seq, col) = count(seq[1:col] != "-" and seq[1:col] != ".")

To convert a reference residue number to an alignment column:

alignment_col_for_residue(seq, k) =
  first col where residue_index(seq, col) == k

Different genes show different residue numbers in the same alignment block because their gap patterns differ. Therefore, a residue range such as 150-197 is only meaningful together with a reference sequence ID.

Implemented MSA Modes

The MSA revision dialog supports three modes.

alignment列: User enters 1-based inclusive alignment columns. This is the most direct mode and includes gap columns.

参考基因编号: User chooses or types a reference gene ID, then enters nongap residue numbers for that reference sequence. The backend converts the residue range to alignment columns and slices all sequences using those columns.

自动保守窗口: The backend calculates a conserved window from the source MSA and redraws that region.

Conserved Region Scoring

For each alignment column:

nongap_frac(col) = non_gap_count / sequence_count
identity(col) = max_residue_count / non_gap_count
score(col) = identity(col) * nongap_frac(col)

For each sliding window:

window_score = mean(score)
window_nongap = mean(nongap_frac)

The selected window is:

window_nongap >= min_nongap
and highest window_score

Default parameters currently used:

window_len = 60
min_nongap = 0.6

The recommendation API returns:

start_col
end_col
mean_score
mean_nongap
alignment_length
sequence_count
source msa_file

Naming Rules

Use distinct names for different sources of region plots.

Full MSA plot:

{prefix}.msa_plot-XX.png
{prefix}.msa_plot_msa.pdf

Manual or reference-sequence revision:

{prefix}.msa_region_{START}_{END}_msa.png
{prefix}.msa_region_{START}_{END}.manifest.json

Automatically selected conserved region:

{prefix}.msa_conserved_region_{START}_{END}_msa.png
{prefix}.msa_conserved_region_{START}_{END}.manifest.json

Do not use msa_region for automatic default conserved plots. Keeping msa_conserved_region separate makes the frontend grouping and provenance clear.

Frontend Pattern

The image preview action should preserve image context:

selected image path
selected image file name
inferred prefix
stage name

For MSA images, prefix inference handles:

{prefix}.msa_plot-05.png
{prefix}.msa_region_150_197_msa.png
{prefix}.msa_conserved_region_330_389_msa.png
{prefix}.pep.msa.fa

When the user clicks 修订:

1. Set stage to msa_region_plot.
2. Set msaSourceImage to the selected image URL.
3. Resolve msaFile from image or manifest.
4. Load sequence IDs for the reference-gene dropdown.
5. Load conserved-region recommendation.
6. Fill the recommended alignment columns by default.
7. Keep all fields editable.

The reference gene control should be a searchable, creatable select:

few genes: direct selection
many genes: type to filter
missing option: allow full ID input

Backend Pattern

The backend should not rely only on prefix. It should resolve the source input from the most specific context available:

1. Explicit msaFile.
2. Current msaSourceImage.
3. Stage manifest artifact.
4. Fallback final/{prefix}.pep.msa.fa.

For image-derived MSA resolution, support names such as:

{prefix}.msa_plot-05.png
{prefix}.msa_region_150_197_msa.png
{prefix}.msa_conserved_region_330_389_msa.png

This prevents stale prefixes such as At from causing the backend to look for the wrong file.

Result Display Pattern

Keep original images and derived images separate.

For MSA:

2.1 MSA Alignment Pages
  full MSA images
  自动保守区 MSA 图

2.2 MSA区间绘图
  user-triggered revised region plots

The frontend result payload should expose a structured subgroup rather than relying only on filename sorting:

{
  "phylogeny_msa": {
    "images": [],
    "files": [],
    "msa_groups": {
      "conserved": []
    }
  }
}

This same pattern can be reused by other stages:

stage.images              original/default images
stage.files               ordinary artifacts
stage.revision_groups.X   derived or recommended redraws

Manifest Requirements

Every redraw must write a manifest recording:

stage
status
prefix
source_msa
selection_mode
start_col_1based
end_col_1based_inclusive
region_length
mean_score
mean_nongap
output_files

For reference-sequence mode, also record:

reference_id
reference_start_residue
reference_end_residue

For automatic mode, also record:

window_len
min_nongap

Validation Checklist

For future image revision features, validate layer by layer.

1. CLI:

   • Run the stage on a real artifact.
   • Confirm output image exists.
   • Confirm manifest records the source input and parameters.

2. Backend:

   • Submit through /api/execute.
   • Confirm task status is success.
   • Confirm logs show the correct input file, not a stale prefix.

3. Recommendation API:

   • Call the recommendation endpoint with a selected image.
   • Confirm it resolves the correct source file.
   • Confirm returned parameters match the expected algorithm.

4. Frontend:

   • Hard refresh after service restart.
   • Open an image, click 修订.
   • Confirm dialog shows source image, source file, recommendation, and editable controls.
   • Submit and confirm the new image appears in the correct result group.

Lessons For Other Stages

Do not make a revision dialog depend only on global stage parameters. The selected image is part of the execution context.

Prefer this flow:

selected image -> infer source artifact -> recommend parameters -> allow edits -> rerun -> grouped output

Keep default generated figures, automatic recommendations, and user revisions as separate artifact classes. This makes provenance clearer and prevents users from mistaking a hand-picked or automatically selected region for the full result.