ggiplot.Rmd

---
title: "Comparing ggiplot with iplot"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Comparing ggiplot with iplot}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

As far as possible, the **ggfixest** plotting functions try to mimic the
behaviour of their base compatriots. However, they also offer additional
functionality thanks to the **ggplot2** API. This vignette will walk you through
the key differences and correspondences, specifically with regards to
`ggiplot` versus the original `iplot`.^[The `ggcoefplot` and `coefplot`
functions share a subset of the differences presented here, so you should be
aware of those too once you've read this vignette.]

Start by loading **ggfixest**. This will automatically load **ggplot2** and
and **fixest** too, as both of these packages are required for this one to
work.

```{r setup}
library(ggfixest)
```

In the examples that follow, I'll be drawing on the **fixest** 
[introductory vignette](https://lrberge.github.io/fixest/articles/fixest_walkthrough.html),
as well as the `iplot` help documentation. 

### Example 1: Vanilla TWFE

```{r est_did}
data(base_did)

est_did = feols(y ~ x1 + i(period, treat, 5) | id + period, base_did)
```

Let's compare the (base) `iplot` and `ggiplot` default plots.

```{r est_did_plot_defaults}
iplot(est_did)
ggiplot(est_did)
```

There are some small differences, but they are certainly producing the same
basic plot. To get even closer to the original, we could specify the use of 
errorbar(s) rather than (`ggiplot`'s default of) pointrange(s).

```{r est_did_ebar}
ggiplot(est_did, geom = 'errorbar')
```

Many of the arguments for `iplot` carry over to `ggiplot` too. This is
deliberate, since we want to reduce the cognitive overhead of switching between
the two plotting methods. For example, we can join points using the same 
`pt.join = TRUE` argument.

```{r est_did_pt_join}
iplot(est_did, pt.join = TRUE)
ggiplot(est_did, pt.join = TRUE, geom_style = 'errorbar')
```

The `ggiplot` defaults are slightly different in some cases, but may require
less arguments depending on what you want to do. For example,

```{r est_did_ribbon}
# iplot(est_did, pt.join = TRUE, ci.lty = 0, ci.width = 0, ci.fill = TRUE)
iplot(
	est_did, pt.join = TRUE, ci.lty = 0, ci.width = 0, ci.fill = TRUE,
	ci.fill.par = list(col = 'black', alpha = 0.3)
	)
ggiplot(est_did, geom_style = 'ribbon')
ggiplot(est_did, geom_style = 'ribbon', pt.pch = NA, col = 'orange')
```

Unlike base `iplot`, multiple confidence interval levels are supported.
This works for ribbons too.

```{r est_did_ci_multi}
ggiplot(est_did, ci_level = c(.8, .95))
```

Another new feature (i.e. unsupported in base `iplot`) is adding aggregated
post- and/or pre-treatment effects to your plots. Here's an example that builds
on the previous plot, by adding the mean post-treatment effect.

```{r est_did_aggr_eff}
ggiplot(
	est_did, ci_level = c(.8, .95),
	aggr_eff = "post", aggr_eff.par = list(col = "orange") # default col is grey
	)
```

### Example 2: Multiple estimation (i)

We'll demonstrate multiple estimation functionality using the staggered treatment example
(comparing vanilla TWFE with the Sun-Abraham estimator) from the **fixest**
introductory vignette.

```{r base_stagg}
data(base_stagg)

est_twfe = feols(
	y ~ x1 + i(time_to_treatment, treated, ref = c(-1, -1000)) | id + year,
	data = base_stagg
	)

est_sa20 = feols(
	y ~ x1 + sunab(year_treated, year) | id + year,
	data = base_stagg
	)
```

Again, for comparison, here the base `iplot` original. Note that we add the 
legend manually.

```{r stagg_iplot}
iplot(
	list('TWFE' = est_twfe, 'Sun & Abraham (2020)' = est_sa20),
	main = 'Staggered treatment', ref.line = -1, pt.join = TRUE
	)
legend(
	'topleft', col = c(1, 2), pch = c(20, 17),
	legend = c('TWFE', 'Sun & Abraham (2020)')
	)
```

Here's the `ggiplot` version.

```{r stagg_ggiplot}
ggiplot(
	list('TWFE' = est_twfe, 'Sun & Abraham (2020)' = est_sa20),
	main = 'Staggered treatment', ref.line = -1, pt.join = TRUE
	)
```

If we don't name out list of models then it defaults to something sensible.

```{r stagg_ggiplot_noname}
ggiplot(
	list(est_twfe, est_sa20),
	main = 'Staggered treatment', ref.line = -1, pt.join = TRUE
	)
```

One nice thing about the **ggplot2** API is that it makes changing multiplot
figures simple. For example, if you don't like the presentation of "dodged" 
models in a single frame, then it's easy to facet them instead using 
the `multi_style = 'facet'` argument.

```{r stagg_ggiplot_facet}
ggiplot(
	list('TWFE' = est_twfe, 'Sun & Abraham (2020)' = est_sa20),
	main = 'Staggered treatment', ref.line = -1, pt.join = TRUE,
	multi_style = 'facet'
	)
```

### Example 3: Multiple estimation (ii)

An area where `ggiplot` shines is in complex multiple estimation cases, such
as lists of `fixest_multi` objects. To illustrate, let's add a split variable
(group) to our staggered dataset.

```{r base_stagg_grp}
base_stagg_grp = base_stagg
base_stagg_grp$grp = ifelse(base_stagg_grp$id %% 2 == 0, 'Evens', 'Odds')
```

Now re-run our two regressions from earlier, but splitting the sample to
generate `fixest_multi` objects.

```{r stagg_grp}
est_twfe_grp = feols(
	y ~ x1 + i(time_to_treatment, treated, ref = c(-1, -1000)) | id + year,
	data = base_stagg_grp, split = ~ grp
	)
est_sa20_grp = feols(
	y ~ x1 + sunab(year_treated, year) | id + year,
	base_stagg_grp, split = ~ grp
	)
```

Both `iplot` and `ggiplot` do fine with a single `fixest_multi` object (although
remember that we have to manually add a legend for the former)

```{r stagg_grp_single}
iplot(est_twfe_grp, ref.line = -1, main = 'Staggered treatment: TWFE')
legend('topleft', col = c(1, 2), pch = c(20, 17), legend = c('Evens', 'Odds'))
ggiplot(est_twfe_grp, ref.line = -1, main = 'Staggered treatment: TWFE')
```

However, `iplot` complains if we combine a list of _several_ `fixest_multi` 
objects.

```{r stagg_grp_multi_iplot, error = TRUE}
iplot(
	list('TWFE' = est_twfe_grp, 'Sun & Abraham (2020)' = est_sa20_grp),
	ref.line = -1, main = 'Staggered treatment: Split mutli-sample'
	)
```

In contrast, `ggiplot` works...

```{r stagg_grp_multi_ggiplot}
ggiplot(
	list('TWFE' = est_twfe_grp, 'Sun & Abraham (2020)' = est_sa20_grp),
	ref.line = -1, main = 'Staggered treatment: Split mutli-sample'
	)
```

... but is even better when we use faceting instead of dodged errorbars.
Let's use this as an opportunity to construct a fancy plot that invokes some
additional arguments and ggplot theming.

```{r stagg_grp_multi_ggiplot_fancy}
ggiplot(
    list("TWFE" = est_twfe_grp, "Sun & Abraham (2020)" = est_sa20_grp),
    ref.line = -1,
    main = "Staggered treatment: Split mutli-sample",
    xlab = "Time to treatment",
    multi_style = "facet",
    geom_style = "ribbon",
    facet_args = list(labeller = labeller(id = \(x) gsub(".*: ", "", x))),
    theme = theme_minimal() +
        theme(
            text = element_text(family = "HersheySans"),
            plot.title = element_text(hjust = 0.5),
            legend.position = "none"
        )
)

```


### Asides 

#### On theming and scale adjustments

Setting the theme inside the `ggiplot` call is optional and not strictly
necessary, since the ggplot2 API allows programmatic updating of existing
plots. E.g.

```{r theme_update}
last_plot() +
	labs(caption = 'Note: Super fancy plot brought to you by ggiplot')
last_plot() + 
	theme_grey() + 
	theme(legend.position = 'none') +
	scale_fill_brewer(palette = 'Set1', aesthetics = c('colour', 'fill'))
```

etc.

#### On dictionaries

Dictionaries work similarly to `iplot`. Simple example:

```{r dict}
base_did$letter = letters[base_did$period]
est_letters = feols(y ~ x1 + i(letter, treat, 'e') | id+letter, base_did)

# Dictionary for capitalising the letters
dict = LETTERS[1:10]; names(dict) = letters[1:10]

ggiplot(est_letters) # No dictionary
```

You can either set the dictionary directly in the plot call...

```{r dict_direct}
ggiplot(est_letters, dict = dict)
```

... Or, set it globally using the `setFixest_dict` macro.

```{r dict_global}
setFixest_dict(dict)
ggiplot(est_letters)

setFixest_dict() # reset
```