Skip to article frontmatterSkip to article content
Site not loading correctly?

This may be due to an incorrect BASE_URL configuration. See the MyST Documentation for reference.

GREGOR enrichment analysis

Tests whether a set of trait-associated variants falls inside annotated regulatory features more often than a matched control set does.

Overview

A set of trait-associated variants is more interpretable if you can say what kind of sequence they fall in. Enrichment testing asks whether they overlap a class of genomic feature - an annotation, a chromatin state, a set of regulatory elements - more often than chance allows, where chance has to account for the fact that variants are not exchangeable: they differ in minor allele frequency, in the number of LD proxies they carry, and in distance to the nearest gene. GREGOR builds matched control variants on exactly those properties - minor allele frequency, LD proxy count, distance to the nearest TSS, and local gene density - so the comparison is fair.

GREGOR’s own PValue column, defined in the GREGOR paper, sometimes comes back greater than 1, and a p-value says less about a result than the size of the enrichment does. This module therefore parses GREGOR’s intermediate output into a 2x2 table - inside versus outside the annotation peak, positive set versus matched negative set - and runs Fisher’s exact test on it to recover both a p-value and an odds ratio.

When to run it. After you have a variant set worth characterising - fine-mapped credible sets, or GWAS hits - and an annotation you want to test them against.

Input

  • --index_snp_file: the positive variant set, one chr:pos per line with no header, on the same build as the reference database (hg19 for the standard ones). Example tests/fixtures/gregor/index.snps.txt:

    chr1:752566
    chr1:776546
    chr2:233567
  • --bed_file_index: a two-column tab-separated index naming each annotation and pointing at its bed file. Example tests/fixtures/gregor/protocol_example.bed.file.index:

    annotationA    <path>/annotationA.bed
    annotationB    <path>/annotationB.bed
    annotationC    <path>/annotationC.bed
  • --gregor_db: the GREGOR reference database directory, one SQLite CUBE table per chromosome. The full per-population reference is around 20 GB and is distributed under the University of Michigan license, so it is not bundled here and input/enrichment/protocol_example.gregor_ref is a placeholder. A downsized chr22 EUR slice is committed under tests/fixtures/gregor/EUR so the notebook can be smoke-tested end to end.

  • --pop: the reference population, EUR by default. It has to match the population the database was built for.

  • --r2_threshold and --ld_window_size: what counts as an LD buddy, 0.7 and 10000 by default. Both have to match the values the reference database was built with, 1 Mb for the standard r2 >= 0.7 databases.

  • --fisher1 and --fisher2, used by gregor_fisher_plot only: two enrichment-result tables to plot against each other, in the form the gregor workflow writes. Example input/enrichment/protocol_example.trait1_enrichment_results.txt:

    Bed_File              odds   low    high   p_fisher
    Promoter_UCSC.bed     1.377  0.751  2.011  0.0653
    Enhancer_Hoffman.bed  1.886  1.15   2.307  0.4567
  • --cwd: the directory outputs are written to.

Output

  • {cwd}/{index_snp_file}.gregor.conf - the GREGOR configuration file built from the supplied paths and parameters. The key lines of output/gregor/protocol_example.index.gregor.conf:

    INDEX_SNP_FILE = tests/fixtures/gregor/index.snps.txt
    BED_FILE_INDEX = tests/fixtures/gregor/protocol_example.bed.file.index
    REF_DIR = input/enrichment/protocol_example.gregor_ref
    R2THRESHOLD = 0.7 ## must be greater than 0.7
    LDWINDOWSIZE = 10000 ## must be less than this window; these two values define LD buddies
    POPULATION = EUR  ## define the population, you can specify EUR, AFR, AMR or ASN
  • {name}_gregor_output/StatisticSummaryFile.txt - GREGOR’s raw overlap statistics, one row per annotation bed file.

  • {name}_variant_counts.txt and {name}_enrichment_results.txt - the parsed 2x2 counts (inside versus outside the annotation peak, positive versus matched-negative set) and the per-annotation Fisher exact-test p-values and odds ratios.

  • {cwd}/{fisher1}_vs_{fisher2}_enrichment.pdf - the odds-ratio comparison plot across annotations.

Only the configuration file ships with the repository. Carrying the example past step 1 needs the full GREGOR reference database, so output/gregor holds the .conf and GREGOR’s generated job scripts but no summary, counts, or results tables.

Minimal Working Example

Steps 1 and 2 need the GREGOR reference database and the GREGOR perl software; step 3 runs on the two example result tables alone.

GREGOR enrichment scan

Configuration file only

gregor_conf only writes a .gregor.conf from the supplied paths and parameters and never invokes GREGOR.

Timing: TBD (on toy dataset)

The full chain

gregor repeats the configuration step, then runs GREGOR and Fisher-tests its output. It expects the GREGOR perl tool as GREGOR on PATH and a reference database.

Timing: TBD (on toy dataset)

Plot an odds-ratio comparison

gregor_fisher_plot is self-contained R and runs from two *_enrichment_results.txt tables alone, with no reference database or GREGOR install needed.

Timing: TBD (on toy dataset)

Command Interface

usage: sos run pipeline/gregor.ipynb
               [workflow_name | -t targets] [options] [workflow_options]
  workflow_name:        Single or combined workflows defined in this script
  targets:              One or more targets to generate
  options:              Single-hyphen sos parameters (see "sos run -h" for details)
  workflow_options:     Double-hyphen workflow-specific parameters

Workflows:
  gregor_conf
  gregor
  gregor_fisher_plot

Global Workflow Options:
  --cwd output (as path)
                        working directory
  --container ''
                        Software container option

Sections
  gregor_conf, gregor_1: make configuration file for GREGOR
    Workflow Options:
      --gregor-db VAL (as path, required)
      --pop EUR
      --index-snp-file VAL (as path, required)
      --bed-file-index VAL (as path, required)
      --r2-threshold 0.7 (as float)
      --ld-window-size 10000 (as int)
      --min-neighbor 10 (as int)
      --job-number 10 (as int)
  gregor_2:             run GREGOR
  gregor_3:             Fisher test of enrichment
  gregor_fisher_plot:   enrichment plot with fisher test results
    Workflow Options:
      --fisher1 VAL (as path, required)
      --fisher2 VAL (as path, required)

Workflow implementation

GREGOR is an external perl tool that is not ported to R; it is installed from the gregor conda package and is on PATH as GREGOR, so gregor_2 below simply calls it. The package brings its own perl and the modules GREGOR needs (DBI, Switch, DBD::SQLite), so no separate library installation is required — note that this means a bare perl -MDBI in your shell can still fail while GREGOR itself works.

To run a scan by hand, generate the configuration file with the gregor_conf workflow above and pass it to GREGOR directly:

GREGOR --conf output/gregor/index.gregor.conf

--ld_window_size must match the window the reference database’s r2 tables were built with, and --min_neighbor must be small enough for the matched-control bins that reference actually contains. A mismatch does not raise an error: GREGOR keeps searching for matched controls it will never find, so the run simply appears to hang.