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:

```text
alignment_col = 1, 2, 3, ...
```

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

Reference-sequence residue coordinates:

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

To convert a reference residue number to an alignment column:

```text
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:

```text
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:

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

The selected window is:

```text
window_nongap >= min_nongap
and highest window_score
```

Default parameters currently used:

```text
window_len = 60
min_nongap = 0.6
```

The recommendation API returns:

```text
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:

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

Manual or reference-sequence revision:

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

Automatically selected conserved region:

```text
{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:

```text
selected image path
selected image file name
inferred prefix
stage name
```

For MSA images, prefix inference handles:

```text
{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:

```text
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:

```text
{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:

```text
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:

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

This same pattern can be reused by other stages:

```text
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:

```text
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:

```text
reference_id
reference_start_residue
reference_end_residue
```

For automatic mode, also record:

```text
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:

```text
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.