gmat integration

Ownership and ordering contracts for genotype panels and sparse LD.

Scope

The R workflow has one owner at each layer:

gbase Glist → gbase sparse-LD preparation → gmat disk resource → task packages

gbase::gprep() owns genotype preparation and augments a Glist with sparse-LD identity, marker and sample selections, paths, settings, and provenance. gbits owns BED decoding. gmat owns panel mappings, sparse-LD computation, the disk format, validation, and readers. Task packages accept the Glist and use installed public gmat interfaces from C++.

Serializable bridge objects

Root gsuite retains only the BED resource and panel objects needed by its own internal genotype integration:

  • gsuite_bed_resource retains canonical BED/BIM/FAM paths, physical counts, and literal ordered BIM/FAM metadata.
  • gsuite_bed_panel retains component resources, exact selections, selected metadata, and zero-based native source mappings.

These list-style S3 objects have no external pointers. Sparse-LD preparation and access are not duplicated in root gsuite.

Identity and ordering

Component order is list order. Components must have identical ordered (family_id, individual_id) pairs before selection. Sample identities and per-component marker IDs are resolved exactly, and requested order is preserved. Global marker order concatenates component selections. Duplicate or missing identities are errors. Nothing silently sorts chromosomes, positions, markers, samples, or alleles.

The gbase::gprep(task = "sparseld") contract, numerical conventions, and Glist fields are specified in sparse-LD preparation.

Limitations

The integration does not harmonize alleles, flip dosage, convert genome builds, or parse summary statistics. All five files in a persistent gmat sparse-LD resource must remain available together.

See the gmat method catalogue for the complete native contracts.