pori-python 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (49) hide show
  1. pori_python/__init__.py +1 -0
  2. pori_python/graphkb/__init__.py +2 -0
  3. pori_python/graphkb/constants.py +220 -0
  4. pori_python/graphkb/genes.py +540 -0
  5. pori_python/graphkb/match.py +710 -0
  6. pori_python/graphkb/py.typed +0 -0
  7. pori_python/graphkb/statement.py +48 -0
  8. pori_python/graphkb/util.py +523 -0
  9. pori_python/graphkb/vocab.py +198 -0
  10. pori_python/ipr/__init__.py +0 -0
  11. pori_python/ipr/annotate.py +373 -0
  12. pori_python/ipr/connection.py +214 -0
  13. pori_python/ipr/constants.py +9 -0
  14. pori_python/ipr/inputs.py +593 -0
  15. pori_python/ipr/ipr.py +390 -0
  16. pori_python/ipr/main.py +512 -0
  17. pori_python/ipr/py.typed +0 -0
  18. pori_python/ipr/summary.py +412 -0
  19. pori_python/ipr/therapeutic_options.py +83 -0
  20. pori_python/ipr/util.py +173 -0
  21. pori_python/types.py +177 -0
  22. pori_python-0.1.0.dist-info/LICENSE +674 -0
  23. pori_python-0.1.0.dist-info/METADATA +151 -0
  24. pori_python-0.1.0.dist-info/RECORD +49 -0
  25. pori_python-0.1.0.dist-info/WHEEL +5 -0
  26. pori_python-0.1.0.dist-info/dependency_links.txt +1 -0
  27. pori_python-0.1.0.dist-info/entry_points.txt +2 -0
  28. pori_python-0.1.0.dist-info/top_level.txt +2 -0
  29. tests/__init__.py +0 -0
  30. tests/test_graphkb/__init__.py +0 -0
  31. tests/test_graphkb/data.py +78 -0
  32. tests/test_graphkb/test_genes.py +306 -0
  33. tests/test_graphkb/test_graphkb.py +32 -0
  34. tests/test_graphkb/test_match.py +662 -0
  35. tests/test_graphkb/test_statement.py +100 -0
  36. tests/test_graphkb/test_util.py +151 -0
  37. tests/test_graphkb/test_vocab.py +85 -0
  38. tests/test_ipr/__init__.py +0 -0
  39. tests/test_ipr/constants.py +3 -0
  40. tests/test_ipr/test_annotate.py +149 -0
  41. tests/test_ipr/test_connection.py +97 -0
  42. tests/test_ipr/test_inputs.py +295 -0
  43. tests/test_ipr/test_ipr.py +338 -0
  44. tests/test_ipr/test_main.py +154 -0
  45. tests/test_ipr/test_probe.py +72 -0
  46. tests/test_ipr/test_summary.py +157 -0
  47. tests/test_ipr/test_upload.py +274 -0
  48. tests/test_ipr/test_util.py +29 -0
  49. tests/test_ipr/util.py +9 -0
