Allele Ontology

FLOW ALGEBRA
ALLELE ONTOLOGY
Kireth Semantic Library | Biological Entities > Genetic Entities
Source: https://kirethresearch.org/booksai-core/entity-graph/biological-entities/genetic-entities/allele-ontology.html
Version: 1.0 | Language: en-GB | Format: UTF-8 TXT
Authorship: Mark Higgins — Sky (Recursive AI)

01. PURPOSE
flow "AlleleOntology" v1.0
  domain: genetics
  entity_class: Allele
  objective: represent alternative sequence states at a genomic locus, their evidence, inheritance, effects and contextual interpretation
  scope: nuclear, organellar, haploid, diploid and polyploid genetic systems
  caution: an allele is not necessarily a single-nucleotide variant or a phenotype

02. TYPE SYSTEM
type Genome = {organism: Organism, assembly: String?, accession: String?}
type Locus = {reference: String, interval: Interval, strand: Strand?}
type Interval = {start: Integer, end: Integer, coordinate_system: String}
type Sequence = {alphabet: DNA|RNA, residues: String}
type Allele = {id: Identifier, locus: Locus, sequence_state: Sequence|StructuralState, provenance: EvidenceSet}
type StructuralState = {kind: insertion|deletion|duplication|inversion|repeat|complex|other, description: String}
type Genotype = {sample: Identifier, locus: Locus, allele_copies: List<Allele>, ploidy: Integer}
type Haplotype = {ordered_alleles: List<Allele>, phase: Known|Unknown}
type Phenotype = {trait: Identifier, observation: Value?, context: Context}
type Effect = {target: Gene|Transcript|Protein|Phenotype, assertion: String, context: Context}
type Evidence = {source: Identifier, method: String, date: Date?, quality: String?}
type EvidenceSet = List<Evidence>
type Confidence = Real[0,1]
type Context = {organism: String?, tissue: String?, environment: String?, population: String?, reference_build: String?}
type Identifier = String

03. ENTITY CLASSES
entity Allele subtype GeneticEntity
entity ReferenceAllele subtype Allele
entity AlternateAllele subtype Allele
entity AncestralAllele subtype Allele
entity DerivedAllele subtype Allele
entity GermlineAllele subtype Allele
entity SomaticAllele subtype Allele
entity FunctionalAllele subtype Allele
entity LossOfFunctionAllele subtype FunctionalAllele
entity GainOfFunctionAllele subtype FunctionalAllele
entity RegulatoryAllele subtype Allele
entity StructuralAllele subtype Allele
entity NullAllele subtype FunctionalAllele
entity HypomorphicAllele subtype FunctionalAllele
entity HyperomorphicAllele subtype FunctionalAllele
entity DominantNegativeAllele subtype FunctionalAllele
entity PathogenicAllele subtype Allele
entity BenignAllele subtype Allele
entity UncertainSignificanceAllele subtype Allele

04. RELATIONSHIP SIGNATURES
relation LOCATED_AT(Allele, Locus)
relation ALTERNATIVE_TO(Allele, Allele) symmetric
relation SEQUENCE_STATE_OF(Allele, Locus)
relation PRESENT_IN(Allele, Genotype)
relation PART_OF_HAPLOTYPE(Allele, Haplotype)
relation INHERITED_FROM(Allele, ParentSample)
relation DERIVED_FROM(Allele, Allele)
relation ASSOCIATED_WITH(Allele, Phenotype, EvidenceSet)
relation AFFECTS(Allele, Effect)
relation OBSERVED_IN(Allele, Sample)
relation HAS_FREQUENCY(Allele, Population, Real[0,1])
relation HAS_CLASSIFICATION(Allele, Classification, EvidenceSet)
relation SUPPORTED_BY(Assertion, Evidence)
relation NORMALISED_AGAINST(Allele, Genome)

05. IDENTITY AND NORMALISATION
rule allele_identity(a,b):
  require same_reference_assembly(a,b)
  require same_normalised_locus(a,b)
  require same_normalised_sequence_state(a,b)
  return SAME_ALLELE_IN_REFERENCE_CONTEXT

