Align X and Y articles for techmix and trajectory (#241)

Co-authored-by: Mauro Lepore <mauro@2degrees-investing.org>

R/plot_trajectoryY.R

@@ -57,7 +57,22 @@ plot_trajectoryY <- function(data,
                              scenario_specs_good_to_bad,
                              main_line_metric,
                              additional_line_metrics = NULL) {
+  abort_if_missing_names(scenario_specs_good_to_bad, "scenario")
   check_number_scenarios(scenario_specs_good_to_bad)
+  if (!("label" %in% names(scenario_specs_good_to_bad))) {
+    scenario_specs_good_to_bad$label <- scenario_specs_good_to_bad$scenario
+  }
+
+  abort_if_missing_names(main_line_metric, "metric")
+  if (!("label" %in% names(main_line_metric))) {
+    main_line_metric$label <- main_line_metric$metric
+  }
+  if (!is.null(additional_line_metrics)) {
+    abort_if_missing_names(additional_line_metrics, "metric")
+    if (!("label" %in% names(additional_line_metrics))) {
+      additional_line_metrics$label <- additional_line_metrics$metric
+    }
+  }
 
   # plot scenario areas
   scenario_specs_areas <- get_ordered_scenario_specs_with_colours(

vignettes/articles/r2dii-plot-X-versus-Y.Rmd

@@ -61,12 +61,15 @@ 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.
+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()`),, 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.
+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.
@@ -91,8 +94,13 @@ 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.
+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
 

vignettes/articles/r2dii-plot-X.Rmd

@@ -85,6 +85,27 @@ market_share %>%
   plot_techmixX() + labs(title = "Techmix plot")
 ```
 
+You may customize the plot further by:
+
+* Setting custom colours and colour labels using `ggplot` function `scale_color_manual()`.
+* Picking the years to be plotted by filtering the data passed to `plot_techmixX()` (by default the extreme years in the data are plotted). 
+
+At the moment the labels of the bars are derived from the data and it is not possible to change or remove them (as it is possible with ["Y" API](https://2degreesinvesting.github.io/r2dii.plot/articles/articles/r2dii-plot-Y.html)).
+
+```{r error = TRUE}
+market_share %>%
+  filter(
+    metric %in% chosen_metrics,
+    sector == "power",
+    region == "global",
+    between(year, 2020, 2025)
+  ) %>% 
+  plot_techmixX() + 
+  scale_fill_manual(
+    values = c("black", "brown", "grey", "blue", "green4"),
+    labels = c("Coal Cap.", "Oil Cap.", "Gas Cap.", "Hydro Cap.", "Renewables Cap."))
+```
+
 ### Trajectory
 
 Use `plot_trajectoryX()` with `market_share`-like data. Again, learn which rows
@@ -104,7 +125,7 @@ plot_trajectoryX(data) + labs(title = "Trajectory plot")
 ```
 
 Use `main_line` argument to indicate which trajectory line should be most 
-visually salient (solid black line).
+visually salient (solid black line). Without the argument, the first 'metric' in data which is not a scenario is used as a main line.
 
 ```{r}
 plot_trajectoryX(data, main_line = "projected")

vignettes/articles/r2dii-plot-Y.Rmd

@@ -52,15 +52,16 @@ some typical things you may do:
 
 ```{r}
 cement <- prep_timelineY(
-  filter(sda, sector == "cement", year >= 2020), 
-  extrapolate = TRUE)
+  filter(sda, sector == "cement", year >= 2020),
+  extrapolate = TRUE
+)
 
-plot_timelineY(cement) + 
+plot_timelineY(cement) +
   labs(title = "Timeline plot")
 ```
 
 * `plot_timelineY()` defaults to recoding `line_name` to title case, and allows
-custom recoding and colour setting via a data frame passed to the argument 
+custom recoding and colour setting via a data frame passed to the argument
 `specs`.
 
 ```{r}
@@ -80,9 +81,9 @@ plot_timelineY(cement, specs = custom)
 ### Techmix
 
 The techmix plot uses `market_share`-like data. First prepare it with
-`prep_techmixY()`, then plot it with `plot_techmixY()`. `prep_techmiY()` 
-includes a number of arguments that help you meet the `data` requirements
-of `plot_techmixY()`.
+`prep_techmixY()`, then plot it with `plot_techmixY()`. `prep_techmiY()`
+includes a number of arguments that help you meet the `data` requirements of
+`plot_techmixY()`.
 
 ```{r}
 data <- prep_techmixY(
@@ -95,12 +96,11 @@ data <- prep_techmixY(
   value = "technology_share"
 )
 
-plot_techmixY(data)
+plot_techmixY(data) + labs(title = "Techmix plot")
 ```
 
-
-You can also add a bunch of customizations (order and choice of bars to show, 
-custom labels, custom colours) using additional `plot_techmixY()` arguments. 
+You can also add a bunch of customizations (order and choice of bars to show,
+custom labels, custom colours) using additional `plot_techmixY()` arguments.
 
 ```{r}
 data <- prep_techmixY(
@@ -116,27 +116,30 @@ data <- prep_techmixY(
 metric_type_order <- c("portfolio_2020", "benchmark_2020", "portfolio_2025", "benchmark_2025", "scenario_2025")
 metric_type_label <- c("Port. 2020", "Bench. 2020", "Port. 2025", "Bench. 2025", "Scen. 2025")
 
-tech_colors_custom <- tibble(
+tech_colors_custom <- data.frame(
   technology = c("coalcap", "oilcap", "gascap", "nuclearcap", "hydrocap", "renewablescap"),
   label = c("Coal Cap.", "Oil Cap.", "Gas Cap.", "Nuclear Cap.", "Hydro Cap.", "Renewables Cap."),
-  hex = c("black", "brown", "grey", "red", "blue", "green4")
+  hex = c("black", "brown", "grey", "red", "blue", "green4"),
+  stringsAsFactors = FALSE
 )
+tech_colors_custom
 
 plot_techmixY(
-  data, 
+  data,
   metric_type_order = metric_type_order,
   metric_type_label = metric_type_label,
   tech_colours = tech_colors_custom
-  )
+)
 ```
 
 ### Trajectory
 
-The techmix plot uses `market_share`-like data. First prepare it with
+The trajectory plot uses `market_share`-like data. First prepare it with
 `prep_trajectoryY()`, then plot it with `plot_trajectoryY()`. As you may expect
-by now, `prep_trajectoryY()` includes arguments to meet the `data` requirements 
-of `plot_trajectoryY()`. `plot_trajectoryY()` inputs a number of data frames 
-which you can create with `dplyr::tibble()`.
+by now, `prep_trajectoryY()` includes arguments to meet the `data` requirements
+of `plot_trajectoryY()`. `plot_trajectoryY()` inputs a number of data frames
+which require you to specify the order of scenarios and order of significance
+for the trajectory lines.
 
 ```{r}
 data <- prep_trajectoryY(
@@ -148,16 +151,37 @@ data <- prep_trajectoryY(
   value = "production"
 )
 
-scenario_specs <- tibble(
+scenario_specs <- data.frame(
   scenario = c("sds", "sps", "cps"),
-  label = c("SDS", "STEPS", "CPS")
+  stringsAsFactors = FALSE
 )
 
-main_line_metric <- tibble(metric = "projected", label = "Portfolio")
+main_line_metric <- data.frame(metric = "projected", stringsAsFactors = FALSE)
 
-additional_line_metrics <- tibble(
+additional_line_metrics <- data.frame(
   metric = "corporate_economy",
-  label = "Corporate Economy"
+  stringsAsFactors = FALSE
+)
+
+plot_trajectoryY(
+  data,
+  scenario_specs_good_to_bad = scenario_specs,
+  main_line_metric = main_line_metric,
+  additional_line_metrics = additional_line_metrics
+) + labs(title = "Trajectory plot")
+```
+
+Use `normalize = FALSE` if you prefer not to normalize to the start year.
+
+```{r}
+data <- prep_trajectoryY(
+  market_share,
+  sector_filter = "power",
+  technology_filter = "renewablescap",
+  region_filter = "global",
+  scenario_source_filter = "demo_2020",
+  value = "production",
+  normalize = FALSE
 )
 
 plot_trajectoryY(
@@ -166,6 +190,45 @@ plot_trajectoryY(
   main_line_metric = main_line_metric,
   additional_line_metrics = additional_line_metrics
 )
+``` 
+
+You can customize the labels in the plot by adding 'label' column to the input
+data frames.
+
+```{r}
+data <- prep_trajectoryY(
+  market_share,
+  sector_filter = "power",
+  technology_filter = "renewablescap",
+  region_filter = "global",
+  scenario_source_filter = "demo_2020",
+  value = "production"
+)
+
+scenario_specs <- data.frame(
+  scenario = c("sds", "sps", "cps"),
+  label = c("SDS", "STEPS", "CPS"),
+  stringsAsFactors = FALSE
+)
+
+main_line_metric <- data.frame(
+  metric = "projected", 
+  label = "Portfolio",
+  stringsAsFactors = FALSE
+)
+
+additional_line_metrics <- data.frame(
+  metric = "corporate_economy",
+  label = "Corporate Economy",
+  stringsAsFactors = FALSE
+)
+
+plot_trajectoryY(
+  data,
+  scenario_specs_good_to_bad = scenario_specs,
+  main_line_metric = main_line_metric,
+  additional_line_metrics = additional_line_metrics
+) + labs(title = "Trajectory plot")
 ```
 
 If you haven't done so already, please see the [article about the "X"