alethiotx.artemis.hgnc

12def download(
13    gene_has_family_url="https://storage.googleapis.com/public-download-files/hgnc/csv/csv/genefamily_db_tables/gene_has_family.csv",
14    family_url="https://storage.googleapis.com/public-download-files/hgnc/csv/csv/genefamily_db_tables/family.csv",
15    hgnc_complete_url="https://storage.googleapis.com/public-download-files/hgnc/tsv/tsv/hgnc_complete_set.txt"
16):
17    """
18    Download HGNC (HUGO Gene Nomenclature Committee) data tables.
19    This function downloads three datasets from the HGNC public repository:
20    gene-family associations, family definitions, and the complete gene set.
21    :param gene_has_family_url: URL to the gene_has_family CSV file containing
22        gene-to-family associations, defaults to HGNC public storage URL
23    :type gene_has_family_url: str, optional
24    :param family_url: URL to the family CSV file containing family definitions,
25        defaults to HGNC public storage URL
26    :type family_url: str, optional
27    :param hgnc_complete_url: URL to the complete HGNC dataset in TSV format,
28        defaults to HGNC public storage URL
29    :type hgnc_complete_url: str, optional
30    :return: A tuple containing three pandas DataFrames:
31    - gene_has_family: DataFrame with gene-to-family associations
32    - family: DataFrame with family information
33    - hgnc_data: DataFrame with complete HGNC gene set
34    :rtype: tuple[pandas.DataFrame, pandas.DataFrame, pandas.DataFrame]
35    :raises requests.exceptions.RequestException: If download fails
36    :raises pandas.errors.ParserError: If CSV/TSV parsing fails
37    Example
38    -------
39    >>> gene_has_family, family, hgnc_data = download()
40    Downloading HGNC gene_has_family table...
41    Downloading HGNC family table...
42    Downloading HGNC complete set (this may take a moment)...
43    """
44    print("Downloading HGNC gene_has_family table...")
45    gene_has_family = pd.read_csv(gene_has_family_url)
46    
47    print("Downloading HGNC family table...")
48    family = pd.read_csv(family_url)
49    
50    print("Downloading HGNC complete set (this may take a moment)...")
51    hgnc_data = pd.read_csv(hgnc_complete_url, sep='\t', low_memory=False)
52    
53    return gene_has_family, family, hgnc_data

 55def process(gene_has_family, family, hgnc_data):
 56    """
 57    Process HGNC gene family data and create detailed mappings.
 58    This function processes HGNC (HUGO Gene Nomenclature Committee) data to analyze
 59    gene family relationships. It extracts numeric HGNC IDs, counts genes per family,
 60    and creates comprehensive gene-to-family mappings with associated metadata.
 61    :param gene_has_family: DataFrame containing gene-to-family relationships with columns
 62                            'hgnc_id' and 'family_id'
 63    :type gene_has_family: pandas.DataFrame
 64    :param family: DataFrame containing family information with columns 'id', 'abbreviation',
 65                   and 'name'
 66    :type family: pandas.DataFrame
 67    :param hgnc_data: DataFrame containing HGNC gene information with columns 'hgnc_id',
 68                      'symbol', 'name', 'locus_group', and 'locus_type'
 69    :type hgnc_data: pandas.DataFrame
 70    :return: A tuple containing:
 71    - ``family_summary``: DataFrame with family information and gene counts, sorted by
 72    total_genes_in_family in descending order
 73    - ``gene_family_mapping``: DataFrame with detailed gene-to-family mappings including
 74    gene symbols, names, locus information, and family details
 75    :rtype: tuple[pandas.DataFrame, pandas.DataFrame]
 76    :raises ValueError: If HGNC IDs cannot be converted to numeric format
 77    .. note::
 78       The function expects HGNC IDs in the format "HGNC:12345" in the hgnc_data DataFrame.
 79       These are converted to numeric values for processing.
 80    .. note::
 81       Progress information is printed to stdout during processing.
 82    """
 83    print("\nProcessing HGNC data...")
 84    
 85    # Extract numeric HGNC ID from "HGNC:12345" format
 86    hgnc_data['hgnc_id_numeric'] = hgnc_data['hgnc_id'].str.replace('HGNC:', '').astype(int)
 87    
 88    # Count genes per family
 89    gene_counts = gene_has_family.groupby('family_id').size().reset_index(name='total_genes_in_family')
 90    
 91    # Add gene counts to family table
 92    family_summary = family.merge(gene_counts, left_on='id', right_on='family_id', how='left')
 93    family_summary['total_genes_in_family'] = family_summary['total_genes_in_family'].fillna(0).astype(int)
 94    
 95    # Sort by number of genes
 96    family_summary = family_summary.sort_values('total_genes_in_family', ascending=False)
 97    
 98    print(f"  Found {len(family_summary)} gene families")
 99    print(f"  Total genes with family assignments: {len(gene_has_family)}")
100    
101    # Create detailed gene-to-family mapping
102    gene_family_mapping = gene_has_family.merge(
103        hgnc_data[['hgnc_id_numeric', 'symbol', 'name', 'locus_group', 'locus_type']], 
104        left_on='hgnc_id',
105        right_on='hgnc_id_numeric',
106        how='left'
107    ).merge(
108        family[['id', 'abbreviation', 'name']], 
109        left_on='family_id', 
110        right_on='id',
111        how='left',
112        suffixes=('_gene', '_family')
113    )
114    
115    print(f"  Created mapping for {len(gene_family_mapping)} gene-family pairs")
116    
117    return family_summary, gene_family_mapping