Source: main.js

  1. import * as UMAP from "https://esm.sh/umap-js@1.3.3";
  2. import * as Plotly from "https://cdn.jsdelivr.net/npm/plotly.js-dist/+esm";
  4. import * as am5 from "https://cdn.jsdelivr.net/npm/@amcharts/amcharts5/+esm";
  5. import * as am5hierarchy from "https://cdn.jsdelivr.net/npm/@amcharts/amcharts5/hierarchy/+esm";
  7. import * as am5themes_Animated from "https://cdn.jsdelivr.net/npm/@amcharts/amcharts5@5.3.7/themes/Animated.js/+esm";
  9. import { default as plotMSPrevalence } from "./mSigPortalScripts/client/src/components/controls/plotly/msPrevalence/msPrevalence.js";
  10. import { default as plotSignatureAssociation } from "./mSigPortalScripts/client/src/components/controls/plotly/msAssociation/msAssociation.js";
  11. import { default as plotMutationalProfileSBS96 } from "./mSigPortalScripts/client/src/components/controls/plotly/mutationalProfiles/sbs96.js";
  12. import { default as plotMutationalProfileSBS192 } from "./mSigPortalScripts/client/src/components/controls/plotly/mutationalProfiles/sbs192.js";
  13. import { default as plotMutationalProfileSBS288 } from "./mSigPortalScripts/client/src/components/controls/plotly/mutationalProfiles/sbs288.js";
  14. import { default as plotMutationalProfileSBS384 } from "./mSigPortalScripts/client/src/components/controls/plotly/mutationalProfiles/sbs384.js";
  15. import { default as plotMutationalProfileSBS1536 } from "./mSigPortalScripts/client/src/components/controls/plotly/mutationalProfiles/sbs1536.js";
  17. import { default as plotMutationalProfileDBS78 } from "./mSigPortalScripts/client/src/components/controls/plotly/mutationalProfiles/dbs78.js";
  18. import { default as plotMutationalProfileDBS186 } from "./mSigPortalScripts/client/src/components/controls/plotly/mutationalProfiles/dbs186.js";
  20. import { default as plotMutationalProfileID28 } from "./mSigPortalScripts/client/src/components/controls/plotly/mutationalProfiles/id28.js";
  21. import { default as plotMutationalProfileID29 } from "./mSigPortalScripts/client/src/components/controls/plotly/mutationalProfiles/id29.js";
  22. import { default as plotMutationalProfileID83 } from "./mSigPortalScripts/client/src/components/controls/plotly/mutationalProfiles/id83.js";
  23. import { default as plotMutationalProfileID415 } from "./mSigPortalScripts/client/src/components/controls/plotly/mutationalProfiles/id415.js";
  24. import { default as plotMutationalProfileRS32 } from "./mSigPortalScripts/client/src/components/controls/plotly/mutationalProfiles/rs32.js";
  26. import { default as plotMutationalProfileSBS96Comparison } from "./mSigPortalScripts/client/src/components/controls/plotly/profileComparison/sbs96.js";
  27. import { default as plotMutationalProfileSBS192Comparison } from "./mSigPortalScripts/client/src/components/controls/plotly/profileComparison/sbs192.js";
  28. import { default as plotMutationalProfileDBS78Comparison } from "./mSigPortalScripts/client/src/components/controls/plotly/profileComparison/dbs78.js";
  29. import { default as plotMutationalProfileID83Comparison } from "./mSigPortalScripts/client/src/components/controls/plotly/profileComparison/id83.js";
  30. import { default as plotMutationalProfileRS32Comparison } from "./mSigPortalScripts/client/src/components/controls/plotly/profileComparison/rs32.js";
  32. import { preprocessData, kFoldCV } from "./mSigSDKScripts/machineLearning.js";
  34. import {
  35.   convertMatrix,
  36.   convertWGStoPanel,
  37.   init_sbs_mutational_spectra,
  38.   convertMutationalSpectraIntoJSON,
  39. } from "./mSigSDKScripts/userData.js";
  40. import {
  41.   linspace,
  42.   deepCopy,
  43.   nnls,
  44.   formatHierarchicalClustersToAM5Format,
  45.   groupBy,
  46.   createDistanceMatrix,
  47.   hierarchicalClustering,
  48.   doubleClustering,
  49.   cosineSimilarity,
  50. } from "./mSigSDKScripts/utils.js";
  52. import {
  53.   getProjectsByGene,
  54.   getTpmCountsByGenesOnProjects,
  55.   getTpmCountsByGenesFromFiles,
  56.   getMafInformationFromProjects,
  57.   getVariantInformationFromMafFiles,
  58.   convertTCGAProjectIntoJSON,
  59. } from "./mSigSDKScripts/tcga.js";
  61. // import every single function one by one from the mSigPortalAPIs.js file
  63. import {
  64.   getMutationalSignaturesOptions,
  65.   getMutationalSignaturesData,
  66.   getMutationalSignaturesSummary,
  67.   getMutationalSpectrumOptions,
  68.   getMutationalSpectrumData,
  69.   getMutationalSpectrumSummary,
  70.   getMutationalSignatureAssociationOptions,
  71.   getMutationalSignatureAssociationData,
  72.   getMutationalSignatureActivityOptions,
  73.   getMutationalSignatureActivityData,
  74.   getMutationalSignatureLandscapeData,
  75.   getMutationalSignatureEtiologyOptions,
  76.   getMutationalSignatureEtiologyData,
  77. } from "./mSigSDKScripts/mSigPortalAPIs.js";
  79. // import * as mSigPortalPlotting from "./index.js";
  81. const mSigSDK = (function () {
  82.   /**
  83.    * @namespace mSigPortalData
  84.    */
  86.   /**
  87.    * @namespace mSigPortalPlots
  88.    */
  90.   /**
  91.    * @namespace machineLearning
  92.    */
  94.   /**
  95.    * @namespace userData
  96.    */
  98.   /**
  99.    * @namespace tcga
  100.    */
  103.   //#region Plot the summary of a dataset
  105.   function plotGraphWithPlotlyAndMakeDataDownloadable(divID, data, layout) {
  106.     // Plot the graph using Plotly
  107.     Plotly.default.newPlot(divID, data, layout);
  109.     // Ensure Font Awesome CSS is included
  110.     const fontAwesomeLink =
  111.       "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.1/css/all.min.css";
  112.     if (!document.querySelector(`link[href="${fontAwesomeLink}"]`)) {
  113.       const link = document.createElement("link");
  114.       link.rel = "stylesheet";
  115.       link.href = fontAwesomeLink;
  116.       document.head.appendChild(link);
  117.     }
  119.     // Get the container of the Plotly graph
  120.     const container = document.getElementById(divID);
  122.     // Ensure the container has a relative position
  123.     container.style.position = "relative";
  125.     // Create a download button with only the Font Awesome download icon
  126.     const downloadBtn = document.createElement("div");
  127.     downloadBtn.innerHTML =
  128.       '<button class="btn"><i class="fa fa-download"></i></button>';
  129.     const btn = downloadBtn.firstChild;
  131.     // Position the button at the bottom right corner of the container
  132.     btn.style.position = "absolute";
  133.     btn.style.bottom = "0";
  134.     btn.style.right = "0";
  136.     // Add an event listener to handle the download action
  137.     btn.addEventListener("click", function () {
  138.       const graphData = {
  139.         traces: data,
  140.         layout: layout,
  141.       };
  142.       const blob = new Blob([JSON.stringify(graphData, null, 2)], {
  143.         type: "application/json",
  144.       });
  145.       const url = URL.createObjectURL(blob);
  146.       const a = document.createElement("a");
  147.       a.href = url;
  148.       a.download = "graph_data.json";
  149.       a.click();
  150.       URL.revokeObjectURL(url);
  151.     });
  153.     // Append the download button to the container
  154.     container.appendChild(btn);
  156.     // Add the provided CSS
  157.     const css = `
  158.         .btn {
  159.             background-color: DodgerBlue;
  160.             border: none;
  161.             border-radius: 100%;
  162.             color: white;
  163.             padding: 12px 12px;
  164.             cursor: pointer;
  165.             font-size: 20px;
  166.         }
  168.         .btn:hover {
  169.             background-color: RoyalBlue;
  170.         }
  171.     `;
  173.     const style = document.createElement("style");
  174.     style.type = "text/css";
  175.     style.appendChild(document.createTextNode(css));
  176.     document.head.appendChild(style);
  177.   }
  179.   /**
  181. Generates a mutational spectrum summary plot and displays it in a given HTML div element.
  182. @async
  183. @function plotProfilerSummary
  184. @memberof mSigPortalPlots
  185. @param {string} [studyName="PCAWG"] - The name of the cancer genomics study to use. Default is "PCAWG".
  186. @param {string} [genomeDataType="WGS"] - The type of genomic data to use. Default is "WGS".
  187. @param {string} [cancerTypeOrGroup="Lung-AdenoCA"] - The cancer type or group to display. Default is "Lung-AdenoCA".
  188. @param {number} [numberOfResults=50] - The maximum number of results to display. Default is 50.
  189. @param {string} [divID="mutationalSpectrumSummary"] - The ID of the HTML div element where the plot will be displayed. Default is "mutationalSpectrumSummary".
  190. @returns {Promise<void>} A Promise that resolves when the plot is displayed or rejects if there is an error.
  191. @throws {Error} If there is an error retrieving or displaying the plot, this function will throw an Error with a message describing the error.
  192. */
  194.   // This function plots the mutational spectrum summary for the given parameters.
  195.   // Input:
  196.   // - studyName: Name of the study for which the data is to be fetched
  197.   // - genomeDataType: Type of the genome data to be fetched
  198.   // - cancerTypeOrGroup: Cancer type or group for which the data is to be fetched
  199.   // - numberOfResults: Number of results to be fetched
  200.   // Output: A mutational spectrum summary plot of the given parameters
  201.   async function plotProfilerSummary(
  202.     studyName = "PCAWG",
  203.     genomeDataType = "WGS",
  204.     cancerTypeOrGroup = "Lung-AdenoCA",
  205.     numberOfResults = 50,
  206.     divID = "mutationalSpectrumSummary"
  207.   ) {
  208.     try {
  209.       const summary = await getMutationalSpectrumSummary(
  210.         studyName,
  211.         genomeDataType,
  212.         cancerTypeOrGroup,
  213.         numberOfResults
  214.       );
  215.       let data = await getBarPlotData(summary);
  216.       if (data.length == 0) {
  217.         // $(`#${divID}`).html(
  218.         //   `<p style="color:red">Error: no data available for the selected parameters.</p>`
  219.         // );
  220.       } else {
  221.         let layout = {
  222.           title: `${studyName} ${cancerTypeOrGroup} ${genomeDataType} Mutational Spectrum Summary`,
  223.           xaxis: {
  224.             title: "Sample",
  225.           },
  226.           yaxis: {
  227.             title: "Log (Number of Mutations)",
  228.           },
  229.           barmode: "stack",
  230.         };
  231.         plotGraphWithPlotlyAndMakeDataDownloadable(divID, data, layout);
  232.       }
  233.     } catch (err) {
  234.       console.error(err);
  235.       $(`#${divID}`).html(`<p>Error: ${err.message}</p>`);
  236.     }
  237.   }
  239.   async function getBarPlotData(summary) {
  240.     let data = [];
  241.     for (let i = 0; i < summary.length; i++) {
  242.       if (
  243.         !data.some(
  244.           (e) => e.name === summary[i]["profile"] + `: ${summary[i]["matrix"]}`
  245.         )
  246.       ) {
  247.         data.push({
  248.           x: [summary[i]["sample"]],
  249.           y: [summary[i]["logTotalMutations"]],
  250.           text: [parseInt(summary[i]["meanTotalMutations"])],
  251.           type: "bar",
  252.           name: summary[i]["profile"] + `: ${summary[i]["matrix"]}`,
  253.           marker: {
  254.             color: summary[i].color,
  255.           },
  256.         });
  257.       } else {
  258.         let existingData = data.find(
  259.           (e) => e.name === summary[i]["profile"] + `: ${summary[i]["matrix"]}`
  260.         );
  261.         existingData.x.push(summary[i]["sample"]);
  262.         existingData.y.push(summary[i]["logTotalMutations"]);
  263.         existingData.text.push(parseInt(summary[i]["meanTotalMutations"]));
  264.       }
  265.     }
  266.     return data;
  267.   }
  269.   // This function plots the mutational spectrum mutational count as boxplots for each cancer type for the given dataset.
  271.   /**
  273. Plots the mutational burden by cancer type for a given project.
  274. @async
  275. @function plotProjectMutationalBurdenByCancerType
  276. @memberof mSigPortalPlots
  277. @param {Object} project - An object containing mutational data for different cancer types.
  278. @param {string} divID - The ID of the div where the plot should be displayed.
  279. @returns {Promise} - A Promise that resolves when the plot is displayed.
  280. @example
  281. // Example usage:
  282. plotProjectMutationalBurdenByCancerType(projectData, "plotDiv");
  283. */
  284.   async function plotProjectMutationalBurdenByCancerType(project, divID) {
  285.     project = groupBy(project, "cancer");
  286.     Object.keys(project).forEach(function (key, index) {
  287.       project[key] = groupBy(project[key], "sample");
  288.       Object.keys(project[key]).forEach(function (patient, index) {
  289.         project[key][patient] = Object.values(
  290.           extractMutationalSpectra(project[key][patient], "sample")
  291.         )[0];
  292.       });
  293.     });
  295.     // Loop through all the cancertypes in project and create a trace for each cancer type and add it to the data array
  297.     const cancerTypes = Object.keys(project);
  299.     const data = [];
  301.     const boxColor = {};
  302.     const allColors = linspace(0, 360, cancerTypes.length);
  303.     for (var i = 0; i < cancerTypes.length - 1; i++) {
  304.       var result = "hsl(" + allColors[i] + ",50%" + ",50%)";
  305.       boxColor[cancerTypes[i]] = result;
  306.     }
  308.     for (let cancerType of cancerTypes) {
  309.       const cancerTypeData = Object.values(project[cancerType]);
  311.       const trace = {
  312.         // x: Object.keys(project[cancerType]),
  313.         y: Object.values(cancerTypeData).map((e) =>
  314.           Math.log10(Object.values(e).reduce((a, b) => a + b, 0))
  315.         ),
  316.         type: "box",
  317.         name: cancerType,
  318.         marker: {
  319.           color: boxColor[cancerType],
  320.         },
  321.         boxpoints: "Outliers",
  322.       };
  324.       data.push(trace);
  325.     }
  327.     const layout = {
  328.       title: `Mutational Burden by Cancer Type`,
  329.       xaxis: {
  330.         title: "Cancer Type",
  331.         type: "category",
  332.         automargin: true,
  333.       },
  334.       yaxis: {
  335.         title: "Log (Number of Mutations)",
  336.       },
  337.       barmode: "stack",
  338.       height: 600,
  339.     };
  341.     plotGraphWithPlotlyAndMakeDataDownloadable(divID, data, layout);
  342.   }
  344.   //#endregion
  346.   //#region Plot a patient's mutational spectra
  348.   /**
  349.    * Plots the mutational spectrum for the given parameters.
  350.    * @async
  351.    * @function plotPatientMutationalSpectrumuserData
  352.    * @memberof mSigPortalPlots
  353.    * @param {Object} mutationalSpectra - An object containing the mutational spectra data.
  354.    * @param {number} [matrixSize=96] - The size of the matrix to be plotted.
  355.    * @param {string} [divID="mutationalSpectrumMatrix"] - The ID of the div element where the plot will be displayed.
  356.    */
  357.   async function plotPatientMutationalSpectrumuserData(
  358.     mutationalSpectra,
  359.     matrixSize = 96,
  360.     divID = "mutationalSpectrumMatrix"
  361.   ) {
  362.     const numberOfPatients = Object.keys(mutationalSpectra).length;
  363.     if (numberOfPatients == 0) {
  364.       $(`#${divID}`).html(
  365.         `<p style="color:red">Error: no data available for the selected parameters.</p>`
  366.       );
  367.     } else if (numberOfPatients > 1) {
  368.       const layout = {
  369.         title: `Mutational Spectra for ${Object.keys(mutationalSpectra).join(
  370.           ", "
  371.         )}`,
  372.         xaxis: { title: "Mutation Type" },
  373.         yaxis: { title: "Count" },
  374.         barmode: "group",
  375.       };
  377.       const traces = Object.keys(mutationalSpectra).map((patient) => ({
  378.         x: Object.keys(mutationalSpectra[patient]),
  379.         y: Object.values(mutationalSpectra[patient]),
  380.         name: `${patient}`,
  381.         type: "bar",
  382.       }));
  384.       plotGraphWithPlotlyAndMakeDataDownloadable(divID, traces, layout);
  385.     } else {
  386.       let traces = [];
  388.       const layout = {
  389.         title: `Mutational Spectra for ${Object.keys(mutationalSpectra).join(
  390.           ", "
  391.         )}`,
  392.         xaxis: { title: "Mutation Type" },
  393.         yaxis: { title: "Count" },
  394.         barmode: "group",
  395.       };
  397.       for (let i = 0; i < Object.keys(mutationalSpectra).length; i++) {
  398.         let plotlyData = formatMutationalSpectraData(
  399.           mutationalSpectra[Object.keys(mutationalSpectra)[i]],
  400.           Object.keys(mutationalSpectra)[i]
  401.         );
  403.         traces = traces.concat(plotlyData);
  404.       }
  406.       plotGraphWithPlotlyAndMakeDataDownloadable(divID, traces, layout);
  407.     }
  408.   }
  410.   /**
  411. Renders a plot of the mutational spectra for one or more patients in a given div element ID using Plotly.
  412. @async
  413. @function plotPatientMutationalSpectrum
  414. @memberof mSigPortalPlots
  415. @param {Object} mutationalSpectra - An object containing the mutational spectra data for one or more patients.
  416. @param {number} [matrixSize=96] - The size of the plot matrix. Defaults to 96.
  417. @param {string} [divID='mutationalSpectrumMatrix'] - The ID of the div element to render the plot in. Defaults to 'mutationalSpectrumMatrix'.
  418. @returns {Promise<void>} A promise that resolves when the plot has been rendered.
  419. @throws {Error} An error is thrown if no data is available for the selected parameters.
  420. */
  422.   // This function plots the mutational spectrum for the given parameters.
  423.   async function plotPatientMutationalSpectrum(
  424.     mutationalSpectra,
  425.     divID = "mutationalSpectrumMatrix"
  426.   ) {
  427.     let matrixSize = mutationalSpectra[0].length;
  428.     let mutationType = mutationalSpectra[0][0].profile;
  429.     const numberOfPatients = Object.keys(mutationalSpectra).length;
  430.     console.log(numberOfPatients, mutationType, matrixSize);
  432.     if (numberOfPatients == 0) {
  433.       $(`#${divID}`).html(
  434.         `<p style="color:red">Error: no data available for the selected parameters.</p>`
  435.       );
  436.     } else if (
  437.       numberOfPatients > 2 &&
  438.       matrixSize == 96 &&
  439.       mutationType == "SBS"
  440.     ) {
  441.       mutationalSpectra = extractMutationalSpectra(mutationalSpectra);
  442.       const layout = {
  443.         title: `Mutational Spectra for ${Object.keys(mutationalSpectra).join(
  444.           ", "
  445.         )}`,
  446.         xaxis: { title: "Mutation Type" },
  447.         yaxis: { title: "Count" },
  448.         barmode: "group",
  449.       };
  451.       const traces = Object.keys(mutationalSpectra).map((patient) => ({
  452.         x: Object.keys(mutationalSpectra[patient]),
  453.         y: Object.values(mutationalSpectra[patient]),
  454.         name: `${patient}`,
  455.         type: "bar",
  456.       }));
  458.       plotGraphWithPlotlyAndMakeDataDownloadable(divID, traces, layout);
  459.     } else if (
  460.       numberOfPatients == 2 &&
  461.       matrixSize == 96 &&
  462.       mutationType == "SBS"
  463.     ) {
  464.       let traces = plotMutationalProfileSBS96Comparison(
  465.         mutationalSpectra[0],
  466.         mutationalSpectra[1]
  467.       );
  468.       plotGraphWithPlotlyAndMakeDataDownloadable(
  469.         divID,
  470.         traces.traces,
  471.         traces.layout
  472.       );
  473.       return traces;
  474.     } else if (
  475.       numberOfPatients == 1 &&
  476.       matrixSize == 96 &&
  477.       mutationType == "SBS"
  478.     ) {
  479.       let traces = plotMutationalProfileSBS96(mutationalSpectra[0]);
  480.       plotGraphWithPlotlyAndMakeDataDownloadable(
  481.         divID,
  482.         traces.traces,
  483.         traces.layout
  484.       );
  485.       return traces;
  486.     } else if (
  487.       numberOfPatients == 1 &&
  488.       matrixSize == 192 &&
  489.       mutationType == "SBS"
  490.     ) {
  491.       let traces = plotMutationalProfileSBS192(mutationalSpectra[0]);
  492.       plotGraphWithPlotlyAndMakeDataDownloadable(
  493.         divID,
  494.         traces.traces,
  495.         traces.layout
  496.       );
  497.       return traces;
  498.     } else if (
  499.       numberOfPatients == 2 &&
  500.       matrixSize == 192 &&
  501.       mutationType == "SBS"
  502.     ) {
  503.       let traces = plotMutationalProfileSBS192Comparison(
  504.         mutationalSpectra[0],
  505.         mutationalSpectra[1]
  506.       );
  507.       plotGraphWithPlotlyAndMakeDataDownloadable(
  508.         divID,
  509.         traces.traces,
  510.         traces.layout
  511.       );
  512.       return traces;
  513.     } else if (
  514.       numberOfPatients == 1 &&
  515.       matrixSize == 288 &&
  516.       mutationType == "SBS"
  517.     ) {
  518.       let traces = plotMutationalProfileSBS288(mutationalSpectra[0]);
  519.       plotGraphWithPlotlyAndMakeDataDownloadable(
  520.         divID,
  521.         traces.traces,
  522.         traces.layout
  523.       );
  524.       return traces;
  525.     } else if (
  526.       numberOfPatients == 1 &&
  527.       matrixSize == 384 &&
  528.       mutationType == "SBS"
  529.     ) {
  530.       let traces = plotMutationalProfileSBS384(mutationalSpectra[0]);
  531.       plotGraphWithPlotlyAndMakeDataDownloadable(
  532.         divID,
  533.         traces.traces,
  534.         traces.layout
  535.       );
  536.       return traces;
  537.     } else if (
  538.       numberOfPatients == 1 &&
  539.       matrixSize == 1536 &&
  540.       mutationType == "SBS"
  541.     ) {
  542.       let traces = plotMutationalProfileSBS1536(mutationalSpectra[0]);
  543.       plotGraphWithPlotlyAndMakeDataDownloadable(
  544.         divID,
  545.         traces.traces,
  546.         traces.layout
  547.       );
  548.       return traces;
  549.     } else if (
  550.       numberOfPatients == 1 &&
  551.       matrixSize == 78 &&
  552.       mutationType == "DBS"
  553.     ) {
  554.       let traces = plotMutationalProfileDBS78(mutationalSpectra[0]);
  555.       plotGraphWithPlotlyAndMakeDataDownloadable(
  556.         divID,
  557.         traces.traces,
  558.         traces.layout
  559.       );
  560.       return traces;
  561.     } else if (
  562.       numberOfPatients == 2 &&
  563.       matrixSize == 78 &&
  564.       mutationType == "DBS"
  565.     ) {
  566.       let traces = plotMutationalProfileDBS78Comparison(
  567.         mutationalSpectra[0],
  568.         mutationalSpectra[1],
  569.         "pc"
  570.       );
  571.       plotGraphWithPlotlyAndMakeDataDownloadable(
  572.         divID,
  573.         traces.traces,
  574.         traces.layout
  575.       );
  576.       return traces;
  577.     } else if (
  578.       numberOfPatients == 1 &&
  579.       matrixSize == 186 &&
  580.       mutationType == "DBS"
  581.     ) {
  582.       let traces = plotMutationalProfileDBS186(mutationalSpectra[0]);
  583.       plotGraphWithPlotlyAndMakeDataDownloadable(
  584.         divID,
  585.         traces.traces,
  586.         traces.layout
  587.       );
  588.       return traces;
  589.     } else if (
  590.       numberOfPatients == 1 &&
  591.       matrixSize == 28 &&
  592.       mutationType == "ID"
  593.     ) {
  594.       let traces = plotMutationalProfileID28(mutationalSpectra[0]);
  595.       plotGraphWithPlotlyAndMakeDataDownloadable(
  596.         divID,
  597.         traces.traces,
  598.         traces.layout
  599.       );
  600.       return traces;
  601.     } else if (
  602.       numberOfPatients == 1 &&
  603.       matrixSize == 29 &&
  604.       mutationType == "ID"
  605.     ) {
  606.       let traces = plotMutationalProfileID29(mutationalSpectra[0]);
  607.       plotGraphWithPlotlyAndMakeDataDownloadable(
  608.         divID,
  609.         traces.traces,
  610.         traces.layout
  611.       );
  612.       return traces;
  613.     } else if (
  614.       numberOfPatients == 1 &&
  615.       matrixSize == 83 &&
  616.       mutationType == "ID"
  617.     ) {
  618.       let traces = plotMutationalProfileID83(mutationalSpectra[0]);
  619.       plotGraphWithPlotlyAndMakeDataDownloadable(
  620.         divID,
  621.         traces.traces,
  622.         traces.layout
  623.       );
  624.       return traces;
  625.     } else if (
  626.       numberOfPatients == 2 &&
  627.       matrixSize == 83 &&
  628.       mutationType == "ID"
  629.     ) {
  630.       let traces = plotMutationalProfileID83Comparison(
  631.         mutationalSpectra[0],
  632.         mutationalSpectra[1],
  633.         "pc"
  634.       );
  635.       plotGraphWithPlotlyAndMakeDataDownloadable(
  636.         divID,
  637.         traces.traces,
  638.         traces.layout
  639.       );
  640.       return traces;
  641.     } else if (
  642.       numberOfPatients == 1 &&
  643.       matrixSize == 415 &&
  644.       mutationType == "ID"
  645.     ) {
  646.       let traces = plotMutationalProfileID415(mutationalSpectra[0]);
  647.       plotGraphWithPlotlyAndMakeDataDownloadable(
  648.         divID,
  649.         traces.traces,
  650.         traces.layout
  651.       );
  652.       return traces;
  653.     } else if (
  654.       numberOfPatients == 1 &&
  655.       matrixSize == 32 &&
  656.       mutationType == "RS"
  657.     ) {
  658.       let traces = plotMutationalProfileRS32(mutationalSpectra[0]);
  659.       plotGraphWithPlotlyAndMakeDataDownloadable(
  660.         divID,
  661.         traces.traces,
  662.         traces.layout
  663.       );
  664.       return traces;
  665.     } else if (
  666.       numberOfPatients == 2 &&
  667.       matrixSize == 32 &&
  668.       mutationType == "RS"
  669.     ) {
  670.       let traces = plotMutationalProfileRS32Comparison(
  671.         mutationalSpectra[0],
  672.         mutationalSpectra[1]
  673.       );
  674.       plotGraphWithPlotlyAndMakeDataDownloadable(
  675.         divID,
  676.         traces.traces,
  677.         traces.layout
  678.       );
  679.       return traces;
  680.     } else {
  681.       let traces = [];
  683.       const layout = {
  684.         title: `Mutational Spectra for ${Object.keys(mutationalSpectra).join(
  685.           ", "
  686.         )}`,
  687.         xaxis: { title: "Mutation Type" },
  688.         yaxis: { title: "Count" },
  689.         barmode: "group",
  690.       };
  692.       for (let i = 0; i < Object.keys(mutationalSpectra).length; i++) {
  693.         let plotlyData = formatMutationalSpectraData(
  694.           mutationalSpectra[Object.keys(mutationalSpectra)[i]],
  695.           Object.keys(mutationalSpectra)[i]
  696.         );
  698.         traces = traces.concat(plotlyData);
  699.       }
  701.       plotGraphWithPlotlyAndMakeDataDownloadable(divID, traces, layout);
  702.     }
  703.   }
  705.   /**
  706.    * Converts the mutational spectra data to a format that can be used to create a Plotly chart.
  707.    * @function formatMutationalSpectraData
  708.    * @memberof mSigPortalData
  709.    * @param {Object} mutationalSpectrum - An object containing the mutational spectra data.
  710.    * @param {string} sample - The name of the sample.
  711.    * @returns {Object[]} The data in a format that can be used to create a Plotly chart. The data is an array of objects. Each object has a name, x, y, and type property. The name property is the name of the mutation type. The x property is an array of the mutation names. The y property is an array of the mutation frequencies. The type property is the type of substitution that takes place.
  712.    */
  714.   function formatMutationalSpectraData(mutationalSpectrum, sample) {
  715.     const matrixSize = Object.keys(mutationalSpectrum).length;
  716.     if (matrixSize === 96) {
  717.       const substitutionTypes = ["C>A", "C>G", "C>T", "T>A", "T>C", "T>G"];
  719.       const data = substitutionTypes.map((substitutionType) => {
  720.         return {
  721.           name: `${substitutionType}  ${sample}`,
  722.           x: [],
  723.           y: [],
  724.           type: "bar",
  725.         };
  726.       });
  728.       substitutionTypes.forEach((substitutionType) => {
  729.         Object.keys(mutationalSpectrum)
  730.           .filter((key) => {
  731.             return key.includes(substitutionType);
  732.           })
  733.           .forEach((key) => {
  734.             data
  735.               .find((e) => e.name === `${substitutionType}  ${sample}`)
  736.               .x.push(key);
  737.             data
  738.               .find((e) => e.name === `${substitutionType}  ${sample}`)
  739.               .y.push(mutationalSpectrum[key]);
  740.           });
  741.       });
  743.       return data;
  744.     } else if (matrixSize === 192) {
  745.       console.error("Not supported yet");
  746.     } else if (matrixSize === 1536) {
  747.       console.error("Not supported yet");
  748.     } else {
  749.       console.error("Invalid Matrix Size");
  750.     }
  751.   }
  753.   //#endregion
  755.   //#region Creates a force directed tree of the patients in the study based on their mutational spectra
  757.   /**
  758.    * Extracts the mutational spectra out of the mSigPortal API call.
  759.    * @function extractMutationalSpectra
  760.    * @memberof mSigPortalData
  761.    * @param {Object[]} data - An array of objects containing the data from the mSigPortal API call.
  762.    * @param {string} [groupName="sample"] - The name of the group to extract the mutational spectra from.
  763.    * @returns {Object} An object containing the mutational spectra data grouped by the specified group name.
  764.    */
  766.   function extractMutationalSpectra(data, groupName = "sample") {
  767.     data = data.flat();
  769.     // Group all of the dictionaries in the data array by sample name
  770.     let groupedData = groupBy(data, groupName);
  772.     // Converts the grouped data into mutational spectrum dictionaries that can be used to create a force directed tree.
  773.     Object.keys(groupedData).forEach(function (key) {
  774.       let mutationalSpectrum = init_sbs_mutational_spectra();
  776.       groupedData[key].forEach((mutation) => {
  777.         let mutationType = mutation["mutationType"];
  778.         if (groupName == "sample") {
  779.           mutationalSpectrum[mutationType] = mutation["mutations"];
  780.         } else if (groupName == "signatureName") {
  781.           mutationalSpectrum[mutationType] = mutation["contribution"];
  782.         } else {
  783.           console.error("Invalid group name");
  784.         }
  785.       });
  787.       groupedData[key] = mutationalSpectrum;
  788.     });
  789.     return groupedData;
  790.   }
  792.   /**
  793.    * @async
  794.    * @function plotCosineSimilarityHeatMap
  795.    * @description Generates a cosine similarity heatmap based on mutational spectra data.
  796.    * This function processes grouped mutational data to compute cosine similarities,
  797.    * optionally performs double clustering to reorder the data, and then visualizes
  798.    * the similarities using a Plotly heatmap. It also supports displaying a table
  799.    * representation of the cosine similarity matrix alongside the heatmap.
  800.    * @memberof mSigPortalPlots
  801.    * @param {Object} groupedData - The input data object where keys represent sample names
  802.    *   and values are objects representing mutational spectra. The mutational spectra
  803.    *   should be represented as key-value pairs where keys are mutation types and values
  804.    *   are counts or frequencies.
  805.    *   Example:
  806.    *   ```
  807.    *   {
  808.    *     'Sample1': {'C>A': 10, 'C>G': 15, 'C>T': 20, ...},
  809.    *     'Sample2': {'C>A': 5, 'C>G': 8, 'C>T': 12, ...},
  810.    *     ...
  811.    *   }
  812.    *   ```
  813.    *   The range of keys (mutation types) should be consistent across all samples. The values
  814.    *   (counts or frequencies) can be integers or floats, and their range can vary based on the
  815.    *   underlying data, but typically they are non-negative.
  816.    *
  817.    * @param {string} [studyName="PCAWG"] - The name of the study. This is used in the
  818.    *   title of the heatmap. Common values include study identifiers like "PCAWG",
  819.    *   "TCGA", or specific project names. The parameter should be a string and can
  820.    *   technically accept any string value, but it is intended to represent the name
  821.    *   of a study or dataset.
  822.    *
  823.    * @param {string} [genomeDataType="WGS"] - The type of genomic data. This is also
  824.    *   used in the title of the heatmap. Expected values typically include abbreviations
  825.    *   for common genomic data types such as "WGS" (Whole Genome Sequencing), "WES"
  826.    *   (Whole Exome Sequencing), "RNA-Seq", etc. Similar to `studyName`, any string
  827.    *   is technically accepted, but the intended use is to describe the data type.
  828.    *
  829.    * @param {string} [cancerType="Lung-AdenoCA"] - The type of cancer. This is included
  830.    *   in the title of the heatmap. Common values are standard cancer type
  831.    *   abbreviations or names, like "Lung-AdenoCA" (Lung Adenocarcinoma), "BRCA"
  832.    *   (Breast Invasive Carcinoma), etc. Any string value is accepted, but it should
  833.    *   represent a specific cancer type.
  834.    *
  835.    * @param {string} [divID="cosineSimilarityHeatMap"] - The ID of the HTML element where
  836.    *   the heatmap will be rendered. This should be a valid HTML element ID. If an element
  837.    *   with this ID does not exist, one will be created and appended to the document body.
  838.    *   Any string is accepted, but it should correspond to a unique ID in the HTML
  839.    *   document to avoid conflicts.
  840.    *
  841.    * @param {boolean} [conductDoubleClustering=true] - A flag indicating whether to
  842.    *   perform double clustering (hierarchical clustering on both rows and columns)
  843.    *   on the cosine similarity matrix. If `true`, the rows and columns of the heatmap
  844.    *   will be reordered based on the clustering. If `false`, the order of samples in
  845.    *   `groupedData` will be maintained. Boolean values `true` or `false` are expected.
  846.    *
  847.    * @param {string} [colorscale="RdBu"] - The Plotly colorscale to use for the heatmap.
  848.    *   This can be any valid Plotly colorscale name (e.g., "Viridis", "Greys", "YlGnBu",
  849.    *   "RdBu"). Plotly provides a wide range of predefined colorscales. The chosen
  850.    *   colorscale will affect the visual representation of the similarity values. Any
  851.    *   string is accepted but it should correspond to a valid Plotly colorscale for
  852.    *   optimal results.
  853.    *
  854.    * @param {boolean} [showTable=false] - A flag indicating whether to display a table
  855.    *   representation of the cosine similarity matrix alongside the heatmap. If `true`,
  856.    *   a table will be rendered next to the heatmap. If `false`, only the heatmap will
  857.    *   be displayed. Boolean values `true` or `false` are expected.
  858.    *
  859.    * @returns {Promise<number[][]>} A Promise that resolves to the cosine similarity matrix.
  860.    *   The matrix is a two-dimensional array of numbers, where each number represents
  861.    *   the cosine similarity between two samples. The values range from 0 to 1, where 1
  862.    *   indicates perfect similarity and 0 indicates no similarity. The dimensions of
  863.    *   the matrix will be NxN, where N is the number of samples in `groupedData`.
  864.    *
  865.    * @throws Will throw an error if the `cosineSimilarity` function or the
  866.    *   `plotGraphWithPlotlyAndMakeDataDownloadable` function throws an error.
  867.    *
  868.    */
  870.   async function plotCosineSimilarityHeatMap(
  871.     groupedData,
  872.     studyName = "PCAWG",
  873.     genomeDataType = "WGS",
  874.     cancerType = "Lung-AdenoCA",
  875.     divID = "cosineSimilarityHeatMap",
  876.     conductDoubleClustering = true,
  877.     colorscale = "RdBu",
  878.     showTable = false
  879.   ) {
  880.     let container = document.getElementById(divID);
  881.     if (!container) {
  882.       container = document.createElement('div');
  883.       container.id = divID;
  884.       document.body.appendChild(container);
  885.     }
  887.     container.innerHTML = '';
  888.     container.style.display = 'flex';
  889.     container.style.flexDirection = showTable ? 'row' : 'column';
  890.     container.style.gap = '20px';
  891.     container.style.width = '100%';
  892.     container.style.alignItems = 'center'; // Center items vertically
  894.     const heatmapDiv = document.createElement('div');
  895.     heatmapDiv.id = `${divID}-heatmap`;
  896.     heatmapDiv.style.flex = showTable ? '1' : '1';
  897.     container.appendChild(heatmapDiv);
  899.     groupedData = extractMutationalSpectra(groupedData);
  900.     let distanceMatrix = await createDistanceMatrix(
  901.       Object.values(groupedData).map((data) => Object.values(data)),
  902.       cosineSimilarity,
  903.       true
  904.     );
  906.     let cosSimilarityMatrix = distanceMatrix.map(function (row) {
  907.       return row.map(function (cell) {
  908.         return 1 - cell;
  909.       });
  910.     });
  912.     let reorderedData;
  913.     if (conductDoubleClustering) {
  914.       reorderedData = doubleClustering(
  915.         cosSimilarityMatrix,
  916.         Object.keys(groupedData),
  917.         Object.keys(groupedData)
  918.       );
  919.     } else {
  920.       reorderedData = {
  921.         matrix: cosSimilarityMatrix,
  922.         rowNames: Object.keys(groupedData),
  923.         colNames: Object.keys(groupedData),
  924.       };
  925.     }
  927.     let plotlyData = [
  928.       {
  929.         z: reorderedData.matrix,
  930.         x: reorderedData.rowNames,
  931.         y: reorderedData.colNames,
  932.         type: "heatmap",
  933.         colorscale: colorscale,
  934.       },
  935.     ];
  937.     let layout = {
  938.       title: `${studyName} ${cancerType} ${genomeDataType} Cosine Similarity Heatmap`,
  939.       height: 800,
  940.       width: showTable ? container.offsetWidth * 0.6 : container.offsetWidth,
  941.       xaxis: {
  942.         title: "Sample",
  943.         type: "category",
  944.         nticks: Object.keys(groupedData).length,
  945.       },
  946.       yaxis: {
  947.         title: "Sample",
  948.         type: "category",
  949.         nticks: Object.keys(groupedData).length,
  950.       },
  951.     };
  953.     plotGraphWithPlotlyAndMakeDataDownloadable(heatmapDiv.id, plotlyData, layout);
  955.     if (showTable) {
  956.       const tableDiv = document.createElement('div');
  957.       tableDiv.id = `${divID}-table`;
  958.       tableDiv.style.flex = '1';
  959.       tableDiv.style.overflowX = 'auto';
  960.       tableDiv.style.display = 'flex';  // Add flex display
  961.       tableDiv.style.alignItems = 'center';  // Center vertically
  962.       tableDiv.style.height = '800px';  // Match heatmap height
  963.       container.appendChild(tableDiv);
  965.       const tableWrapper = document.createElement('div');  // Add wrapper for table
  966.       tableWrapper.style.width = '100%';
  967.       tableDiv.appendChild(tableWrapper);
  969.       const table = document.createElement('table');
  970.       table.style.borderCollapse = 'collapse';
  971.       table.style.width = '100%';
  972.       table.style.fontSize = '12px';
  974.       // Create header row with simple styling
  975.       const thead = document.createElement('thead');
  976.       const headerRow = document.createElement('tr');
  977.       headerRow.innerHTML = '<th style="border: 1px solid #ddd; padding: 8px; background-color: #f8f9fa;">Sample</th>';
  978.       reorderedData.colNames.forEach(colName => {
  979.         headerRow.innerHTML += `<th style="border: 1px solid #ddd; padding: 8px; background-color: #f8f9fa;">${colName}</th>`;
  980.       });
  981.       thead.appendChild(headerRow);
  982.       table.appendChild(thead);
  984.       // Create table body with simple styling
  985.       const tbody = document.createElement('tbody');
  986.       reorderedData.matrix.forEach((row, rowIndex) => {
  987.         const tr = document.createElement('tr');
  988.         tr.innerHTML = `<td style="border: 1px solid #ddd; padding: 8px; font-weight: bold;">${reorderedData.rowNames[rowIndex]}</td>`;
  989.         row.forEach(value => {
  990.           const formattedValue = value.toFixed(3);
  991.           tr.innerHTML += `<td style="border: 1px solid #ddd; padding: 8px; text-align: center;">${formattedValue}</td>`;
  992.         });
  993.         tbody.appendChild(tr);
  994.       });
  995.       table.appendChild(tbody);
  996.       tableWrapper.appendChild(table);
  997.     }
  999.     return cosSimilarityMatrix;
  1000.   }
  1002.   /**
  1003.    * @memberof mSigPortalPlots
  1004.    * @function plotSignatureActivityDataBy
  1005.    * @description Generates a box plot of signature activity data, grouped by a specified attribute. The function takes a dataset and groups it by the provided attribute (e.g., "signatureName", "study", "cancerType"). For each group, it creates a box trace where the y-values represent the log10 of the exposure values and the x-values are set to the group name. The box plot displays the distribution of exposure values for each group, with the option to show all individual data points (jittered for better visibility). Hovering over the data points reveals the sample name and the log10 of the exposure value. The plot also indicates the fraction of samples within each group that have non-zero exposure.
  1006.    *
  1007.    * @param {string} divID - The ID of the div element where the plot will be rendered.
  1008.    * @param {Array<object>} data - An array of objects representing the signature activity data. Each object must have at least the following properties:
  1009.    *   - `exposure`: A numeric value representing the exposure of a signature. It can be any positive number or zero.
  1010.    *   - `sample`: A string representing the sample ID.
  1011.    *   - The `data` array must also contain a property matching the name specified by the `group` parameter (e.g., "signatureName", "study", "cancerType").
  1012.    * @param {string} [group="signatureName"] - The attribute to group the data by. Possible values are any property name present in the data objects, including, but not limited to:
  1013.    *   - `"signatureName"`: Groups the data by signature names.
  1014.    *   - `"study"`: Groups the data by study IDs.
  1015.    *   - `"cancerType"`: Groups the data by cancer types.
  1016.    *   - `"sample"`: Groups the data by sample IDs (Note: this might not result in a meaningful box plot).
  1017.    *   - Any other custom property that exists in the data objects.
  1018.    *   The default value is `"signatureName"`.
  1019.    * @return {void} - This function does not return a value. It directly renders the plot in the specified `divID`.
  1020.    */
  1021.   function plotSignatureActivityDataBy(divID, data, group = "signatureName") {
  1022.     // Group the data by the specified group using the groupBy function
  1023.     const groupedData = groupBy(data, group);
  1025.     // Create an array of box trace objects for each group
  1026.     const groupTraces = Object.keys(groupedData).map((groupName) => {
  1027.       const exposures = groupedData[groupName].map((d) =>
  1028.         Math.log10(d.exposure)
  1029.       );
  1030.       const samples = groupedData[groupName].map((d) => d.sample);
  1031.       const numNonZero = exposures.filter(
  1032.         (exposure) => exposure !== -Infinity
  1033.       ).length;
  1034.       return {
  1035.         y: exposures,
  1036.         x: new Array(exposures.length).fill(groupName),
  1037.         type: "box",
  1038.         name: groupName,
  1039.         boxpoints: "all",
  1040.         jitter: 0.3,
  1041.         hovertext: samples,
  1042.         hovertemplate:
  1043.           `<b>${groupName}</b><br>Log(Exposure): %{y:.2f}<br>` +
  1044.           `Fraction of samples with non-zero exposure: ${numNonZero} / ${exposures.length}`,
  1045.       };
  1046.     });
  1048.     // Plot the box traces using Plotly and display the plot in the specified divID
  1049.     plotGraphWithPlotlyAndMakeDataDownloadable(divID, groupTraces, {
  1050.       title: `Cumulative Exposure for ${group}`,
  1051.       yaxis: { title: "Log(Exposure)" },
  1052.       xaxis: { title: group },
  1053.     });
  1054.   }
  1056.   /**
  1057.    * @memberof mSigPortalPlots
  1058.    * @function plotForceDirectedTree
  1059.    * @description This function generates and displays a force-directed tree representing the relationships between patients in a study based on their mutational spectra. It calculates the cosine similarity between the mutational spectra of patients, performs hierarchical clustering based on these similarities, and then visualizes the resulting clusters as a force-directed tree.
  1060.    *
  1061.    * @param {object} groupedData - An object where keys represent sample IDs and values are objects containing mutational spectra data. The structure of `groupedData` is expected to be:
  1062.    *   `{ sampleId1: { mutationType1: count1, mutationType2: count2, ... }, sampleId2: { mutationType1: count3, mutationType2: count4, ... }, ... }`
  1063.    *   The inner objects (e.g., `{ mutationType1: count1, ... }`) represent the mutational spectrum for a given sample. `mutationType` keys can be any string representing a type of mutation (e.g., "C>A", "T>G"), and `count` values are non-negative integers representing the number of times that mutation type is observed in the sample.
  1064.    * @param {string} [studyName="PCAWG"] - The name of the study. This is used for labeling purposes in the visualization. Common values include, but are not limited to:
  1065.    *   - `"PCAWG"`
  1066.    *   - `"TCGA"`
  1067.    *   - Any other string representing a specific study.
  1068.    * @param {string} [genomeDataType="WGS"] - The type of genome data used. This is also used for labeling purposes. Possible values include:
  1069.    *   - `"WGS"`: Whole Genome Sequencing
  1070.    *   - `"WES"`: Whole Exome Sequencing
  1071.    *   - `"RNA-Seq"`: RNA Sequencing
  1072.    * @param {string} [cancerType="Lung-AdenoCA"] - The type of cancer being studied. This is used for labeling in the visualization. Examples include:
  1073.    *   - `"Lung-AdenoCA"`: Lung Adenocarcinoma
  1074.    *   - `"Breast-AdenoCA"`: Breast Adenocarcinoma
  1075.    *   - Any valid cancer type identifier.
  1076.    * @param {string} [divID="forceDirectedTree"] - The ID of the HTML div element where the force-directed tree will be rendered.
  1077.    * @return {object} - Returns the formatted hierarchical clusters used to generate the force-directed tree. The structure of this object is compatible with the AM5 charting library and represents the hierarchical relationships between samples based on their mutational spectra. The format is a nested object where each level represents a node in the tree. Each node can have properties such as `name`, `value`, `children` (an array of child nodes), and potentially others added during formatting.
  1078.    */
  1080.   // This function plots a force directed tree of the patients in the study based on their mutational spectra
  1081.   async function plotForceDirectedTree(
  1082.     groupedData,
  1083.     studyName = "PCAWG",
  1084.     genomeDataType = "WGS",
  1085.     cancerType = "Lung-AdenoCA",
  1086.     divID = "forceDirectedTree"
  1087.   ) {
  1088.     groupedData = extractMutationalSpectra(groupedData);
  1089.     let distanceMatrix = await createDistanceMatrix(
  1090.       Object.values(groupedData).map((data) => Object.values(data)),
  1091.       cosineSimilarity,
  1092.       true
  1093.     );
  1095.     let clusters = await hierarchicalClustering(
  1096.       distanceMatrix,
  1097.       Object.keys(groupedData)
  1098.     );
  1100.     let formattedClusters = formatHierarchicalClustersToAM5Format(
  1101.       clusters,
  1102.       studyName,
  1103.       genomeDataType,
  1104.       cancerType,
  1105.       Object.keys(groupedData).length,
  1106.       groupedData
  1107.     );
  1109.     // $(`#${divID}`).css({"width": "100%", "height": "550px", "max-width": "100%"})
  1110.     const element = document.getElementById(divID);
  1111.     element.style.width = "100%";
  1112.     element.style.height = "600px";
  1113.     element.style.maxWidth = "100%";
  1115.     generateForceDirectedTree(formattedClusters, divID);
  1117.     return formattedClusters;
  1118.   }
  1120.   async function generateForceDirectedTree(data, divID) {
  1121.     // Create root element
  1122.     // https://www.amcharts.com/docs/v5/getting-started/#Root_element
  1123.     var root = am5.Root.new(divID);
  1125.     // Set themes
  1126.     // https://www.amcharts.com/docs/v5/concepts/themes/
  1127.     root.setThemes([am5themes_Animated.default.new(root)]);
  1129.     // Create wrapper container
  1130.     var container = root.container.children.push(
  1131.       am5.Container.new(root, {
  1132.         width: am5.percent(100),
  1133.         height: am5.percent(100),
  1134.         layout: root.verticalLayout,
  1135.       })
  1136.     );
  1138.     // Create series
  1139.     // https://www.amcharts.com/docs/v5/charts/hierarchy/#Adding
  1140.     var series = container.children.push(
  1141.       am5hierarchy.ForceDirected.new(root, {
  1142.         singleBranchOnly: false,
  1143.         downDepth: 2,
  1144.         initialDepth: 0,
  1145.         valueField: "totalMutationCount",
  1146.         categoryField: "name",
  1147.         childDataField: "children",
  1148.         minRadius: 20,
  1149.         maxRadius: 80,
  1150.         centerStrength: 0.5,
  1151.       })
  1152.     );
  1154.     series.nodes.template._settings.tooltipText =
  1155.       "Total Mutations: {totalMutationCount}";
  1156.     series.adapters.add("fill", function (fill, target) {
  1157.       return fill.lighten(target.dataItem.level * 0.25);
  1158.     });
  1160.     series.data.setAll([data]);
  1161.     series.set("selectedDataItem", series.dataItems[0]);
  1163.     series.appear(1000, 100);
  1164.   }
  1166.   //#endregion
  1168.   //#region Visualizes a set of mutational spectra using UMAP.
  1171.   /**
  1172.  * @memberof mSigPortalPlots
  1173.  * @function plotUMAPVisualization
  1174.  * @description Generates a UMAP (Uniform Manifold Approximation and Projection) visualization of mutational spectra data. UMAP is a dimensionality reduction technique used to project high-dimensional data into a lower-dimensional space (typically 2D or 3D) while preserving the global structure of the data. This function takes mutational spectra data, applies UMAP to reduce its dimensionality, and then creates either a 2D or 3D scatter plot to visualize the results. If `nComponents` is set to 3, it additionally generates a mesh3d trace to highlight the density of points in the 3D space.
  1175.  *
  1176.  * @param {object} data - An object representing the mutational spectra data. The structure of `data` is expected to be:
  1177.  *   `{ sampleId1: { mutationType1: count1, mutationType2: count2, ... }, sampleId2: { mutationType1: count3, mutationType2: count4, ... }, ... }`
  1178.  *   The outer keys (e.g., `sampleId1`, `sampleId2`) are sample identifiers (strings). The inner objects (e.g., `{ mutationType1: count1, ... }`) represent the mutational spectrum for a given sample. `mutationType` keys can be any string representing a type of mutation (e.g., "C>A", "T>G"), and `count` values are non-negative integers representing the number of times that mutation type is observed in the sample.
  1179.  * @param {string} [datasetName="PCAWG"] - The name of the dataset being visualized. This is used as part of the plot title. Examples include:
  1180.  *   - `"PCAWG"`
  1181.  *   - `"TCGA"`
  1182.  *   - Any other string that appropriately identifies the dataset.
  1183.  * @param {string} divID - The ID of the HTML div element where the plot will be rendered.
  1184.  * @param {number} [nComponents=3] - The number of dimensions to reduce the data to using UMAP. This determines whether a 2D or 3D plot is generated. Possible values are:
  1185.  *   - `2`: Generates a 2D scatter plot.
  1186.  *   - `3`: Generates a 3D scatter plot with an additional mesh3d trace.
  1187.  *   Any other positive integer is technically permissible but may not yield meaningful visualizations.
  1188.  * @param {number} [minDist=0.1] - The effective minimum distance between embedded points in the UMAP projection. Smaller values result in a more clustered embedding, while larger values preserve more of the global structure. The valid range is between 0.0 and 1.0.
  1189.  * @param {number} [nNeighbors=15] - The number of neighboring points to consider when constructing the UMAP. Larger values capture more global structure in the data, while smaller values preserve more local structure. Values should be positive integers, typically in the range of 2 to 100.
  1190.  * @return {object} - Returns the trace object used by Plotly to generate the visualization. This object contains the data points, plot type, marker settings, and, in the case of a 3D plot, the mesh3d settings. The structure depends on the value of `nComponents`.
  1191.  */
  1192.   async function plotUMAPVisualization(
  1193.     data,
  1194.     datasetName = "PCAWG",
  1195.     divID,
  1196.     nComponents = 3,
  1197.     minDist = 0.1,
  1198.     nNeighbors = 15
  1199.   ) {
  1200.     data = extractMutationalSpectra(data);
  1201.     let umap = new UMAP.default.UMAP({
  1202.       nComponents: nComponents,
  1203.       minDist: minDist,
  1204.       nNeighbors: nNeighbors,
  1205.     });
  1206.     let embeddings = await umap.fit(
  1207.       Object.values(data).map((data) => Object.values(data))
  1208.     );
  1209.     let plotType = nComponents === 3 ? "scatter3d" : "scatter";
  1210.     let axisLabels = nComponents === 3 ? ["X", "Y", "Z"] : ["X", "Y"];
  1212.     let trace = [
  1213.       {
  1214.         x: embeddings.map((d) => d[0]),
  1215.         y: embeddings.map((d) => d[1]),
  1216.         text: Object.keys(data),
  1217.         mode: "markers",
  1218.         type: plotType,
  1219.         marker: { size: 6 },
  1220.       },
  1221.     ];
  1223.     if (nComponents === 3) {
  1224.       trace[0].z = embeddings.map((d) => d[2]);
  1226.       trace.push({
  1227.         alphahull: 7,
  1228.         opacity: 0.1,
  1229.         type: "mesh3d",
  1230.         x: embeddings.map((d) => d[0]),
  1231.         y: embeddings.map((d) => d[1]),
  1232.         z: embeddings.map((d) => d[2]),
  1233.       });
  1234.     }
  1236.     let layout = {
  1237.       title: `${nComponents} Component UMAP Projection of ${datasetName} Dataset`,
  1238.       xaxis: { title: axisLabels[0] },
  1239.       yaxis: { title: axisLabels[1] },
  1240.     };
  1242.     if (nComponents === 3) {
  1243.       layout.scene = { zaxis: { title: axisLabels[2] } };
  1244.     }
  1246.     plotGraphWithPlotlyAndMakeDataDownloadable(divID, trace, layout);
  1248.     return trace;
  1249.   }
  1251.   //#endregion
  1253.   //#region Signature Fitting
  1255.   /**
  1256.    * Fits mutational spectra to known mutational signatures using non-negative least squares (NNLS).
  1257.    *
  1258.    * This function calculates the exposure of mutational signatures for each sample by fitting
  1259.    * the observed mutational spectra to the reference mutational signatures. It then filters out
  1260.    * signatures whose contribution is below a fraction of the total exposure, by setting their
  1261.    * exposures to zero.
  1262.    *
  1263.    * You can choose to return exposures as absolute values (raw counts from NNLS) or relative values
  1264.    * (sum to 1 for each sample). The filtering threshold is a fraction between 0 and 1.
  1265.    *
  1266.    * @async
  1267.    * @function fitMutationalSpectraToSignatures
  1268.    * @memberof machineLearning
  1269.    * @param {Object} mutationalSignatures - Reference mutational signatures. Each key is a signature name,
  1270.    * and each value is an object of mutation types (e.g., {"C>A": weight, "C>G": weight}).
  1271.    * @param {Object} mutationalSpectra - Mutational spectra for each sample. Each key is a sample ID,
  1272.    * and each value is an object of mutation types with their counts (e.g., {"C>A": count, "C>G": count}).
  1273.    * @param {Object} [options] - Configuration options for filtering and output.
  1274.    * @param {number} [options.exposureThreshold=0] - Exclude signatures below this fraction of the total,
  1275.    * by setting their exposures to zero. Must be between 0 and 1.
  1276.    * @param {("absolute"|"relative")} [options.exposureType="relative"] - Return exposures as absolute or relative.
  1277.    * @param {boolean} [options.renormalize=true] - Whether to normalize exposures so that they sum to 1 after filtering.
  1278.    * @returns {Object} - An object with sample IDs as keys. Each value is an object of signature exposures.
  1279.    *
  1280.    * @example
  1281.    * // Example usage:
  1282.    * // 1. Get mutational signatures (e.g., from the mSigPortal API)
  1283.    * const mutationalSignatures = await mSigPortal.mSigPortalData.getMutationalSignaturesData(
  1284.    *   "WGS", "COSMIC_v3_Signatures_GRCh37_SBS96", "SBS", 96, 1000
  1285.    * );
  1286.    *
  1287.    * // 2. Extract mutational spectra for each sample
  1288.    * const extractedSpectra = await mSigPortal.mSigPortalData.extractMutationalSpectra(
  1289.    *   mutationalSignatures, "signatureName"
  1290.    * );
  1291.    *
  1292.    * // 3. Fit spectra to signatures with post-fit filtering
  1293.    * const nnlsExposures = await mSigPortal.signatureFitting.fitMutationalSpectraToSignatures(
  1294.    *   mutationalSignatures,
  1295.    *   extractedSpectra,
  1296.    *   {
  1297.    *     exposureThreshold: 0.1,
  1298.    *     exposureType: "relative",
  1299.    *     renormalize: true
  1300.    *   }
  1301.    * );
  1302.    *
  1303.    * console.log(nnlsExposures);
  1304.    * // {
  1305.    * //   Sample1: { SBS1: 0.75, SBS2: 0.25, SBS3: 0 },
  1306.    * //   Sample2: { SBS1: 0.9, SBS2: 0.1, SBS3: 0 },
  1307.    * //   ...
  1308.    * // }
  1309.    */
  1310.   async function fitMutationalSpectraToSignatures(
  1311.     mutationalSignatures,
  1312.     mutationalSpectra,
  1313.     {
  1314.       exposureThreshold = 0,
  1315.       exposureType = "relative",
  1316.       renormalize = true
  1317.     } = {}
  1318.   ) {
  1319.     // Validate the threshold
  1320.     if (exposureThreshold < 0 || exposureThreshold > 1) {
  1321.       throw new Error("exposureThreshold must be between 0 and 1.");
  1322.     }
  1324.     const signatureNames = Object.keys(mutationalSignatures);
  1325.     const sampleNames = Object.keys(mutationalSpectra);
  1327.     // Convert reference signatures to arrays for NNLS
  1328.     const nnlsInputSignatures = Object.values(mutationalSignatures).map(signatureData =>
  1329.       Object.values(signatureData)
  1330.     );
  1332.     // Convert mutational spectra to arrays for NNLS
  1333.     const nnlsInputMatrix = Object.values(mutationalSpectra).map(spectrumData =>
  1334.       Object.values(spectrumData)
  1335.     );
  1337.     const results = {};
  1339.     for (let i = 0; i < sampleNames.length; i++) {
  1340.       const sampleName = sampleNames[i];
  1341.       const nnlsInput = nnlsInputMatrix[i];
  1343.       // 1. Perform NNLS
  1344.       const nnlsOutput = await nnls(nnlsInputSignatures, nnlsInput);
  1345.       const exposureValues = nnlsOutput.x;
  1346.       delete nnlsOutput.x;
  1348.       // 2. Build an object of signature exposures (raw from NNLS)
  1349.       let sampleExposures = {};
  1350.       for (let j = 0; j < signatureNames.length; j++) {
  1351.         sampleExposures[signatureNames[j]] = exposureValues[j];
  1352.       }
  1354.       // 3. Calculate the total exposure
  1355.       const totalExposure = Object.values(sampleExposures).reduce((acc, val) => acc + val, 0);
  1357.       // 4. Filter out signatures below the fraction threshold by setting to 0
  1358.       if (totalExposure > 0) {
  1359.         for (let signature of signatureNames) {
  1360.           const fraction = sampleExposures[signature] / totalExposure;
  1361.           if (fraction < exposureThreshold) {
  1362.             sampleExposures[signature] = 0;
  1363.           }
  1364.         }
  1365.       }
  1367.       // 5. If renormalize is true, adjust exposures to sum to 1
  1368.       if (renormalize) {
  1369.         const filteredTotal = Object.values(sampleExposures).reduce((a, b) => a + b, 0);
  1370.         if (filteredTotal > 0) {
  1371.           for (let signature of signatureNames) {
  1372.             sampleExposures[signature] = sampleExposures[signature] / filteredTotal;
  1373.           }
  1374.         }
  1375.       }
  1377.       // 6. If returning relative exposures, ensure they sum to 1
  1378.       if (exposureType === "relative" && !renormalize) {
  1379.         const filteredTotal = Object.values(sampleExposures).reduce((a, b) => a + b, 0);
  1380.         if (filteredTotal > 0) {
  1381.           for (let signature of signatureNames) {
  1382.             sampleExposures[signature] = sampleExposures[signature] / filteredTotal;
  1383.           }
  1384.         }
  1385.       }
  1387.       // 7. Store the final exposures for each sample
  1388.       results[sampleName] = sampleExposures;
  1389.     }
  1391.     return results;
  1392.   }
  1395.   /**
  1396.    * @memberof mSigPortalPlots
  1397.    * @function plotPatientMutationalSignaturesExposure
  1398.    * @description Generates a pie chart visualizing the exposure of a single sample to a set of mutational signatures. The function takes exposure data, which includes the relative contribution of each signature to the sample's mutational profile, and displays it in a pie chart format.
  1399.    *
  1400.    * @param {object} exposureData - An object containing the exposure data for a set of samples. The structure of `exposureData` is expected to be:
  1401.    *   `{ sampleId1: { signatureName1: exposureValue1, signatureName2: exposureValue2, ... }, sampleId2: { signatureName1: exposureValue3, signatureName2: exposureValue4, ... }, ... }`
  1402.    *   The outer keys (e.g., `sampleId1`, `sampleId2`) are sample identifiers (strings). The inner objects (e.g., `{ signatureName1: exposureValue1, ... }`) represent the exposure values for a given sample. `signatureName` keys are strings representing the names of mutational signatures (e.g., "SBS1", "SBS5"), and `exposureValue` are non-negative numbers representing the contribution of that signature to the sample. These values typically sum to 1 for each sample. The `exposureData` object can contain multiple samples, but only the data for the specified `sample` will be used for plotting. `exposureData` must also have a `rnorm` property which is a number.
  1403.    * @param {string} divID - The ID of the HTML div element where the pie chart will be rendered.
  1404.    * @param {string} sample - The ID of the sample for which to plot the mutational signature exposure. This should be one of the keys in the `exposureData` object (e.g., "sampleId1", "sampleId2").
  1405.    * @return {object} - Returns the data object used by Plotly to generate the pie chart. This object contains the labels (signature names), values (exposure values), and other settings for the pie chart. The format is:
  1406.    *   `{ labels: [signatureName1, signatureName2, ...], values: [exposureValue1, exposureValue2, ...], name: "sample exposure values", textposition: "inside", hole: 0.4, hoverinfo: "name + value", type: "pie" }`
  1407.    */
  1408.   // This function plots the exposure of a set of samples to a set of mutational signatures
  1409.   async function plotPatientMutationalSignaturesExposure(
  1410.     exposureData,
  1411.     divID,
  1412.     sample
  1413.   ) {
  1414.     let dataset = deepCopy(exposureData);
  1416.     const rnorm = dataset["rnorm"];
  1417.     delete dataset["rnorm"];
  1418.     const plotType = "pie";
  1419.     const plotTitle = `Mutational Signature Exposure for ${sample} (r-norm = ${rnorm})`;
  1421.     let data = {
  1422.       labels: Object.keys(dataset),
  1423.       values: Object.values(dataset),
  1424.       name: `${sample} exposure values`,
  1425.       textposition: "inside",
  1426.       hole: 0.4,
  1427.       hoverinfo: "name + value",
  1428.       type: plotType,
  1429.     };
  1431.     let layout = {
  1432.       title: plotTitle,
  1433.     };
  1435.     plotGraphWithPlotlyAndMakeDataDownloadable(divID, [data], layout);
  1437.     return data;
  1438.   }
  1440.   /**
  1441.    * @memberof mSigPortalPlots
  1442.    * @function plotDatasetMutationalSignaturesExposure
  1443.    * @description Generates a heatmap visualizing the exposure of multiple samples to a set of mutational signatures within a dataset. The function provides options for displaying relative or absolute exposure values and for performing double hierarchical clustering to reorder the rows and columns of the heatmap. It also allows customization of the color scale used to represent exposure values.
  1444.    *
  1445.    * @param {object} exposureData - An object containing the exposure data for a set of samples. The structure of `exposureData` is expected to be:
  1446.    *   `{ sampleId1: { signatureName1: exposureValue1, signatureName2: exposureValue2, ..., rnorm: number }, sampleId2: { signatureName1: exposureValue3, signatureName2: exposureValue4, ..., rnorm: number }, ... }`
  1447.    *   The outer keys (e.g., `sampleId1`, `sampleId2`) are sample identifiers (strings). The inner objects (e.g., `{ signatureName1: exposureValue1, ... }`) represent the exposure values for a given sample. `signatureName` keys are strings representing the names of mutational signatures (e.g., "SBS1", "SBS5"), and `exposureValue` are non-negative numbers representing the contribution of that signature to the sample. `rnorm` is a number that will be removed from the data before plotting.
  1448.    * @param {string} divID - The ID of the HTML div element where the heatmap will be rendered.
  1449.    * @param {boolean} [relative=true] - A boolean indicating whether to display relative or absolute exposure values.
  1450.    *   - `true`: The exposure values for each sample are normalized to sum to 1, representing the relative contribution of each signature.
  1451.    *   - `false`: The raw exposure values are displayed.
  1452.    * @param {string} [datasetName="PCAWG"] - The name of the dataset being visualized. This is used as part of the plot title. Examples include:
  1453.    *   - `"PCAWG"`
  1454.    *   - `"TCGA"`
  1455.    *   - Any other string that appropriately identifies the dataset.
  1456.    * @param {boolean} [doubleCluster=true] - A boolean indicating whether to perform double hierarchical clustering on the exposure data.
  1457.    *   - `true`: The rows and columns of the heatmap are reordered based on the results of double clustering, which groups similar samples and signatures together.
  1458.    *   - `false`: The rows and columns are displayed in the order they appear in the input `exposureData`.
  1459.    * @param {string | Array} [colorscale="Custom"] - The color scale to use for the heatmap. Possible values are:
  1460.    *   - `"Custom"`: A predefined custom color scale designed for visualizing exposure data.
  1461.    *   - Any valid Plotly color scale name (e.g., `"Viridis"`, `"Blues"`, `"Hot"`, etc.).
  1462.    *   - An array of arrays defining a custom color scale, where each inner array specifies a color stop with a value between 0 and 1 and a corresponding RGB color string (e.g., `[["0.0", "rgb(49,54,149)"], ["1.0", "rgb(165,0,38)"]]`).
  1463.    * @return {object} - Returns the data object used by Plotly to generate the heatmap. This object contains the z values (exposure values), x values (signature names), y values (sample names), and other settings for the heatmap, including the color scale. The structure is:
  1464.    *   `{ z: [[exposureValue1, exposureValue2, ...], [exposureValue3, exposureValue4, ...], ...], x: [signatureName1, signatureName2, ...], y: [sampleId1, sampleId2, ...], type: "heatmap", colorscale: colorscale }`
  1465.    */
  1466.   async function plotDatasetMutationalSignaturesExposure(
  1467.     exposureData,
  1468.     divID,
  1469.     relative = true,
  1470.     datasetName = "PCAWG",
  1471.     doubleCluster = true,
  1472.     colorscale = "Custom"
  1473.   ) {
  1474.     let dataset = deepCopy(exposureData);
  1475.     // Remove the rnorm values from each sample of the exposure data
  1477.     for (let sample in dataset) {
  1478.       delete dataset[sample]["rnorm"];
  1479.     }
  1481.     if (relative) {
  1482.       for (let sample in dataset) {
  1483.         let total = 0;
  1484.         for (let signature in dataset[sample]) {
  1485.           total += dataset[sample][signature];
  1486.         }
  1487.         for (let signature in dataset[sample]) {
  1488.           dataset[sample][signature] /= total;
  1489.         }
  1490.       }
  1491.     }
  1492.     let reorderedData;
  1493.     if (doubleCluster) {
  1494.       reorderedData = doubleClustering(
  1495.         Object.values(dataset).map((data) => Object.values(data)),
  1496.         Object.keys(dataset),
  1497.         Object.keys(dataset[Object.keys(dataset)[0]])
  1498.       );
  1499.     } else {
  1500.       console.log("data is not ordered");
  1501.       reorderedData = {
  1502.         matrix: Object.values(dataset).map((data) => Object.values(data)),
  1503.         rowNames: Object.keys(dataset),
  1504.         colNames: Object.keys(dataset[Object.keys(dataset)[0]]),
  1505.       };
  1506.     }
  1507.     if (colorscale == "custom") {
  1508.       colorscale = [
  1509.         ["0.0", "rgb(49,54,149)"],
  1510.         ["0.025", "rgb(69,117,180)"],
  1511.         ["0.05", "rgb(116,173,209)"],
  1512.         ["0.075", "rgb(171,217,233)"],
  1513.         ["0.1", "rgb(224,243,248)"],
  1514.         ["0.125", "rgb(254,224,144)"],
  1515.         ["0.15", "rgb(253,174,97)"],
  1516.         ["0.175", "rgb(244,109,67)"],
  1517.         ["0.2", "rgb(215,48,39)"],
  1518.         ["1.0", "rgb(165,0,38)"],
  1519.       ];
  1520.     }
  1522.     let data = {
  1523.       z: reorderedData.matrix,
  1524.       x: reorderedData.colNames,
  1525.       y: reorderedData.rowNames,
  1526.       type: "heatmap",
  1527.       colorscale: colorscale,
  1528.     };
  1530.     let layout = {
  1531.       title: `Mutational Signature Exposure for ${datasetName} Dataset`,
  1532.       xaxis: {
  1533.         title: "Samples",
  1534.         nticks: Object.keys(dataset[Object.keys(dataset)[0]]).length,
  1535.       },
  1536.       yaxis: {
  1537.         title: "Mutational Signatures",
  1538.         nticks: Object.keys(dataset).length,
  1539.       },
  1540.       height: 800,
  1541.     };
  1543.     plotGraphWithPlotlyAndMakeDataDownloadable(divID, [data], layout);
  1545.     return data;
  1546.   }
  1548.   /**
  1549.    * @memberof mSigPortalPlots
  1550.    * @function plotSignatureAssociations
  1551.    * @description This function generates and plots a scatter plot with marginal histograms, along with statistical analysis, to visualize the association between two mutational signatures. It calculates and displays the linear regression line, Pearson correlation, and Spearman correlation, providing insights into the relationship between the exposures of two signatures in a set of samples.
  1552.    *
  1553.    * @param {string} divID - The ID of the HTML div element where the plot will be rendered.
  1554.    * @param {object} data - An array of objects representing the exposure data for a set of samples. Each object in the array should have the following properties:
  1555.    *   - `sample`: A string representing the sample ID.
  1556.    *   - `signatureName`: A string representing the name of the mutational signature.
  1557.    *   - `exposure`: A numeric value representing the exposure of the signature in the sample.
  1558.    * @param {string} signature1 - The name of the first mutational signature. This should match the `signatureName` values in the `data` array. The values can be any valid signature name present in the dataset, for example, "SBS1", "SBS5", "DBS1", "ID4".
  1559.    * @param {string} signature2 - The name of the second mutational signature. This should also match the `signatureName` values in the `data` array. Similar to `signature1`, the values can be any signature name present in the dataset and can also be the same as `signature1` to assess the distribution of a single signature.
  1560.    * @return {void} - This function does not return a value. It directly renders the plot in the specified `divID`.
  1561.    */
  1562.   /**
  1563.    * @memberof mSigPortalPlots
  1564.    * @function MsAssociation
  1565.    * @description Calculates the association between two mutational signatures across a set of samples. It computes the linear regression, Pearson correlation, and Spearman correlation between the log-transformed exposures of the two signatures. The results are used to generate a scatter plot with marginal histograms, visualizing the relationship between the signatures.
  1566.    *
  1567.    * @param {object[]} data - An array of objects representing the exposure data for a set of samples. Each object in the array should have the following properties:
  1568.    *   - `sample`: A string representing the sample ID.
  1569.    *   - `signatureName`: A string representing the name of the mutational signature.
  1570.    *   - `exposure`: A numeric value representing the exposure of the signature in the sample. This value can theoretically range from 0 to infinity, although in practice, values are often normalized.
  1571.    * @param {string} signatureName1 - The name of the first mutational signature. This should match the `signatureName` values in the `data` array.
  1572.    * @param {string} signatureName2 - The name of the second mutational signature. This should also match the `signatureName` values in the `data` array. It can be the same as `signatureName1`.
  1573.    * @param {boolean} [both=false] - A boolean flag indicating whether to filter the data to include only samples where both signatures have non-zero exposure.
  1574.    *   - `true`: Only samples with non-zero exposure to both signatures are included in the analysis. If `signatureName1` and `signatureName2` are the same, then no filtering occurs.
  1575.    *   - `false`: All samples are included in the analysis, regardless of whether they have non-zero exposure to both signatures.
  1576.    * @return {object} - Returns an object containing the traces and layout for a Plotly plot.
  1577.    *   - `traces`: An array of trace objects to be used in a Plotly plot. This includes the main scatter plot trace, the linear regression line trace, and two marginal histogram traces.
  1578.    *   - `layout`: An object containing the layout configuration for a Plotly plot, including title, axis labels, annotations, and other visual properties.
  1579.    */
  1581.   function plotSignatureAssociations(divID, data, signature1, signature2) {
  1582.     let dat = plotSignatureAssociation(data, signature1, signature2);
  1583.     plotGraphWithPlotlyAndMakeDataDownloadable(divID, dat.traces, dat.layout);
  1584.   }
  1586.   /**
  1587.  * @memberof mSigPortalPlots
  1588.  * @function plotMSPrevalenceData
  1589.  * @description This function is a wrapper around the `plotMSPrevalence` function. It takes the output of `plotMSPrevalence` and uses it to generate a Plotly plot, which is then displayed in a specified div. The plot visualizes the prevalence of mutational signatures.
  1590.  *
  1591.  * @param {string} divID - The ID of the div element where the plot will be rendered.
  1592.  * @param {object} data - An object representing the mutational signature prevalence data. The `data` object is expected to be an array of objects with the following structure:
  1593.  *   `[{ signatureName: "SBS1", sample: "sample1", exposure: 10, burden: 5 }, { signatureName: "SBS5", sample: "sample1", exposure: 20, burden: 5 }, ... ]`
  1594.  *   Where `signatureName` is the name of a mutational signature (string), `sample` is a sample identifier (string), `exposure` is a non-negative number representing the exposure of that signature in the sample, and `burden` is a numeric value representing the mutational burden for the sample.
  1595.  * @return {void} - This function does not return a value. It directly renders the plot in the specified `divID`.
  1596.  */
  1597.   /**
  1598.    * @memberof mSigPortalPlots
  1599.    * @function MSPrevalence
  1600.    * @description Calculates and visualizes the prevalence of mutational signatures across a set of samples, grouped by cancer type. The function generates two plots: a pie chart showing the overall prevalence of each signature based on total mutations (exposure) and a bar chart displaying the frequency of each signature across samples, considering a minimum exposure threshold.
  1601.    *
  1602.    * @param {object} data - An object representing the mutational signature prevalence data. The `data` object is expected to be an array of objects with the following structure:
  1603.    *   `[{ signatureName: "SBS1", sample: "sample1", exposure: 10, burden: 5 }, { signatureName: "SBS5", sample: "sample1", exposure: 20, burden: 5 }, ... ]`
  1604.    *   Where `signatureName` is the name of a mutational signature (string), `sample` is a sample identifier (string), `exposure` is a non-negative number representing the exposure of that signature in the sample (can be 0), and `burden` is a numeric value representing the mutational burden for the sample (must be a number).
  1605.    * @param {number|null|undefined} minimum - The minimum exposure value for a signature in a sample to be considered prevalent in that sample. Samples with exposure below this threshold are not counted in the frequency calculation for the bar chart. If `minimum` is `null` or `undefined`, it defaults to 100.
  1606.    *   - `null` or `undefined`: Sets the minimum exposure to 100.
  1607.    *   - Any positive number: Sets the minimum exposure to that number.
  1608.    * @return {{traces: object[], layout: object}} - Returns an object containing the `traces` and `layout` for a Plotly plot.
  1609.    *   - `traces`: An array of trace objects. If the maximum frequency of signatures (considering the `minimum` threshold) is less than 1%, the array contains only a single pie chart trace. Otherwise, it contains a pie chart trace followed by multiple bar chart traces (one for each signature).
  1610.    *   - `layout`: An object defining the layout of the plot, including title annotations, axis settings, and overall appearance. It includes conditional logic to handle cases where no signature has a frequency greater than 1%.
  1611.    */
  1613.   function plotMSPrevalenceData(divID, data) {
  1614.     let dat = plotMSPrevalence(data);
  1615.     plotGraphWithPlotlyAndMakeDataDownloadable(divID, dat.traces, dat.layout);
  1616.   }
  1618.   //#endregion
  1620.   //#region Define the public members of the mSigSDK
  1621.   const mSigPortalData = {
  1622.     getMutationalSignaturesOptions,
  1623.     getMutationalSignaturesData,
  1624.     getMutationalSignaturesSummary,
  1625.     getMutationalSpectrumOptions,
  1626.     getMutationalSpectrumData,
  1627.     getMutationalSpectrumSummary,
  1628.     getMutationalSignatureAssociationOptions,
  1629.     getMutationalSignatureAssociationData,
  1630.     getMutationalSignatureActivityOptions,
  1631.     getMutationalSignatureActivityData,
  1632.     getMutationalSignatureLandscapeData,
  1633.     getMutationalSignatureEtiologyOptions,
  1634.     getMutationalSignatureEtiologyData,
  1635.     extractMutationalSpectra,
  1636.   };
  1637.   const mSigPortalPlots = {
  1638.     plotProfilerSummary,
  1639.     plotPatientMutationalSpectrum,
  1640.     plotForceDirectedTree,
  1641.     plotCosineSimilarityHeatMap,
  1642.     plotUMAPVisualization,
  1643.     plotProjectMutationalBurdenByCancerType,
  1644.     plotSignatureActivityDataBy,
  1645.     plotSignatureAssociations,
  1646.     plotMSPrevalenceData,
  1647.   };
  1649.   const mSigPortal = {
  1650.     mSigPortalData,
  1651.     mSigPortalPlots,
  1652.   };
  1654.   const userData = {
  1655.     convertMatrix,
  1656.     convertWGStoPanel,
  1657.     plotPatientMutationalSpectrumuserData,
  1658.     convertMutationalSpectraIntoJSON,
  1659.   };
  1661.   const TCGA = {
  1662.     getProjectsByGene,
  1663.     getTpmCountsByGenesOnProjects,
  1664.     getTpmCountsByGenesFromFiles,
  1665.     getMafInformationFromProjects,
  1666.     getVariantInformationFromMafFiles,
  1667.     convertTCGAProjectIntoJSON,
  1668.   };
  1669.   const tools = {
  1670.     groupBy,
  1671.   };
  1673.   const signatureFitting = {
  1674.     fitMutationalSpectraToSignatures,
  1675.     plotPatientMutationalSignaturesExposure,
  1676.     plotDatasetMutationalSignaturesExposure,
  1677.   };
  1679.   const machineLearning = {
  1680.     preprocessData,
  1681.     kFoldCV,
  1682.   };
  1684.   //#endregion
  1686.   // Public members
  1687.   return {
  1688.     mSigPortal,
  1689.     userData,
  1690.     tools,
  1691.     machineLearning,
  1692.     signatureFitting,
  1693.     TCGA,
  1694.   };
  1695. })();
  1697. export { mSigSDK };