add methods

methods/gdc_api_calls.py

@@ -0,0 +1,634 @@
+#!/usr/bin/env python3
+import ast
+import glob
+import json
+import os
+from functools import reduce
+from pathlib import Path
+
+import pandas as pd
+import requests
+
+proj_root = Path(__file__).resolve().parent.parent
+
+
+# match "lymphoid leukemia" in query to "lymphoid leukemias" in GDC disease_type
+# load project_mappings
+# the function to create this tsv file is a one-time run, found as one of the api functions below
+project_mappings = pd.read_csv(
+    os.path.join(proj_root, "csvs", "gdc_projects.tsv"), 
+    sep="\t", index_col=0, names=["project", "desc"]
+)
+project_mappings["desc"] = project_mappings["desc"].apply(ast.literal_eval)
+project_mappings = project_mappings["desc"].to_dict()
+
+
+def get_gene_mutation_data(start, stop, step):
+    # cannot query the entire thing at once, need to do it in parts
+    for mini_stop in range(start, stop, step):
+        if mini_stop != 0:
+            # curl_cmd = "https://api.gdc.cancer.gov/ssms?fields=gene_aa_change&from={}&size={}".format(start, mini_stop)
+            # print('curl cmd {}'.format(curl_cmd))
+            response = requests.get(curl_cmd)
+            out_file = "_".join([str(start), str(mini_stop), "gene.mutation.txt"])
+            with open(out_file, "w") as response_out:
+                response_out.write(response.text)
+            start = mini_stop
+    # final curl_cmd
+    curl_cmd = (
+        "https://api.gdc.cancer.gov/ssms?fields=gene_aa_change&from={}&size={}".format(
+            start, stop
+        )
+    )
+    # print('curl cmd {}'.format(curl_cmd))
+    response = requests.get(curl_cmd)
+    out_file = "_".join([str(start), str(stop), "gene.mutation.txt"])
+    with open(out_file, "w") as response_out:
+        response_out.write(response.text)
+
+
+def process_gene_mutation_data():
+    gdc_genes = {}
+    gene_mutation_data_files = glob.glob("*gene.mutation.txt")
+    # print('gene_mutation_data_files {}'.format(gene_mutation_data_files))
+    for f in gene_mutation_data_files:
+        # print('processing file {}'.format(f))
+        with open(f, "r") as f_in:
+            data = json.load(f_in)
+            for item in data["data"]["hits"]:
+                for gene_aa_change in item["gene_aa_change"]:
+                    gene, mutation = gene_aa_change.split(" ")
+                    if not gene in gdc_genes:
+                        gdc_genes[gene] = []
+                    if not mutation in gdc_genes[gene]:
+                        gdc_genes[gene].append(mutation)
+
+    with open("gdc_genes_mutations.json", "w") as f_out:
+        json.dump(gdc_genes, f_out, indent=4)
+
+
+# this function creates the project mappings tsv file
+# only to be run once
+def get_gdc_project_ids(start, stop):
+    project_mappings = {}
+    curl_cmd = "https://api.gdc.cancer.gov/projects?fields=project_id,disease_type,primary_site,name&from={}&size={}".format(
+        start, stop
+    )
+    # print('curl cmd {}'.format(curl_cmd))
+    out_file = "gdc_projects.tsv"
+    try:
+        response = requests.get(curl_cmd)
+        # print('status code {}'.format(response.status_code))
+        with open(out_file, "w") as response_out:
+            for item in response.json()["data"]["hits"]:
+                disease_type_and_name = item["disease_type"] + [item["name"]]
+                line = f"{item['project_id']}\t{disease_type_and_name}\n"
+                response_out.write(line)
+                project_mappings[item["project_id"]] = disease_type_and_name
+        # print('project_mappings {}'.format(project_mappings))
+    except Exception as e:
+        print("unable to execute GDC API request {}".format(str(e)))
+    return project_mappings
+
+
+def get_ssm_id(gene, mutation):
+    ssm_id_endpt = "https://api.gdc.cancer.gov/ssms"
+    fields = ["mutation_type"]
+    fields = ",".join(fields)
+    expand = ["consequence.transcript"]
+    filters = {
+        "op": "=",
+        "content": {"field": "ssms.gene_aa_change", "value": "[gene][mutation]"},
+    }
+    filters["content"]["value"] = gene + " " + mutation
+    # print('filters {}'.format(filters))
+    params = {
+        "filters": json.dumps(filters),
+        "fields": fields,
+        "expand": expand,
+        "size": 10,
+    }
+    try:
+        response = requests.get(ssm_id_endpt, params=params)
+        response_json = json.loads(response.content)
+        ssm_id = response_json["data"]["hits"][0]["id"]
+    except Exception as e:
+        print("unable to execute GDC API request {}".format(str(e)))
+        ssm_id = None
+    return ssm_id
+
+
+def get_ssm_counts(ssm_id):
+    # get project level counts of ssm
+    ssm_counts_by_project = {}
+
+    ssm_occurrences_endpt = "https://api.gdc.cancer.gov/ssm_occurrences"
+    fields = ["case.project.project_id", "case.case_id"]
+    fields = ",".join(fields)
+    filters = {"op": "=", "content": {"field": "ssm.ssm_id", "value": ssm_id}}
+    params = {"filters": json.dumps(filters), "fields": fields, "size": 1000}
+    try:
+        response = requests.get(ssm_occurrences_endpt, params=params)
+        ssm_counts = json.loads(response.content)
+        for item in ssm_counts["data"]["hits"]:
+            project_name = item["case"]["project"]["project_id"]
+            case_id_list = "case_id_list"
+            if not project_name in ssm_counts_by_project:
+                ssm_counts_by_project[project_name] = {}
+                ssm_counts_by_project[project_name][case_id_list] = []
+            ssm_counts_by_project[project_name][case_id_list].append(
+                item["case"]["case_id"]
+            )
+            ssm_counts_by_project[project_name]["ssm_counts"] = (
+                ssm_counts_by_project[project_name]["ssm_counts"] + 1
+                if "ssm_counts" in ssm_counts_by_project[project_name]
+                else 1
+            )
+    except Exception as e:
+        print("unable to execute GDC API request {}".format(str(e)))
+    return ssm_counts_by_project
+
+
+def get_available_cnv_data_for_project(project):
+    case_ssm_endpt = "https://api.gdc.cancer.gov/case_ssms"
+    fields = ["project.project_id", "available_variation_data"]
+    fields = ",".join(fields)
+    filters = {
+        "op": "and",
+        "content": [
+            {
+                "op": "in",
+                "content": {"field": "available_variation_data", "value": "cnv"},
+            },
+            {"op": "=", "content": {"field": "project.project_id", "value": project}},
+        ],
+    }
+    params = {"filters": json.dumps(filters), "fields": fields, "size": 1000}
+    try:
+        response = requests.get(case_ssm_endpt, params=params)
+        response_json = json.loads(response.content)
+        total_case_count = response_json["data"]["pagination"]["total"]
+    except Exception as e:
+        print("unable to execute GDC API request {}".format(str(e)))
+        total_case_count = 0
+    # print('total case count {}'.format(total_case_count))
+    return total_case_count
+
+
+def get_available_ssm_data_for_project(project):
+    case_ssm_endpt = "https://api.gdc.cancer.gov/case_ssms"
+    fields = ["project.project_id", "available_variation_data"]
+    fields = ",".join(fields)
+
+    filters = {
+        "op": "and",
+        "content": [
+            {
+                "op": "in",
+                "content": {"field": "available_variation_data", "value": "ssm"},
+            },
+            {"op": "=", "content": {"field": "project.project_id", "value": project}},
+        ],
+    }
+    params = {"filters": json.dumps(filters), "fields": fields, "size": 1000}
+    try:
+        response = requests.get(case_ssm_endpt, params=params)
+        response_json = json.loads(response.content)
+        total_case_count = response_json["data"]["pagination"]["total"]
+    except Exception as e:
+        print("unable to execute GDC API request {}".format(str(e)))
+    return total_case_count
+
+
+def get_top_mutated_genes_by_project(cancer_entities, top_k):
+    # need an AI way of recognizing top k from query, here using 10 as default
+    top_mutated_genes_by_project = {}
+    # if cancer_entities is empty, initialize some entities
+    if not cancer_entities:
+        cancer_entities = list(project_mappings.keys())
+
+    for ce in cancer_entities:
+        endpt = "https://api.gdc.cancer.gov/analysis/top_mutated_genes_by_project"
+
+        fields = ["gene_id", "symbol"]
+        fields = ",".join(fields)
+
+        filters = {
+            "op": "and",
+            "content": [
+                {
+                    "op": "in",
+                    "content": {"field": "case.project.project_id", "value": [ce]},
+                }
+            ],
+        }
+        params = {"filters": json.dumps(filters), "fields": fields, "size": 1000}
+        try:
+            response = requests.get(endpt, params=params)
+            response_json = json.loads(response.content)
+            top_mutated_genes_by_project[ce] = response_json["data"]["hits"][:top_k]
+        except Exception as e:
+            print("unable to execute GDC API request {}".format(str(e)))
+    return top_mutated_genes_by_project
+
+
+def return_joint_single_cnv_frequency(cnv, cnv_change, cnv_change_5_category):
+    result_text = []
+    # set category for heterozygous del
+    if not cnv_change_5_category:
+        if cnv_change == "Loss":
+            cnv_change_5_category = "Heterozygous Deletion"
+        # print('formatting results {}'.format(cnv_change_5_category))
+    cnv_freq = {}
+    for ce, v in cnv.items():
+        cnv_freq[ce] = {}
+        genes = list(v.keys())
+        # print('ce, genes {} {}'.format(ce, genes))
+        total_number_of_cases_with_cnv_data = get_available_cnv_data_for_project(ce)
+        # skip if total number of cnv cases from API is 0
+        if not total_number_of_cases_with_cnv_data:
+            continue
+
+        if len(genes) > 1:
+            cases_with_cnvs = [set(cnv[ce][g]["case_id_list"]) for g in genes]
+            shared_cases = list(reduce(lambda x, y: x & y, cases_with_cnvs))
+            # print('shared_cases {}'.format(shared_cases))
+            joint_frequency = round(
+                (len(shared_cases) / total_number_of_cases_with_cnv_data) * 100, 2
+            )
+            result_text.append(
+                "joint frequency in {} is {}%".format(ce, joint_frequency)
+            )
+        else:
+            joint_frequency = 0
+            for k2, v2 in v.items():
+                result_text.append(
+                    "The frequency of {} {} in {} is {}%".format(
+                        k2, cnv_change_5_category, ce, v2["frequency"]
+                    )
+                )
+    return result_text
+
+
+def get_cnv_filter_with_cnv_change_category(cnv_change, ce, ge, cnv_change_5_category):
+
+    filter = {
+        "op": "and",
+        "content": [
+            {"op": "in", "content": {"field": "cnv.cnv_change", "value": [cnv_change]}},
+            {
+                "op": "in",
+                "content": {
+                    "field": "cnv.cnv_change_5_category",
+                    "value": [cnv_change_5_category],
+                },
+            },
+            {
+                "op": "=",
+                "content": {"field": "cnv.consequence.gene.symbol", "value": ge},
+            },
+            {"op": "=", "content": {"field": "case.project.project_id", "value": ce}},
+        ],
+    }
+    return filter
+
+
+def get_freq_cnv_loss_or_gain(gene_entities, cancer_entities, query, cnv_and_ssm_flag):
+    cnv = {}
+    lc_query = query.lower()
+    # need to figure out how to get deletion and gain
+    # V1 is only co-deletion, or co-gain
+    loss_terms = ["loss", "loh", "deletion", "co-deletion", "lost", "LOH"]
+    if any(term in lc_query for term in loss_terms):
+        cnv_change = "Loss"
+        if "homozygous" in lc_query:
+            cnv_change_5_category = "Homozygous Deletion"
+        else:
+            cnv_change_5_category = "Loss"
+    else:
+        cnv_change = "Gain"
+        if "amplification" in lc_query:
+            cnv_change_5_category = "Amplification"
+        else:
+            cnv_change_5_category = "Gain"
+
+    if not cancer_entities:
+        cancer_entities = list(project_mappings.keys())
+
+    # print('cnv change, cnv change 5 category in query {} {}'.format(
+    #  cnv_change, cnv_change_5_category))
+
+    for ce in cancer_entities:
+        for ge in gene_entities:
+            # print('processing {}, {}'.format(ce, ge))
+            endpt = "https://api.gdc.cancer.gov/cnv_occurrences"
+            fields = [
+                "cnv.chromosome",
+                "cnv.cnv_change",
+                "cnv.cnv_change_5_category" "cnv.consequence.gene.symbol",
+                "case.case_id",
+                "case.project.project_id",
+            ]
+            fields = ",".join(fields)
+            filters = get_cnv_filter_with_cnv_change_category(
+                cnv_change, ce, ge, cnv_change_5_category
+            )
+            params = {"filters": json.dumps(filters), "fields": fields, "size": 1000}
+            try:
+                # print('filters {}'.format(json.dumps(filters)))
+                # skip if response not successful
+                response = requests.get(endpt, params=params)
+                response_json = json.loads(response.content)
+            except Exception as e:
+                print("exception: {}".format(str(e)))
+                continue
+
+            total_number_of_cases_with_cnv_data = get_available_cnv_data_for_project(ce)
+            # skip if cannot obtain total # of cnv cases from API
+            if not total_number_of_cases_with_cnv_data:
+                continue
+
+            if not ce in cnv:
+                cnv[ce] = {}
+            if not ge in cnv[ce]:
+                cnv[ce][ge] = {}
+
+            case_id_list = []
+            for item in response_json["data"]["hits"]:
+                if item["case"]["case_id"]:
+                    case_id_list.append(item["case"]["case_id"])
+            number_of_cases_with_cnv_change = len(case_id_list)
+            # print('number of cases with cnv change {}'.format(number_of_cases_with_cnv_change))
+            freq = number_of_cases_with_cnv_change / total_number_of_cases_with_cnv_data
+            cnv[ce][ge]["case_id_list"] = case_id_list
+            cnv[ce][ge]["frequency"] = round(freq * 100, 2)
+
+    # print('debug: cnv {}'.format(cnv))
+    if cnv_and_ssm_flag:
+        return cnv
+    else:
+        result_text = return_joint_single_cnv_frequency(
+            cnv, cnv_change, cnv_change_5_category
+        )
+        cancer_entities = list(cnv.keys())
+        return result_text, cancer_entities
+
+
+def get_msi_frequency(cancer_entities):
+    msi_h_frequency = {}
+    result_text = []
+    # init some starting cancer entities if none
+    if not cancer_entities:
+        cancer_entities = list(project_mappings.keys())
+    for ce in cancer_entities:
+        endpt = "https://api.gdc.cancer.gov/files"
+        fields = [
+            "cases.project.project_id",
+            "msi_score",
+            "msi_status",
+            "experimental_strategy",
+        ]
+        fields = ",".join(fields)
+
+        filters = {
+            "op": "and",
+            "content": [
+                {"op": "=", "content": {"field": "data_format", "value": "BAM"}},
+                {
+                    "op": "in",
+                    "content": {
+                        "field": "experimental_strategy",
+                        "value": ["WXS", "WGS"],
+                    },
+                },
+                {
+                    "op": "in",
+                    "content": {"field": "cases.project.project_id", "value": [ce]},
+                },
+            ],
+        }
+        params = {"filters": json.dumps(filters), "fields": fields, "size": 10000}
+        try:
+            response = requests.get(endpt, params=params)
+            response_json = json.loads(response.content)
+
+            msi_results = []
+            for item in response_json["data"]["hits"]:
+                # only score tumors where MSI status is computed for frequency
+                if "msi_status" in item:
+                    # exclude None
+                    if item['msi_status']:
+                        msi_results.append(item["msi_status"])
+            freq = msi_results.count("MSI") / len(msi_results)
+            msi_h_frequency[ce] = {"frequency": round(freq * 100, 2)}
+            result_text.append(
+                "The frequency of MSI in {} is {}%".format(
+                    ce, msi_h_frequency[ce]["frequency"]
+                )
+            )
+        except Exception as e:
+            print("unable to execute GDC API request {}".format(str(e)))
+    ce_api_success = list(msi_h_frequency.keys())
+    return result_text, ce_api_success
+
+
+def get_ensembl_gene_ids(gene_entities):
+    ensembl_gene_ids = []
+    for ge in gene_entities:
+        endpt = "https://api.gdc.cancer.gov/genes"
+        fields = ["gene_id"]
+        fields = ",".join(fields)
+        filters = {
+            "op": "and",
+            "content": [{"op": "=", "content": {"field": "symbol", "value": ge}}],
+        }
+        params = {"filters": json.dumps(filters), "fields": fields, "size": 100}
+        try:
+            response = requests.get(endpt, params=params)
+            response_json = json.loads(response.content)
+            ensembl_gene_ids.append(response_json["data"]["hits"][0]["gene_id"])
+        except Exception as e:
+            print("unable to execute GDC API request {}".format(str(e)))
+    return ensembl_gene_ids
+
+
+def get_total_variation_data_for_project(project):
+    case_ssm_endpt = "https://api.gdc.cancer.gov/case_ssms"
+    fields = ["project.project_id", "available_variation_data"]
+    fields = ",".join(fields)
+
+    filters = {
+        "op": "and",
+        "content": [
+            {
+                "op": "in",
+                "content": {
+                    "field": "available_variation_data",
+                    "value": ["ssm", "cnv"],
+                },
+            },
+            {"op": "=", "content": {"field": "project.project_id", "value": project}},
+        ],
+    }
+    params = {"filters": json.dumps(filters), "fields": fields, "size": 1000}
+    try:
+        response = requests.get(case_ssm_endpt, params=params)
+        response_json = json.loads(response.content)
+        total_case_count = response_json["data"]["pagination"]["total"]
+    except Exception as e:
+        print("unable to execute GDC API request {}".format(str(e)))
+        total_case_count = 0
+
+    return total_case_count
+
+
+def get_cases_with_ssms_in_a_gene(project, gene_name):
+
+    result = {}
+    endpt = "https://api.gdc.cancer.gov/ssm_occurrences"
+    fields = ["case.case_id"]
+    fields = ",".join(fields)
+
+    filters = {
+        "op": "and",
+        "content": [
+            {
+                "op": "=",
+                "content": {"field": "case.project.project_id", "value": project},
+            },
+            {
+                "op": "in",
+                "content": {
+                    "field": "ssm.consequence.transcript.gene.symbol",
+                    "value": gene_name,
+                },
+            },
+        ],
+    }
+    params = {"filters": json.dumps(filters), "fields": fields, "size": 1000}
+    try:
+        response = requests.get(endpt, params=params)
+        response_json = json.loads(response.content)
+        case_id_list = []
+        for item in response_json["data"]["hits"]:
+            if item["case"]["case_id"]:
+                case_id_list.append(item["case"]["case_id"])
+        result["case_id_list"] = list(set(case_id_list))
+    except Exception as e:
+        print("unable to execute GDC API request {}".format(str(e)))
+    return result
+
+
+def run_cnv_ssm_api(decompose_result, cancer_entities, query):
+    """
+    decompose_result['cnv_and_ssm'] = True
+    decompose_result['cnv_gene'] = cnv_gene.split(':')[1]
+    decompose_result['mut_gene'] = mut_gene.split(':')[1]
+    decompose_result['cnv_change_type'] = match_term
+    """
+    gene_entities = []
+    cases_with_ssm_and_cnvs = []
+    result = []
+    gene_entities.append(decompose_result["cnv_gene"])
+    cnv_result = get_freq_cnv_loss_or_gain(
+        gene_entities, cancer_entities, query, cnv_and_ssm_flag=True
+    )
+
+    for ce in cancer_entities:
+
+        try:
+            # get_cases_with_ssms_in_a_gene returns the number of cases with ssms
+            ssm_result = get_cases_with_ssms_in_a_gene(
+                project=ce, gene_name=decompose_result["mut_gene"]
+            )
+            # calcuate overlap of cases and return freq
+            cases_with_ssm_and_cnvs = [
+                set(cnv_result[ce][decompose_result["cnv_gene"]]["case_id_list"]),
+                set(ssm_result["case_id_list"]),
+            ]
+            shared_cases = list(reduce(lambda x, y: x & y, cases_with_ssm_and_cnvs))
+            total_case_count = get_total_variation_data_for_project(project=ce)
+            # print('shared_cases, len {} {}'.format(shared_cases, len(shared_cases)))
+            # print('total_case_count {}'.format(total_case_count))
+            freq = round((len(shared_cases) / total_case_count) * 100, 2)
+            joint_freq = "The joint frequency in {} is {}%".format(ce, freq)
+        except Exception as e:
+            joint_freq = "joint freq in {} is not available".format(ce)
+        result.append(joint_freq)
+    return result, cancer_entities
+
+
+def get_top_cases_counts_by_gene(gene_entities, cancer_entities):
+    top_cases_counts_by_gene = {}
+    result = []
+    emsembl_gene_ids = get_ensembl_gene_ids(gene_entities)
+    if not cancer_entities:
+        cancer_entities = list(project_mappings.keys())
+    for ce in cancer_entities:
+        top_cases_counts_by_gene[ce] = {}
+        # note this gives you ssm + cnv
+        endpt = "https://api.gdc.cancer.gov/analysis/top_cases_counts_by_genes?gene_ids={}".format(
+            ",".join(emsembl_gene_ids)
+        )
+        response = requests.get(endpt)
+        response_json = json.loads(response.content)
+        try:
+            for item in response_json["aggregations"]["projects"]["buckets"]:
+                if item["key"] == ce:
+                    cases_with_mutations = item["doc_count"]
+            # total_case_count = get_available_ssm_data_for_project(ce)
+            total_case_count = get_total_variation_data_for_project(project=ce)
+            cases_without_mutations = total_case_count - cases_with_mutations
+            top_cases_counts_by_gene[ce]["cases_with_mutations"] = cases_with_mutations
+            top_cases_counts_by_gene[ce][
+                "cases_without_mutations"
+            ] = cases_without_mutations
+            top_cases_counts_by_gene[ce]["total_case_count"] = total_case_count
+            freq = cases_with_mutations / total_case_count
+            top_cases_counts_by_gene[ce]["frequency"] = round(freq * 100, 2)
+            result.append(
+                "The frequency of cases with mutations in {} is {}%".format(
+                    ce, top_cases_counts_by_gene[ce]["frequency"]
+                )
+            )
+        except Exception as e:
+            result.append("frequency unavailable from API for {}".format(ce))
+    cancer_entities = list(top_cases_counts_by_gene.keys())
+    return result, cancer_entities
+
+
+def get_project_summary(cancer_entities):
+    project_summary = {}
+    for ce in cancer_entities:
+        endpt = "https://api.gdc.cancer.gov/projects/{}?expand=summary,summary.experimental_strategies,summary.data_categories".format(
+            ce
+        )
+        response = requests.get(endpt)
+        response_json = json.loads(response.content)
+        project_summary[ce]["project_summary"] = response_json["data"]
+    return project_summary
+
+
+def map_cancer_entities_to_project(initial_cancer_entities, project_mappings):
+    project_match = {}
+    for ce in initial_cancer_entities:
+        # cancer_wild_card = '*' + ce
+        endpoint = "https://api.gdc.cancer.gov/projects"
+        fields = ["project_id", "disease_type", "name"]
+        fields = ",".join(fields)
+
+        filters = {"op": "=", "content": {"field": "name", "value": [ce]}}
+        params = {"filters": json.dumps(filters), "fields": fields, "size": 10000}
+        try:
+            response = requests.get(endpoint, params=params)
+            response_json = json.loads(response.content)
+            # print('response_json {}'.format(json.dumps(
+            #    response_json, indent=4)))
+            for item in response_json["data"]["hits"]:
+                project_id = item["project_id"]
+            project_match[ce] = project_id
+        except Exception as e:
+            pass
+            # print('unable to return a match from projects endpt '
+            #      'perform further checks on project_mappings')
+    return project_match

