From df86e8a9e93838d5cd4e11e5db804f0386e3ff57 Mon Sep 17 00:00:00 2001
From: Sam El-Kamand
Date: Mon, 29 Jul 2024 15:13:20 +1000
Subject: [PATCH] docs: v0.6 of ggoncoplot JOSS paper
---
paper/jats/paper.jats | 64 ++++++++++++++++++++++++------------------
paper/paper.docx | Bin 643945 -> 644090 bytes
paper/paper.md | 14 ++++-----
paper/paper.pdf | Bin 724426 -> 725410 bytes
4 files changed, 43 insertions(+), 35 deletions(-)
diff --git a/paper/jats/paper.jats b/paper/jats/paper.jats
index 6ff3960..4b3a50d 100644
--- a/paper/jats/paper.jats
+++ b/paper/jats/paper.jats
@@ -95,20 +95,22 @@ a Creative Commons Attribution 4.0 International License (CC BY
Summary
- The ggoncoplot R package generates interactive oncoplots (also
- called oncoprints) to visualize mutational patterns across patient
- cancer cohorts
+
The ggoncoplot R package generates interactive oncoplots to
+ visualize mutational patterns across patient cancer cohorts
([fig:oncoplot]).
- Oncoplots reveal patterns of gene co-mutation and include marginal
- plots that indicate co-occurrence of gene mutations and tumour
- features. It is useful to relate gene mutation patterns seen in an
- oncoplot to patterns seen in other plot types, including gene
- expression t-SNE plots or methylation UMAPs. There are, however, no
- existing oncoplot-generating R packages that support dynamic data
- linkage between different plots. To addresses this gap and enable
- rapid exploration of a variety of data types we constructed the
- ggoncoplot package for the production of oncoplots that are easily
- integrated with custom visualisations and that support synchronised
+ Oncoplots, also called oncoprints, reveal patterns of gene co-mutation
+ and include marginal plots that indicate co-occurrence of gene
+ mutations with tumour and clinical features. It is useful to relate
+ gene mutation patterns seen in an oncoplot to patterns in other plot
+ types, including gene expression t-SNE plots or methylation UMAPs. The
+ simplest and most intuitive approach to examining such relations is to
+ link plots dynamically such that samples selected in an oncoplot can
+ be highlighted in other plots. There are, however, no existing
+ oncoplot-generating R packages that support dynamic data linkage
+ between different plots. To address this gap and enable rapid
+ exploration of a variety of data types we constructed the ggoncoplot
+ package for the production of oncoplots that are easily integrated
+ with custom visualisations and that support synchronised
data-selections across plots
([fig:multimodal_selection]).
ggoncoplot is available on GitHub at
@@ -150,44 +152,50 @@ a Creative Commons Attribution 4.0 International License (CC BY
Statement of Need
- Oncoplots are highly effectively for visualising mutation data in
+
Oncoplots are highly effective for visualising mutation data in
cancer cohorts but are challenging to generate with the major R
plotting systems (base, lattice, or ggplot2) due to their algorithmic
- and graphical complexity. Simplifying the process would make oncoplots
- more accessible to researchers. Packages like ComplexHeatmap
+ and graphical complexity. Simplifying the process of generating
+ oncoplots would make them more accessible to researchers. Existing
+ packages including ComplexHeatmap
(Gu,
2022), maftools
(Mayakonda
et al., 2018), and genVisR
(Skidmore
et al., 2016) all make static oncoplots easier to create, but
- there is still a significant unmet need for an easy method of creating
- oncoplots with the following features:
+ there is still a significant unmet need for user-friendly method of
+ creating oncoplots with the following features:
Interactive plots: Customizable tooltips,
cross-selection of samples across different plots, and
- auto-copying of sample identifiers on click.
+ auto-copying of sample identifiers on click. This enables
+ exploration of trends in multiomic datasets as shown in
+ [fig:multimodal_selection].
Support for tidy datasets: Compatibility with
tidy, tabular mutation-level formats (MAF files or relational
- databases), typical of cancer cohort datasets.
+ databases), typical of cancer cohort datasets. This greatly
+ improves the range of datasets that can be quickly and easily
+ visualised in an oncoplot.
- Auto colouring: Automatic selection of colour
- palettes for datasets where consequence annotations are aligned
- with standard variant effect dictionaries (PAVE, SO, or MAF).
+ Auto-colouring: Automatic selection of colour
+ palettes for datasets where the consequence annotations are
+ aligned with standard variant effect dictionaries (PAVE, SO, or
+ MAF).
Versatility: The ability to visualize entities
- other than gene mutations, including noncoding features (e.g.,
- enhancers) and non-genomic entities (e.g., microbial presence in
- microbiome datasets).
+ other than gene mutations, such as noncoding features (e.g.,
+ promoter or enhancer mutations) and non-genomic entities (e.g.,
+ microbial presence in microbiome datasets).
- We developed ggoncoplot as the first R package that addresses all
- these challenges simultaneously
+
We developed ggoncoplot as the first R package to address all these
+ challenges together
([fig:comparison]).
Examples of all key features are available in the
ggoncoplot
diff --git a/paper/paper.docx b/paper/paper.docx
index 963f1d021d6384bc13d795b82d58ca3922ee40cd..1b97b4a1250f061ea2d1424ed4b78a9b0102826f 100644
GIT binary patch
delta 4681
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
QgB~0MbK(UJg0Ii=fA).
+The ggoncoplot R package generates interactive oncoplots to visualize mutational patterns across patient cancer cohorts (\autoref{fig:oncoplot}). Oncoplots, also called oncoprints, reveal patterns of gene co-mutation and include marginal plots that indicate co-occurrence of gene mutations with tumour and clinical features. It is useful to relate gene mutation patterns seen in an oncoplot to patterns in other plot types, including gene expression t-SNE plots or methylation UMAPs. The simplest and most intuitive approach to examining such relations is to link plots dynamically such that samples selected in an oncoplot can be highlighted in other plots. There are, however, no existing oncoplot-generating R packages that support dynamic data linkage between different plots. To address this gap and enable rapid exploration of a variety of data types we constructed the ggoncoplot package for the production of oncoplots that are easily integrated with custom visualisations and that support synchronised data-selections across plots (\autoref{fig:multimodal_selection}). ggoncoplot is available on GitHub at .
![ggoncoplot output visualising mutational trends in the TCGA breast carcinoma cohort. Individual patient samples are plotted on the x-axis, hierarchically sorted so that samples with the most frequent gene mutations appear on the leftmost side. The plot indicates that PIK3CA is the most frequently mutated gene, followed by TP53. Marginal plots indicate the total number of mutations per sample (top), and the number of samples showing mutations in each gene, coloured by mutation type (right). A range of clinical features, including progesterone and estrogen receptor status are shown on the marginal plot at the bottom. A detailed description of the ggoncoplot sorting algorithm is available [here](https://selkamand.github.io/ggoncoplot/articles/sorting_algorithm.html). \label{fig:oncoplot}](oncoplot.pdf)
@@ -41,18 +41,18 @@ The ggoncoplot R package generates interactive oncoplots (also called oncoprints
# Statement of Need
-Oncoplots are highly effectively for visualising mutation data in cancer cohorts but are challenging to generate with the major R plotting systems (base, lattice, or ggplot2) due to their algorithmic and graphical complexity. Simplifying the process would make oncoplots more accessible to researchers. Packages like ComplexHeatmap [@Gu:2022], maftools [@Mayakonda:2018], and genVisR [@Skidmore:2016] all make static oncoplots easier to create, but there is still a significant unmet need for an easy method of creating oncoplots with the following features:
+Oncoplots are highly effective for visualising mutation data in cancer cohorts but are challenging to generate with the major R plotting systems (base, lattice, or ggplot2) due to their algorithmic and graphical complexity. Simplifying the process of generating oncoplots would make them more accessible to researchers. Existing packages including ComplexHeatmap [@Gu:2022], maftools [@Mayakonda:2018], and genVisR [@Skidmore:2016] all make static oncoplots easier to create, but there is still a significant unmet need for user-friendly method of creating oncoplots with the following features:
-- **Interactive plots**: Customizable tooltips, cross-selection of samples across different plots, and auto-copying of sample identifiers on click.
+- **Interactive plots**: Customizable tooltips, cross-selection of samples across different plots, and auto-copying of sample identifiers on click. This enables exploration of trends in multiomic datasets as shown in \autoref{fig:multimodal_selection}.
-- **Support for tidy datasets**: Compatibility with tidy, tabular mutation-level formats (MAF files or relational databases), typical of cancer cohort datasets.
+- **Support for tidy datasets**: Compatibility with tidy, tabular mutation-level formats (MAF files or relational databases), typical of cancer cohort datasets. This greatly improves the range of datasets that can be quickly and easily visualised in an oncoplot.
-- **Auto colouring**: Automatic selection of colour palettes for datasets where consequence annotations are aligned with standard variant effect dictionaries (PAVE, SO, or MAF).
+- **Auto-colouring**: Automatic selection of colour palettes for datasets where the consequence annotations are aligned with standard variant effect dictionaries (PAVE, SO, or MAF).
-- **Versatility**: The ability to visualize entities other than gene mutations, including noncoding features (e.g., enhancers) and non-genomic entities (e.g., microbial presence in microbiome datasets).
+- **Versatility**: The ability to visualize entities other than gene mutations, such as noncoding features (e.g., promoter or enhancer mutations) and non-genomic entities (e.g., microbial presence in microbiome datasets).
-We developed ggoncoplot as the first R package that addresses all these challenges simultaneously (\autoref{fig:comparison}). Examples of all key features are available in the [ggoncoplot manual](https://selkamand.github.io/ggoncoplot/articles/manual.html).
+We developed ggoncoplot as the first R package to address all these challenges together (\autoref{fig:comparison}). Examples of all key features are available in the [ggoncoplot manual](https://selkamand.github.io/ggoncoplot/articles/manual.html).
![Comparison of R packages for creating oncoplots. ^1^Requires the shiny and interactiveComplexHeatmap packages. ^2^Exclusively colours tiles based on mutation impact which must be described using valid MAF variant classification terms. ^3^Requires the user to first summarise mutations at the gene level and format as a sample by gene matrix with mutations separated by semicolons (wide format). ^4^For MAF inputs the most severe consequence is chosen, however for non-MAF datasets users must manually define the mutation impact hierarchy. ^5^Non-unique mutation types are treated as one observation, however if different mutation types affect one gene, the individual mutations can be plotted with different shapes or sizes in a user-configured manner. \label{fig:comparison}](ggoncoplot_comparison.pdf)
diff --git a/paper/paper.pdf b/paper/paper.pdf
index 778e10736dd89c8011b267e5441eaff647c0fdf1..99e745215ca5bb1199f45b36d1cf099a05f26d84 100644
GIT binary patch
delta 19658
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