# SPDX-License-Identifier: Apache-2.0 # Copyright 2026 Scienting # # Source Code: https://git.scient.ing/papers/paperspec # See the LICENSE.md file for full license terms. """Biological sequences tied to words: identities and rules (paperspec.sequences).""" import copy import hashlib import pytest from hypothesis import given, settings, strategies as st from conftest import read_jsonl, vector_cases from helpers_lib2 import PROPS, RECORDS, accepted_by_schema, rule_chapters from paperspec import sequences CASES = vector_cases("sequences") IDENTITIES = [c for c in CASES if c["op"] == "identity"] PROBLEMS = [c for c in CASES if c["op"] == "problems"] RULES = ( "layer.sequence.value", "layer.sequence.identity", "layer.sequence.region", "layer.sequence.variant", ) BIOLOGY = read_jsonl(RECORDS / "biology" / "annotations.jsonl") PEPTIDE = next(c for c in PROBLEMS if c["id"] == "valid-regions")["annotation"] VALUE = PEPTIDE["body"]["value"] def edited(annotation, **body): """A copy of `annotation` whose body has the given fields replaced; None removes a field.""" out = copy.deepcopy(annotation) for key, value in body.items(): if value is None: out["body"].pop(key, None) else: out["body"][key] = value return out def with_value(value, alphabet="protein", **body): """The peptide annotation over `value`, with its identity made to match.""" return edited( PEPTIDE, value=value, alphabet=alphabet, identity=sequences.identity(alphabet, value), regions=None, **body, ) def messages(annotation): """The (rule, message) pairs `problems` reports for `annotation`.""" return [(x["rule"], x["message"]) for x in sequences.problems(annotation)] # --- identities ----------------------------------------------------------------------------------------------- @pytest.mark.parametrize("case", IDENTITIES, ids=lambda c: c["id"]) def test_identity_vectors(case): assert sequences.identity(case["alphabet"], case["text"]) == case["expect"] def test_the_identity_is_the_alphabet_and_sixteen_hex_digits_of_the_residues_hash(): digest = hashlib.sha256(b"MKV").hexdigest()[:16] assert sequences.identity("protein", "MKV") == "protein:" + digest assert sequences.identity("dna", "MKV") == "dna:" + digest def test_residues_drop_the_gaps_and_nothing_else(): assert sequences.residues("AC-GT--") == "ACGT" assert sequences.residues("---") == "" assert sequences.residues("ac*") == "ac*" @given(st.text(alphabet="ACDEFGHIKLMNPQRSTVWY", min_size=1, max_size=40), st.data()) @PROPS def test_gaps_change_the_numbering_of_nothing_and_the_identity_of_nothing( residues, data ): positions = data.draw(st.lists(st.integers(0, len(residues)), max_size=6)) gapped = residues for p in sorted(positions, reverse=True): gapped = gapped[:p] + "-" + gapped[p:] assert sequences.residues(gapped) == residues assert sequences.identity("protein", gapped) == sequences.identity( "protein", residues ) def test_the_alphabets_allow_the_letters_the_chapter_lists(): protein, dna, rna = (sequences.ALPHABETS[a] for a in ("protein", "dna", "rna")) assert set("ACDEFGHIKLMNPQRSTVWY") <= protein assert set("UO*-BXZJ") <= protein assert "U" not in dna assert "T" not in rna assert {"U", "*"}.isdisjoint(dna) assert all("-" in letters for letters in (protein, dna, rna)) assert set("RYKMSWBDHVN") <= dna & rna # --- rules ----------------------------------------------------------------------------------------------------- @pytest.mark.parametrize("rule", RULES) def test_the_rules_are_registered_in_the_layers_chapter(rule): assert rule_chapters()[rule] == "spec/18-layers.md" @pytest.mark.parametrize("case", PROBLEMS, ids=lambda c: c["id"]) def test_problems_vectors(case): got = sequences.problems(case["annotation"]) assert got == case["expect"] assert accepted_by_schema(case["annotation"]) is case["schema"] assert {x["rule"] for x in got} <= set(rule_chapters()) @pytest.mark.parametrize("case", PROBLEMS, ids=lambda c: c["id"]) def test_a_vector_is_named_for_the_rule_it_breaks(case): stem = case["id"].split("-", 1)[0] rules = {x["rule"] for x in case["expect"]} if stem == "valid": assert rules == set() else: assert "layer.sequence." + stem in rules def test_every_rule_is_broken_by_some_vector(): assert {x["rule"] for c in PROBLEMS for x in c["expect"]} == set(RULES) @pytest.mark.parametrize("annotation", BIOLOGY, ids=lambda a: a["body"]["role"]) def test_the_biology_layer_breaks_no_rule(annotation): assert annotation["body"]["kind"] == "sequence" assert sequences.problems(annotation) == [] @pytest.mark.parametrize( "body", [{"kind": "comment"}, {}], ids=["other-kind", "no-kind"] ) def test_an_annotation_of_another_kind_is_refused(body): with pytest.raises(ValueError, match="not a sequence annotation"): sequences.problems({"body": body}) @pytest.mark.parametrize("alphabet", [None, "peptide", "DNA"]) def test_an_unknown_alphabet_is_the_only_problem_reported(alphabet): annotation = edited(PEPTIDE, alphabet=alphabet, identity="whatever") assert [r for r, _ in messages(annotation)] == ["layer.sequence.value"] assert "dna, protein, rna" in messages(annotation)[0][1] def test_letters_the_alphabet_lacks_are_listed_once_each_in_order(): got = messages(with_value("EkZk*-?", "dna")) assert got == [ ("layer.sequence.value", "'*', '?', 'E', 'Z', 'k' is not a dna residue") ] def test_a_value_of_gaps_only_has_no_residue(): got = messages(with_value("---")) assert got == [("layer.sequence.value", "the value has no residue, only gaps")] def test_an_empty_value_has_no_residue_and_hashes_the_empty_string(): assert messages(with_value("")) == [ ("layer.sequence.value", "the value has no residue, only gaps") ] def test_a_wrong_identity_is_replaced_by_the_right_one_in_the_message(): got = messages(edited(PEPTIDE, identity="protein:0000000000000000")) assert got == [ ( "layer.sequence.identity", "the identity is not " + sequences.identity("protein", VALUE), ) ] def test_a_missing_identity_breaks_the_identity_rule(): assert [r for r, _ in messages(edited(PEPTIDE, identity=None))] == [ "layer.sequence.identity" ] @pytest.mark.parametrize( ("region", "first_message"), [ ({"start": 50, "end": 49}, "region 0 starts at 50, after its end 49"), ({"start": 41, "end": 50}, "region 0, 41-50, is outside the residues 42-76"), ({"start": 50, "end": 77}, "region 0, 50-77, is outside the residues 42-76"), ({"end": 50}, "region 0, 0-50, is outside the residues 42-76"), ({"start": 50}, "region 0 starts at 50, after its end 0"), ({}, "region 0, 0-0, is outside the residues 42-76"), ], ids=["reversed", "before-first", "after-last", "no-start", "no-end", "empty"], ) def test_regions_must_lie_within_the_residues(region, first_message): got = messages(edited(PEPTIDE, regions=[region])) assert got == [("layer.sequence.region", first_message)] @pytest.mark.parametrize( "region", [{"start": 42, "end": 42}, {"start": 76, "end": 76}, {"start": 42, "end": 76}], ) def test_regions_may_touch_either_end_or_one_residue(region): assert sequences.problems(edited(PEPTIDE, regions=[region])) == [] def test_each_region_is_judged_and_numbered_on_its_own(): regions = [ {"start": 44, "end": 51}, {"start": 90, "end": 91}, {"start": 60, "end": 55}, ] got = messages(edited(PEPTIDE, regions=regions)) assert [r for r, _ in got] == ["layer.sequence.region"] * 2 assert got[0][1].startswith("region 1, 90-91") assert got[1][1].startswith("region 2 starts at 60") def test_a_sequence_without_a_start_is_numbered_from_one(): annotation = edited(PEPTIDE, start=None, regions=[{"start": 1, "end": 35}]) assert sequences.problems(annotation) == [] outside = edited(PEPTIDE, start=None, regions=[{"start": 1, "end": 36}]) assert messages(outside)[0][1] == "region 0, 1-36, is outside the residues 1-35" def test_gaps_are_not_numbered(): value = "LSDED-FKAVFGMTRSAFANLPLWKQQNLKKEKGLF" annotation = with_value(value, variants=[{"position": 47, "ref": "F", "alt": "A"}]) assert sequences.problems(annotation) == [] shifted = with_value(value, variants=[{"position": 48, "ref": "F", "alt": "A"}]) assert messages(shifted) == [ ( "layer.sequence.variant", "variant 0 says F is at 48, but the residue there is K", ) ] def test_a_variant_outside_the_residues_is_reported_with_its_numbers(): variant = {"position": 100, "ref": "L", "alt": "A"} got = messages(edited(PEPTIDE, variants=[variant])) assert got == [ ("layer.sequence.variant", "variant 0 is at 100, outside the residues 42-76") ] def test_a_variant_that_names_the_wrong_residue_says_what_is_there(): variant = {"position": 42, "ref": "A", "alt": "C"} got = messages(edited(PEPTIDE, variants=[variant])) assert got == [ ( "layer.sequence.variant", "variant 0 says A is at 42, but the residue there is L", ) ] def test_a_variant_to_the_same_residue_is_no_change(): variant = {"position": 42, "ref": "L", "alt": "L"} got = messages(edited(PEPTIDE, variants=[variant])) assert got == [("layer.sequence.variant", "variant 0 changes L at 42 to itself")] def test_a_variant_to_a_letter_the_alphabet_lacks_is_refused(): variant = {"position": 42, "ref": "L", "alt": "z"} got = messages(edited(PEPTIDE, variants=[variant])) assert got == [ ("layer.sequence.variant", "variant 0: 'z' is not a protein residue") ] def test_a_variant_may_delete_with_a_gap_or_stop_with_a_star(): variants = [ {"position": 42, "ref": "L", "alt": "-"}, {"position": 43, "ref": "S", "alt": "*"}, ] assert sequences.problems(edited(PEPTIDE, variants=variants)) == [] def test_a_variant_outside_the_residues_can_also_change_to_itself(): variant = {"position": 0, "ref": "L", "alt": "L"} got = messages(edited(PEPTIDE, variants=[variant])) assert [r for r, _ in got] == ["layer.sequence.variant"] * 2 def test_a_variant_without_fields_breaks_the_rule(): got = messages(edited(PEPTIDE, variants=[{}])) assert [r for r, _ in got] == ["layer.sequence.variant"] * 2 def test_each_variant_is_numbered_in_its_message(): variants = [ {"position": 42, "ref": "L", "alt": "A"}, {"position": 43, "ref": "X", "alt": "A"}, ] got = messages(edited(PEPTIDE, variants=variants)) assert [m.split(" ")[1] for _, m in got] == ["1"] @given( st.text(alphabet="ACDEFGHIKLMNPQRSTVWY", min_size=3, max_size=50), st.integers(1, 500), st.data(), ) @settings(PROPS, max_examples=60) def test_a_sequence_whose_regions_and_variants_agree_with_its_residues_breaks_no_rule( residues, start, data ): last = start + len(residues) - 1 region_start = data.draw(st.integers(start, last)) region_end = data.draw(st.integers(region_start, last)) position = data.draw(st.integers(start, last)) ref = residues[position - start] alt = data.draw(st.sampled_from(sorted(sequences.ALPHABETS["protein"] - {ref}))) annotation = edited( PEPTIDE, value=residues, start=start, identity=sequences.identity("protein", residues), regions=[{"start": region_start, "end": region_end}], variants=[{"position": position, "ref": ref, "alt": alt}], ) assert sequences.problems(annotation) == [] past = edited(annotation, regions=[{"start": region_start, "end": last + 1}]) assert [x["rule"] for x in sequences.problems(past)] == ["layer.sequence.region"] wrong = edited( annotation, variants=[{"position": position, "ref": alt, "alt": ref}] ) assert [x["rule"] for x in sequences.problems(wrong)] == ["layer.sequence.variant"]