moonbit-gffkit

moonbit-gffkit is a MoonBit toolkit for GFF3 and GTF genome annotation files. It parses annotation rows, keeps attributes queryable, builds a gene-transcript-exon model, and exports compact JSON or BED output for downstream scripts.

The project is intentionally small at the edges and solid in the middle: pure MoonBit library code, a native CLI, fixture-driven tests, and no runtime service requirement.

Features

• Parse GFF3 and GTF records with checked coordinate validation.
• Preserve GFF3 key=value attributes, flags, and common percent escapes.
• Preserve GTF quoted attributes, including values with spaces.
• Query features by type, attribute, and genomic interval.
• Build gene -> transcript -> exon/CDS/UTR hierarchies.
• Export annotations as BED6, deterministic JSON, and tabular summary counts.
• Run as a library or through the gffkit CLI.

Install

This repository targets the current MoonBit toolchain used during development:

moon version --all

Build and test:

moon check --target all --deny-warn
moon test --target all --deny-warn
moon fmt --check
moon info

CLI Usage

moon run cmd/gffkit -- validate testdata/basic.gff3
moon run cmd/gffkit -- stats testdata/basic.gtf
moon run cmd/gffkit -- filter exon testdata/basic.gff3
moon run cmd/gffkit -- to-bed testdata/basic.gff3
moon run cmd/gffkit -- to-json testdata/basic.gtf

Example output:

features    5
genes    1
transcripts    1
exons    2
cds    1

Library Example

let text =
  #|chr1    RefSeq    gene    1000    5000    .    +    .    ID=gene:BRCA1;Name=BRCA1
  #|
let annotation = parse_gff3(text)
let genes = annotation.to_gene_models()
println(genes[0].id)

API Overview

• parse_gff3(text) parses GFF3 text.
• parse_gtf(text) parses GTF text.
• parse_auto(text) detects GFF3/GTF from headers and attribute style.
• Annotation::filter_by_type(type) returns features of a type.
• Annotation::find_by_attribute(key, value) returns matching features.
• Annotation::overlapping(seqid=..., start=..., end=...) returns interval overlaps.
• Annotation::to_gene_models() builds gene-centric models.
• Annotation::to_bed() exports BED6.
• Annotation::to_json() exports stable JSON.
• Annotation::summary() returns count totals.
• Reference catalogs expose common feature terms, attributes, biotypes, validation rules, evidence labels, and sequence region labels.

Scope

The first release focuses on annotation text processing. It does not implement tabix indexing, BGZF compression, FASTA sequence extraction, or a genome browser. The public model is shaped so those pieces can be added later without replacing the parser.

Repository Notes

The repository is prepared for hackathon review with source files, tests, CI, license, examples, and submission notes. The current MoonBit source scale is about 5.4k lines including generated interface information. See docs/source-notes.md and docs/competition-checklist.md.

License

MIT.