methods/utilities.py

@@ -0,0 +1,523 @@
+#!/usr/bin/env python3
+# various utility functions employed by the pipeline
+import json
+import re
+import time
+from functools import reduce, wraps
+
+import numpy as np
+import pandas as pd
+import spacy
+import torch
+
+from guidance.models import Transformers
+from guidance import gen as guidance_gen
+
+from huggingface_hub import HfFolder, hf_hub_download
+from transformers import AutoTokenizer, BertTokenizer, AutoModelForCausalLM, BertForSequenceClassification
+
+
+from methods import gdc_api_calls
+
+
+def load_llama_llm(AUTH_TOKEN):
+    # hugging face model
+    # https://huggingface.co/blog/llama32
+    model_id = "meta-llama/Llama-3.2-3B-Instruct"
+    tok = AutoTokenizer.from_pretrained(
+        model_id, trust_remote_code=True, 
+        token=AUTH_TOKEN
+    )
+    model = AutoModelForCausalLM.from_pretrained(
+            model_id, 
+            torch_dtype=torch.float16, 
+            trust_remote_code=True,
+            token=AUTH_TOKEN
+    )
+    model = model.to('cuda')
+    model = model.eval()
+
+    return model, tok
+
+
+def load_gdc_genes_mutations_hf(AUTH_TOKEN):
+    dataset_id = 'uc-ctds/GDC-QAG-genes-mutations'
+    filename = 'gdc_genes_mutations.json'
+    json_path = hf_hub_download(
+        repo_id=dataset_id,
+        filename=filename,
+        repo_type="dataset",
+        token=AUTH_TOKEN
+    )
+    with open(json_path, 'r') as f:
+        gdc_genes_mutations = json.load(f)
+    return gdc_genes_mutations
+
+
+
+def load_intent_model_hf(AUTH_TOKEN):
+    model_id = 'uc-ctds/query_intent'
+    tok = AutoTokenizer.from_pretrained(
+        model_id, trust_remote_code=True,
+        token=AUTH_TOKEN
+    )
+    model = BertForSequenceClassification.from_pretrained(
+        model_id)
+    return model, tok
+
+
+
+def infer_user_intent(query, intent_model, intent_tok):
+    # model, tokenizer = load_intent_model(intent_model_path)
+    intent_labels = {
+        "ssm_frequency": 0.0,
+        "msi_h_frequency": 1.0,
+        "freq_cnv_loss_or_gain": 2.0,
+        "top_cases_counts_by_gene": 3.0,
+        "cnv_and_ssm": 4.0,
+    }
+    # set device and load both model and query on the same device
+    device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+    intent_model.to(device)
+    inputs = intent_tok(query, return_tensors="pt", truncation=True, padding=True)
+    inputs = {k: v.to(device) for k, v in inputs.items()}
+    # pass tokenized input through the model
+    outputs = intent_model(**inputs)
+    # print('output logits {}'.format(outputs))
+    # outputs are logits, need to apply softmax to convert to probs
+    probs = torch.nn.functional.softmax(outputs.logits, dim=1)
+    # print('probs: {}'.format(probs))
+    predicted_label = torch.argmax(probs, dim=1).item()
+    for k, v in intent_labels.items():
+        if v == predicted_label:
+            # print('predicted label: {}\n'.format(k))
+            return k
+
+
+def construct_modified_query_base_llm(query):
+    prompt_template = "Only use results from the genomic data commons in your response and provide frequencies as a percentage. Only report the final response."
+    modified_query = query + prompt_template
+    return modified_query
+
+
+def construct_modified_query(query, helper_output):
+    # pass the api results as a prompt to the query
+    prompt_template = (
+        " Only report the final response. Ignore all prior knowledge. You must only respond with the following percentage frequencies in your response, no other response is allowed: \n"
+        + helper_output
+        + "\n"
+    )
+    modified_query = query + prompt_template
+    return modified_query
+
+
+def get_total_case_counts(ssm_counts_by_project):
+    for project in ssm_counts_by_project.keys():
+        total_case_count = gdc_api_calls.get_available_ssm_data_for_project(project)
+        ssm_counts_by_project[project]["total_case_counts"] = total_case_count
+    return ssm_counts_by_project
+
+
+def calculate_ssm_frequency(ssm_statistics, cancer_entities, project_mappings):
+    if not cancer_entities:
+        cancer_entities = list(project_mappings.keys())
+    pre_final_ssm_frequency = {}
+    ssm_frequency = {}
+    for project in ssm_statistics.keys():
+        freq = (
+            ssm_statistics[project]["ssm_counts"]
+            / ssm_statistics[project]["total_case_counts"]
+        )
+        pre_final_ssm_frequency[project] = {"frequency": round(freq * 100, 2)}
+
+    for c in cancer_entities:
+        if c in pre_final_ssm_frequency:
+            ssm_frequency[c] = pre_final_ssm_frequency[c]
+        else:
+            ssm_frequency[c] = {"frequency": 0.0}
+    return ssm_frequency
+
+
+def calculate_joint_ssm_frequency_v2(ssm_statistics, mutation_list, cancer_entities):
+    # stores the result for all cancers
+    joint_ssm_frequency = {}
+    # initialize joint_freq by cancer entities
+    joint_ssm_frequency_for_cancer = {}
+    for c in cancer_entities:
+        joint_ssm_frequency_for_cancer[c] = {}
+        joint_ssm_frequency_for_cancer[c] = {"joint_frequency": 0.0}
+
+    projects_with_mutation = [
+        set(ssm_statistics[mutation].keys()) for mutation in mutation_list
+    ]
+    overlapping_projects_with_mutation = list(
+        reduce(lambda x, y: x & y, projects_with_mutation)
+    )
+    for project in overlapping_projects_with_mutation:
+        cases_with_mutation = [
+            set(ssm_statistics[mutation][project]["case_id_list"])
+            for mutation in mutation_list
+        ]
+        shared_cases = list(reduce(lambda x, y: x & y, cases_with_mutation))
+        # print('shared cases, len shared cases {} {}'.format(shared_cases, len(shared_cases)))
+        if shared_cases:
+            if project not in joint_ssm_frequency:
+                joint_ssm_frequency[project] = {}
+            total_case_counts = gdc_api_calls.get_available_ssm_data_for_project(
+                project
+            )
+            joint_frequency = len(shared_cases) / total_case_counts
+            # print('shared_cases {}'.format(shared_cases))
+            # print('joint freq {}'.format(joint_frequency))
+            joint_ssm_frequency[project]["joint_frequency"] = round(
+                joint_frequency * 100, 2
+            )
+    # filter for specific cancer type and return
+    for c in cancer_entities:
+        if c in joint_ssm_frequency:
+            joint_ssm_frequency_for_cancer[c]["joint_frequency"] = joint_ssm_frequency[
+                c
+            ]["joint_frequency"]
+    return joint_ssm_frequency_for_cancer
+
+
+def flatten_ssm_results_to_text(result, result_type):
+    result_text = []
+    if result_type == "joint_frequency":
+        for k, v in result.items():
+            if k == "joint_frequency":
+                for k2, v2 in v.items():
+                    result_text.append(
+                        "joint frequency in {} is {}%".format(k2, v2["joint_frequency"])
+                    )
+    else:
+        for k, v in result.items():
+            if k != "joint_frequency":
+                for k2, v2 in v.items():
+                    result_text.append(
+                        "The frequency of {} in {} is {}%".format(
+                            k, k2, v2["frequency"]
+                        )
+                    )
+    return result_text
+
+
+def get_ssm_frequency(
+    gene_entities, mutation_entities, cancer_entities, project_mappings
+):
+    ssm_statistics = {}
+    mutation_list = []
+    result = {}
+    # to match the genes with mutations
+    if len(mutation_entities) > len(gene_entities):
+        gene_entities = gene_entities * len(mutation_entities)
+    # print('gene entities {}'.format(gene_entities))
+    for gene, mutation in zip(gene_entities, mutation_entities):
+        mutation_name = "_".join([gene, mutation])
+        # print('computing frequency of {}'.format(mutation_name))
+        mutation_list.append(mutation_name)
+        ssm_id = gdc_api_calls.get_ssm_id(gene, mutation)
+        ssm_counts_by_project = gdc_api_calls.get_ssm_counts(ssm_id)
+        ssm_statistics[mutation_name] = get_total_case_counts(ssm_counts_by_project)
+        # full_result for all cancer entities
+        # test code for generalizability to multiple cancer entities
+        # full_result format is {'project1': {'frequency': }, 'project2': {'frequency':}, 'projectn': {'frequency':}}
+        full_result = calculate_ssm_frequency(
+            ssm_statistics[mutation_name], cancer_entities, project_mappings
+        )
+        # result format:
+        """
+    { 
+      'gene_mutation': # e.g. JAK2_V617F
+      {
+        'project1': {'frequency': }, 
+        'project2': {'frequency':}, 
+        'projectn': {'frequency':}
+      }
+    }
+    'project1': {'frequency': }, 'project2': {'frequency':}
+    """
+        result[mutation_name] = {
+            k: v for k, v in full_result.items() if k in cancer_entities
+        }
+        # if no entity match to specific gdc projects, return all
+        if not result[mutation_name].values():
+            result[mutation_name] = full_result
+    # print('API result ssm freq {}'.format(result))
+    # final cancer entities
+    for k, v in result.items():
+        cancer_entities = list(v.keys())
+    # print('ssm freq cancer entities {}'.format(cancer_entities))
+    # print('mutation list {}'.format(mutation_list))
+    # only supporting for two mutations atm
+    if len(mutation_list) > 1:
+        # print('computing joint frequency')
+        result["joint_frequency"] = calculate_joint_ssm_frequency_v2(
+            ssm_statistics, mutation_list=mutation_list, cancer_entities=cancer_entities
+        )
+        result_text = flatten_ssm_results_to_text(result, result_type="joint_frequency")
+    else:
+        result["joint_frequency"] = 0
+        result_text = flatten_ssm_results_to_text(
+            result, result_type="single_frequency"
+        )
+    # print('result_text {}'.format(result_text))
+    return result_text, cancer_entities
+
+
+def decompose_mutation_and_cnv(query, match_term, gdc_genes_mutations):
+    decompose_result = {}
+    genes = [g for g in query.split(" ") if g in gdc_genes_mutations.keys()]
+    # query must have cnv first, followed by mutation
+    cnv_gene_name, mut_gene_name = genes[0], genes[1]
+    # print('cnv_gene_name, mut_gene_name {} {}'.format(
+    #  cnv_gene_name, mut_gene_name))
+    decompose_result["cnv_and_ssm"] = True
+    decompose_result["cnv_gene"] = cnv_gene_name
+    decompose_result["mut_gene"] = mut_gene_name
+    decompose_result["cnv_change_type"] = match_term
+    return decompose_result
+
+
+def get_freq_of_cnv_and_ssms(
+    query, cancer_entities, gene_entities, gdc_genes_mutations
+):
+    lc_query = query.lower()
+    match_term = ""
+    cnv_terms = [
+        "amplification",
+        "deletion",
+        "loss",
+        "gain",
+        "homozygous deletion",
+        "heterozygous deletion",
+    ]
+    for term in cnv_terms:
+        if term in lc_query:
+            match_term = term
+    # print('match_term {}'.format(match_term))
+    if match_term:
+        decompose_result = decompose_mutation_and_cnv(
+            query, match_term, gdc_genes_mutations
+        )
+        # print('decompose result {}'.format(decompose_result))
+        result, cancer_entities = gdc_api_calls.run_cnv_ssm_api(
+            decompose_result, cancer_entities, query
+        )
+        # print('result {}'.format(result))
+    else:
+        # no specific match terms, return freq of cnvs + ssm
+        result, cancer_entities = gdc_api_calls.get_top_cases_counts_by_gene(
+            gene_entities, cancer_entities
+        )
+    return result, cancer_entities
+
+
+def return_initial_cancer_entities(query, model):
+    nlp = spacy.load(model)
+    doc = nlp(query)
+    result = doc.ents
+    initial_cancer_entities = [e.text for e in result if e.label_ == "DISEASE"]
+    return initial_cancer_entities
+
+
+def infer_gene_entities_from_query(query, gdc_genes_mutations):
+    entities = []
+    # gene recognition with simple dict-based method
+    for g in gdc_genes_mutations.keys():
+        if (g in query) and (g in query.split(" ")):
+            entities.append(g)
+    return entities
+
+
+def check_if_project_id_in_query(project_list, query):
+    # check if mention of project keys
+    # e.g. TCGA-BRCA in query
+    final_entities = [
+        potential_ce
+        for potential_ce in query.split(" ")
+        if potential_ce in project_list
+    ]
+    return final_entities
+
+
+def proj_id_and_partial_match(query, project_mappings, initial_cancer_entities):
+    final_entities = []
+    if initial_cancer_entities:
+        # print('checking for full match between initial cancer entities and GDC project descriptions')
+        # check for match with project_mapping values
+        #  e.g. match "ovarian serous cystadenocarcinoma" to TCGA-OV project
+        for ic in initial_cancer_entities:
+            for k, v in project_mappings.items():
+                for c in v:
+                    if ic in c.lower():
+                        # print('found!!! {} {}'.format(ic, c.lower()))
+                        final_entities.append(k)
+    else:
+        # print('no initial cancer entities, check for full match between query terms and GDC project descriptions')
+        for term in query.lower().split(" "):
+            for k, v in project_mappings.items():
+                for c in v:
+                    if term in c.lower():
+                        # print('found!!! {} {}'.format(ic, c.lower()))
+                        final_entities.append(k)
+    return list(set(final_entities))
+
+
+def postprocess_cancer_entities(project_mappings, initial_cancer_entities, query):
+    # print('initial cancer entities {}'.format(initial_cancer_entities))
+    project_list = project_mappings.keys()
+    # print('check if GDC project-id mentioned in query')
+    final_entities = check_if_project_id_in_query(project_list, query)
+    if final_entities:
+        return final_entities
+    else:
+        if initial_cancer_entities:
+            # first query GDC projects endpt
+            # print('test 1 (w/ initial entities): querying GDC projects endpt for project_id')
+            gdc_project_match = gdc_api_calls.map_cancer_entities_to_project(
+                initial_cancer_entities, project_mappings
+            )
+            # print('mapped projects to ids {}'.format(gdc_project_match))
+            if gdc_project_match.values():
+                final_entities = list(gdc_project_match.values())
+            if not final_entities:
+                # print('test 2 (w/ initial entities): no result from GDC projects endpt, check for matches '
+                #    'between query terms and gdc project_mappings')
+                final_entities = proj_id_and_partial_match(
+                    query, project_mappings, initial_cancer_entities
+                )
+        else:
+            # no initial_cancer_entities
+            # check project_mappings keys/values for matches with query terms
+            # print('test 3 (w/o initial entities): no result from GDC projects endpt, check for matches '
+            #      'between query terms and gdc project_mappings')
+            final_entities = proj_id_and_partial_match(
+                query, project_mappings, initial_cancer_entities
+            )
+    return final_entities
+
+
+def infer_mutation_entities(gene_entities, query, gdc_genes_mutations):
+    mutation_entities = []
+    for g in gene_entities:
+        for m in gdc_genes_mutations[g]:
+            if m in query:
+                mutation_entities.append(m)
+    return mutation_entities
+
+
+def postprocess_response(row):
+    value_changed = "no"
+    pattern = r".*?(\d*\.\d*)%.*?"
+    delta_final = np.nan
+    delta_prefinal = np.nan
+    generated_stat_final = np.nan
+
+    try:
+        helper_output = row["helper_output"]
+    except Exception as e:
+        # print('unable to generate helper output, returning nan')
+        return pd.Series(["np.nan"] * 8)
+
+    pre_final_response = row["pre_final_llama_with_helper_output"]
+    llama_base_output = row["llama_base_output"]
+
+    try:
+        llama_base_stat = float(re.search(pattern, llama_base_output).group(1))
+    except Exception as e:
+        # print('unable to extract llama base stat {}'.format(str(e)))
+        llama_base_stat = np.nan
+    try:
+        generated_stat_prefinal = float(re.search(pattern, pre_final_response).group(1))
+    except Exception as e:
+        # print('unable to extract generated stat {}'.format(str(e)))
+        generated_stat_prefinal = np.nan
+
+    try:
+        ground_truth_stat = float(re.search(pattern, helper_output).group(1))
+    except Exception as e:
+        # print('unable to extract ground truth stat {}'.format(str(e)))
+        ground_truth_stat = np.nan
+
+    try:
+        delta_llama = llama_base_stat - ground_truth_stat
+    except Exception as e:
+        # print('unable to calculate delta_llama {}'.format(str(e)))
+        delta_llama = np.nan
+
+    if not np.isnan(generated_stat_prefinal) and not np.isnan(ground_truth_stat):
+        delta_prefinal = generated_stat_prefinal - ground_truth_stat
+        if delta_prefinal != 0.0:
+            final_response = "The final answer is: {}%".format(ground_truth_stat)
+            value_changed = "yes"
+        else:
+            final_response = pre_final_response
+        generated_stat_final = float(re.search(pattern, final_response).group(1))
+        delta_final = generated_stat_final - ground_truth_stat
+    else:
+        final_response = "unable to postprocess, check generated or truth stat"
+        value_changed = "na"
+    """
+  print('check if all values are populated:\n')
+  print('delta_llama {}'.format(delta_llama))
+  print('value_changed {}'.format(value_changed))
+  print('ground_truth_stat {}'.format(ground_truth_stat))
+  print('generated_stat_prefinal {}'.format(generated_stat_prefinal))
+  print('delta_prefinal {}'.format(delta_prefinal))
+  print('generated_stat_final {}'.format(generated_stat_final))
+  print('delta_final {}'.format(delta_final))
+  print('final_response {}'.format(final_response))
+  """
+    return pd.Series(
+        [
+            llama_base_stat,
+            delta_llama,
+            value_changed,
+            ground_truth_stat,
+            generated_stat_prefinal,
+            delta_prefinal,
+            generated_stat_final,
+            delta_final,
+            final_response,
+        ]
+    )
+
+
+
+def set_hf_token(token_path):
+    # hugging face token
+    with open(token_path, "r") as hf_token_file:
+        HF_TOKEN = hf_token_file.read().strip()
+    HfFolder.save_token(HF_TOKEN)
+
+
+def get_final_columns():
+
+    # colnames for final output CSV
+    final_columns = [
+        "questions",
+        "intent",
+        "llama_base_output",
+        "helper_output",
+        "cancer_entities",
+        "gene_entities",
+        "mutation_entities",
+        "modified_prompt",
+        "ground_truth_stat",
+        "llama_base_stat",
+        "delta_llama",
+        "final_response",
+    ]
+    return final_columns
+
+
+def timeit(fn):
+    @wraps(fn)
+    def wrapper(*args, **kwargs):
+        start = time.perf_counter()
+        result = fn(*args, **kwargs)
+        end = time.perf_counter()
+        print(f"{fn.__name__} took {end - start:.4f} seconds")
+        return result
+    return wrapper