File Formats

GraphLD supports various input and output file formats for summary statistics, annotations, and gene sets.

Summary Statistics

LDSC Format (.sumstats)

The standard LDSC summary statistics format.

Read with:

import graphld as gld
sumstats = gld.read_ldsc_sumstats("path/to/file.sumstats")

GWAS-VCF Format (.vcf or .vcf.gz)

The GWAS-VCF specification is supported. Required FORMAT fields:

Field	Description
ES	Effect size estimate
SE	Standard error of effect size
LP	-log10 p-value

Read with:

import graphld as gld
sumstats = gld.read_gwas_vcf("path/to/file.vcf")

Parquet Format (.parquet)

Parquet files produced by kodama are supported. The format stores per-trait columns as {trait}_BETA and {trait}_SE, allowing multiple traits per file.

Variant info columns are detected automatically:

• site_ids or SNP
• chrom or CHR
• position or POS
• ref or REF
• alt or ALT

Read with:

import graphld as gld
sumstats = gld.read_parquet_sumstats("path/to/file.parquet")

CLI Usage with Multi-Trait Parquet

When writing graphREML output files from a multi-trait parquet input, select the trait to analyze:

uv run graphld reml sumstats.parquet output --name height

Annotations

LDSC Format (.annot)

Per-chromosome annotation files in LDSC format.

Download BaselineLD model annotations (GRCh38) from the Price lab Google Cloud bucket.

Standard .annot files with variant IDs are supported. thin-annot files without variant IDs can be loaded when a matching positions file supplies coordinates in the same row order.

Read with:

import graphld as gld
annotations = gld.load_annotations("path/to/annot_dir/", chromosome=1)

BED Format (.bed)

UCSC BED files containing genomic regions. Each .bed file creates a binary annotation with 1 for variants whose GRCh38 coordinates match.

BED files should not be stratified per-chromosome. Place them in the annotation directory and they will be processed automatically.

Read with:

import graphld as gld
annotations = gld.load_annotations("path/to/annot_dir/", chromosome=1)

GMT Format (.gmt)

Gene Matrix Transposed format for gene sets. Tab-separated with:

1. Gene set name
2. Description
3. Gene IDs or symbols (remaining columns)

No header row.

Example:

PATHWAY_A    Description of pathway A    GENE1    GENE2    GENE3
PATHWAY_B    Description of pathway B    GENE4    GENE5

Read with:

from score_test.score_test_io import load_gene_annotations
gene_annotations = load_gene_annotations("path/to/gmt_dir/")

LDGM Files

Edge List Format

LDGM precision matrices are stored as edge lists. Files are named like:

1kg_chr1_16103_2888443.EAS.edgelist

SNP List Format

Associated SNP lists contain variant information:

1kg_chr1_16103_2888443.snplist

Metadata CSV

The metadata file contains information about all LDGM blocks:

Column	Description
chrom	Chromosome
chromStart	Block start position
chromEnd	Block end position
name	Edge list filename
snplistName	SNP list filename
population	Population code (e.g., EUR, EAS)
numVariants	Number of variants
numIndices	Number of matrix indices
numEntries	Number of non-zero entries

Read with:

import graphld as gld
metadata = gld.read_ldgm_metadata("path/to/metadata.csv", populations=["EUR"])