///|
fn attr_ref(
  key : String,
  format : String,
  category : String,
  description : String,
  typical_scope : String,
) -> AttributeReference {
  { key, format, category, description, typical_scope }
}

///|
pub fn reference_attributes() -> Array[AttributeReference] {
  [
    attr_ref(
      "ID", "GFF3", "identity", "Unique identifier for a feature", "all identified features",
    ),
    attr_ref(
      "Parent", "GFF3", "relationship", "Parent feature identifier", "child features",
    ),
    attr_ref(
      "Name", "GFF3", "display", "Human-readable display name", "genes and transcripts",
    ),
    attr_ref(
      "Alias", "GFF3", "display", "Alternative names or symbols", "genes",
    ),
    attr_ref(
      "Dbxref", "GFF3", "cross_reference", "Database cross references", "all features",
    ),
    attr_ref(
      "Ontology_term", "GFF3", "cross_reference", "Ontology term identifiers", "typed features",
    ),
    attr_ref(
      "Note", "GFF3", "annotation", "Free-text annotation note", "all features",
    ),
    attr_ref(
      "Target", "GFF3", "alignment", "Alignment target and target coordinates", "match features",
    ),
    attr_ref(
      "Gap", "GFF3", "alignment", "CIGAR-like alignment gap string", "match features",
    ),
    attr_ref(
      "Derives_from", "GFF3", "relationship", "Product derivation relationship",
      "polypeptides",
    ),
    attr_ref(
      "Is_circular", "GFF3", "topology", "Circular sequence flag", "chromosomes and contigs",
    ),
    attr_ref(
      "biotype", "GFF3", "classification", "Biological type label", "genes and transcripts",
    ),
    attr_ref(
      "gene_id", "GTF", "identity", "Stable gene identifier", "all GTF features",
    ),
    attr_ref(
      "transcript_id", "GTF", "identity", "Stable transcript identifier", "transcript children",
    ),
    attr_ref(
      "gene_name", "GTF", "display", "Gene display symbol", "gene-derived features",
    ),
    attr_ref(
      "transcript_name", "GTF", "display", "Transcript display name", "transcripts",
    ),
    attr_ref(
      "gene_biotype", "GTF", "classification", "Gene biotype label", "gene-derived features",
    ),
    attr_ref(
      "transcript_biotype", "GTF", "classification", "Transcript biotype label",
      "transcripts",
    ),
    attr_ref(
      "exon_number", "GTF", "ordering", "Ordinal exon number within transcript",
      "exons",
    ),
    attr_ref("exon_id", "GTF", "identity", "Stable exon identifier", "exons"),
    attr_ref(
      "protein_id", "GTF", "identity", "Protein product identifier", "CDS features",
    ),
    attr_ref(
      "ccds_id", "GTF", "cross_reference", "Consensus CDS identifier", "coding transcripts",
    ),
    attr_ref(
      "havana_gene", "GTF", "cross_reference", "HAVANA gene identifier", "genes",
    ),
    attr_ref(
      "havana_transcript", "GTF", "cross_reference", "HAVANA transcript identifier",
      "transcripts",
    ),
    attr_ref(
      "tag", "GTF", "annotation", "Provider-specific tag value", "all features",
    ),
    attr_ref(
      "transcript_support_level", "GTF", "quality", "Transcript support level", "transcripts",
    ),
    attr_ref(
      "version", "GTF", "identity", "Version suffix or release number", "stable identifiers",
    ),
    attr_ref(
      "source", "both", "provenance", "Source program or database", "feature metadata",
    ),
    attr_ref(
      "score", "both", "quantitative", "Feature confidence or score", "scored features",
    ),
    attr_ref("phase", "both", "coding", "CDS frame phase", "CDS features"),
    attr_ref(
      "rank", "both", "ordering", "Generic child order rank", "ordered children",
    ),
    attr_ref(
      "product", "GFF3", "annotation", "Predicted product name", "gene products",
    ),
    attr_ref(
      "product_id", "GFF3", "identity", "Product identifier", "gene products",
    ),
    attr_ref(
      "protein_name", "GFF3", "annotation", "Protein display name", "polypeptides",
    ),
    attr_ref("locus_tag", "GFF3", "identity", "Locus tag identifier", "genes"),
    attr_ref("old_locus_tag", "GFF3", "identity", "Previous locus tag", "genes"),
    attr_ref("gene", "GFF3", "display", "Gene symbol", "gene products"),
    attr_ref("gene_synonym", "GFF3", "display", "Gene synonym", "genes"),
    attr_ref("pseudo", "GFF3", "classification", "Pseudogene flag", "genes"),
    attr_ref(
      "exception", "GFF3", "annotation", "Translational or biological exception",
      "coding features",
    ),
    attr_ref(
      "codon_start", "GFF3", "coding", "CDS codon start offset", "CDS features",
    ),
    attr_ref(
      "transl_table", "GFF3", "coding", "Translation table identifier", "CDS features",
    ),
    attr_ref(
      "inference", "GFF3", "evidence", "Inference evidence string", "predicted features",
    ),
    attr_ref(
      "experiment", "GFF3", "evidence", "Experimental evidence string", "curated features",
    ),
    attr_ref(
      "function", "GFF3", "annotation", "Functional annotation", "gene products",
    ),
    attr_ref(
      "EC_number", "GFF3", "cross_reference", "Enzyme Commission number", "enzymes",
    ),
    attr_ref(
      "GO", "GFF3", "cross_reference", "Gene Ontology reference", "gene products",
    ),
    attr_ref(
      "PFAM", "GFF3", "cross_reference", "PFAM domain reference", "protein domains",
    ),
    attr_ref(
      "InterPro", "GFF3", "cross_reference", "InterPro domain reference", "protein domains",
    ),
    attr_ref(
      "gene_type", "GTF", "classification", "Gene type label", "gene-derived features",
    ),
    attr_ref(
      "transcript_type", "GTF", "classification", "Transcript type label", "transcripts",
    ),
    attr_ref(
      "level", "GTF", "quality", "GENCODE annotation level", "GENCODE features",
    ),
    attr_ref(
      "ont", "GTF", "cross_reference", "Ontology label", "GENCODE features",
    ),
    attr_ref(
      "remap_status", "GTF", "provenance", "Genome remap status", "remapped annotations",
    ),
    attr_ref(
      "remap_num_mappings", "GTF", "provenance", "Number of remapped locations",
      "remapped annotations",
    ),
    attr_ref(
      "remap_target_status", "GTF", "provenance", "Target assembly remap status",
      "remapped annotations",
    ),
    attr_ref(
      "logic_name", "GTF", "provenance", "Ensembl analysis logic name", "Ensembl features",
    ),
    attr_ref(
      "external_name", "GTF", "display", "External display name", "Ensembl features",
    ),
    attr_ref(
      "external_source", "GTF", "provenance", "External source database", "Ensembl features",
    ),
    attr_ref(
      "percentage_gene_gc_content", "GTF", "quantitative", "Gene GC content percentage",
      "genes",
    ),
    attr_ref(
      "description", "GTF", "annotation", "Free-text feature description", "genes",
    ),
    attr_ref(
      "source_id", "both", "provenance", "Source-specific identifier", "imported features",
    ),
    attr_ref(
      "owner", "both", "provenance", "Owning dataset or group", "curated projects",
    ),
    attr_ref(
      "created_by", "both", "provenance", "Creator pipeline name", "curated projects",
    ),
    attr_ref(
      "created_at", "both", "provenance", "Creation timestamp", "curated projects",
    ),
    attr_ref(
      "updated_at", "both", "provenance", "Update timestamp", "curated projects",
    ),
    attr_ref(
      "confidence", "both", "quality", "Confidence class or score", "predicted features",
    ),
    attr_ref(
      "coverage", "both", "quantitative", "Read or alignment coverage", "evidence-backed features",
    ),
    attr_ref(
      "identity", "both", "quantitative", "Sequence identity percentage", "alignment features",
    ),
    attr_ref(
      "evalue", "both", "quantitative", "Search e-value", "homology features",
    ),
    attr_ref(
      "bitscore", "both", "quantitative", "Search bit score", "homology features",
    ),
    attr_ref(
      "coverage_depth", "both", "quantitative", "Depth across feature interval",
      "sequencing features",
    ),
    attr_ref(
      "read_support", "both", "evidence", "Number of reads supporting feature", "RNA-seq features",
    ),
    attr_ref(
      "junction_support", "both", "evidence", "Splice junction support count", "transcripts",
    ),
    attr_ref(
      "peptide_support", "both", "evidence", "Peptide evidence support", "coding features",
    ),
    attr_ref(
      "ortholog", "both", "cross_reference", "Orthologous feature reference", "comparative annotations",
    ),
    attr_ref(
      "paralog", "both", "cross_reference", "Paralogous feature reference", "comparative annotations",
    ),
    attr_ref(
      "species", "both", "provenance", "Species name for projected feature", "comparative annotations",
    ),
    attr_ref(
      "assembly", "both", "provenance", "Genome assembly identifier", "all features",
    ),
    attr_ref(
      "release", "both", "provenance", "Annotation release identifier", "all features",
    ),
    attr_ref(
      "pipeline", "both", "provenance", "Pipeline name", "predicted features",
    ),
    attr_ref(
      "model_version", "both", "provenance", "Prediction model version", "predicted features",
    ),
    attr_ref(
      "curator", "both", "provenance", "Manual curator identifier", "curated features",
    ),
    attr_ref(
      "review_status", "both", "quality", "Review state", "curated features",
    ),
    attr_ref(
      "partial", "both", "quality", "Partial feature flag", "incomplete features",
    ),
    attr_ref(
      "truncated", "both", "quality", "Truncated feature flag", "incomplete features",
    ),
    attr_ref(
      "frameshift", "both", "quality", "Frameshift annotation flag", "coding features",
    ),
    attr_ref(
      "stop_retained", "both", "quality", "Retained stop codon flag", "coding features",
    ),
    attr_ref(
      "readthrough", "both", "classification", "Readthrough transcript flag", "transcripts",
    ),
    attr_ref(
      "nmd_candidate", "both", "classification", "Nonsense mediated decay candidate flag",
      "transcripts",
    ),
    attr_ref(
      "mane_select", "GTF", "quality", "MANE Select tag", "human transcripts",
    ),
    attr_ref(
      "appris", "GTF", "quality", "APPRIS principal/alternative tag", "transcripts",
    ),
    attr_ref("basic", "GTF", "quality", "GENCODE basic tag", "transcripts"),
    attr_ref(
      "canonical", "both", "quality", "Canonical isoform flag", "transcripts",
    ),
    attr_ref(
      "mane_plus_clinical", "GTF", "quality", "MANE Plus Clinical tag", "human transcripts",
    ),
    attr_ref(
      "transcript_rank", "both", "ordering", "Transcript ranking within gene", "transcripts",
    ),
    attr_ref(
      "exon_rank", "both", "ordering", "Exon ranking within transcript", "exons",
    ),
    attr_ref(
      "cds_rank", "both", "ordering", "CDS ranking within transcript", "CDS features",
    ),
    attr_ref(
      "utr_rank", "both", "ordering", "UTR ranking within transcript", "UTR features",
    ),
    attr_ref(
      "parent_type", "both", "relationship", "Parent feature type hint", "child features",
    ),
    attr_ref(
      "child_count", "both", "quantitative", "Number of child features", "container features",
    ),
    attr_ref(
      "transcript_count", "both", "quantitative", "Number of transcripts in gene",
      "genes",
    ),
    attr_ref(
      "exon_count", "both", "quantitative", "Number of exons in transcript", "transcripts",
    ),
    attr_ref(
      "cds_length", "both", "quantitative", "Coding length in bases", "transcripts",
    ),
    attr_ref(
      "exon_length", "both", "quantitative", "Exonic length in bases", "transcripts",
    ),
    attr_ref(
      "intron_length", "both", "quantitative", "Intronic length in bases", "transcripts",
    ),
    attr_ref(
      "gc_content", "both", "quantitative", "GC content percentage", "sequence features",
    ),
    attr_ref(
      "repeat_class", "both", "classification", "Repeat class label", "repeat features",
    ),
    attr_ref(
      "repeat_family", "both", "classification", "Repeat family label", "repeat features",
    ),
    attr_ref(
      "variant_id", "both", "identity", "Variant identifier", "variant features",
    ),
    attr_ref(
      "ref_allele", "both", "variant", "Reference allele", "variant features",
    ),
    attr_ref(
      "alt_allele", "both", "variant", "Alternative allele", "variant features",
    ),
    attr_ref(
      "clinical_significance", "both", "variant", "Clinical interpretation label",
      "variant features",
    ),
    attr_ref(
      "phenotype", "both", "annotation", "Associated phenotype", "variant or gene features",
    ),
    attr_ref(
      "disease", "both", "annotation", "Disease association", "variant or gene features",
    ),
    attr_ref(
      "sample", "both", "provenance", "Sample identifier", "sample-derived features",
    ),
    attr_ref(
      "population", "both", "provenance", "Population label", "variant features",
    ),
    attr_ref(
      "allele_frequency", "both", "quantitative", "Allele frequency", "variant features",
    ),
    attr_ref(
      "supporting_reads", "both", "evidence", "Supporting read identifiers or count",
      "variant features",
    ),
    attr_ref(
      "motif", "both", "regulatory", "Sequence motif label", "regulatory features",
    ),
    attr_ref(
      "motif_id", "both", "regulatory", "Motif database identifier", "regulatory features",
    ),
    attr_ref(
      "tf_name", "both", "regulatory", "Transcription factor name", "binding sites",
    ),
    attr_ref(
      "cell_type", "both", "provenance", "Cell type label", "functional genomics features",
    ),
    attr_ref(
      "tissue", "both", "provenance", "Tissue label", "functional genomics features",
    ),
    attr_ref(
      "development_stage", "both", "provenance", "Developmental stage label", "functional genomics features",
    ),
    attr_ref(
      "assay", "both", "provenance", "Assay type", "functional genomics features",
    ),
    attr_ref(
      "signal_value", "both", "quantitative", "Signal value", "functional genomics features",
    ),
    attr_ref(
      "p_value", "both", "quantitative", "P-value", "statistical features",
    ),
    attr_ref(
      "q_value", "both", "quantitative", "Adjusted q-value", "statistical features",
    ),
    attr_ref(
      "fold_change", "both", "quantitative", "Fold change", "differential features",
    ),
  ]
}

///|
pub fn find_reference_attribute(key : String) -> AttributeReference {
  for item in reference_attributes() {
    if item.key == key {
      return item
    }
  }
  attr_ref(
    key, "both", "custom", "Project-specific attribute", "custom features",
  )
}

///|
pub fn reference_attributes_by_category(
  category : String,
) -> Array[AttributeReference] {
  let result : Array[AttributeReference] = []
  for item in reference_attributes() {
    if item.category == category {
      result.push(item)
    }
  }
  result
}

///|
pub fn reference_attributes_by_format(
  format : String,
) -> Array[AttributeReference] {
  let result : Array[AttributeReference] = []
  for item in reference_attributes() {
    if item.format == format || item.format == "both" {
      result.push(item)
    }
  }
  result
}

///|
pub fn AttributeReference::to_tsv_row(self : AttributeReference) -> String {
  [self.key, self.format, self.category, self.description, self.typical_scope].join(
    "\t",
  )
}

///|
pub fn reference_attributes_tsv() -> String {
  let lines : Array[String] = [
    "key\tformat\tcategory\tdescription\ttypical_scope",
  ]
  for item in reference_attributes() {
    lines.push(item.to_tsv_row())
  }
  lines.join("\n") + "\n"
}