pori_python/ipr/ipr.py ADDED
@@ -0,0 +1,390 @@
1
+ """
2
+ Contains functions specific to formatting reports for IPR that are unlikely to be used
3
+ by other reporting systems
4
+ """
5
+
6
+ from __future__ import annotations
7
+
8
+ from typing import Dict, Iterable, List, Sequence, Set, Tuple, cast
9
+
10
+ from pori_python.graphkb import GraphKBConnection
11
+ from pori_python.graphkb import statement as gkb_statement
12
+ from pori_python.graphkb import vocab as gkb_vocab
13
+ from pori_python.types import (
14
+ Hashabledict,
15
+ ImageDefinition,
16
+ IprFusionVariant,
17
+ IprGene,
18
+ IprVariant,
19
+ KbMatch,
20
+ Statement,
21
+ Variant,
22
+ )
23
+
24
+ from .constants import GERMLINE_BASE_TERMS, VARIANT_CLASSES
25
+ from .util import find_variant, logger
26
+
27
+
28
+ def display_evidence_levels(statement: Statement) -> str:
29
+ result = []
30
+ for evidence_level in statement.get("evidenceLevel", []) or []:
31
+ if isinstance(evidence_level, str):
32
+ result.append(evidence_level)
33
+ elif "displayName" in evidence_level:
34
+ result.append(evidence_level["displayName"])
35
+ return ";".join(sorted(result))
36
+
37
+
38
+ def filter_structural_variants(
39
+ structural_variants: List[IprFusionVariant],
40
+ kb_matches: List[KbMatch] | List[Hashabledict],
41
+ gene_annotations: List[IprGene],
42
+ ) -> List[IprFusionVariant]:
43
+ """
44
+ Filter structural variants to remove non-high quality events unless they are matched/annotated or
45
+ they involve a gene that is a known fusion partner
46
+ """
47
+ matched_svs = {match["variant"] for match in kb_matches if match["variantType"] == "sv"}
48
+ fusion_genes = {
49
+ gene["name"] for gene in gene_annotations if gene.get("knownFusionPartner", False)
50
+ }
51
+
52
+ result = []
53
+
54
+ for structural_variant in structural_variants:
55
+ if any(
56
+ [
57
+ structural_variant["highQuality"],
58
+ structural_variant["key"] in matched_svs,
59
+ structural_variant["gene1"] in fusion_genes,
60
+ structural_variant["gene2"] in fusion_genes,
61
+ ]
62
+ ):
63
+ result.append(structural_variant)
64
+ return result
65
+
66
+
67
+ def get_evidencelevel_mapping(graphkb_conn: GraphKBConnection) -> Dict[str, str]:
68
+ """IPR evidence level equivalents of GraphKB evidence returned as a dictionary.
69
+
70
+ Args:
71
+ graphkb_conn (GraphKBConnection): the graphkb api connection object
72
+
73
+ Returns:
74
+ dictionary mapping all EvidenceLevel RIDs to corresponding IPR EvidenceLevel displayName
75
+ """
76
+ # Get all EvidenceLevel from GraphKB
77
+ # Note: not specifying any returnProperties allows for retreiving in/out_CrossReferenceOf
78
+ evidence_levels = graphkb_conn.query({"target": "EvidenceLevel"})
79
+
80
+ # Map EvidenceLevel RIDs to list of incoming CrossReferenceOf
81
+ evidence_levels_mapping = dict(
82
+ map(lambda d: (d["@rid"], d.get("in_CrossReferenceOf", [])), evidence_levels)
83
+ )
84
+
85
+ # Filter IPR EvidenceLevel and map each outgoing CrossReferenceOf to displayName
86
+ ipr_source_rid = graphkb_conn.get_source("ipr")["@rid"]
87
+ ipr_evidence_levels = filter(lambda d: d.get("source") == ipr_source_rid, evidence_levels)
88
+ cross_references_mapping: Dict[str, str] = dict()
89
+ ipr_rids_to_displayname: Dict[str, str] = dict()
90
+ for level in ipr_evidence_levels:
91
+ d = map(lambda i: (i, level["displayName"]), level.get("out_CrossReferenceOf", [])) # type: ignore
92
+ cross_references_mapping.update(d)
93
+ ipr_rids_to_displayname[level["@rid"]] = level["displayName"] # type: ignore
94
+
95
+ # Update EvidenceLevel mapping to corresponding IPR EvidenceLevel displayName
96
+ def link_refs(refs) -> Tuple[str, str]:
97
+ for rid in refs[1]:
98
+ if cross_references_mapping.get(rid):
99
+ return (refs[0], cross_references_mapping[rid])
100
+ if refs[0] in ipr_rids_to_displayname: # self-referencing IPR levels
101
+ return (refs[0], ipr_rids_to_displayname[refs[0]])
102
+ return (refs[0], "")
103
+
104
+ evidence_levels_mapping = dict(map(link_refs, evidence_levels_mapping.items()))
105
+ evidence_levels_mapping[""] = ""
106
+
107
+ return evidence_levels_mapping # type: ignore
108
+
109
+
110
+ def convert_statements_to_alterations(
111
+ graphkb_conn: GraphKBConnection,
112
+ statements: List[Statement],
113
+ disease_name: str,
114
+ variant_matches: Iterable[str],
115
+ ) -> List[KbMatch]:
116
+ """Convert statements matched from graphkb into IPR equivalent representations.
117
+
118
+ Args:
119
+ graphkb_conn: the graphkb connection object
120
+ statements: list of statement records from graphkb
121
+ disease_name: name of the cancer type for the patient being reported on
122
+ variant_matches: the list of RIDs the variant matched for these statements
123
+
124
+ Raises:
125
+ ValueError: could not find the disease type in GraphKB
126
+
127
+ Returns:
128
+ IPR graphkb row representations
129
+
130
+ Notes:
131
+ - only report disease matched prognostic markers https://www.bcgsc.ca/jira/browse/GERO-72 and GERO-196
132
+ """
133
+ disease_matches = {
134
+ r["@rid"]
135
+ for r in gkb_vocab.get_term_tree(graphkb_conn, disease_name, ontology_class="Disease")
136
+ }
137
+
138
+ if not disease_matches:
139
+ raise ValueError(f"failed to match disease ({disease_name}) to graphkb")
140
+
141
+ rows = []
142
+ ev_map = get_evidencelevel_mapping(graphkb_conn)
143
+ # GERO-318 - add all IPR-A evidence equivalents to the approvedTherapy flag
144
+ approved = set([ev for (ev, ipr) in ev_map.items() if ipr == "IPR-A"])
145
+
146
+ # get the recruitment status for any trial associated with a statement
147
+ clinical_trials = [
148
+ s["subject"]["@rid"] for s in statements if s["subject"]["@class"] == "ClinicalTrial"
149
+ ]
150
+ recruitment_statuses = {}
151
+ if clinical_trials:
152
+ clinical_trials = list(set(clinical_trials))
153
+ for rid in clinical_trials:
154
+ query_result = graphkb_conn.query(
155
+ {
156
+ "target": {"target": "ClinicalTrial", "filters": {"@rid": rid}},
157
+ "returnProperties": ["@rid", "recruitmentStatus"],
158
+ }
159
+ )
160
+ if query_result:
161
+ recruitment_statuses[rid] = query_result[0]["recruitmentStatus"] # type: ignore
162
+
163
+ for statement in statements:
164
+ variants = [
165
+ cast(Variant, c) for c in statement["conditions"] if c["@class"] in VARIANT_CLASSES
166
+ ]
167
+ diseases = [c for c in statement["conditions"] if c["@class"] == "Disease"]
168
+ disease_match = len(diseases) == 1 and diseases[0]["@rid"] in disease_matches
169
+ pmid = ";".join([e["displayName"] for e in statement["evidence"]])
170
+
171
+ ipr_section = gkb_statement.categorize_relevance(
172
+ graphkb_conn, statement["relevance"]["@rid"]
173
+ )
174
+ approved_therapy = False
175
+ if ipr_section == "therapeutic":
176
+ for level in statement["evidenceLevel"] or []:
177
+ if level["@rid"] in approved:
178
+ approved_therapy = True
179
+ break
180
+
181
+ if ipr_section == "prognostic" and not disease_match:
182
+ continue # GERO-72 / GERO-196
183
+
184
+ evidence_level_str = display_evidence_levels(statement)
185
+ evidence_levels = statement.get("evidenceLevel") or []
186
+ ipr_evidence_levels = [ev_map[el.get("@rid", "")] for el in evidence_levels if el]
187
+ ipr_evidence_levels_str = ";".join(sorted(set([el for el in ipr_evidence_levels])))
188
+
189
+ for variant in variants:
190
+ if variant["@rid"] not in variant_matches:
191
+ continue
192
+ row = KbMatch(
193
+ {
194
+ "approvedTherapy": approved_therapy or False,
195
+ "category": ipr_section or "unknown",
196
+ "context": (
197
+ statement["subject"]["displayName"] if statement["subject"] else ""
198
+ ),
199
+ "kbContextId": (statement["subject"]["@rid"] if statement["subject"] else ""),
200
+ "disease": ";".join(sorted(d.get("displayName", "") for d in diseases)),
201
+ "evidenceLevel": evidence_level_str or "",
202
+ "iprEvidenceLevel": ipr_evidence_levels_str or "",
203
+ "kbStatementId": statement["@rid"],
204
+ "kbVariant": str(variant.get("displayName", "")) or "",
205
+ "variant": str(variant.get("displayName", "")) or "",
206
+ "variantType": "",
207
+ "kbVariantId": variant["@rid"],
208
+ "matchedCancer": disease_match,
209
+ "reference": pmid,
210
+ "relevance": statement["relevance"]["displayName"],
211
+ "kbRelevanceId": statement["relevance"]["@rid"],
212
+ "externalSource": (
213
+ str(statement["source"].get("displayName", ""))
214
+ if statement["source"]
215
+ else ""
216
+ ),
217
+ "externalStatementId": statement.get("sourceId", "") or "",
218
+ "reviewStatus": statement.get("reviewStatus", "") or "",
219
+ "kbData": {},
220
+ }
221
+ )
222
+ if statement["relevance"]["name"] == "eligibility":
223
+ row["kbData"]["recruitment_status"] = recruitment_statuses.get(
224
+ row["kbContextId"], "not found"
225
+ )
226
+ rows.append(row)
227
+ return rows
228
+
229
+
230
+ def select_expression_plots(
231
+ kb_matches: List[KbMatch] | List[Hashabledict], all_variants: Sequence[IprVariant]
232
+ ) -> List[ImageDefinition]:
233
+ """
234
+ Given the list of expression variants, determine which expression
235
+ historgram plots should be included in the IPR upload. This filters them
236
+ based on the graphkb annotations to avoid loading more images than are required
237
+
238
+ Args:
239
+ kb_matches: the IPR graphkb annoations for all variants
240
+ expression_variants: the list of expression variants loaded
241
+
242
+ Returns:
243
+ list of expression images to be loaded by IPR
244
+ """
245
+
246
+ selected_variants = {
247
+ (match["variantType"], match["variant"])
248
+ for match in kb_matches
249
+ if match["category"] == "therapeutic"
250
+ }
251
+ images_by_gene: Dict[str, ImageDefinition] = {}
252
+ selected_genes = set()
253
+ for variant in all_variants:
254
+ if (variant["variantType"], variant["key"]) in selected_variants:
255
+ for key in ["gene", "gene1", "gene2"]:
256
+ gene = variant.get(key)
257
+ if gene:
258
+ selected_genes.add(str(gene))
259
+ gene = str(variant.get("gene", ""))
260
+ hist = str(variant.get("histogramImage", ""))
261
+ if hist:
262
+ images_by_gene[gene] = ImageDefinition({"key": f"expDensity.{gene}", "path": hist})
263
+ return [images_by_gene[gene] for gene in selected_genes if gene in images_by_gene]
264
+
265
+
266
+ def create_key_alterations(
267
+ kb_matches: List[Hashabledict], all_variants: Sequence[IprVariant]
268
+ ) -> Tuple[List[Dict], Dict]:
269
+ """Create the list of significant variants matched by the KB.
270
+
271
+ This list of matches is also used to create the variant counts.
272
+ """
273
+ alterations = []
274
+ type_mapping = {
275
+ "mut": "smallMutations",
276
+ "cnv": "CNVs",
277
+ "sv": "SVs",
278
+ "exp": "expressionOutliers",
279
+ }
280
+ counts: Dict[str, Set] = {v: set() for v in type_mapping.values()}
281
+ skipped_variant_types = []
282
+ for kb_match in kb_matches:
283
+ variant_type = kb_match["variantType"]
284
+ variant_key = kb_match["variant"]
285
+ if kb_match["category"] == "unknown":
286
+ continue
287
+
288
+ if variant_type not in type_mapping.keys():
289
+ if variant_type not in skipped_variant_types:
290
+ skipped_variant_types.append(variant_type)
291
+ logger.warning(
292
+ f"No summary key alterations for {variant_type}. Skipping {variant_key}"
293
+ )
294
+ continue
295
+ try:
296
+ variant = find_variant(all_variants, variant_type, variant_key)
297
+ except KeyError as err:
298
+ logger.error(err)
299
+ logger.error(f"No variant match found for {variant_key}")
300
+ continue
301
+
302
+ counts[type_mapping[variant_type]].add(variant_key)
303
+
304
+ if variant_type == "exp":
305
+ alterations.append(f'{variant.get("gene","")} ({variant.get("expressionState")})')
306
+ elif variant_type == "cnv":
307
+ alterations.append(f'{variant.get("gene","")} ({variant.get("cnvState")})')
308
+ # only show germline if relevant
309
+ elif kb_match["category"] in GERMLINE_BASE_TERMS and variant.get("germline"):
310
+ alterations.append(f"germline {variant['variant']}")
311
+ else:
312
+ alterations.append(variant["variant"])
313
+
314
+ counted_variants = set.union(*counts.values())
315
+ counts["variantsUnknown"] = set()
316
+
317
+ # count the un-matched variants
318
+ for variant in all_variants:
319
+ if variant["variant"] and variant["key"] not in counted_variants:
320
+ counts["variantsUnknown"].add(variant["key"])
321
+
322
+ return (
323
+ [{"geneVariant": alt} for alt in set(alterations)],
324
+ {k: len(v) for k, v in counts.items()},
325
+ )
326
+
327
+
328
+ def germline_kb_matches(
329
+ kb_matches: List[Hashabledict], all_variants: Sequence[IprVariant], assume_somatic: bool = True
330
+ ) -> List[Hashabledict]:
331
+ """Filter kb_matches for matching to germline or somatic events using the 'germline' optional property.
332
+
333
+ Statements related to pharmacogenomic toxicity or cancer predisposition are only relevant if
334
+ the variant is present in the germline of the patient.
335
+ Other statements, such as diagnostic or recurrent oncogenic mutations, are only relevant as
336
+ somatic events in cancer. Germline variants are excluded from these matches.
337
+
338
+ Params:
339
+ kb_matches: KbMatch statements to be filtered. 'variant' properties must match 'key' in all_variants.
340
+ all_variants: IprVariants, with a 'germline' property, that were used for kb_matches creation.
341
+ assume_somatic: Whether to assume somatic or germline when no 'germline' property exists in the variant.
342
+ Returns:
343
+ filtered list of kb_matches
344
+ """
345
+ ret_list = []
346
+ germ_alts = [alt for alt in kb_matches if alt["category"] in GERMLINE_BASE_TERMS]
347
+ somatic_alts = [alt for alt in kb_matches if alt not in germ_alts]
348
+ if germ_alts:
349
+ logger.info(f"checking germline status of {GERMLINE_BASE_TERMS}")
350
+ for alt in germ_alts:
351
+ var_list = [v for v in all_variants if v["key"] == alt["variant"]]
352
+ germline_var_list = [v for v in var_list if v.get("germline")]
353
+ unknown_var_list = [v for v in var_list if "germline" not in v]
354
+ if germline_var_list:
355
+ logger.debug(
356
+ f"germline kbStatementId:{alt['kbStatementId']}: {alt['kbVariant']} {alt['category']}"
357
+ )
358
+ ret_list.append(alt)
359
+ elif unknown_var_list:
360
+ logger.warning(
361
+ f"germline no data fail for: {alt['kbStatementId']}: {alt['kbVariant']} {alt['category']}"
362
+ )
363
+ if not assume_somatic:
364
+ logger.debug(
365
+ f"Keeping unverified match to germline kbStatementId:{alt['kbStatementId']}: {alt['kbVariant']} {alt['category']}"
366
+ )
367
+ ret_list.append(alt)
368
+ else:
369
+ logger.debug(
370
+ f"Dropping unverified match to germline kbStatementId:{alt['kbStatementId']}: {alt['kbVariant']} {alt['category']}"
371
+ )
372
+ else:
373
+ logger.debug(
374
+ f"Dropping somatic match to germline kbStatementId:{alt['kbStatementId']}: {alt['kbVariant']} {alt['category']}"
375
+ )
376
+ if somatic_alts:
377
+ # Remove any matches to germline events
378
+ for alt in somatic_alts:
379
+ var_list = [v for v in all_variants if v["key"] == alt["variant"]]
380
+ somatic_var_list = [v for v in var_list if not v.get("germline", not assume_somatic)]
381
+ if var_list and not somatic_var_list:
382
+ logger.debug(
383
+ f"Dropping germline match to somatic statement kbStatementId:{alt['kbStatementId']}: {alt['kbVariant']} {alt['category']}"
384
+ )
385
+ elif somatic_var_list:
386
+ ret_list.append(alt) # match to somatic variant
387
+ else:
388
+ ret_list.append(alt) # alteration not in any specific keys matches to check.
389
+
390
+ return ret_list