agc

README

go-agc

A pure-Go reader for Assembled Genomes Compressor (AGC) v3 archives.

The read-only library opens local files or arbitrary io.ReaderAt backends, validates file-format major version 3, lists samples and contigs, retrieves named contigs, and iterates one sample or the complete archive. Metadata and sequence streams are decoded lazily with bounded working memory. Other AGC file-format major versions are intentionally rejected.

archive, err := agc.Open("genomes.agc")
if err != nil {
	return err
}
defer archive.Close()

samples, err := archive.Samples()
reference, err := archive.ReferenceSample()
contigs, err := archive.Contigs(reference)
err = archive.IterateSample(reference, func(contig agc.Contig) error {
	return consume(contig.Name, contig.Sequence)
})

The implementation is read-only and lazily reads indexed archive parts. It uses github.com/klauspost/compress/zstd and does not require cgo or the AGC executable. Tests include the upstream toy archive, generated v3 fixtures, corruption cases, optional reference-CLI cross-checks, and benchmarks.

Releases

This is a library-only Go module, so releases are semantic-version Git tags; there are no executable artifacts to build. See RELEASING.md for the tagging workflow and consumer installation command.

Documentation

Overview

Package agc reads Assembled Genomes Compressor (AGC) v3 archives.

Archives are decoded lazily from an io.ReaderAt. The package is read-only.

Index

• Variables
• type Archive
  • func Open(path string) (*Archive, error)
  • func OpenReaderAt(r io.ReaderAt, size int64) (*Archive, error)
  • func (a *Archive) Close() error
  • func (a *Archive) Contig(sample Sample, name string) (Contig, error)
  • func (a *Archive) Contigs(sample Sample) ([]ContigInfo, error)
  • func (a *Archive) IterateAll(yield func(Contig) error) error
  • func (a *Archive) IterateSample(sample Sample, yield func(Contig) error) error
  • func (a *Archive) ReferenceSample() (Sample, error)
  • func (a *Archive) Samples() ([]Sample, error)
  • func (a *Archive) Version() Version
• type Contig
• type ContigInfo
• type Sample
• type Version

Variables

var (
	// ErrClosed is returned when an operation uses a closed archive.
	ErrClosed = errors.New("agc: archive is closed")
	// ErrCorruptArchive marks malformed, truncated, or inconsistent input.
	ErrCorruptArchive = errors.New("agc: corrupt archive")
	// ErrUnsupportedVersion marks an AGC archive whose file-format major version is not 3.
	ErrUnsupportedVersion = errors.New("agc: unsupported file-format version")
	// ErrSampleNotFound marks a lookup for a sample not present in the archive.
	ErrSampleNotFound = errors.New("agc: sample not found")
	// ErrContigNotFound marks a lookup for a contig not present in the selected sample.
	ErrContigNotFound = errors.New("agc: contig not found")
)

Types

type Archive

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

Archive is an open, read-only AGC v3 archive.

func Open

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

Open opens a local AGC v3 archive. Close releases the underlying file.

func OpenReaderAt

func OpenReaderAt(r io.ReaderAt, size int64) (*Archive, error)

OpenReaderAt opens an AGC v3 archive from a ReaderAt and its exact size. The caller retains ownership of r; Archive.Close does not close it.

func (*Archive) Close

func (a *Archive) Close() error

Close closes the archive. It is safe to call more than once.

func (*Archive) Contig

func (a *Archive) Contig(sample Sample, name string) (Contig, error)

Contig retrieves and decodes a named contig from a sample. Name matching follows AGC: the query and stored header are compared up to the first ASCII whitespace, while the returned Contig.Name retains the full stored header.

func (*Archive) Contigs

func (a *Archive) Contigs(sample Sample) ([]ContigInfo, error)

Contigs returns a sample's contigs in archive order. Each result retains its sample identity separately from its stored contig name.

func (*Archive) IterateAll

func (a *Archive) IterateAll(yield func(Contig) error) error

IterateAll decodes every contig in archive sample order and contig order, stopping on the first error returned by yield.

func (*Archive) IterateSample

func (a *Archive) IterateSample(sample Sample, yield func(Contig) error) error

IterateSample decodes a sample's contigs in archive order, holding at most one yielded contig's sequence at a time. Iteration stops on the first error returned by yield.

func (*Archive) ReferenceSample

func (a *Archive) ReferenceSample() (Sample, error)

ReferenceSample returns the first sample stored in the v3 collection.

func (*Archive) Samples

func (a *Archive) Samples() ([]Sample, error)

Samples returns samples in archive order. The reference sample is first.

func (*Archive) Version

func (a *Archive) Version() Version

Version returns the validated AGC file-format version.

type Contig

type Contig struct {
	Sample   Sample
	Name     string
	Sequence []byte
}

Contig contains one decoded contig.

type ContigInfo

type ContigInfo struct {
	Sample Sample
	Name   string
}

ContigInfo identifies a contig and its owning sample separately.

type Sample

type Sample struct {
	Name string
}

Sample identifies a sample independently from any of its contigs.

type Version

type Version struct {
	Major uint32
	Minor uint32
}

Version is the AGC file-format version, not the producer's software version.