update ggstackplot Rmd in favor of examples

Author: sebkopf

DESCRIPTION

@@ -48,6 +48,7 @@ Suggests:
     rmarkdown,
     testthat (>= 3.0.0),
     vdiffr,
-    scales
+    scales,
+    pangaear
 Config/testthat/edition: 3
 VignetteBuilder: knitr

R/ggstackplot-package.R

@@ -10,6 +10,6 @@ NULL
 #' @details
 #' `r lifecycle::badge("stable")`
 #'
-#' Have you ever wanted to compare multiple panels of line plots that do not share coordinate schemes? These kinds of plots are ubiquitous in the Earth sciences, but there is not an easy way to create them with ggplot facets. Check out the functionality provided by ggstackplots with useful examples and plot styling ideas at <https://ggstackplot.kopflab.org>
+#' Have you ever wanted to create (partly) overlapping line plots with matched color-coding of the data and axes? These kinds of plots are common in climatology and oceanography research but there is not an easy way to create them with ggplot facets. The ggstackplot package builds on [ggplot2](https://ggplot2.tidyverse.org/) to provide a straightforward approach to building these kinds of plots while retaining the powerful grammar of graphics approach of ggplots. Check out the functionality provided by ggstackplots at <https://ggstackplot.kopflab.org>
 #'
 "_PACKAGE"

README.Rmd

