Checking if Lead Variants are Novel

GWASLab can check if the lead variants of your summary statistics overlap with reported variants or not based on the physical distance.

.get_novel()

mysumstats.get_novel(
    known=None,
    efo=None,
    only_novel=False,
    windowsizekb_for_novel=1000,
    windowsizekb=500,
    sig_level=5e-8,
    if_get_lead=True,
    group_key=None,
    use_p=False,
    anno=False,
    wc_correction=False,
    use_cache=True,
    cache_dir="./",
    build="19",
    source="ensembl",
    gwascatalog_source="NCBI",
    output_known=False,
    show_child_traits=True,
    verbose=True
)

GWASLab checks overlap with a local file of variants or records in GWAS Catalog.

When build="19" (hg19/GRCh37), coordinates are first lifted over to hg38, then the same steps run. GWAS catalog queries and novelty checks use hg38; returned coordinates are in hg38 in that case.

Required Parameters

Either known or efo must be provided:

• known: string or pandas.DataFrame, path to the local file of reported variants or a DataFrame containing known variants with CHR/POS columns

• efo: string or list, EFO ID, MONDO ID, or trait name for the target trait(s), used for querying the GWAS Catalog API v2. Supports IDs and trait names; a list may mix formats.

Examples: - EFO ID: "EFO_0001360" (type 2 diabetes) - MONDO ID: "MONDO_0005148" (type 2 diabetes) - Trait name: "type 2 diabetes mellitus" - Multiple traits (mixed): efo=['type 2 diabetes mellitus', 'MONDO_0004247', 'EFO_0004330']

Parameters

Return Value

Returns a pandas.DataFrame containing variants with novelty status and metadata:

• NOVEL: Boolean indicating novelty status
• DISTANCE_TO_KNOWN: Distance to nearest known variant (in base pairs)
• LOCATION_OF_KNOWN: Relative position to known variant
• KNOWN_ID: ID of matching known variant
• Additional metadata from known variants (if available)

Examples

# Check if lead variants are novel for type 2 diabetes
novel_variants = mysumstats.get_novel(
    efo="EFO_0001360",
    build="38",
    windowsizekb_for_novel=1000
)

# Check if lead variants are novel using trait name
novel_variants = mysumstats.get_novel(
    efo="type 2 diabetes mellitus",
    build="38"
)

# Check if lead variants are novel using local file
novel_variants = mysumstats.get_novel(
    known="/path/to/known_variants.txt",
    windowsizekb_for_novel=1000
)

# Check if lead variants are novel using DataFrame
known_df = pd.read_csv("/path/to/known_variants.txt")
novel_variants = mysumstats.get_novel(
    known=known_df,
    windowsizekb_for_novel=1000
)

# Return only novel variants
novel_only = mysumstats.get_novel(
    efo="EFO_0001360",
    only_novel=True,
    build="38"
)

# Also output the known variants for comparison
result = mysumstats.get_novel(
    efo="EFO_0001360",
    output_known=True,
    build="38"
)

# If you already have lead variants extracted
novel_variants = mysumstats.get_novel(
    efo="EFO_0001360",
    if_get_lead=False,  # Skip lead variant extraction
    build="38"
)

# efo supports a mix of trait names, MONDO IDs, and EFO IDs
novel_variants = mysumstats.get_novel(
    efo=['coffee consumption', 'MONDO_0004247', 'EFO_0004330'],
    build="38"
)

# Use custom cache directory for GWAS catalog data
novel_variants = mysumstats.get_novel(
    efo="EFO_0001360",
    cache_dir="/path/to/cache",
    build="38"
)

Caching (when using efo)

When you use the efo parameter to query the GWAS Catalog, use_cache and cache_dir control where results are stored and reused:

• use_cache (default True): Use cached data when available.
• cache_dir (default "./"): Directory for cache files.

Cache file naming:

• API v2: JSON files named
  GWASCatalog_v2_{efo}_associationsByTraitSummary_text_{date}_{suffix}.json
  (the suffix encodes significance level and show_child_traits).
• Legacy fallback (e.g. when the v2 API fails or for some MONDO traits): JSON files named
  GWASCatalog_{efo}_associationsByTraitSummary_text_{date}_childTrue.json
  or ..._childFalse.json in the same cache_dir.

Caching applies only when known variants are fetched via efo; it is not used when you pass a local known file or DataFrame.

Notes

• The function first extracts lead variants (unless if_get_lead=False) and then checks their novelty.
• When build="19", sumstats are lifted to hg38 before lead extraction and novelty checks; returned coordinates are in hg38.
• Novelty is determined based on physical distance: variants within windowsizekb_for_novel kb of a known variant are considered "known".
• GWAS Catalog queries require internet connection and may take some time depending on the trait.
• The function supports both GRCh37 (build="19") and GRCh38 (build="38"); with build="19", liftover to hg38 is applied automatically.
• When using group_key, variants are compared within groups, useful for multi-trait analyses.

Reference

• Buniello, A., MacArthur, J. A. L., Cerezo, M., Harris, L. W., Hayhurst, J., Malangone, C., ... & Parkinson, H. (2019). The NHGRI-EBI GWAS Catalog of published genome-wide association studies, targeted arrays and summary statistics 2019. Nucleic acids research, 47(D1), D1005-D1012.