HGNC Client

The HGNC client provides gene symbol standardization and validation using the HUGO Gene Nomenclature Committee database.

Overview

The HGNCClient class provides:

• Symbol standardization - Converts aliases to approved symbols
• Gene validation - Verifies gene symbols exist in HGNC
• Batch processing - Efficiently processes multiple genes
• Alternative symbols - Handles previous and alias symbols
• Caching - Reduces API load with local caching

Features

• Comprehensive search - Searches approved symbols, aliases, and previous symbols
• Status filtering - Only returns approved and active genes
• Fuzzy matching - Handles common symbol variations
• Error recovery - Graceful handling of API timeouts and errors
• Performance optimization - Batched requests and intelligent caching

API Reference

custom_panel.core.hgnc_client

HGNC (HUGO Gene Nomenclature Committee) client for gene symbol standardization.

This module provides a client for interacting with the HGNC REST API to standardize gene symbols and retrieve gene information.

HGNCClient

HGNCClient(timeout=30, max_retries=3, retry_delay=1.0, cache_manager=None)

Client for interacting with the HGNC REST API.

Initialize the HGNC client.

Parameters:

Name	Type	Description	Default
timeout	int	Request timeout in seconds	30
max_retries	int	Maximum number of retry attempts	3
retry_delay	float	Delay between retries in seconds	1.0
cache_manager	CacheManager | None	Optional cache manager instance	None

clear_cache

clear_cache()

Clear all cached results.

get_cache_info

get_cache_info()

Get cache statistics for monitoring performance.

Returns:

Type	Description
dict[str, Any]	Dictionary with cache statistics

get_gene_info cached

get_gene_info(symbol)

Get comprehensive gene information for a symbol.

Parameters:

Name	Type	Description	Default
symbol	str	Gene symbol	required

Returns:

Type	Description
dict[str, Any] | None	Dictionary with gene information or None if not found

hgnc_id_to_symbol cached

hgnc_id_to_symbol(hgnc_id)

Convert HGNC ID to approved gene symbol.

Parameters:

Name	Type	Description	Default
hgnc_id	str	HGNC ID (e.g., "HGNC:5")	required

Returns:

Type	Description
str | None	Approved gene symbol or None if not found

standardize_symbol cached

standardize_symbol(symbol)

Standardize a gene symbol to the approved HGNC symbol.

This method tries multiple approaches: 1. Direct symbol lookup 2. Previous symbol lookup 3. Alias symbol lookup

Parameters:

Name	Type	Description	Default
symbol	str	Input gene symbol	required

Returns:

Type	Description
str	Standardized HGNC symbol or original symbol if not found

standardize_symbols

standardize_symbols(symbols)

Standardize multiple gene symbols.

Parameters:

Name	Type	Description	Default
symbols	list[str]	List of gene symbols	required

Returns:

Type	Description
dict[str, dict[str, str | None]]	Dictionary mapping original symbols to dict containing approved_symbol and hgnc_id

standardize_symbols_batch cached

standardize_symbols_batch(symbols)

Standardize multiple gene symbols using HGNC batch API.

This method now constructs a proper GET request with an 'OR' query.

Parameters:

Name	Type	Description	Default
symbols	tuple[str, ...]	Tuple of gene symbols (tuple for caching compatibility)	required

Returns:

Type	Description
dict[str, dict[str, str | None]]	Dictionary mapping original symbols to dict containing approved_symbol and hgnc_id

symbol_to_hgnc_id cached

symbol_to_hgnc_id(symbol)

Convert a gene symbol to HGNC ID.

Parameters:

Name	Type	Description	Default
symbol	str	Gene symbol	required

Returns:

Type	Description
str | None	HGNC ID (e.g., "HGNC:5") or None if not found