alethiotx.artemis.pathway

 7def get(search, rif = 'generif'):
 8   """
 9   Query the Geneshot API to retrieve gene associations for a search term.
10
11   :param search: The search term to query for gene associations
12   :type search: str
13   :param rif: The type of reference to use for gene associations, defaults to ``generif``
14   :type rif: str, optional
15   :return: A DataFrame containing gene associations with columns for gene symbols (index),
16            gene_count (number of associations), and rank (relevance ranking)
17   :rtype: pandas.DataFrame
18
19   :raises requests.exceptions.RequestException: If the API request fails
20
21   **Example**
22   >>> df = get_pathway_genes('cancer')
23   >>> print(df.head())
24
25   .. note::
26      Gene symbols containing hyphens (-) or underscores (_) are filtered out from the results.
27
28   """
29   GENESHOT_URL = 'https://maayanlab.cloud/geneshot/api/search'
30   payload = {"rif": rif, "term": search}
31   response = requests.post(GENESHOT_URL, json=payload)
32   data = json.loads(response.text)
33   d = DataFrame(data)
34   d['rank'] = d['gene_count'].apply(lambda x: x[1])
35   d['gene_count'] = d['gene_count'].apply(lambda x: x[0])
36   d = d[(~d.index.str.contains('-')) & (~d.index.str.contains('_'))]
37   return d

39def load(date = '2025-11-11', n = 100):
40   """
41   Retrieve pathway genes for multiple disease types from S3 storage.
42
43   This function reads CSV files containing pathway gene data for various diseases,
44   sorts them by gene count and rank, and returns the top N pathways for each disease.
45
46   :param date: Date string in ``YYYY-MM-DD`` format representing the data version,
47               defaults to ``2025-11-11``
48   :type date: str, optional
49   :param n: Number of top pathways to retrieve for each disease, defaults to 100
50   :type n: int, optional
51
52   :return: A tuple containing lists of pathway indices for each disease type in the
53            following order: (breast, lung, prostate, melanoma, bowel, diabetes,
54            cardiovascular)
55   :rtype: tuple[list, list, list, list, list, list, list]
56
57   :raises FileNotFoundError: If the specified CSV files do not exist in S3
58   :raises ValueError: If the CSV files are malformed or missing required columns
59
60   **Example**
61   >>> breast, lung, prostate, melanoma, bowel, diabetes, cardio = load_pathway_genes(
62   ...     date='2025-11-11', n=50
63   ... )
64   >>> len(breast)
65   50
66
67   .. note::
68   
69      The function expects CSV files to be located at
70      ``s3://alethiotx-artemis/data/pathway_genes/{date}/{disease}.csv``
71
72   .. note::
73
74      Each CSV file must contain ``gene_count`` and ``rank`` columns for sorting
75
76   """
77   breast = read_csv('s3://alethiotx-artemis/data/pathway_genes/' + date + '/breast.csv', index_col = 0)
78   breast = breast.sort_values(['gene_count', 'rank'], ascending=False).head(n).sort_index().index.tolist()
79   lung = read_csv('s3://alethiotx-artemis/data/pathway_genes/' + date + '/lung.csv', index_col = 0)
80   lung = lung.sort_values(['gene_count', 'rank'], ascending=False).head(n).sort_index().index.tolist()
81   bowel = read_csv('s3://alethiotx-artemis/data/pathway_genes/' + date + '/bowel.csv', index_col = 0)
82   bowel = bowel.sort_values(['gene_count', 'rank'], ascending=False).head(n).sort_index().index.tolist()
83   prostate = read_csv('s3://alethiotx-artemis/data/pathway_genes/' + date + '/prostate.csv', index_col = 0)
84   prostate = prostate.sort_values(['gene_count', 'rank'], ascending=False).head(n).sort_index().index.tolist()
85   melanoma = read_csv('s3://alethiotx-artemis/data/pathway_genes/' + date + '/melanoma.csv', index_col = 0)
86   melanoma = melanoma.sort_values(['gene_count', 'rank'], ascending=False).head(n).sort_index().index.tolist()
87   diabetes = read_csv('s3://alethiotx-artemis/data/pathway_genes/' + date + '/diabetes.csv', index_col = 0)
88   diabetes = diabetes.sort_values(['gene_count', 'rank'], ascending=False).head(n).sort_index().index.tolist()
89   cardiovascular = read_csv('s3://alethiotx-artemis/data/pathway_genes/' + date + '/cardiovascular.csv', index_col = 0)
90   cardiovascular = cardiovascular.sort_values(['gene_count', 'rank'], ascending=False).head(n).sort_index().index.tolist()
91
92   return (breast, lung, prostate, melanoma, bowel, diabetes, cardiovascular)

 94def unique(genes: list, overlap = 1, common_genes = []):
 95    """
 96    Remove overlapping genes from pathway gene lists.
 97    This function identifies genes that appear in multiple pathways (based on the
 98    specified overlap threshold) and removes them from each pathway's gene list,
 99    returning uniquified pathway gene lists.
100    :param genes: A list of gene lists, where each inner list represents genes
101                  associated with a particular pathway.
102    :type genes: list
103    :param overlap: The minimum number of pathways a gene must appear in to be
104                    considered overlapping and removed. Defaults to 1.
105    :type overlap: int, optional
106    :param common_genes: A list of genes that should be considered as commonly
107                         overlapping regardless of their occurrence count.
108    :type common_genes: list, optional
109    :return: A copy of the input gene lists with overlapping genes removed from
110             each pathway.
111    :rtype: list
112
113    **Example**
114    >>> genes = [['GENE1', 'GENE2', 'GENE3'], ['GENE2', 'GENE4'], ['GENE3', 'GENE5']]
115    >>> uniquify_pathway_genes(genes, overlap=2)
116    [['GENE1'], ['GENE4'], ['GENE5']]
117    """
118    overlapping_genes = find_overlapping_genes(genes, overlap = overlap, common_genes = common_genes)
119    
120    res = genes.copy()
121
122    for n, y in enumerate(res):
123        res[n] = [x for x in y if x not in overlapping_genes]
124
125    return(res)