Research: when/why is ins_code needed for residue identity?

[coderabbitai]

Summary

atomarray_to_gemmi in src/sampleworks/eval/synthetic_utils.py (and residue-identity logic elsewhere in the repo) keys residues on (chain_id, res_id) or (chain_id, res_id, atom_name), without incorporating ins_code. Biotite AtomArray objects do expose an ins_code annotation, and CIF inputs can carry _atom_site.pdbx_PDB_ins_code, so residues that share a res_id but differ by insertion code could currently be merged/misidentified.

Separately, WaterFlow code keys residue identity on (chain_id, res_id, ins_code), which is inconsistent with the convention used in this repo.

Why this needs research first

Before deciding whether to change the repo-wide convention (or leave it as-is), we need to understand:

• How often, and in what real-world structures/datasets, ins_code is actually populated (non-blank) in inputs processed by this codebase.
• Whether any current pipelines (synthetic SF/density generation, reward functions, structure loading utilities) could produce silently incorrect results due to ignoring ins_code.
• Why WaterFlow chose to include ins_code in its identity key, and whether that reflects a real correctness requirement or just defensive coding.

Affected areas

• src/sampleworks/eval/synthetic_utils.py (atomarray_to_gemmi)
• src/sampleworks/utils/atom_array_utils.py (residue/atom identity helpers)
• Any other residue-identity keying in the repo that currently omits ins_code

Acceptance criteria

• Document findings on when/why ins_code is populated and relevant in practice (e.g., which structures/datasets), and whether it's already handled by upstream loading/filtering steps.
• Decide whether to adopt (chain_id, res_id, ins_code) repo-wide, keep the current convention, or handle it case-by-case.
• If a change is warranted, list the specific functions/files to update.

References

• PR: feat(rewards): add reciprocal-space reward (Fprotein from SFC) #272
• Discussion: feat(rewards): add reciprocal-space reward (Fprotein from SFC) #272 (comment)
• Requested by: @marcuscollins