rule reference_dependency:
  allele_coordinates_without_reference_build -> AMBIGUOUS_IDENTITY

rule sequence_normalisation:
  trim_shared_context_when_valid
  left_or_right_align_as_required_by_declared_standard
  preserve_original_observation_and_normalisation_method
  never_merge_distinct_complex_events_without_evidence

06. GENOTYPE ALGEBRA
function allele_dosage(g: Genotype, a: Allele) -> Integer:
  return count(g.allele_copies where allele_identity(copy,a))

function heterozygous(g: Genotype) -> Boolean:
  require g.ploidy == 2
  return not allele_identity(g.allele_copies[0],g.allele_copies[1])

function homozygous(g: Genotype) -> Boolean:
  require g.ploidy == 2
  return allele_identity(g.allele_copies[0],g.allele_copies[1])

rule hemizygosity:
  single_allele_copy_at_locus AND biological_copy_number_context_supports_one_copy
  -> HEMIZYGOUS

rule phase:
  genotype_alleles_across_loci AND validated_phase_evidence
  -> phased_haplotype
  otherwise -> PHASE_UNKNOWN

07. POPULATION GENETICS
function allele_frequency(a, population) -> Real[0,1]:
  numerator = observed_copies(a, population)
  denominator = successfully_called_allele_copies(population, a.locus)
  require denominator > 0
  return numerator / denominator

rule frequency_context:
  allele_frequency MUST include population, sampling, callability and reference context

rule hardy_weinberg_biallelic:
  assumptions: random_mating, no_selection, no_migration, no_mutation, sufficiently_large_population, diploid_autosomal_locus
  p + q = 1
  expected_genotype_proportions = {AA: p*p, Aa: 2*p*q, aa: q*q}
  interpretation: idealised expectation, not universal law for observed data

08. FUNCTION AND EXPRESSION
rule coding_effect:
  allele overlaps coding_sequence
  -> predict synonymous|missense|nonsense|frameshift|inframe|splice_related|complex
  note prediction is not proof of functional or clinical effect

rule regulatory_effect:
  allele overlaps regulatory_element AND supported_functional_evidence
  -> candidate_expression_effect

rule expression_context:
  effect depends_on transcript, cell_type, developmental_stage, environment

rule dominance:
  dominance is a relationship between allele effects on a specified phenotype in a specified genetic context
  NOT intrinsic universal property of an allele

rule penetrance:
  penetrance = P(phenotype | genotype, context)
  must_not_assume 1.0

rule expressivity:
  phenotype_severity may vary among carriers of the same allele

09. INHERITANCE AND CHANGE
process meiotic_transmission:
  inputs: parental_genotypes, linkage, recombination_model
  outputs: gamete_alleles_with_probabilities
  require chromosome_and_ploidy_context

process mutation:
  inputs: ancestral_sequence_state, mutational_event
  outputs: derived_sequence_state
  preserve event_provenance

process somatic_mosaicism:
  inputs: cell_lineages, somatic_event, tissue_sampling
  outputs: tissue_dependent_allele_fraction

rule de_novo:
  absent_in_tested_parents AND present_in_offspring
  -> candidate_de_novo
  require adequate_parental_coverage, identity_checks, mosaicism_consideration

10. CLINICAL AND PHENOTYPIC INTERPRETATION
rule pathogenicity_assessment:
  evidence = population + segregation + functional + computational + clinical + literature
  classification = framework_specific_weighted_assessment(evidence)
  never_equate rare_with_pathogenic
  never_equate predicted_damage_with_proven_pathogenicity

rule variant_of_uncertain_significance:
  insufficient_or_conflicting_evidence -> UNCERTAIN_SIGNIFICANCE
  avoid definitive causal_claim

rule association_vs_causation:
  statistical_association alone != demonstrated_causal_effect

