gff3idx

Documentation

Overview

Package gff3idx provides two backends for querying GFF3 features: an in-memory index (MemQuerier) and a persistent mmap-based binary index. Both implement the Querier interface.

In-memory usage:

q := gff3idx.Wrap(records)
feat, _ := q.ByID("gene00001")

Binary index usage:

gff3idx.Build(records, "genes.gff3idx")
idx, _ := gff3idx.Open("genes.gff3idx")
feat, _ := idx.ByID("gene00001")

Index

• Constants
• func Build(records []*gff3.Record, outPath string) error
• func ByteOrder() binary.ByteOrder
• func NextPow2(n uint32) uint32
• type EntryRecord
• type Feature
• type GeneChildren
• type GeneRecord
• type HashSlot
• type Header
• type MemQuerier
  • func Wrap(records []*gff3.Record) *MemQuerier
  • func (m *MemQuerier) ByID(id string) (*Feature, bool)
  • func (m *MemQuerier) ChildrenOf(geneID string) (*GeneChildren, bool)
  • func (m *MemQuerier) InRange(chr string, minStart, maxEnd int) []SpatialFeat
• type Querier
• type Reader
  • func Open(path string) (*Reader, error)
  • func (r *Reader) ByID(id string) (*Feature, bool)
  • func (r *Reader) ChildrenOf(geneID string) (*GeneChildren, bool)
  • func (r *Reader) ChrCount() uint32
  • func (r *Reader) Close() error
  • func (r *Reader) EntryCount() uint32
  • func (r *Reader) GeneCount() uint32
  • func (r *Reader) InRange(chr string, minStart, maxEnd int) []SpatialFeat
• type SpatialFeat
• type SpatialFeatureRec
• type SpatialHeader

Constants

const (
	Magic   = "GFFI"
	Version = 1
)

const EntryRecordSize = 40

const GeneRecordSize = 24

const HashSlotSize = 16

const HeaderSize = 64

const SpatialFeatureRecSize = 24

const SpatialHeaderSize = 16

Functions

func Build

func Build(records []*gff3.Record, outPath string) error

Build constructs a binary index file from parsed GFF3 records.

The resulting file can be opened with Open() for repeated mmap-based queries. Index size is approximately 150 MB per million records.

func ByteOrder

func ByteOrder() binary.ByteOrder

func NextPow2

func NextPow2(n uint32) uint32

Types

type EntryRecord

type EntryRecord struct {
	Start        int64
	End          int64
	ChrOffset    uint32
	SourceOffset uint32
	TypeOffset   uint32
	ScoreOffset  uint32
	StrandOffset uint32
	Phase        int32
}

type Feature

type Feature struct {
	SeqID  string
	Source string
	Type   string
	Start  int
	End    int
	Score  string
	Strand string
	Phase  int
}

Feature represents a single GFF3 feature returned from a query.

type GeneChildren

type GeneChildren struct {
	Transcripts []string // mRNA IDs
	CDSs        []string // CDS feature IDs
	Exons       []string // exon feature IDs
}

GeneChildren holds the IDs of a gene's child features, grouped by type.

type GeneRecord

type GeneRecord struct {
	TranscriptCount uint32
	CDSCount        uint32
	ExonCount       uint32

	DataOffset uint64
	// contains filtered or unexported fields
}

type HashSlot

type HashSlot struct {
	Hash uint64
	Val  uint64
}

type Header

type Header struct {
	Magic   [4]byte
	Version uint32

	EntryCount     uint32
	SpatialChrs    uint32
	GeneCount      uint32
	StringPoolSize uint64
	EntriesOffset  uint64
	SpatialOffset  uint64
	GenesOffset    uint64
	StringPoolOff  uint64
	// contains filtered or unexported fields
}

type MemQuerier

type MemQuerier struct {
	// contains filtered or unexported fields
}

MemQuerier is an in-memory index built from parsed GFF3 records. It implements Querier with zero build cost — just wrap your records and start querying.

Memory cost is approximately the same as the underlying []*Record slice plus index overhead (maps for ID, gene hierarchy, and spatial).

func Wrap

func Wrap(records []*gff3.Record) *MemQuerier

Wrap builds an in-memory Querier from parsed GFF3 records.

Records without an ID attribute are skipped. Discontiguous features (same ID on multiple lines) have their coordinate extents merged.

func (*MemQuerier) ByID

func (m *MemQuerier) ByID(id string) (*Feature, bool)

func (*MemQuerier) ChildrenOf

func (m *MemQuerier) ChildrenOf(geneID string) (*GeneChildren, bool)

func (*MemQuerier) InRange

func (m *MemQuerier) InRange(chr string, minStart, maxEnd int) []SpatialFeat

type Querier

type Querier interface {
	// ByID looks up a feature by its ID attribute.
	// Returns nil, false if not found.
	ByID(id string) (*Feature, bool)

	// ChildrenOf returns the gene's child features grouped by type:
	// transcripts (mRNA), CDSs, and exons.
	// Traverses the two-level hierarchy gene → mRNA → (CDS, exon).
	ChildrenOf(geneID string) (*GeneChildren, bool)

	// InRange returns all features that overlap the given genomic interval.
	// Returns nil if chromosome not found.
	InRange(chr string, minStart, maxEnd int) []SpatialFeat
}

Querier is the common interface for both in-memory and binary index backends.

type Reader

type Reader struct {
	// contains filtered or unexported fields
}

Reader is a Querier backed by a memory-mapped binary index file. Created by Open(), must be Closed() to release resources.

func Open

func Open(path string) (*Reader, error)

Open mmaps a binary index file and returns a queryable Reader. The Reader implements Querier. Close() must be called to release the mmap region and file handle.

The index file is validated on open (magic, version, bounds checks).

func (*Reader) ByID

func (r *Reader) ByID(id string) (*Feature, bool)

func (*Reader) ChildrenOf

func (r *Reader) ChildrenOf(geneID string) (*GeneChildren, bool)

func (*Reader) ChrCount

func (r *Reader) ChrCount() uint32

func (*Reader) Close

func (r *Reader) Close() error

func (*Reader) EntryCount

func (r *Reader) EntryCount() uint32

func (*Reader) GeneCount

func (r *Reader) GeneCount() uint32

func (*Reader) InRange

func (r *Reader) InRange(chr string, minStart, maxEnd int) []SpatialFeat

type SpatialFeat

type SpatialFeat struct {
	Start int
	End   int
	ID    string
	Type  string
}

SpatialFeat is a lightweight feature record returned by InRange queries.

type SpatialFeatureRec

type SpatialFeatureRec struct {
	Start      int64
	End        int64
	IDOffset   uint32
	TypeOffset uint32
}

type SpatialHeader

type SpatialHeader struct {
	ChrOffset    uint32
	FeatureCount uint32
	DataOffset   uint64
}