Namespace: mSigPortalPlots

mSigPortalPlots

Source:

Methods

(static) MSPrevalence(data, minimum) → {Object}

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.
Parameters:
Name Type Description
data object An object representing the mutational signature prevalence data. The `data` object is expected to be an array of objects with the following structure: `[{ signatureName: "SBS1", sample: "sample1", exposure: 10, burden: 5 }, { signatureName: "SBS5", sample: "sample1", exposure: 20, burden: 5 }, ... ]` 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).
minimum number | null | undefined 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. - `null` or `undefined`: Sets the minimum exposure to 100. - Any positive number: Sets the minimum exposure to that number.
Source:
Returns:
- Returns an object containing the `traces` and `layout` for a Plotly plot. - `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). - `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%.
Type
Object

(static) MsAssociation(data, signatureName1, signatureName2, bothopt) → {object}

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.
Parameters:
Name Type Attributes Default Description
data Array.<object> An array of objects representing the exposure data for a set of samples. Each object in the array should have the following properties: - `sample`: A string representing the sample ID. - `signatureName`: A string representing the name of the mutational signature. - `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.
signatureName1 string The name of the first mutational signature. This should match the `signatureName` values in the `data` array.
signatureName2 string 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`.
both boolean <optional>
 false A boolean flag indicating whether to filter the data to include only samples where both signatures have non-zero exposure. - `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. - `false`: All samples are included in the analysis, regardless of whether they have non-zero exposure to both signatures.
Source:
Returns:
- Returns an object containing the traces and layout for a Plotly plot. - `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. - `layout`: An object containing the layout configuration for a Plotly plot, including title, axis labels, annotations, and other visual properties.
Type
object

(async, static) plotCosineSimilarityHeatMap(groupedData, studyNameopt, genomeDataTypeopt, cancerTypeopt, divIDopt, conductDoubleClusteringopt, colorscaleopt, showTableopt) → {Promise.<Array.<Array.<number>>>}

Generates a cosine similarity heatmap based on mutational spectra data. This function processes grouped mutational data to compute cosine similarities, optionally performs double clustering to reorder the data, and then visualizes the similarities using a Plotly heatmap. It also supports displaying a table representation of the cosine similarity matrix alongside the heatmap.
Parameters:
Name Type Attributes Default Description
groupedData Object The input data object where keys represent sample names and values are objects representing mutational spectra. The mutational spectra should be represented as key-value pairs where keys are mutation types and values are counts or frequencies. Example: ``` { 'Sample1': {'C>A': 10, 'C>G': 15, 'C>T': 20, ...}, 'Sample2': {'C>A': 5, 'C>G': 8, 'C>T': 12, ...}, ... } ``` The range of keys (mutation types) should be consistent across all samples. The values (counts or frequencies) can be integers or floats, and their range can vary based on the underlying data, but typically they are non-negative.
studyName string <optional>
 "PCAWG" The name of the study. This is used in the title of the heatmap. Common values include study identifiers like "PCAWG", "TCGA", or specific project names. The parameter should be a string and can technically accept any string value, but it is intended to represent the name of a study or dataset.
genomeDataType string <optional>
 "WGS" The type of genomic data. This is also used in the title of the heatmap. Expected values typically include abbreviations for common genomic data types such as "WGS" (Whole Genome Sequencing), "WES" (Whole Exome Sequencing), "RNA-Seq", etc. Similar to `studyName`, any string is technically accepted, but the intended use is to describe the data type.
cancerType string <optional>
 "Lung-AdenoCA" The type of cancer. This is included in the title of the heatmap. Common values are standard cancer type abbreviations or names, like "Lung-AdenoCA" (Lung Adenocarcinoma), "BRCA" (Breast Invasive Carcinoma), etc. Any string value is accepted, but it should represent a specific cancer type.
divID string <optional>
 "cosineSimilarityHeatMap" The ID of the HTML element where the heatmap will be rendered. This should be a valid HTML element ID. If an element with this ID does not exist, one will be created and appended to the document body. Any string is accepted, but it should correspond to a unique ID in the HTML document to avoid conflicts.
