03-emissions.Rmd

# Emissions {#emissions}

**This chapter will show you how to create charts** showing annual emissions for one or more *categories* and one or more *pollutants*.

It will also show you how to customize those charts with:

- a unique *color* for each category;
- directly labeled *values* at specific years; and
- reader-friendly *names* for categories.

Finally, it will show you how to create *area charts*, consistent with all of the above.

All of what you learn will be extensible to the chapters on [Throughputs], [Growth Profiles], [Emission Factors], and [Control Factors].

## Key functions

This section relies on three key functions:

- `filter_categories()`
- `filter_pollutants()`
- `chart_annual_emissions_by()`

If you have read the vignette *Introduction to BY Data*^[This is being migrated from an R vignette to a GitBook like this one. Stay tuned!] then you are already familiar with `filter_categories()` and `filter_pollutants()`.

The `chart_annual_emissions_by()` function --- and its shorter form, `chart_annual_emissions()` --- will be the foundation of this section. To learn more about `chart_annual_emissions_by()`, you can always type `help("chart_annual_emissions_by")`.

## Charting annual emissions

Let's try it out on a relatively simple case: charting NO~x~ emissions from BY2011 category #283 Water Heating.

```{r BY2011_annual_emission_data-283-NOx, fig.height=3, out.height=300}
#
# This is an absolutely minimal example for `chart_annual_emissions()`.
# We're going to build on it, adding improvements as we go.
#
BY2011_annual_emission_data %>%
  filter_categories(
    283) %>%
  filter_pollutants(
    "NOx") %>%
  chart_annual_emissions()
```

That's a great first step!

## Coloring by category

If you want to chart more than one category, you'll probably want a way to distinguish them visually. Let's use `color` to distinguish (and compare) #283 Water Heating and #284 Space Heating.

```{r BY2011_annual_emission_data-283-284-NOx, fig.height=3, out.height=300}
#
# Here we'll color by `category`. You could also color by `cnty_abbr`. (Try it!)
#
# By default, `filter_categories()` adds a new column `category`. If you don't
# name the categories --- which we will do, further along --- then they are 
# simply prefixed with "#". So, for example, when `cat_id` is 283, the default 
# for `category` will be "#283".
#
# The suffix `_by()` --- on `chart_annual_emissions_by()` --- is mostly just
# there for readability. Things should still work if you forget and use
# `chart_annual_emissions()` instead.
# 
BY2011_annual_emission_data %>%
  filter_categories(
    283, 
    284) %>%
  filter_pollutants(
    "NOx") %>%
  chart_annual_emissions_by(
    color = category)
```

```{block type="note"}
The default colors are provided by `scale_color_tableau()`. You can try using a different color scheme if you like. Go to the "Help" pane in RStudio, and type "scale_color_", then wait. You should see a list of choices pop up.

If you wind up with more than ten colors, rethink the chart. Maybe grouping categories would be helpful? In later sections, we will learn how.
```

## Flagging specific values

Displaying exact values on a chart can be helpful to the reader. Then, they don't have to consult a separate table. 

To do this, simply supply `flag_years`. If you want to change the template for what exactly is displayed --- digits, text, etc. --- you can supply `flag_labels` too. See the [Appendix](#appendix-howto-flag_labels).

```{r BY2011_annual_emission_data-283-284-NOx-flag_years, fig.height=3, out.height=300}
#
# Use `flag_years` to display values directly in the chart.
#
BY2011_annual_emission_data %>%
  filter_categories(
    283, 
    284) %>%
  filter_pollutants(
    "NOx") %>%
  chart_annual_emissions_by(
    color = category,
    flag_years = CY(1993, 2011, 2030))
```

## Humanizing category names

You can also, in the process of filtering, supply more human-readable names for the categories.

```{r BY2011_annual_emission_data-283-284-NOx-humanize_category_names, fig.height=3, out.height=300}
#
# Names supplied to `filter_categories()` appear in the data as a new column,
# `category`. Following that, we can ask `chart_annual_emissions_by()` to use
# `category` as the basis for coloring.
# 
BY2011_annual_emission_data %>%
  filter_categories(
    "#283 Space Heating" = 283, 
    "#284 Water Heating" = 284) %>%
  filter_pollutants(
    "NOx") %>%
  chart_annual_emissions_by(
    color = category,
    flag_years = CY(1993, 2011, 2030))
```

## Titling and captioning

Last but not least, you can provide a `title`, `subtitle`, and/or `caption`.

```{r BY2011_annual_emission_data-chart_annual_emissions_by-category-with_title}
#
# An explicit `title`, `subtitle`, and/or `caption` can be supplied to
# `chart_annual_emissions_by()`. This is strongly encouraged!!
#
# The default caption is just "DRAFT YYYY-mm-dd."
# 
BY2011_annual_emission_data %>%
  filter_categories(
    "#283 Space Heating" = 283, 
    "#284 Water Heating" = 284) %>%
  filter_pollutants(
    "NOx") %>%
  chart_annual_emissions_by(
    color = category,
    flag_years = CY(1993, 2011, 2030),
    title = "Residential NG Combustion: Space and Water Heating",
    subtitle = "Between CY1993-2002, controls on NOx from water heating were strengthened.")
```

## Making an area chart

Stacking can be a good way to show how the total and the proportions vary over time. (Compare with the line-charts above, which are not stacked.)

To create a stacked ("area") chart, simply pass `fill = ...` instead of `color = ...`.

```{r BY2011_annual_emission_data-283-284-NOx-fill_by_category}
#
# `fill` can be supplied in place of `color`.
# 
# `subtitle = str_c(..., sep = "\n")` means "combine multiple lines of text".
# We can use this to avoid subtitles running off the chart.
#
BY2011_annual_emission_data %>%
  filter_categories(
    "#283 Space Heating" = 283, 
    "#284 Water Heating" = 284) %>%
  filter_pollutants(
    "NOx") %>%
  chart_annual_emissions_by(
    fill = category,
    title = "Residential NG Combustion: Space and Water Heating",
    subtitle = str_c(
      "Combined emissions from water and space heating have declined.",
      "But, they are projected to return to 1990 levels by 2030.",
      sep = "\n"))
```

## More than one pollutant

Above, we've kept things simple by just focusing on NO~x~. But you'll often want to show more than one pollutant at the same time. You can definitely do that!

```{r BY2011_annual_emission_data-283-284-multiple_pollutants, fig.height=6, out.height=600}
#
# If multiple pollutants are represented in the data that is passed to
# `chart_annual_emissions_by()`, it will try to be helpful by creating a
# sub-plot for each pollutant. This ought to be a safe approach.
# 
BY2011_annual_emission_data %>%
  filter_categories(
    "#283 Space Heating" = 283, 
    "#284 Water Heating" = 284) %>%
  filter_pollutants(
    "NOx",
    "PM10") %>%
  chart_annual_emissions_by(
    color = category,
    title = "Residential NG Combustion: Space and Water Heating",
    subtitle = "Between CY1993-2002, controls on NOx from water heating were strengthened.")
```