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:

Gene set name
Description
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"])