# 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.