conductDoubleClustering boolean <optional>
 true A flag indicating whether to perform double clustering (hierarchical clustering on both rows and columns) on the cosine similarity matrix. If `true`, the rows and columns of the heatmap will be reordered based on the clustering. If `false`, the order of samples in `groupedData` will be maintained. Boolean values `true` or `false` are expected.
colorscale string <optional>
 "RdBu" The Plotly colorscale to use for the heatmap. This can be any valid Plotly colorscale name (e.g., "Viridis", "Greys", "YlGnBu", "RdBu"). Plotly provides a wide range of predefined colorscales. The chosen colorscale will affect the visual representation of the similarity values. Any string is accepted but it should correspond to a valid Plotly colorscale for optimal results.
showTable boolean <optional>
 false A flag indicating whether to display a table representation of the cosine similarity matrix alongside the heatmap. If `true`, a table will be rendered next to the heatmap. If `false`, only the heatmap will be displayed. Boolean values `true` or `false` are expected.
Source:
Throws:
Will throw an error if the `cosineSimilarity` function or the `plotGraphWithPlotlyAndMakeDataDownloadable` function throws an error.
Returns:
A Promise that resolves to the cosine similarity matrix. The matrix is a two-dimensional array of numbers, where each number represents the cosine similarity between two samples. The values range from 0 to 1, where 1 indicates perfect similarity and 0 indicates no similarity. The dimensions of the matrix will be NxN, where N is the number of samples in `groupedData`.
Type
Promise.<Array.<Array.<number>>>

(static) plotDatasetMutationalSignaturesExposure(exposureData, divID, relativeopt, datasetNameopt, doubleClusteropt, colorscaleopt) → {object}

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.
Parameters:
Name Type Attributes Default Description
exposureData object An object containing the exposure data for a set of samples. The structure of `exposureData` is expected to be: `{ sampleId1: { signatureName1: exposureValue1, signatureName2: exposureValue2, ..., rnorm: number }, sampleId2: { signatureName1: exposureValue3, signatureName2: exposureValue4, ..., rnorm: number }, ... }` 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.
divID string The ID of the HTML div element where the heatmap will be rendered.
relative boolean <optional>
 true A boolean indicating whether to display relative or absolute exposure values. - `true`: The exposure values for each sample are normalized to sum to 1, representing the relative contribution of each signature. - `false`: The raw exposure values are displayed.
datasetName string <optional>
 "PCAWG" The name of the dataset being visualized. This is used as part of the plot title. Examples include: - `"PCAWG"` - `"TCGA"` - Any other string that appropriately identifies the dataset.
doubleCluster boolean <optional>
 true A boolean indicating whether to perform double hierarchical clustering on the exposure data. - `true`: The rows and columns of the heatmap are reordered based on the results of double clustering, which groups similar samples and signatures together. - `false`: The rows and columns are displayed in the order they appear in the input `exposureData`.
colorscale string | Array <optional>
 "Custom" The color scale to use for the heatmap. Possible values are: - `"Custom"`: A predefined custom color scale designed for visualizing exposure data. - Any valid Plotly color scale name (e.g., `"Viridis"`, `"Blues"`, `"Hot"`, etc.). - 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)"]]`).
Source:
Returns:
- 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: `{ z: [[exposureValue1, exposureValue2, ...], [exposureValue3, exposureValue4, ...], ...], x: [signatureName1, signatureName2, ...], y: [sampleId1, sampleId2, ...], type: "heatmap", colorscale: colorscale }`
Type
object

