From 225cadd08e8faea362541d7d95c60f18dc606c17 Mon Sep 17 00:00:00 2001 From: Mauro Lepore Date: Wed, 9 Jun 2021 08:47:23 -0600 Subject: [PATCH 1/3] DRY intro to r2dii.plot X and Y --- README.Rmd | 218 +--------- README.md | 417 ++++++++++--------- inst/intro.Rmd | 225 ++++++++++ vignettes/articles/r2dii-plot-X-versus-Y.Rmd | 140 +------ 4 files changed, 445 insertions(+), 555 deletions(-) create mode 100644 inst/intro.Rmd diff --git a/README.Rmd b/README.Rmd index 088a9744..1f0582a3 100644 --- a/README.Rmd +++ b/README.Rmd @@ -12,30 +12,6 @@ knitr::opts_chunk$set( fig.align = "left", out.width = "100%" ) - -#' Pull the title of a documented object -#' This function helps keep README and help files in sync. -#' @param name String. The name of a documented object. -#' @return String. -#' @examples -#' pull_title("plot_trajectory") -pull_title <- function(name, db = enframe_documentation("r2dii.plot")) { - is_name <- db$name == name - out <- db$title[is_name] - tolower(out) -} - -enframe_documentation <- function(package) { - db <- utils::hsearch_db(package, lib.loc = locate_package(package))[["Base"]] - names(db) <- tolower(names(db)) - db -} - -locate_package <- function(pkg) { - locate <- function(path) any(grepl(pkg, list.files(path))) - has_pkg <- unlist(lapply(.libPaths(), locate)) - .libPaths()[has_pkg][[1]] -} ``` # r2dii.plot @@ -48,197 +24,9 @@ experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](h [![CRAN status](https://www.r-pkg.org/badges/version/r2dii.plot)](https://CRAN.R-project.org/package=r2dii.plot) -The goal of r2dii.plot is to provide users with plotting and data -processing functions that will allow the users to create standard 2DII plots -using `PACTA_analysis` or banks' output data as input. The plots are in the form -of ggplot objects. - -## Installation - -You can install the development version of r2dii.plot from -[GitHub](https://github.com/2DegreesInvesting/r2dii.plot) with: - -```r -# install.packages("devtools") -devtools::install_github("2DegreesInvesting/r2dii.plot") -``` - -[How to minimize installation errors?](https://gist.github.com/maurolepore/a0187be9d40aee95a43f20a85f4caed6#installation) - -## Example - -```{r} -library(dplyr, warn.conflicts = FALSE) -library(ggplot2, warn.conflicts = FALSE) -library(r2dii.plot) -``` - -* `market_share` `r pull_title("market_share")`. - -```{r} -market_share -``` - -* `prep_trajectoryY()`: `r pull_title("prep_trajectory")`. - -```{r} -data_trajectory <- prep_trajectoryY( - market_share, - sector_filter = "power", - technology_filter = "oilcap", - region_filter = "global", - scenario_source_filter = "demo_2020", - end_year_filter = 2025, - normalize = TRUE -) +```{r echo=FALSE} +intro <- system.file("intro.Rmd", package = "r2dii.plot") ``` -* `plot_trajectoryY()` is an alternative to `plot_trajectoryB()`. - -```{r} -# `plot_trajectoryY()` takes more arguments - -scenario_specs <- tibble( - scenario = c("sds", "sps", "cps"), - label = c("SDS", "STEPS", "CPS") -) - -main_line_metric <- tibble( - metric = "projected", - label = "Portfolio" -) - -additional_line_metrics <- tibble( - metric = "corporate_economy", - label = "Corporate Economy" -) - -plot_trajectoryY( - data_trajectory, - scenario_specs_good_to_bad = scenario_specs, - main_line_metric = main_line_metric, - additional_line_metrics = additional_line_metrics -) - -# more elaborate annotations, title and labels - -data_trajectory <- prep_trajectoryY( - market_share, - sector_filter = "power", - technology_filter = "renewablescap", - region_filter = "global", - scenario_source_filter = "demo_2020", - value = "production", - end_year_filter = 2025, - normalize = TRUE -) - -scenario_specs <- tibble( - scenario = c("sds", "sps", "cps"), - label = c( - "Sustainable Development Scenario", - "Stated Policies Scenario", - "Current Policies Scenario") -) - -plot <- plot_trajectoryY(data_trajectory, - scenario_specs_good_to_bad = scenario_specs, - main_line_metric = main_line_metric, - additional_line_metrics = additional_line_metrics -) - -plot + - ggplot2::theme( - plot.margin = ggplot2::unit(c(0.5, 7, 0.5, 0.5), "cm") - ) + - ggplot2::labs( - title = "Production trajectory of Renewables Capacity technology\n in the Power sector", - subtitle = "The coloured areas indicate trajectories in reference to a scenario.\n The red area indicates trajectories below any sustainble scenario.", - x = "Year", - y = "Production rate (normalized to 2020)" - ) -``` - -* `prep_techmixY()` `r pull_title("prep_techmix")`. -* `plot_techmixY()` `r pull_title("plot_techmix")`. - -```{r} -# Default colours, all data, added title -sector <- "power" - -data <- prep_techmixY( - market_share, - sector_filter = sector, - years_filter = c(2020, 2025), - region_filter = "global", - scenario_source_filter = "demo_2020", - scenario_filter = "sds", - value = "technology_share" -) - -plot <- plot_techmixY(data) -plot + - ggplot2::labs(title = "Technology mix for the Power sector") - -# Custom colours, all data, no title -power_colors_custom <- tibble( - technology = c("coalcap", "oilcap", "gascap", "nuclearcap", "hydrocap", "renewablescap"), - label = c("Coal Capacity", "Oil Capacity", "Gas Capacity", "Nuclear Capacity", "Hydro Capacity", "Renewables Capacity"), - hex = palette.colors(n = length(technology), palette = "ggplot2") -) - -plot <- plot_techmixY(data, - tech_colours = power_colors_custom -) -plot - -# Default colours, selected data and labels (metric_type parameters), added title - -sector <- "automotive" - -data <- prep_techmixY(market_share, - sector_filter = sector, - years_filter = c(2020, 2025), region_filter = "global", - scenario_source_filter = "demo_2020", - scenario_filter = "sds", value = "technology_share" -) - -metric_type_order = c( - "portfolio_2020", "benchmark_2020", "portfolio_2025", - "benchmark_2025", "scenario_2025" -) -metric_type_labels = c( - "Portfolio 2020", "Benchmark 2020", "Portfolio 2025", - "Benchmark 2025", "Target SDS 2025" - ) - -plot <- plot_techmixY(data, - metric_type_order = metric_type_order, - metric_type_labels = metric_type_labels -) -plot + - ggplot2::labs(title = "Technology mix for the Automotive sector") -``` - -* `prep_timelineY()` `r pull_title("prep_timeline")`. -* `plot_timelineY()` `r pull_title("plot_timelineA")`. - -```{r} -data <- prep_timelineY(sda, sector_filter = "cement", extrapolate = TRUE) - -# Plot and customize with ggplot2 -plot_timelineY(data) + - labs( - title = "Emission intensity trend for Cement.", - x = "Year", - y = "Tons of CO2 per ton", - caption = "Dashed line is an extrapolation of the last value in the dataset." - ) -``` - -* `timeline_specs()` `r pull_title("timeline_specs")`. - -```{r} -# You may use it as a template to create your custom specs -timeline_specs(data) +```{r child=intro} ``` diff --git a/README.md b/README.md index ed289390..e40f6df6 100644 --- a/README.md +++ b/README.md @@ -14,239 +14,252 @@ coverage](https://codecov.io/gh/2DegreesInvesting/r2dii.plot/branch/master/graph status](https://www.r-pkg.org/badges/version/r2dii.plot)](https://CRAN.R-project.org/package=r2dii.plot) -The goal of r2dii.plot is to provide users with plotting and data -processing functions that will allow the users to create standard 2DII -plots using `PACTA_analysis` or banks’ output data as input. The plots -are in the form of ggplot objects. +The goal of r2dii.plot is to help you plot 2DII data in an informative, -## Installation +beautiful, and easy way. + +\#\# Installation You can install the development version of r2dii.plot from -[GitHub](https://github.com/2DegreesInvesting/r2dii.plot) with: -``` r -# install.packages("devtools") -devtools::install_github("2DegreesInvesting/r2dii.plot") -``` +[GitHub](%5Bhttps://github.com/2DegreesInvesting/r2dii.plot)\]()) +with: + +\`\`\`r + +\# install.packages(“devtools”) + +devtools::install\_github(“2DegreesInvesting/r2dii.plot”) + +\`\`\` + +\#\# Example -[How to minimize installation -errors?](https://gist.github.com/maurolepore/a0187be9d40aee95a43f20a85f4caed6#installation) +The r2dii.plot package is designed to work smoothly with other “r2dii” +packages -## Example +– +[r2dii.data](%5Bhttps://2degreesinvesting.github.io/r2dii.data/),\](),) + +[r2dii.match](%5Bhttps://2degreesinvesting.github.io/r2dii.match/),\](),) +and + +[r2dii.analysis](%5Bhttps://2degreesinvesting.github.io/r2dii.analysis/).\]().) +It also + +plays well with the popular packages +[dplyr](%5Bhttps://www.tidyverse.org/)\]()) +and + +[ggplot2](%5Bhttps://ggplot2.tidyverse.org/),\](),) +which help you customize your plots. + +\`\`\`{r setup} -``` r library(dplyr, warn.conflicts = FALSE) + library(ggplot2, warn.conflicts = FALSE) + library(r2dii.plot) -``` - -- `market_share` dataset imitating the output of - ‘r2dii.analysis::target\_market\_share()’. - -``` r -market_share -#> # A tibble: 1,170 x 8 -#> sector technology year region scenario_source metric production -#> -#> 1 automotive electric 2020 global demo_2020 projected 145942. -#> 2 automotive electric 2020 global demo_2020 corporate_econ… 8134869. -#> 3 automotive electric 2020 global demo_2020 target_cps 145942. -#> 4 automotive electric 2020 global demo_2020 target_sds 145942. -#> 5 automotive electric 2020 global demo_2020 target_sps 145942. -#> 6 automotive electric 2021 global demo_2020 projected 148212. -#> 7 automotive electric 2021 global demo_2020 corporate_econ… 8183411. -#> 8 automotive electric 2021 global demo_2020 target_cps 148361. -#> 9 automotive electric 2021 global demo_2020 target_sds 160625. -#> 10 automotive electric 2021 global demo_2020 target_sps 149016. -#> # … with 1,160 more rows, and 1 more variable: technology_share -``` - -- `prep_trajectoryY()`: . - -``` r -data_trajectory <- prep_trajectoryY( - market_share, - sector_filter = "power", - technology_filter = "oilcap", - region_filter = "global", - scenario_source_filter = "demo_2020", - end_year_filter = 2025, - normalize = TRUE -) -``` -- `plot_trajectoryY()` is an alternative to `plot_trajectoryB()`. +\`\`\` -``` r -# `plot_trajectoryY()` takes more arguments +Your data typically comes from the output of two functions in the +r2dii.analysis -scenario_specs <- tibble( - scenario = c("sds", "sps", "cps"), - label = c("SDS", "STEPS", "CPS") -) +package: -main_line_metric <- tibble( - metric = "projected", - label = "Portfolio" -) +[\`target\_sda()\`](%5Bhttps://2degreesinvesting.github.io/r2dii.analysis/reference/target_sda.html)\]()) -additional_line_metrics <- tibble( - metric = "corporate_economy", - label = "Corporate Economy" -) +and -plot_trajectoryY( - data_trajectory, - scenario_specs_good_to_bad = scenario_specs, - main_line_metric = main_line_metric, - additional_line_metrics = additional_line_metrics -) -``` - - - -``` r -# more elaborate annotations, title and labels - -data_trajectory <- prep_trajectoryY( - market_share, - sector_filter = "power", - technology_filter = "renewablescap", - region_filter = "global", - scenario_source_filter = "demo_2020", - value = "production", - end_year_filter = 2025, - normalize = TRUE -) +[\`target\_market\_share()\`](%5Bhttps://2degreesinvesting.github.io/r2dii.analysis/reference/target_market_share.html).\]().) -scenario_specs <- tibble( - scenario = c("sds", "sps", "cps"), - label = c( - "Sustainable Development Scenario", - "Stated Policies Scenario", - "Current Policies Scenario") -) +Here you’ll use two example datasets that come with r2dii.plot. -plot <- plot_trajectoryY(data_trajectory, - scenario_specs_good_to_bad = scenario_specs, - main_line_metric = main_line_metric, - additional_line_metrics = additional_line_metrics -) +\`\`\`{r} + +sda + +market\_share + +\`\`\` + +r2dii.plot currently supports three kinds of plots: +\`plot\_timeline\*()\`, + +\`plot\_techmix\*()\`, and \`plot\_trajectory\*()\`. Each plot has +specific requirements + +about the main input – passed to the first argument \`data\`. To meet +those + +requirements we currently provide two experimental sets of functions + +([API](%5Bhttps://en.wikipedia.org/wiki/API)s)\]()) +– “X” and “Y”. Both APIs can help + +you get the same basic plots, which you can further customization with +ggplot2. + +Their difference difference is not in what you can do but in how you can +do it: + +\* With the “X” API you meet the \`data\` requirements mainly with + +\`dplyr::filter()\`, and with “internal magic” based on the known +structure of + +r2dii data. This API should be best for users who already use dplyr or +want to + +learn it. + +\* With the “Y” API you could meet the \`data\` requirements with dplyr +but you can + +also use dedicated “preparation” functions (\`prep\_\*Y()\`),, and with +explicit + +arguments to both the preparation and and plotting functions. This API +should + +best for users who do not use dplyr or care about it. + +Users and developers may have different preferences. The tables below +compare + +the X and Y APIs across a number of criteria relevant to them. + +\`\`\`{r echo=FALSE} + +users <- tibble::tribble( + +\~Criteria, \~\`Thin API “X”\`, \~\`Thin API, “Y”\`, + +“Required knowledge of dplyr and ggplot2”, “More”, “Less”, + +“Customization possible”, “Limitless with dplyr and ggplot2”, “Limitless +with dplyr, ggplot2, and r2dii.plot”, + +“Integration with other R workflows”, “More”, “Less”, -plot + - ggplot2::theme( - plot.margin = ggplot2::unit(c(0.5, 7, 0.5, 0.5), "cm") - ) + - ggplot2::labs( - title = "Production trajectory of Renewables Capacity technology\n in the Power sector", - subtitle = "The coloured areas indicate trajectories in reference to a scenario.\n The red area indicates trajectories below any sustainble scenario.", - x = "Year", - y = "Production rate (normalized to 2020)" - ) -``` - - - -- `prep_techmixY()` . -- `plot_techmixY()` . - -``` r -# Default colours, all data, added title -sector <- "power" - -data <- prep_techmixY( - market_share, - sector_filter = sector, - years_filter = c(2020, 2025), - region_filter = "global", - scenario_source_filter = "demo_2020", - scenario_filter = "sds", - value = "technology_share" ) -plot <- plot_techmixY(data) -plot + - ggplot2::labs(title = "Technology mix for the Power sector") -``` +caption <- “The X and Y APIs compared from a user’s perspective.” + +knitr::kable(users, caption = caption) - +devs <- tibble::tribble( + +\~Criteria, \~\`Thin API “X”\`, \~\`Thin API, “Y”\`, + +“Maintenance burden”, “Less”, “More”, + +“Easy to extend”, “More”, “Less”, -``` r -# Custom colours, all data, no title -power_colors_custom <- tibble( - technology = c("coalcap", "oilcap", "gascap", "nuclearcap", "hydrocap", "renewablescap"), - label = c("Coal Capacity", "Oil Capacity", "Gas Capacity", "Nuclear Capacity", "Hydro Capacity", "Renewables Capacity"), - hex = palette.colors(n = length(technology), palette = "ggplot2") ) -plot <- plot_techmixY(data, - tech_colours = power_colors_custom +caption <- “The X and Y APIs compared from a developer’s +perspective.” + +knitr::kable(devs, caption = caption) + +\`\`\` + +To make the comparison concrete consider this small example. Notice the + +resulting plot is the same but the toolkit is different. + +\* “X” API + +\`\`\`{r} + +data <- market\_share + +prep <- filter( + +data, + +sector == “power”, + +technology == “renewablescap”, + +region == “global”, + +scenario\_source == “demo\_2020”, + +year <= 2025 + ) -plot -``` - +plot\_trajectoryX(prep) + + +labs (title = “Trajectory plot with the thin ‘X’ API”) + +\`\`\` + +\* “Y” API + +\`\`\`{r} + +data <- market\_share + +prep <- prep\_trajectoryY( -``` r -# Default colours, selected data and labels (metric_type parameters), added title +data, -sector <- "automotive" +sector\_filter = “power”, + +technology\_filter = “renewablescap”, + +region\_filter = “global”, + +scenario\_source\_filter = “demo\_2020”, + +value = “production” -data <- prep_techmixY(market_share, - sector_filter = sector, - years_filter = c(2020, 2025), region_filter = "global", - scenario_source_filter = "demo_2020", - scenario_filter = "sds", value = "technology_share" ) -metric_type_order = c( - "portfolio_2020", "benchmark_2020", "portfolio_2025", - "benchmark_2025", "scenario_2025" +scenario\_specs <- dplyr::tibble( + +scenario = c(“sds”, “sps”, “cps”), + +label = c(“SDS”, “STEPS”, “CPS”) + ) -metric_type_labels = c( - "Portfolio 2020", "Benchmark 2020", "Portfolio 2025", - "Benchmark 2025", "Target SDS 2025" - ) - -plot <- plot_techmixY(data, - metric_type_order = metric_type_order, - metric_type_labels = metric_type_labels + +main\_line\_metric <- dplyr::tibble(metric = “projected”, label = +“Portfolio”) + +additional\_line\_metrics <- dplyr::tibble( + +metric = “corporate\_economy”, + +label = “Corporate Economy” + ) -plot + - ggplot2::labs(title = "Technology mix for the Automotive sector") -``` - - - -- `prep_timelineY()` . -- `plot_timelineY()` . - -``` r -data <- prep_timelineY(sda, sector_filter = "cement", extrapolate = TRUE) - -# Plot and customize with ggplot2 -plot_timelineY(data) + - labs( - title = "Emission intensity trend for Cement.", - x = "Year", - y = "Tons of CO2 per ton", - caption = "Dashed line is an extrapolation of the last value in the dataset." - ) -``` - - - -- `timeline_specs()` creates the default specs data frame for - ‘plot\_timeliney()’. - -``` r -# You may use it as a template to create your custom specs -timeline_specs(data) -#> # A tibble: 4 x 3 -#> line_name label hex -#> -#> 1 projected Projected #1b324f -#> 2 corporate_economy Corporate Economy #00c082 -#> 3 target_demo Target Demo #ff9623 -#> 4 adjusted_scenario_demo Adjusted Scenario Demo #d0d7e1 -``` + +plot\_trajectoryY( + +prep, + +scenario\_specs\_good\_to\_bad = scenario\_specs, + +main\_line\_metric = main\_line\_metric, + +additional\_line\_metrics = additional\_line\_metrics + +) + + +labs (title = “Trajectory plot with the thick ‘Y’ API”) + +\`\`\` + +For full examples see the dedicated articles \[r2dii.plot + +X\]([https://2degreesinvesting.github.io/r2dii.plot/articles/articles/r2dii-plot-X.html)](https://2degreesinvesting.github.io/r2dii.plot/articles/articles/r2dii-plot-X.html)) + +and \[r2dii.plot + +Y\]([https://2degreesinvesting.github.io/r2dii.plot/articles/articles/r2dii-plot-Y.html).](https://2degreesinvesting.github.io/r2dii.plot/articles/articles/r2dii-plot-Y.html).) diff --git a/inst/intro.Rmd b/inst/intro.Rmd new file mode 100644 index 00000000..b2aacca7 --- /dev/null +++ b/inst/intro.Rmd @@ -0,0 +1,225 @@ +The goal of r2dii.plot is to help you plot 2DII data in an informative, + +beautiful, and easy way. + +\#\# Installation + +You can install the development version of r2dii.plot from + +[GitHub]([https://github.com/2DegreesInvesting/r2dii.plot)](https://github.com/2DegreesInvesting/r2dii.plot)) with: + +\`\`\`r + +\# install.packages("devtools") + +devtools::install_github("2DegreesInvesting/r2dii.plot") + +\`\`\` + +\#\# Example + +The r2dii.plot package is designed to work smoothly with other "r2dii" packages + +-- [r2dii.data]([https://2degreesinvesting.github.io/r2dii.data/),](https://2degreesinvesting.github.io/r2dii.data/),) + +[r2dii.match]([https://2degreesinvesting.github.io/r2dii.match/),](https://2degreesinvesting.github.io/r2dii.match/),) and + +[r2dii.analysis]([https://2degreesinvesting.github.io/r2dii.analysis/).](https://2degreesinvesting.github.io/r2dii.analysis/).) It also + +plays well with the popular packages [dplyr]([https://www.tidyverse.org/)](https://www.tidyverse.org/)) and + +[ggplot2]([https://ggplot2.tidyverse.org/),](https://ggplot2.tidyverse.org/),) which help you customize your plots. + +\`\`\`{r setup} + +library(dplyr, warn.conflicts = FALSE) + +library(ggplot2, warn.conflicts = FALSE) + +library(r2dii.plot) + +\`\`\` + +Your data typically comes from the output of two functions in the r2dii.analysis + +package: + +[\`target_sda()\`]([https://2degreesinvesting.github.io/r2dii.analysis/reference/target_sda.html)](https://2degreesinvesting.github.io/r2dii.analysis/reference/target_sda.html)) + +and + +[\`target_market_share()\`]([https://2degreesinvesting.github.io/r2dii.analysis/reference/target_market_share.html).](https://2degreesinvesting.github.io/r2dii.analysis/reference/target_market_share.html).) + +Here you'll use two example datasets that come with r2dii.plot. + +\`\`\`{r} + +sda + +market_share + +\`\`\` + +r2dii.plot currently supports three kinds of plots: \`plot_timeline\*()\`, + +\`plot_techmix\*()\`, and \`plot_trajectory\*()\`. Each plot has specific requirements + +about the main input -- passed to the first argument \`data\`. To meet those + +requirements we currently provide two experimental sets of functions + +([API]([https://en.wikipedia.org/wiki/API)s)](https://en.wikipedia.org/wiki/API)s)) -- "X" and "Y". Both APIs can help + +you get the same basic plots, which you can further customization with ggplot2. + +Their difference difference is not in what you can do but in how you can do it: + +\* With the "X" API you meet the \`data\` requirements mainly with + +\`dplyr::filter()\`, and with "internal magic" based on the known structure of + +r2dii data. This API should be best for users who already use dplyr or want to + +learn it. + +\* With the "Y" API you could meet the \`data\` requirements with dplyr but you can + +also use dedicated "preparation" functions (\`prep\_\*Y()\`),, and with explicit + +arguments to both the preparation and and plotting functions. This API should + +best for users who do not use dplyr or care about it. + +Users and developers may have different preferences. The tables below compare + +the X and Y APIs across a number of criteria relevant to them. + +\`\`\`{r echo=FALSE} + +users \<- tibble::tribble( + +\~Criteria, \~\`Thin API "X"\`, \~\`Thin API, "Y"\`, + +"Required knowledge of dplyr and ggplot2", "More", "Less", + +"Customization possible", "Limitless with dplyr and ggplot2", "Limitless with dplyr, ggplot2, and r2dii.plot", + +"Integration with other R workflows", "More", "Less", + +) + +caption \<- "The X and Y APIs compared from a user's perspective." + +knitr::kable(users, caption = caption) + +devs \<- tibble::tribble( + +\~Criteria, \~\`Thin API "X"\`, \~\`Thin API, "Y"\`, + +"Maintenance burden", "Less", "More", + +"Easy to extend", "More", "Less", + +) + +caption \<- "The X and Y APIs compared from a developer's perspective." + +knitr::kable(devs, caption = caption) + +\`\`\` + +To make the comparison concrete consider this small example. Notice the + +resulting plot is the same but the toolkit is different. + +\* "X" API + +\`\`\`{r} + +data \<- market_share + +prep \<- filter( + +data, + +sector == "power", + +technology == "renewablescap", + +region == "global", + +scenario_source == "demo_2020", + +year \<= 2025 + +) + +plot_trajectoryX(prep) + + +labs (title = "Trajectory plot with the thin 'X' API") + +\`\`\` + +\* "Y" API + +\`\`\`{r} + +data \<- market_share + +prep \<- prep_trajectoryY( + +data, + +sector_filter = "power", + +technology_filter = "renewablescap", + +region_filter = "global", + +scenario_source_filter = "demo_2020", + +value = "production" + +) + +scenario_specs \<- dplyr::tibble( + +scenario = c("sds", "sps", "cps"), + +label = c("SDS", "STEPS", "CPS") + +) + +main_line_metric \<- dplyr::tibble(metric = "projected", label = "Portfolio") + +additional_line_metrics \<- dplyr::tibble( + +metric = "corporate_economy", + +label = "Corporate Economy" + +) + +plot_trajectoryY( + +prep, + +scenario_specs_good_to_bad = scenario_specs, + +main_line_metric = main_line_metric, + +additional_line_metrics = additional_line_metrics + +) + + +labs (title = "Trajectory plot with the thick 'Y' API") + +\`\`\` + +For full examples see the dedicated articles [r2dii.plot + +X]([https://2degreesinvesting.github.io/r2dii.plot/articles/articles/r2dii-plot-X.html)](https://2degreesinvesting.github.io/r2dii.plot/articles/articles/r2dii-plot-X.html)) + +and [r2dii.plot + +Y]([https://2degreesinvesting.github.io/r2dii.plot/articles/articles/r2dii-plot-Y.html).](https://2degreesinvesting.github.io/r2dii.plot/articles/articles/r2dii-plot-Y.html).) diff --git a/vignettes/articles/r2dii-plot-X-versus-Y.Rmd b/vignettes/articles/r2dii-plot-X-versus-Y.Rmd index e4916bfa..d1170732 100644 --- a/vignettes/articles/r2dii-plot-X-versus-Y.Rmd +++ b/vignettes/articles/r2dii-plot-X-versus-Y.Rmd @@ -9,145 +9,9 @@ knitr::opts_chunk$set( ) ``` -The goal of r2dii.plot is to help you plot 2DII data in an informative, -beautiful, and easy way. - -## Installation - -You can install the development version of r2dii.plot from -[GitHub](https://github.com/2DegreesInvesting/r2dii.plot) with: - -```r -# install.packages("devtools") -devtools::install_github("2DegreesInvesting/r2dii.plot") -``` - -## Example - -The r2dii.plot package is designed to work smoothly with other "r2dii" packages --- [r2dii.data](https://2degreesinvesting.github.io/r2dii.data/), -[r2dii.match](https://2degreesinvesting.github.io/r2dii.match/), and -[r2dii.analysis](https://2degreesinvesting.github.io/r2dii.analysis/). It also -plays well with the popular packages [dplyr](https://www.tidyverse.org/) and -[ggplot2](https://ggplot2.tidyverse.org/), which help you customize your plots. - -```{r setup} -library(dplyr, warn.conflicts = FALSE) -library(ggplot2, warn.conflicts = FALSE) -library(r2dii.plot) -``` - -Your data typically comes from the output of two functions in the r2dii.analysis -package: -[`target_sda()`](https://2degreesinvesting.github.io/r2dii.analysis/reference/target_sda.html) -and -[`target_market_share()`](https://2degreesinvesting.github.io/r2dii.analysis/reference/target_market_share.html). -Here you'll use two example datasets that come with r2dii.plot. - -```{r} -sda - -market_share -``` - -r2dii.plot currently supports three kinds of plots: `plot_timeline*()`, -`plot_techmix*()`, and `plot_trajectory*()`. Each plot has specific requirements -about the main input -- passed to the first argument `data`. To meet those -requirements we currently provide two experimental sets of functions -([API](https://en.wikipedia.org/wiki/API)s) -- "X" and "Y". Both APIs can help -you get the same basic plots, which you can further customization with ggplot2. -Their difference difference is not in what you can do but in how you can do it: - -* With the "X" API you meet the `data` requirements mainly with -`dplyr::filter()`, and with "internal magic" based on the known structure of -r2dii data. This API should be best for users who already use dplyr or want to -learn it. - -* With the "Y" API you could meet the `data` requirements with dplyr but you can -also use dedicated "preparation" functions (`prep_*Y()`),, and with explicit -arguments to both the preparation and and plotting functions. This API should -best for users who do not use dplyr or care about it. - -Users and developers may have different preferences. The tables below compare -the X and Y APIs across a number of criteria relevant to them. - ```{r echo=FALSE} -users <- tibble::tribble( - ~Criteria, ~`Thin API "X"`, ~`Thin API, "Y"`, - "Required knowledge of dplyr and ggplot2", "More", "Less", - "Customization possible", "Limitless with dplyr and ggplot2", "Limitless with dplyr, ggplot2, and r2dii.plot", - "Integration with other R workflows", "More", "Less", -) -caption <- "The X and Y APIs compared from a user's perspective." -knitr::kable(users, caption = caption) - -devs <- tibble::tribble( - ~Criteria, ~`Thin API "X"`, ~`Thin API, "Y"`, - "Maintenance burden", "Less", "More", - "Easy to extend", "More", "Less", - -) -caption <- "The X and Y APIs compared from a developer's perspective." -knitr::kable(devs, caption = caption) +intro <- system.file("intro.Rmd", package = "r2dii.plot") ``` -To make the comparison concrete consider this small example. Notice the -resulting plot is the same but the toolkit is different. - -* "X" API - -```{r} -data <- market_share - -prep <- filter( - data, - sector == "power", - technology == "renewablescap", - region == "global", - scenario_source == "demo_2020", - year <= 2025 -) - -plot_trajectoryX(prep) + - labs (title = "Trajectory plot with the thin 'X' API") -``` - -* "Y" API - -```{r} -data <- market_share - -prep <- prep_trajectoryY( - data, - sector_filter = "power", - technology_filter = "renewablescap", - region_filter = "global", - scenario_source_filter = "demo_2020", - value = "production" -) - -scenario_specs <- dplyr::tibble( - scenario = c("sds", "sps", "cps"), - label = c("SDS", "STEPS", "CPS") -) - -main_line_metric <- dplyr::tibble(metric = "projected", label = "Portfolio") - -additional_line_metrics <- dplyr::tibble( - metric = "corporate_economy", - label = "Corporate Economy" -) - -plot_trajectoryY( - prep, - scenario_specs_good_to_bad = scenario_specs, - main_line_metric = main_line_metric, - additional_line_metrics = additional_line_metrics -) + - labs (title = "Trajectory plot with the thick 'Y' API") +```{r child=intro} ``` - -For full examples see the dedicated articles [r2dii.plot -X](https://2degreesinvesting.github.io/r2dii.plot/articles/articles/r2dii-plot-X.html) -and [r2dii.plot -Y](https://2degreesinvesting.github.io/r2dii.plot/articles/articles/r2dii-plot-Y.html). From fc00396ec6012594fc208c761e5683792b3ecbb2 Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Wed, 9 Jun 2021 15:00:53 +0000 Subject: [PATCH 2/3] Re-build README.Rmd --- README.md | 25 ++++++++++++------------- 1 file changed, 12 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index e40f6df6..b81ebfd4 100644 --- a/README.md +++ b/README.md @@ -133,7 +133,7 @@ the X and Y APIs across a number of criteria relevant to them. \`\`\`{r echo=FALSE} -users <- tibble::tribble( +users \<- tibble::tribble( \~Criteria, \~\`Thin API “X”\`, \~\`Thin API, “Y”\`, @@ -146,11 +146,11 @@ with dplyr, ggplot2, and r2dii.plot”, ) -caption <- “The X and Y APIs compared from a user’s perspective.” +caption \<- “The X and Y APIs compared from a user’s perspective.” knitr::kable(users, caption = caption) -devs <- tibble::tribble( +devs \<- tibble::tribble( \~Criteria, \~\`Thin API “X”\`, \~\`Thin API, “Y”\`, @@ -160,8 +160,7 @@ devs <- tibble::tribble( ) -caption <- “The X and Y APIs compared from a developer’s -perspective.” +caption \<- “The X and Y APIs compared from a developer’s perspective.” knitr::kable(devs, caption = caption) @@ -175,9 +174,9 @@ resulting plot is the same but the toolkit is different. \`\`\`{r} -data <- market\_share +data \<- market\_share -prep <- filter( +prep \<- filter( data, @@ -189,7 +188,7 @@ region == “global”, scenario\_source == “demo\_2020”, -year <= 2025 +year \<= 2025 ) @@ -203,9 +202,9 @@ labs (title = “Trajectory plot with the thin ‘X’ API”) \`\`\`{r} -data <- market\_share +data \<- market\_share -prep <- prep\_trajectoryY( +prep \<- prep\_trajectoryY( data, @@ -221,7 +220,7 @@ value = “production” ) -scenario\_specs <- dplyr::tibble( +scenario\_specs \<- dplyr::tibble( scenario = c(“sds”, “sps”, “cps”), @@ -229,10 +228,10 @@ label = c(“SDS”, “STEPS”, “CPS”) ) -main\_line\_metric <- dplyr::tibble(metric = “projected”, label = +main\_line\_metric \<- dplyr::tibble(metric = “projected”, label = “Portfolio”) -additional\_line\_metrics <- dplyr::tibble( +additional\_line\_metrics \<- dplyr::tibble( metric = “corporate\_economy”, From 7f91ea2bbb0fa9f423b68189937092ee9a804e32 Mon Sep 17 00:00:00 2001 From: Mauro Lepore Date: Wed, 9 Jun 2021 09:22:14 -0600 Subject: [PATCH 3/3] Make README useful again --- README.md | 365 ++++++++----------- inst/intro.Rmd | 265 +++++--------- man/figures/README-unnamed-chunk-6-1.png | Bin 21469 -> 22861 bytes man/figures/README-unnamed-chunk-7-1.png | Bin 26457 -> 23310 bytes vignettes/articles/r2dii-plot-X-versus-Y.Rmd | 148 +++++++- 5 files changed, 391 insertions(+), 387 deletions(-) diff --git a/README.md b/README.md index b81ebfd4..c56a3da1 100644 --- a/README.md +++ b/README.md @@ -15,250 +15,185 @@ status](https://www.r-pkg.org/badges/version/r2dii.plot)](https://CRAN.R-project The goal of r2dii.plot is to help you plot 2DII data in an informative, - beautiful, and easy way. -\#\# Installation +## Installation You can install the development version of r2dii.plot from +[GitHub](https://github.com/2DegreesInvesting/r2dii.plot) with: -[GitHub](%5Bhttps://github.com/2DegreesInvesting/r2dii.plot)\]()) -with: - -\`\`\`r - -\# install.packages(“devtools”) - -devtools::install\_github(“2DegreesInvesting/r2dii.plot”) +``` r +# install.packages("devtools") +devtools::install_github("2DegreesInvesting/r2dii.plot") +``` -\`\`\` - -\#\# Example +## Example The r2dii.plot package is designed to work smoothly with other “r2dii” -packages - -– -[r2dii.data](%5Bhttps://2degreesinvesting.github.io/r2dii.data/),\](),) - -[r2dii.match](%5Bhttps://2degreesinvesting.github.io/r2dii.match/),\](),) -and - -[r2dii.analysis](%5Bhttps://2degreesinvesting.github.io/r2dii.analysis/).\]().) -It also - -plays well with the popular packages -[dplyr](%5Bhttps://www.tidyverse.org/)\]()) -and - -[ggplot2](%5Bhttps://ggplot2.tidyverse.org/),\](),) -which help you customize your plots. - -\`\`\`{r setup} - +packages – +[r2dii.data](https://2degreesinvesting.github.io/r2dii.data/), +[r2dii.match](https://2degreesinvesting.github.io/r2dii.match/), and +[r2dii.analysis](https://2degreesinvesting.github.io/r2dii.analysis/). +It also plays well with the popular packages +[dplyr](https://www.tidyverse.org/) and +[ggplot2](https://ggplot2.tidyverse.org/), which help you customize your +plots. + +``` r library(dplyr, warn.conflicts = FALSE) - library(ggplot2, warn.conflicts = FALSE) - library(r2dii.plot) - -\`\`\` +``` Your data typically comes from the output of two functions in the -r2dii.analysis - -package: - -[\`target\_sda()\`](%5Bhttps://2degreesinvesting.github.io/r2dii.analysis/reference/target_sda.html)\]()) - +r2dii.analysis package: +[`target_sda()`](https://2degreesinvesting.github.io/r2dii.analysis/reference/target_sda.html) and - -[\`target\_market\_share()\`](%5Bhttps://2degreesinvesting.github.io/r2dii.analysis/reference/target_market_share.html).\]().) - +[`target_market_share()`](https://2degreesinvesting.github.io/r2dii.analysis/reference/target_market_share.html). Here you’ll use two example datasets that come with r2dii.plot. -\`\`\`{r} - +``` r sda - -market\_share - -\`\`\` - -r2dii.plot currently supports three kinds of plots: -\`plot\_timeline\*()\`, - -\`plot\_techmix\*()\`, and \`plot\_trajectory\*()\`. Each plot has -specific requirements - -about the main input – passed to the first argument \`data\`. To meet -those - -requirements we currently provide two experimental sets of functions - -([API](%5Bhttps://en.wikipedia.org/wiki/API)s)\]()) -– “X” and “Y”. Both APIs can help - -you get the same basic plots, which you can further customization with -ggplot2. - -Their difference difference is not in what you can do but in how you can -do it: - -\* With the “X” API you meet the \`data\` requirements mainly with - -\`dplyr::filter()\`, and with “internal magic” based on the known -structure of - -r2dii data. This API should be best for users who already use dplyr or -want to - -learn it. - -\* With the “Y” API you could meet the \`data\` requirements with dplyr -but you can - -also use dedicated “preparation” functions (\`prep\_\*Y()\`),, and with -explicit - -arguments to both the preparation and and plotting functions. This API -should - -best for users who do not use dplyr or care about it. +#> # A tibble: 208 x 4 +#> sector year emission_factor_metric emission_factor_value +#> +#> 1 automotive 2002 projected 0.228 +#> 2 automotive 2003 projected 0.226 +#> 3 automotive 2004 projected 0.224 +#> 4 automotive 2005 projected 0.222 +#> 5 automotive 2006 projected 0.220 +#> 6 automotive 2007 projected 0.218 +#> 7 automotive 2008 projected 0.216 +#> 8 automotive 2009 projected 0.214 +#> 9 automotive 2010 projected 0.212 +#> 10 automotive 2011 projected 0.210 +#> # … with 198 more rows + +market_share +#> # A tibble: 1,170 x 8 +#> sector technology year region scenario_source metric production +#> +#> 1 automotive electric 2020 global demo_2020 projected 145942. +#> 2 automotive electric 2020 global demo_2020 corporate_econ… 8134869. +#> 3 automotive electric 2020 global demo_2020 target_cps 145942. +#> 4 automotive electric 2020 global demo_2020 target_sds 145942. +#> 5 automotive electric 2020 global demo_2020 target_sps 145942. +#> 6 automotive electric 2021 global demo_2020 projected 148212. +#> 7 automotive electric 2021 global demo_2020 corporate_econ… 8183411. +#> 8 automotive electric 2021 global demo_2020 target_cps 148361. +#> 9 automotive electric 2021 global demo_2020 target_sds 160625. +#> 10 automotive electric 2021 global demo_2020 target_sps 149016. +#> # … with 1,160 more rows, and 1 more variable: technology_share +``` + +r2dii.plot currently supports three kinds of plots: `plot_timeline*()`, +`plot_techmix*()`, and `plot_trajectory*()`. Each plot has specific +requirements about the main input – passed to the first argument `data`. +To meet those requirements we currently provide two experimental sets of +functions ([API](https://en.wikipedia.org/wiki/API)s) – “X” and “Y”. +Both APIs can help you get the same basic plots, which you can further +customization with ggplot2. Their difference difference is not in what +you can do but in how you can do it: + +- With the “X” API you meet the `data` requirements mainly with + `dplyr::filter()`, and with “internal magic” based on the known + structure of r2dii data. This API should be best for users who + already use dplyr or want to learn it. It allows for slightly less + customization than “Y” but with the advantage of a much simpler + interface. + +- With the “Y” API you could meet the `data` requirements with dplyr + but you can also use dedicated “preparation” functions + (`prep_*Y()`). There are explicit arguments to both the preparation + and plotting functions which allow for a customization inside the + plotting function of what appears in the plot and how (colours, + labels). This API should be best for users who do not use dplyr or + care about it. Users and developers may have different preferences. The tables below -compare - -the X and Y APIs across a number of criteria relevant to them. - -\`\`\`{r echo=FALSE} - -users \<- tibble::tribble( - -\~Criteria, \~\`Thin API “X”\`, \~\`Thin API, “Y”\`, - -“Required knowledge of dplyr and ggplot2”, “More”, “Less”, - -“Customization possible”, “Limitless with dplyr and ggplot2”, “Limitless -with dplyr, ggplot2, and r2dii.plot”, - -“Integration with other R workflows”, “More”, “Less”, - +compare the X and Y APIs across a number of criteria relevant to them. + +| Criteria | Thin API “X” | Thin API, “Y” | +|:----------------------------------------|:---------------------------------|:----------------------------------------------| +| Required knowledge of dplyr and ggplot2 | More | Less | +| Customization possible | Limitless with dplyr and ggplot2 | Limitless with dplyr, ggplot2, and r2dii.plot | +| Integration with other R workflows | More | Less | + +The X and Y APIs compared from a user’s perspective. + +| Criteria | Thin API “X” | Thin API, “Y” | +|:-------------------|:-------------|:--------------| +| Maintenance burden | Less | More | +| Easy to extend | More | Less | + +The X and Y APIs compared from a developer’s perspective. + +To make the comparison concrete consider this small example of a +trajectory plot (the other plot types you can find in the detailed [“X” +API](https://2degreesinvesting.github.io/r2dii.plot/articles/articles/r2dii-plot-X.html) +and [“Y” +API](https://2degreesinvesting.github.io/r2dii.plot/articles/articles/r2dii-plot-Y.html)) +articles. Notice the resulting plot is almost the same (except for the +labels) but the toolkit is different. + +- “X” API + +``` r +data <- market_share + +prep <- filter( + data, + sector == "power", + technology == "renewablescap", + region == "global", + scenario_source == "demo_2020", + year <= 2025 ) -caption \<- “The X and Y APIs compared from a user’s perspective.” - -knitr::kable(users, caption = caption) - -devs \<- tibble::tribble( +plot_trajectoryX(prep) + + labs (title = "Trajectory plot with the thin 'X' API") +``` -\~Criteria, \~\`Thin API “X”\`, \~\`Thin API, “Y”\`, + -“Maintenance burden”, “Less”, “More”, +- “Y” API -“Easy to extend”, “More”, “Less”, +``` r +data <- market_share +prep <- prep_trajectoryY( + data, + sector_filter = "power", + technology_filter = "renewablescap", + region_filter = "global", + scenario_source_filter = "demo_2020", + value = "production" ) -caption \<- “The X and Y APIs compared from a developer’s perspective.” - -knitr::kable(devs, caption = caption) - -\`\`\` - -To make the comparison concrete consider this small example. Notice the - -resulting plot is the same but the toolkit is different. - -\* “X” API - -\`\`\`{r} - -data \<- market\_share - -prep \<- filter( - -data, - -sector == “power”, - -technology == “renewablescap”, - -region == “global”, - -scenario\_source == “demo\_2020”, - -year \<= 2025 - +scenario_specs <- dplyr::tibble( + scenario = c("sds", "sps", "cps"), + label = c("SDS", "STEPS", "CPS") ) -plot\_trajectoryX(prep) + - -labs (title = “Trajectory plot with the thin ‘X’ API”) - -\`\`\` - -\* “Y” API - -\`\`\`{r} - -data \<- market\_share - -prep \<- prep\_trajectoryY( - -data, - -sector\_filter = “power”, - -technology\_filter = “renewablescap”, - -region\_filter = “global”, - -scenario\_source\_filter = “demo\_2020”, - -value = “production” - -) - -scenario\_specs \<- dplyr::tibble( - -scenario = c(“sds”, “sps”, “cps”), - -label = c(“SDS”, “STEPS”, “CPS”) - -) - -main\_line\_metric \<- dplyr::tibble(metric = “projected”, label = -“Portfolio”) - -additional\_line\_metrics \<- dplyr::tibble( - -metric = “corporate\_economy”, - -label = “Corporate Economy” +main_line_metric <- dplyr::tibble(metric = "projected", label = "Portfolio") +additional_line_metrics <- dplyr::tibble( + metric = "corporate_economy", + label = "Corporate Economy" ) -plot\_trajectoryY( - -prep, - -scenario\_specs\_good\_to\_bad = scenario\_specs, - -main\_line\_metric = main\_line\_metric, - -additional\_line\_metrics = additional\_line\_metrics - -) + - -labs (title = “Trajectory plot with the thick ‘Y’ API”) - -\`\`\` - -For full examples see the dedicated articles \[r2dii.plot - -X\]([https://2degreesinvesting.github.io/r2dii.plot/articles/articles/r2dii-plot-X.html)](https://2degreesinvesting.github.io/r2dii.plot/articles/articles/r2dii-plot-X.html)) - -and \[r2dii.plot - -Y\]([https://2degreesinvesting.github.io/r2dii.plot/articles/articles/r2dii-plot-Y.html).](https://2degreesinvesting.github.io/r2dii.plot/articles/articles/r2dii-plot-Y.html).) +plot_trajectoryY( + prep, + scenario_specs_good_to_bad = scenario_specs, + main_line_metric = main_line_metric, + additional_line_metrics = additional_line_metrics +) + + labs (title = "Trajectory plot with the thick 'Y' API") +``` + + + +For full examples see the dedicated articles [r2dii.plot +X](https://2degreesinvesting.github.io/r2dii.plot/articles/articles/r2dii-plot-X.html) +and [r2dii.plot +Y](https://2degreesinvesting.github.io/r2dii.plot/articles/articles/r2dii-plot-Y.html). diff --git a/inst/intro.Rmd b/inst/intro.Rmd index b2aacca7..567ec5f1 100644 --- a/inst/intro.Rmd +++ b/inst/intro.Rmd @@ -1,225 +1,150 @@ The goal of r2dii.plot is to help you plot 2DII data in an informative, - beautiful, and easy way. -\#\# Installation +## Installation You can install the development version of r2dii.plot from +[GitHub](https://github.com/2DegreesInvesting/r2dii.plot) with: -[GitHub]([https://github.com/2DegreesInvesting/r2dii.plot)](https://github.com/2DegreesInvesting/r2dii.plot)) with: - -\`\`\`r - -\# install.packages("devtools") - +```r +# install.packages("devtools") devtools::install_github("2DegreesInvesting/r2dii.plot") +``` -\`\`\` - -\#\# Example +## Example The r2dii.plot package is designed to work smoothly with other "r2dii" packages +-- [r2dii.data](https://2degreesinvesting.github.io/r2dii.data/), +[r2dii.match](https://2degreesinvesting.github.io/r2dii.match/), and +[r2dii.analysis](https://2degreesinvesting.github.io/r2dii.analysis/). It also +plays well with the popular packages [dplyr](https://www.tidyverse.org/) and +[ggplot2](https://ggplot2.tidyverse.org/), which help you customize your plots. --- [r2dii.data]([https://2degreesinvesting.github.io/r2dii.data/),](https://2degreesinvesting.github.io/r2dii.data/),) - -[r2dii.match]([https://2degreesinvesting.github.io/r2dii.match/),](https://2degreesinvesting.github.io/r2dii.match/),) and - -[r2dii.analysis]([https://2degreesinvesting.github.io/r2dii.analysis/).](https://2degreesinvesting.github.io/r2dii.analysis/).) It also - -plays well with the popular packages [dplyr]([https://www.tidyverse.org/)](https://www.tidyverse.org/)) and - -[ggplot2]([https://ggplot2.tidyverse.org/),](https://ggplot2.tidyverse.org/),) which help you customize your plots. - -\`\`\`{r setup} - +```{r setup} library(dplyr, warn.conflicts = FALSE) - library(ggplot2, warn.conflicts = FALSE) - library(r2dii.plot) - -\`\`\` +``` Your data typically comes from the output of two functions in the r2dii.analysis - package: - -[\`target_sda()\`]([https://2degreesinvesting.github.io/r2dii.analysis/reference/target_sda.html)](https://2degreesinvesting.github.io/r2dii.analysis/reference/target_sda.html)) - +[`target_sda()`](https://2degreesinvesting.github.io/r2dii.analysis/reference/target_sda.html) and - -[\`target_market_share()\`]([https://2degreesinvesting.github.io/r2dii.analysis/reference/target_market_share.html).](https://2degreesinvesting.github.io/r2dii.analysis/reference/target_market_share.html).) - +[`target_market_share()`](https://2degreesinvesting.github.io/r2dii.analysis/reference/target_market_share.html). Here you'll use two example datasets that come with r2dii.plot. -\`\`\`{r} - +```{r} sda market_share +``` -\`\`\` - -r2dii.plot currently supports three kinds of plots: \`plot_timeline\*()\`, - -\`plot_techmix\*()\`, and \`plot_trajectory\*()\`. Each plot has specific requirements - -about the main input -- passed to the first argument \`data\`. To meet those - +r2dii.plot currently supports three kinds of plots: `plot_timeline*()`, +`plot_techmix*()`, and `plot_trajectory*()`. Each plot has specific requirements +about the main input -- passed to the first argument `data`. To meet those requirements we currently provide two experimental sets of functions - -([API]([https://en.wikipedia.org/wiki/API)s)](https://en.wikipedia.org/wiki/API)s)) -- "X" and "Y". Both APIs can help - +([API](https://en.wikipedia.org/wiki/API)s) -- "X" and "Y". Both APIs can help you get the same basic plots, which you can further customization with ggplot2. - Their difference difference is not in what you can do but in how you can do it: -\* With the "X" API you meet the \`data\` requirements mainly with - -\`dplyr::filter()\`, and with "internal magic" based on the known structure of - +* With the "X" API you meet the `data` requirements mainly with +`dplyr::filter()`, and with "internal magic" based on the known structure of r2dii data. This API should be best for users who already use dplyr or want to +learn it. It allows for slightly less customization than "Y" but with the +advantage of a much simpler interface. -learn it. - -\* With the "Y" API you could meet the \`data\` requirements with dplyr but you can - -also use dedicated "preparation" functions (\`prep\_\*Y()\`),, and with explicit - -arguments to both the preparation and and plotting functions. This API should - -best for users who do not use dplyr or care about it. +* With the "Y" API you could meet the `data` requirements with dplyr but you can +also use dedicated "preparation" functions (`prep_*Y()`). There are explicit +arguments to both the preparation and plotting functions which allow for a +customization inside the plotting function of what appears in the plot and how +(colours, labels). This API should be best for users who do not use dplyr or +care about it. Users and developers may have different preferences. The tables below compare - the X and Y APIs across a number of criteria relevant to them. -\`\`\`{r echo=FALSE} - -users \<- tibble::tribble( - -\~Criteria, \~\`Thin API "X"\`, \~\`Thin API, "Y"\`, - -"Required knowledge of dplyr and ggplot2", "More", "Less", - -"Customization possible", "Limitless with dplyr and ggplot2", "Limitless with dplyr, ggplot2, and r2dii.plot", - -"Integration with other R workflows", "More", "Less", - +```{r echo=FALSE} +users <- tibble::tribble( + ~Criteria, ~`Thin API "X"`, ~`Thin API, "Y"`, + "Required knowledge of dplyr and ggplot2", "More", "Less", + "Customization possible", "Limitless with dplyr and ggplot2", "Limitless with dplyr, ggplot2, and r2dii.plot", + "Integration with other R workflows", "More", "Less", ) - -caption \<- "The X and Y APIs compared from a user's perspective." - +caption <- "The X and Y APIs compared from a user's perspective." knitr::kable(users, caption = caption) -devs \<- tibble::tribble( - -\~Criteria, \~\`Thin API "X"\`, \~\`Thin API, "Y"\`, - -"Maintenance burden", "Less", "More", - -"Easy to extend", "More", "Less", - +devs <- tibble::tribble( + ~Criteria, ~`Thin API "X"`, ~`Thin API, "Y"`, + "Maintenance burden", "Less", "More", + "Easy to extend", "More", "Less", + ) - -caption \<- "The X and Y APIs compared from a developer's perspective." - +caption <- "The X and Y APIs compared from a developer's perspective." knitr::kable(devs, caption = caption) - -\`\`\` - -To make the comparison concrete consider this small example. Notice the - -resulting plot is the same but the toolkit is different. - -\* "X" API - -\`\`\`{r} - -data \<- market_share - -prep \<- filter( - -data, - -sector == "power", - -technology == "renewablescap", - -region == "global", - -scenario_source == "demo_2020", - -year \<= 2025 - +``` + +To make the comparison concrete consider this small example of a trajectory plot +(the other plot types you can find in the detailed ["X" +API](https://2degreesinvesting.github.io/r2dii.plot/articles/articles/r2dii-plot-X.html) +and ["Y" +API](https://2degreesinvesting.github.io/r2dii.plot/articles/articles/r2dii-plot-Y.html)) +articles. Notice the resulting plot is almost the same (except for the labels) +but the toolkit is different. + +* "X" API + +```{r} +data <- market_share + +prep <- filter( + data, + sector == "power", + technology == "renewablescap", + region == "global", + scenario_source == "demo_2020", + year <= 2025 ) -plot_trajectoryX(prep) + - -labs (title = "Trajectory plot with the thin 'X' API") - -\`\`\` - -\* "Y" API - -\`\`\`{r} +plot_trajectoryX(prep) + + labs (title = "Trajectory plot with the thin 'X' API") +``` -data \<- market_share +* "Y" API -prep \<- prep_trajectoryY( - -data, - -sector_filter = "power", - -technology_filter = "renewablescap", - -region_filter = "global", - -scenario_source_filter = "demo_2020", - -value = "production" +```{r} +data <- market_share +prep <- prep_trajectoryY( + data, + sector_filter = "power", + technology_filter = "renewablescap", + region_filter = "global", + scenario_source_filter = "demo_2020", + value = "production" ) -scenario_specs \<- dplyr::tibble( - -scenario = c("sds", "sps", "cps"), - -label = c("SDS", "STEPS", "CPS") - +scenario_specs <- dplyr::tibble( + scenario = c("sds", "sps", "cps"), + label = c("SDS", "STEPS", "CPS") ) -main_line_metric \<- dplyr::tibble(metric = "projected", label = "Portfolio") - -additional_line_metrics \<- dplyr::tibble( - -metric = "corporate_economy", - -label = "Corporate Economy" +main_line_metric <- dplyr::tibble(metric = "projected", label = "Portfolio") +additional_line_metrics <- dplyr::tibble( + metric = "corporate_economy", + label = "Corporate Economy" ) plot_trajectoryY( - -prep, - -scenario_specs_good_to_bad = scenario_specs, - -main_line_metric = main_line_metric, - -additional_line_metrics = additional_line_metrics - -) + - -labs (title = "Trajectory plot with the thick 'Y' API") - -\`\`\` + prep, + scenario_specs_good_to_bad = scenario_specs, + main_line_metric = main_line_metric, + additional_line_metrics = additional_line_metrics +) + + labs (title = "Trajectory plot with the thick 'Y' API") +``` For full examples see the dedicated articles [r2dii.plot - -X]([https://2degreesinvesting.github.io/r2dii.plot/articles/articles/r2dii-plot-X.html)](https://2degreesinvesting.github.io/r2dii.plot/articles/articles/r2dii-plot-X.html)) - +X](https://2degreesinvesting.github.io/r2dii.plot/articles/articles/r2dii-plot-X.html) and [r2dii.plot - -Y]([https://2degreesinvesting.github.io/r2dii.plot/articles/articles/r2dii-plot-Y.html).](https://2degreesinvesting.github.io/r2dii.plot/articles/articles/r2dii-plot-Y.html).) +Y](https://2degreesinvesting.github.io/r2dii.plot/articles/articles/r2dii-plot-Y.html). diff --git a/man/figures/README-unnamed-chunk-6-1.png b/man/figures/README-unnamed-chunk-6-1.png index dbb95e92cca0ec04e30ec5ee5f123883f2cac2e6..8ecb022182177b4a48fb90724b6c7f1651164fcb 100644 GIT binary patch literal 22861 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 bZEQaIG&nVG$T|T>OLXnBwCG!rTMzyl0nY%c diff --git a/man/figures/README-unnamed-chunk-7-1.png b/man/figures/README-unnamed-chunk-7-1.png index e3dbb994eacba6189d0fe2b6eeb34c2e70eeec8e..4b04d680a83d3a567d6498510c723d3f5b8b559d 100644 GIT binary patch literal 23310 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 T=*>lF79^d6`UmLytpoo9%;uJc diff --git a/vignettes/articles/r2dii-plot-X-versus-Y.Rmd b/vignettes/articles/r2dii-plot-X-versus-Y.Rmd index d1170732..5ca9d157 100644 --- a/vignettes/articles/r2dii-plot-X-versus-Y.Rmd +++ b/vignettes/articles/r2dii-plot-X-versus-Y.Rmd @@ -9,9 +9,153 @@ knitr::opts_chunk$set( ) ``` +The goal of r2dii.plot is to help you plot 2DII data in an informative, +beautiful, and easy way. + +## Installation + +You can install the development version of r2dii.plot from +[GitHub](https://github.com/2DegreesInvesting/r2dii.plot) with: + +```r +# install.packages("devtools") +devtools::install_github("2DegreesInvesting/r2dii.plot") +``` + +## Example + +The r2dii.plot package is designed to work smoothly with other "r2dii" packages +-- [r2dii.data](https://2degreesinvesting.github.io/r2dii.data/), +[r2dii.match](https://2degreesinvesting.github.io/r2dii.match/), and +[r2dii.analysis](https://2degreesinvesting.github.io/r2dii.analysis/). It also +plays well with the popular packages [dplyr](https://www.tidyverse.org/) and +[ggplot2](https://ggplot2.tidyverse.org/), which help you customize your plots. + +```{r setup} +library(dplyr, warn.conflicts = FALSE) +library(ggplot2, warn.conflicts = FALSE) +library(r2dii.plot) +``` + +Your data typically comes from the output of two functions in the r2dii.analysis +package: +[`target_sda()`](https://2degreesinvesting.github.io/r2dii.analysis/reference/target_sda.html) +and +[`target_market_share()`](https://2degreesinvesting.github.io/r2dii.analysis/reference/target_market_share.html). +Here you'll use two example datasets that come with r2dii.plot. + +```{r} +sda + +market_share +``` + +r2dii.plot currently supports three kinds of plots: `plot_timeline*()`, +`plot_techmix*()`, and `plot_trajectory*()`. Each plot has specific requirements +about the main input -- passed to the first argument `data`. To meet those +requirements we currently provide two experimental sets of functions +([API](https://en.wikipedia.org/wiki/API)s) -- "X" and "Y". Both APIs can help +you get the same basic plots, which you can further customization with ggplot2. +Their difference difference is not in what you can do but in how you can do it: + +* With the "X" API you meet the `data` requirements mainly with +`dplyr::filter()`, and with "internal magic" based on the known structure of +r2dii data. This API should be best for users who already use dplyr or want to +learn it. It allows for slightly less customization than "Y" but with the +advantage of a much simpler interface. + +* With the "Y" API you could meet the `data` requirements with dplyr but you can +also use dedicated "preparation" functions (`prep_*Y()`). There are explicit +arguments to both the preparation and plotting functions which allow for a +customization inside the plotting function of what appears in the plot and how +(colours, labels). This API should be best for users who do not use dplyr or +care about it. + +Users and developers may have different preferences. The tables below compare +the X and Y APIs across a number of criteria relevant to them. + ```{r echo=FALSE} -intro <- system.file("intro.Rmd", package = "r2dii.plot") +users <- tibble::tribble( + ~Criteria, ~`Thin API "X"`, ~`Thin API, "Y"`, + "Required knowledge of dplyr and ggplot2", "More", "Less", + "Customization possible", "Limitless with dplyr and ggplot2", "Limitless with dplyr, ggplot2, and r2dii.plot", + "Integration with other R workflows", "More", "Less", +) +caption <- "The X and Y APIs compared from a user's perspective." +knitr::kable(users, caption = caption) + +devs <- tibble::tribble( + ~Criteria, ~`Thin API "X"`, ~`Thin API, "Y"`, + "Maintenance burden", "Less", "More", + "Easy to extend", "More", "Less", + +) +caption <- "The X and Y APIs compared from a developer's perspective." +knitr::kable(devs, caption = caption) ``` -```{r child=intro} +To make the comparison concrete consider this small example of a trajectory plot +(the other plot types you can find in the detailed ["X" +API](https://2degreesinvesting.github.io/r2dii.plot/articles/articles/r2dii-plot-X.html) +and ["Y" +API](https://2degreesinvesting.github.io/r2dii.plot/articles/articles/r2dii-plot-Y.html)) +articles. Notice the resulting plot is almost the same (except for the labels) +but the toolkit is different. + +* "X" API + +```{r} +data <- market_share + +prep <- filter( + data, + sector == "power", + technology == "renewablescap", + region == "global", + scenario_source == "demo_2020", + year <= 2025 +) + +plot_trajectoryX(prep) + + labs (title = "Trajectory plot with the thin 'X' API") +``` + +* "Y" API + +```{r} +data <- market_share + +prep <- prep_trajectoryY( + data, + sector_filter = "power", + technology_filter = "renewablescap", + region_filter = "global", + scenario_source_filter = "demo_2020", + value = "production" +) + +scenario_specs <- dplyr::tibble( + scenario = c("sds", "sps", "cps"), + label = c("SDS", "STEPS", "CPS") +) + +main_line_metric <- dplyr::tibble(metric = "projected", label = "Portfolio") + +additional_line_metrics <- dplyr::tibble( + metric = "corporate_economy", + label = "Corporate Economy" +) + +plot_trajectoryY( + prep, + scenario_specs_good_to_bad = scenario_specs, + main_line_metric = main_line_metric, + additional_line_metrics = additional_line_metrics +) + + labs (title = "Trajectory plot with the thick 'Y' API") ``` + +For full examples see the dedicated articles [r2dii.plot +X](https://2degreesinvesting.github.io/r2dii.plot/articles/articles/r2dii-plot-X.html) +and [r2dii.plot +Y](https://2degreesinvesting.github.io/r2dii.plot/articles/articles/r2dii-plot-Y.html).