@@ -24,41 +24,82 @@ knitr::opts_chunk$set(
 
 ## About
 
-Have you ever wanted to compare multiple panels of line plots that do not share coordinate schemes? These kinds of plots are ubiquitous in the Earth sciences, but there is not an easy way to create them with ggplot facets.
+Have you ever wanted to create (partly) overlapping line plots with matched color-coding of the data and axes? These kinds of plots are common, for example, in climatology and oceanography research but there is not an easy way to create them with ggplot facets. The ggstackplot package builds on [ggplot2](https://ggplot2.tidyverse.org/) to provide a straightforward approach to building these kinds of plots while retaining the powerful grammar of graphics functionality of ggplots.
 
 ## Installation
 
-You can install ggstackplot from [GitHub](https://github.com/) with:
+You can install the development version of ggstackplot from [GitHub](https://github.com/) with:
 
-```{r, eval = FALSE}
-if(!requireNamespace("devtools", quietly = TRUE)) install.packages("devtools")
-devtools::install_github("KopfLab/ggstackplot")
+```
+# install.packages("pak")
+pak::pak("KopfLab/ggstackplot")
 ```
 
 ## Show me some code
 
-```{r example, fig.width=7, fig.height=7}
+```{r mtcars}
 library(ggstackplot)
 
-# using the built-in economics dataset in ggplot2
-ggplot2::economics |>
+# using R's built-in mtcars dataset
+mtcars |> 
   ggstackplot(
     # define shared x axis
-    x = date, 
-    # define stacked y axes
-    y = c(pce, pop, psavert, unemploy),
-    # add a color palette
-    palette = "Set1"
+    x = mpg, 
+    # define multiple y axes
+    y = c("weight" = wt, "horsepower" = hp),
+    # set colors
+    color = c("#E41A1C", "#377EB8"),
+    # set to complete overlap
+    overlap = 1
+  )
+```
+
+## Show me some climate data
+
+```{r, message = FALSE}
+# download a recent dataset from the public climate data repository PANGAEA
+dataset <- pangaear::pg_data(doi = "10.1594/PANGAEA.967047")[[1]]
+
+# show what some of these data look like
+dataset$data[
+  c("Depth ice/snow [m] (Top Depth)", 
+    "Age [ka BP]", 
+    "[SO4]2- [ng/g] (Ion chromatography)")] |>
+  head() |> knitr::kable()
+```
+
+**These data were kindly made available on [PANGEA](`r dataset$url`) by Sigl et al. (2024).**
+
+Full citation:
+
+> `r dataset$citation`
+
+```{r geodata}
+# visualize the data with ggstackplot
+dataset$data |> 
+  ggstackplot(
+    x = "Age [ka BP]",
+    y = c(
+      # vertical stack of the measurements through time
+      "sulfate [ng/g]" = "[SO4]2- [ng/g] (Ion chromatography)",
+      "δ34S [‰]" = "δ34S [SO4]2- [‰ CDT] (Multi-collector ICP-MS (MC-IC...)",
+      "Δ33S [‰]" = "Δ33S [SO4]2- [‰ CDT] (Multi-collector ICP-MS (MC-IC...)"
+    ),
+    # color palette
+    palette = "Dark2",
+    # partial overlap of the panels
+    overlap = 0.4
   )
 ```
 
 ## Show me more
 
-```{r example2, fig.width=7, fig.height=4}
+```{r economics, fig.width=7, fig.height=4}
 library(ggplot2)
 
-# creating a horizontal stack instead of vertical and using some of the many
-# customization features available in ggstackplot
+# using the built-in economics dataset in ggplot2 to create a horizontal stack
+# instead of vertical and using some of the many customization features 
+# available in ggstackplot
 ggplot2::economics |>
   ggstackplot(
     # define shared y axis
@@ -83,13 +124,12 @@ ggplot2::economics |>
     add = 
       list(
         # add points just for 2 plots
-        `unemployed persons` = geom_point(),
-        `personal savings rate` = geom_point()
+        "unemployed persons" = geom_point(),
+        "personal savings rate" = geom_point()
       )
   )
 ```
 
 ## What else can I do with ggstackplot?
 
 - check out the **[Features](https://ggstackplot.kopflab.org/articles/features.html)** vignette for full details on all available functionality
-- check out the **[Examples](https://ggstackplot.kopflab.org/articles/examples.html)** vignette for scientific data examples

README.md

@@ -12,46 +12,105 @@
 
 ## About
 
-Have you ever wanted to compare multiple panels of line plots that do
-not share coordinate schemes? These kinds of plots are ubiquitous in the
-Earth sciences, but there is not an easy way to create them with ggplot
-facets.
+Have you ever wanted to create (partly) overlapping line plots with
+matched color-coding of the data and axes? These kinds of plots are
+common, for example, in climatology and oceanography research but there
+is not an easy way to create them with ggplot facets. The ggstackplot
+package builds on [ggplot2](https://ggplot2.tidyverse.org/) to provide a
+straightforward approach to building these kinds of plots while
+retaining the powerful grammar of graphics functionality of ggplots.
 
 ## Installation
 
-You can install ggstackplot from [GitHub](https://github.com/) with:
+You can install the development version of ggstackplot from
+[GitHub](https://github.com/) with:
 
-``` r
-if(!requireNamespace("devtools", quietly = TRUE)) install.packages("devtools")
-devtools::install_github("KopfLab/ggstackplot")
-```
+    # install.packages("pak")
+    pak::pak("KopfLab/ggstackplot")
 
 ## Show me some code
 
 ``` r
 library(ggstackplot)
 
-# using the built-in economics dataset in ggplot2
-ggplot2::economics |>
+# using R's built-in mtcars dataset
+mtcars |> 
   ggstackplot(
     # define shared x axis
-    x = date, 
-    # define stacked y axes
-    y = c(pce, pop, psavert, unemploy),
-    # add a color palette
-    palette = "Set1"
+    x = mpg, 
+    # define multiple y axes
+    y = c("weight" = wt, "horsepower" = hp),
+    # set colors
+    color = c("#E41A1C", "#377EB8"),
+    # set to complete overlap
+    overlap = 1
   )
 ```
 
-<img src="man/figures/README-example-1.png" width="100%" />
+<img src="man/figures/README-mtcars-1.png" width="100%" />
+
+## Show me some climate data
+
+``` r
+# download a recent dataset from the public climate data repository PANGAEA
+dataset <- pangaear::pg_data(doi = "10.1594/PANGAEA.967047")[[1]]
+
+# show what some of these data look like
+dataset$data[
+  c("Depth ice/snow [m] (Top Depth)", 
+    "Age [ka BP]", 
+    "[SO4]2- [ng/g] (Ion chromatography)")] |>
+  head() |> knitr::kable()
+```
+
+| Depth ice/snow \[m\] (Top Depth) | Age \[ka BP\] | \[SO4\]2- \[ng/g\] (Ion chromatography) |
+|---------------------------------:|--------------:|----------------------------------------:|
+|                          160.215 |       1.20662 |                                   52.00 |
+|                          160.183 |       1.20300 |                                  165.00 |
+|                          160.151 |       1.20276 |                                   93.50 |
+|                          160.022 |       1.20191 |                                   42.25 |
+|                          159.990 |       1.20155 |                                   74.50 |
+|                          159.958 |       1.20130 |                                  104.50 |
+
+**These data were kindly made available on
+[PANGEA](https://doi.org/10.1594/PANGAEA.967047) by Sigl et
+al. (2024).**
+
+Full citation:
+
+> Sigl, Michael; Gabriel, Imogen; Hutchison, William; Burke, Andrea
+> (2024): Sulfate concentration and sulfur isotope data from Greenland
+> TUNU2013 ice-core samples between 740-765 CE \[dataset\]. PANGAEA,
+> <https://doi.org/10.1594/PANGAEA.967047>
+
+``` r
+# visualize the data with ggstackplot
+dataset$data |> 
+  ggstackplot(
+    x = "Age [ka BP]",
+    y = c(
+      # vertical stack of the measurements through time
+      "sulfate [ng/g]" = "[SO4]2- [ng/g] (Ion chromatography)",
+      "δ34S [‰]" = "δ34S [SO4]2- [‰ CDT] (Multi-collector ICP-MS (MC-IC...)",
+      "Δ33S [‰]" = "Δ33S [SO4]2- [‰ CDT] (Multi-collector ICP-MS (MC-IC...)"
+    ),
+    # color palette
+    palette = "Dark2",
+    # partial overlap of the panels
+    overlap = 0.4
+  )
+```
+
+<img src="man/figures/README-geodata-1.png" width="100%" />
 
 ## Show me more
 
 ``` r
 library(ggplot2)
 
-# creating a horizontal stack instead of vertical and using some of the many
-# customization features available in ggstackplot
+# using the built-in economics dataset in ggplot2 to create a horizontal stack
+# instead of vertical and using some of the many customization features 
+# available in ggstackplot
 ggplot2::economics |>
   ggstackplot(
     # define shared y axis
@@ -76,19 +135,16 @@ ggplot2::economics |>
     add = 
       list(
         # add points just for 2 plots
-        `unemployed persons` = geom_point(),
-        `personal savings rate` = geom_point()
+        "unemployed persons" = geom_point(),
+        "personal savings rate" = geom_point()
       )
   )
 ```
 
-<img src="man/figures/README-example2-1.png" width="100%" />
+<img src="man/figures/README-economics-1.png" width="100%" />
 
 ## What else can I do with ggstackplot?
 
 - check out the
   **[Features](https://ggstackplot.kopflab.org/articles/features.html)**
   vignette for full details on all available functionality
-- check out the
-  **[Examples](https://ggstackplot.kopflab.org/articles/examples.html)**
-  vignette for scientific data examples