(static) plotForceDirectedTree(groupedData, studyNameopt, genomeDataTypeopt, cancerTypeopt, divIDopt) → {object}

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.
Parameters:
Name Type Attributes Default Description
groupedData object An object where keys represent sample IDs and values are objects containing mutational spectra data. The structure of `groupedData` is expected to be: `{ sampleId1: { mutationType1: count1, mutationType2: count2, ... }, sampleId2: { mutationType1: count3, mutationType2: count4, ... }, ... }` 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.
studyName string <optional>
 "PCAWG" The name of the study. This is used for labeling purposes in the visualization. Common values include, but are not limited to: - `"PCAWG"` - `"TCGA"` - Any other string representing a specific study.
genomeDataType string <optional>
 "WGS" The type of genome data used. This is also used for labeling purposes. Possible values include: - `"WGS"`: Whole Genome Sequencing - `"WES"`: Whole Exome Sequencing - `"RNA-Seq"`: RNA Sequencing
cancerType string <optional>
 "Lung-AdenoCA" The type of cancer being studied. This is used for labeling in the visualization. Examples include: - `"Lung-AdenoCA"`: Lung Adenocarcinoma - `"Breast-AdenoCA"`: Breast Adenocarcinoma - Any valid cancer type identifier.
divID string <optional>
 "forceDirectedTree" The ID of the HTML div element where the force-directed tree will be rendered.
Source:
Returns:
- 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.
Type
object

(static) plotMSPrevalenceData(divID, data) → {void}

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.
Parameters:
Name Type Description
divID string The ID of the div element where the plot will be rendered.
data object An object representing the mutational signature prevalence data. The `data` object is expected to be an array of objects with the following structure: `[{ signatureName: "SBS1", sample: "sample1", exposure: 10, burden: 5 }, { signatureName: "SBS5", sample: "sample1", exposure: 20, burden: 5 }, ... ]` 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.
Source:
Returns:
- This function does not return a value. It directly renders the plot in the specified `divID`.
Type
void

(static) plotPatientMutationalSignaturesExposure(exposureData, divID, sample) → {object}

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.
Parameters:
Name Type Description
exposureData object An object containing the exposure data for a set of samples. The structure of `exposureData` is expected to be: `{ sampleId1: { signatureName1: exposureValue1, signatureName2: exposureValue2, ... }, sampleId2: { signatureName1: exposureValue3, signatureName2: exposureValue4, ... }, ... }` 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.
divID string The ID of the HTML div element where the pie chart will be rendered.
sample string 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").
Source:
Returns:
- 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: `{ labels: [signatureName1, signatureName2, ...], values: [exposureValue1, exposureValue2, ...], name: "sample exposure values", textposition: "inside", hole: 0.4, hoverinfo: "name + value", type: "pie" }`
Type
object

(async, static) plotPatientMutationalSpectrum(mutationalSpectra, matrixSizeopt, divIDopt) → {Promise.<void>}

Renders a plot of the mutational spectra for one or more patients in a given div element ID using Plotly.
Parameters:
Name Type Attributes Default Description
mutationalSpectra Object An object containing the mutational spectra data for one or more patients.
matrixSize number <optional>
 96 The size of the plot matrix. Defaults to 96.
divID string <optional>
 'mutationalSpectrumMatrix' The ID of the div element to render the plot in. Defaults to 'mutationalSpectrumMatrix'.
Source:
Throws:
An error is thrown if no data is available for the selected parameters.
Type
Error
Returns:
A promise that resolves when the plot has been rendered.
Type
Promise.<void>

(async, static) plotPatientMutationalSpectrumuserData(mutationalSpectra, matrixSizeopt, divIDopt)

Plots the mutational spectrum for the given parameters.
Parameters:
Name Type Attributes Default Description
mutationalSpectra Object An object containing the mutational spectra data.
matrixSize number <optional>
 96 The size of the matrix to be plotted.
divID string <optional>
 "mutationalSpectrumMatrix" The ID of the div element where the plot will be displayed.
Source:

(async, static) plotProfilerSummary(studyNameopt, genomeDataTypeopt, cancerTypeOrGroupopt, numberOfResultsopt, divIDopt) → {Promise.<void>}