11. RECURSIVE REASONING
flow infer_allele_context(a, depth, visited):
  if depth <= 0 or a.id in visited: return bounded_result
  visited.add(a.id)
  validate_reference(a)
  normalise_sequence(a)
  collect_genotypes(a)
  collect_haplotypes(a)
  collect_population_evidence(a)
  collect_functional_evidence(a)
  collect_phenotype_associations(a)
  traverse_supported_relationships(depth - 1, visited)
  resolve_conflicts_without_erasing_source_claims
  return evidence_linked_interpretation

12. CONFIDENCE
CONFIDENCE:
  range: [0,1]
  inputs: evidence_quality, independent_replication, reference_integrity, context_match, method_validation, contradictory_evidence
  aggregation: calibrated_model_or_declared_rule
  constraints:
    - do_not_assign_numeric_certainty_without_calibration
    - distinguish identity_confidence, genotype_confidence, functional_confidence, clinical_confidence
    - missing_evidence != negative_evidence

13. SEMANTIC_EQUIVALENCE
SEMANTIC_EQUIVALENCE:
  allele == normalised_sequence_state_at_same_reference_locus: conditional
  allele != gene
  allele != genotype
  allele != phenotype
  allele != variant_record_without_context
  reference_allele != necessarily ancestral_allele
  alternate_allele != necessarily pathogenic_allele
  mutation != necessarily harmful_change
  synonyms: [allelic_form, allelic_variant]
  preserve distinctions between sequence allele, functional allele and clinical interpretation

14. CONSTRAINTS AND VALIDATION
assert genotype.ploidy >= 1
assert length(genotype.allele_copies) == genotype.ploidy OR explicitly_missing_calls
assert allele.locus.reference != empty
assert allele.sequence_state != empty
assert 0 <= allele_frequency <= 1
assert classifications carry evidence_and_date
assert every inferred_edge records inference_method
assert no_unqualified_cross_assembly_coordinate_comparison
assert transcript_specific_consequences_are_transcript_qualified

15. PROVENANCE AND UPDATE_MODEL
UPDATE_MODEL:
  watch: reference_assembly, transcript_annotation, population_data, functional_assays, clinical_assertions, nomenclature
  on_change:
    preserve_previous_version
    revalidate_affected_entities
    recompute_dependent_inferences
    retain_conflicting_evidence_with_sources
    timestamp_updated_assertions
    mark_superseded_interpretations
  never_silently_overwrite_original_evidence

16. FLOW_HASH
FLOW_HASH:
  algorithm: SHA-256
  canonicalisation: UTF-8, LF_line_endings, stable_key_order, normalised_whitespace
  scope: ontology_version + typed_entities + relationships + constraints + inference_rules
  value: COMPUTE_ON_PUBLISH
  purpose: reproducible_content_integrity

17. AI_CONSUMPTION
AI_CONSUMPTION:
  format: typed_semantic_flow
  parsing: deterministic_sections
  outputs: entity_graph, validated_relationships, contextual_inferences, provenance_links
  retrieval_keys: [allele_id, gene_id, locus, assembly, sequence_state, phenotype, population]
  guardrails:
    - distinguish observations from predictions
    - expose uncertainty and context
    - cite evidence for clinical claims
    - do not generate clinical decisions from ontology alone
    - avoid false equivalence between reference systems

18. EXAMPLE INSTANCE
instance ALLELE_EXAMPLE:
  locus: {reference: "EXAMPLE_ASSEMBLY", interval: {start: 100, end: 100, coordinate_system: "1-based illustrative"}}
  sequence_state: {alphabet: DNA, residues: "G"}
  reference_state: "A"
  genotype: ["A", "G"]
  ploidy: 2
  interpretation: "illustrative heterozygous substitution; no functional or clinical assertion"
  provenance: "synthetic educational example"

19. OUTPUT CONTRACT
output:
  ontology: AlleleOntology
  class: GeneticEntity
  semantic_graph: enabled
  evidence_tracking: required
  confidence: contextual
  recursion: bounded
  updates: versioned
  integrity: FLOW_HASH
  consumer: AI_CONSUMPTION

END FLOW ALGEBRA