Generates a mutational spectrum summary plot and displays it in a given HTML div element.
Parameters:
Name Type Attributes Default Description
studyName string <optional>
 "PCAWG" The name of the cancer genomics study to use. Default is "PCAWG".
genomeDataType string <optional>
 "WGS" The type of genomic data to use. Default is "WGS".
cancerTypeOrGroup string <optional>
 "Lung-AdenoCA" The cancer type or group to display. Default is "Lung-AdenoCA".
numberOfResults number <optional>
 50 The maximum number of results to display. Default is 50.
divID string <optional>
 "mutationalSpectrumSummary" The ID of the HTML div element where the plot will be displayed. Default is "mutationalSpectrumSummary".
Source:
Throws:
If there is an error retrieving or displaying the plot, this function will throw an Error with a message describing the error.
Type
Error
Returns:
A Promise that resolves when the plot is displayed or rejects if there is an error.
Type
Promise.<void>

(async, static) plotProjectMutationalBurdenByCancerType(project, divID) → {Promise}

Plots the mutational burden by cancer type for a given project.
Parameters:
Name Type Description
project Object An object containing mutational data for different cancer types.
divID string The ID of the div where the plot should be displayed.
Source:
Returns:
- A Promise that resolves when the plot is displayed.
Type
Promise
Example
// Example usage:
plotProjectMutationalBurdenByCancerType(projectData, "plotDiv");

(static) plotSignatureActivityDataBy(divID, data, groupopt) → {void}

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.
Parameters:
Name Type Attributes Default Description
divID string The ID of the div element where the plot will be rendered.
data Array.<object> An array of objects representing the signature activity data. Each object must have at least the following properties: - `exposure`: A numeric value representing the exposure of a signature. It can be any positive number or zero. - `sample`: A string representing the sample ID. - The `data` array must also contain a property matching the name specified by the `group` parameter (e.g., "signatureName", "study", "cancerType").
group string <optional>
 "signatureName" The attribute to group the data by. Possible values are any property name present in the data objects, including, but not limited to: - `"signatureName"`: Groups the data by signature names. - `"study"`: Groups the data by study IDs. - `"cancerType"`: Groups the data by cancer types. - `"sample"`: Groups the data by sample IDs (Note: this might not result in a meaningful box plot). - Any other custom property that exists in the data objects. The default value is `"signatureName"`.
Source:
Returns:
- This function does not return a value. It directly renders the plot in the specified `divID`.
Type
void

(static) plotSignatureAssociations(divID, data, signature1, signature2) → {void}

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.
Parameters:
Name Type Description
divID string The ID of the HTML div element where the plot will be rendered.
data object An array of objects representing the exposure data for a set of samples. Each object in the array should have the following properties: - `sample`: A string representing the sample ID. - `signatureName`: A string representing the name of the mutational signature. - `exposure`: A numeric value representing the exposure of the signature in the sample.
signature1 string 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".
signature2 string 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.
Source:
Returns:
- This function does not return a value. It directly renders the plot in the specified `divID`.
Type
void

(static) plotUMAPVisualization(data, datasetNameopt, divID, nComponentsopt, minDistopt, nNeighborsopt) → {object}

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.
Parameters:
Name Type Attributes Default Description
data object An object representing the mutational spectra data. The structure of `data` is expected to be: `{ sampleId1: { mutationType1: count1, mutationType2: count2, ... }, sampleId2: { mutationType1: count3, mutationType2: count4, ... }, ... }` 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.
datasetName string <optional>
 "PCAWG" The name of the dataset being visualized. This is used as part of the plot title. Examples include: - `"PCAWG"` - `"TCGA"` - Any other string that appropriately identifies the dataset.
divID string The ID of the HTML div element where the plot will be rendered.
nComponents number <optional>
 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: - `2`: Generates a 2D scatter plot. - `3`: Generates a 3D scatter plot with an additional mesh3d trace. Any other positive integer is technically permissible but may not yield meaningful visualizations.
minDist number <optional>
 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.
nNeighbors number <optional>
 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.
Source:
Returns:
- 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`.
Type
object