---
title: "Introduction to `carbonr`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Introduction to `carbonr`}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

## Overview

`carbonr` is a package in R to conveniently calculate carbon-equivalent emissions.

The emissions values in the calculations are mostly from the [UK Government report (2023)](https://www.gov.uk/government/publications/greenhouse-gas-reporting-conversion-factors-2023) when available. It is specified where the calculations have come from if they are not from the UK Government report (2023).

## Motivation
`carbonr` aims to provide a reliable and reproducible approach to calculating emissions levels, ensuring that the results can be saved, edited, and redistributed easily. Further, `carbonr` aims to be transparent in its calculations and values applied. This has the bonus of allowing for flexibility and customisation in estimating carbon-equivalent emissions.

The vision for `carbonr` is to expand and become more comprehensive. We invite contributions from the community to extend the package's functionality, build additional features, and transform it into a more robust tool for estimating carbon-equivalent emissions. Similarly, we invite open discussions and contribution to capture different perspectives and enhancing the functionality of the package.

Finally, `carbonr` aims to make the estimation of carbon-equivalent emissions more accessible by offering a user-friendly front-end interface using Shiny. This ensures that the tools are easier to use, even for individuals with limited programming experience.

## Installation

You can install the development version of carbonr from [GitHub](https://github.com/):

```{r, eval = FALSE}
# install.packages("devtools")
devtools::install_github("IDEMSInternational/carbonr")
```

## Usage
Currently in `carbonr`, you can calculate your emissions from raw materials, such as raw fuels, paper, or metal emissions, or you can calculate from different categories such as flights, overall office or household estimated emissions, or vehicles. There are additional options relating specifically to operating theatres as well. Functions include:

* `airplane_emissions()`
* `ferry_emissions()`
* `rail_emissions()`
* `land_emissions()`
* `vehicle_emissions()`
* `hotel_emissions()`
* `building_emissions()`
* `office_emissions()`
* `household_emissions()`
* `construction_emissions()`
* `electrical_emissions()`
* `material_emissions()`
* `metal_emissions()`
* `paper_emissions()`
* `plastic_emissions()`
* `raw_fuels()`
* `anaesthetic_emissions()`
* `clinical_emissions()`
* `clinical_theatre_data()`

These all return carbon-equivalent emissions in tonnes.

A shiny app is also available by `shiny_emissions()` to calculate carbon-equivalent emissions with a GUI.

We give some small examples in using the functions in `carbonr()`.

```{r, message = FALSE, warning = FALSE}
library(carbonr)
```

To calculate emissions for a flight between Vancouver and Toronto, we first want to find the name of the airports. We do this using the `airport_finder()` function:

```{r, message = FALSE, warning = FALSE, eval=FALSE, include=TRUE}
airport_finder(name = "Vancouver")
```
```{r, message = FALSE, warning = FALSE, echo = FALSE}
airport_finder(name = "Vancouver") %>%
  knitr::kable()
```
```{r, message = FALSE, warning = FALSE, eval=FALSE, include=TRUE}
airport_finder(name = "Toronto")
```
```{r, message = FALSE, warning = FALSE, echo = FALSE}
airport_finder(name = "Toronto") %>%
  knitr::kable()
```

Now we can find the overall emission value using the appropriate IATA code. These distances are calculated using the Haversine formula:
```{r, message = FALSE, warning = FALSE}
airplane_emissions("YVR", "YTZ")
```

A similar approach can be performed for ferry emissions. For example, to calculate emissions for a round trip ferry from Melbourne to New York, we first find the appropriate seaport code with the `seaport_finder()` function:
```{r, message = FALSE, warning = FALSE, eval=FALSE, include=TRUE}
seaport_finder(country = "Australia", city = "Melbourne")
```
```{r, message = FALSE, warning = FALSE, echo = FALSE}
seaport_finder(country = "Australia", city = "Melbourne") %>%
  knitr::kable()
```
```{r, message = FALSE, warning = FALSE, eval=FALSE, include=TRUE}
seaport_finder(country = "US", city = "New York")
```
```{r, message = FALSE, warning = FALSE, echo = FALSE}
seaport_finder(country = "US", city = "New York") %>%
  knitr::kable()
```

Now we can find the overall emission value using the appropriate seaport code:
```{r, message = FALSE, warning = FALSE}
ferry_emissions("POR", "BOY", round_trip = TRUE)
```

For the UK we can calculate emissions for a train journey. Like with `airplane_emissions()` and `ferry_emissions()`, the distances are calculated using the Haversine formula - this is calculated as the crow flies. As before, we first find the stations. As always, for a more accurate estimation we can include via points:

To calculate emissions for a train journey from Bristol Temple Meads to Edinburgh Waverley, via Birmingham New Street. We can use a data frame and `purrr::map()` to read through the data easier:

```{r, message = FALSE, warning = FALSE, eval=FALSE, include=TRUE}
multiple_ind <- tibble::tribble(~ID, ~station,
                        "From", "Bristol",
                        "To", "Edinburgh",
                        "Via", "Birmingham")
purrr::map(.x = multiple_ind$station, .f = ~rail_finder(.x)) %>%
  dplyr::bind_rows()
```
```{r, message = FALSE, warning = FALSE, echo=FALSE}
multiple_ind <- tibble::tribble(~ID, ~station,
                        "From", "Bristol",
                        "To", "Edinburgh",
                        "Via", "Birmingham")
purrr::map(.x = multiple_ind$station, .f = ~rail_finder(.x)) %>%
  dplyr::bind_rows() %>%
  knitr::kable()
```

Then we can estimate the overall tCO2e emissions for the journey:
```{r, message = FALSE, warning = FALSE}
rail_emissions(from = "Bristol Temple Meads", to = "Edinburgh", via = "Birmingham New Street")
```

We can use a data frame to read through the data easier in general. For example, if we had data for multiple individuals, or journeys:
```{r, message = FALSE, warning = FALSE, eval=FALSE, include=TRUE}
multiple_ind <- tibble::tribble(~ID, ~rail_from, ~rail_to, ~air_from, ~air_to, ~air_via,
                        "Clint", "Bristol Temple Meads", "Paddington", "LHR", "KIS", "NBO",
                        "Zara", "Bristol Temple Meads", "Paddington", "LHR", "LAX", "ORL")
multiple_ind %>%
  dplyr::rowwise() %>%
  dplyr::mutate(plane_emissions = airplane_emissions(air_from,
                                              air_to,
                                              air_via)) %>%
  dplyr::mutate(train_emissions = rail_emissions(rail_from,
                                          rail_to)) %>%
  dplyr::mutate(total_emissions = plane_emissions + train_emissions)
```
```{r, message = FALSE, warning = FALSE, echo = FALSE}
multiple_ind <- tibble::tribble(~ID, ~rail_from, ~rail_to, ~air_from, ~air_to, ~air_via,
                        "Clint", "Bristol Temple Meads", "Paddington", "LHR", "KIS", "NBO",
                        "Zara", "Bristol Temple Meads", "Paddington", "LHR", "LAX", "ORL")
multiple_ind %>%
  dplyr::rowwise() %>%
  dplyr::mutate(plane_emissions = airplane_emissions(air_from,
                                              air_to,
                                              air_via)) %>%
  dplyr::mutate(train_emissions = rail_emissions(rail_from,
                                          rail_to)) %>%
  dplyr::mutate(total_emissions = plane_emissions + train_emissions) %>%
  knitr::kable()
```

Additional emissions can be calculated as well. For example, office emissions, or more advance emissions can be given with other functions, such as the `material_emissions()`, `construction_emissions()`, and `raw_fuels()` functions.

### Operating Theatre Emissions
Upon request, we have introduced the estimation of CO2e emissions specifically for operating theatres. We walk through a small example to demonstrate this function.

To begin, we'll create a dummy data frame of clinical data. The data frame will serve as a representative sample of the information typically found in operating theatres. It could include various parameters such as the anaesthetic type (desflurane, isoflurane), the wet clinical waste in kg, the electricity in kWh, and general waste in kg. 

```{r, message = FALSE, warning = FALSE, eval=FALSE, include=TRUE}
df <- data.frame(time = c("10/04/2000", "10/04/2000", "11/04/2000", "11/04/2000", "12/04/2000", "12/04/2000"),
theatre = rep(c("A", "B"), times = 3),
desflurane = c(30, 0, 25, 0, 28, 0),
isoflurane = c(0, 37, 0, 30, 0, 35),
clinical_waste = c(80, 90, 80, 100, 120, 110),
electricity_kwh = c(100, 110, 90, 100, 100, 110),
general_waste = c(65, 55, 70, 50, 60, 30))
```
```{r, message = FALSE, warning = FALSE, echo=FALSE}
data.frame(time = c("10/04/2000", "10/04/2000", "11/04/2000", "11/04/2000", "12/04/2000", "12/04/2000"),
theatre = rep(c("A", "B"), times = 3),
desflurane = c(30, 28, 25, 0, 0, 0),
isoflurane = c(0, 0, 0, 30, 37, 35),
clinical_waste = c(80, 90, 80, 100, 120, 110),
electricity_kwh = c(100, 110, 90, 100, 100, 110),
general_waste = c(65, 55, 70, 50, 60, 30)) %>%
  knitr::kable()
```

After creating the dummy data frame of clinical data, we can obtain the CO2e emissions and the carbon price index by the `clinical_theatre_data` function. This information can be conveniently presented in a table format:

```{r, message = FALSE, warning = FALSE, eval=FALSE, include=TRUE}
# get emissions and CPI (carbon price index)
clinical_theatre_data(
  df,
  time = time,
  name = theatre,
  wet_clinical_waste = clinical_waste,
  wet_clinical_waste_unit = "kg",
  electricity_kWh = electricity_kwh,
  plastic_vars = c(average = "general_waste"),
  include_cpi = TRUE,
  jurisdiction = "Australia",
  year = 2023,
  value_col = "value_2024",
  strict = TRUE
)
```
```{r, message = FALSE, warning = FALSE, echo=FALSE}
# get emissions and CPI (carbon price index)
df <- data.frame(time = c("10/04/2000", "10/04/2000", "11/04/2000", "11/04/2000", "12/04/2000", "12/04/2000"),
theatre = rep(c("A", "B"), times = 3),
desflurane = c(30, 0, 25, 0, 28, 0),
isoflurane = c(0, 37, 0, 30, 0, 35),
clinical_waste = c(80, 90, 80, 100, 120, 110),
electricity_kwh = c(100, 110, 90, 100, 100, 110),
general_waste = c(65, 55, 70, 50, 60, 30))
results <- clinical_theatre_data(
  df,
  time = time,
  name = theatre,
  wet_clinical_waste = clinical_waste,
  wet_clinical_waste_unit = "kg",
  electricity_kWh = electricity_kwh,
  plastic_vars = c(average = "general_waste"),
  include_cpi = TRUE,
  jurisdiction = "Australia",
  year = 2023,
  value_col = "value_2024",
  strict = TRUE
)

results[[1]] %>% knitr::kable()
```

## Shiny App

An interactive calculator using Shiny can be accessed by the `shiny_emissions()` function. This calculator uses some of the functions in the `carbonr` package: 
```{r, eval = FALSE}
shiny_emissions()
```

## References

#### Other Online Calculators:
- [Carbonfund.org](https://shop.climeco.com/individual/individual-emissions-calculator/)
- [Carbon Footprint Calculator](https://www.carbonfootprint.com/calculatorfaqs.html)

#### Sources
1. UK Government Report: Department for Energy Security and Net Zero. (2024). [Greenhouse Gas Reporting: Conversion Factors 2024](https://www.gov.uk/government/publications/greenhouse-gas-reporting-conversion-factors-2024); UK Government Report: Department for Energy Security and Net Zero. (2025). [Greenhouse Gas Reporting: Conversion Factors 2025](https://www.gov.uk/government/publications/greenhouse-gas-reporting-conversion-factors-2025).

2. Radiative Forcing Factor: DEFRA, 2016. Government GHG conversion factors for company reporting.

3. Clinical Anaesthetic Emissions: Various sources including -

Varughese, S. and Ahmed, R., 2021. Environmental and occupational considerations of anesthesia: a narrative review and update. Anesthesia & Analgesia, 133(4), pp.826-835;

McGain, F., Muret, J., Lawson, C. and Sherman, J.D., 2020. Environmental sustainability in anaesthesia and critical care. British Journal of Anaesthesia, 125(5), pp.680-692;

Wyssusek, K., Chan, K.L., Eames, G. and Whately, Y., 2022. Greenhouse gas reduction in anaesthesia practice: a departmental environmental strategy. BMJ Open Quality, 11(3), p.e001867;

Sherman, J., Le, C., Lamers, V. and Eckelman, M., 2012. Life cycle greenhouse gas emissions of anesthetic drugs. Anesthesia & Analgesia, 114(5), pp.1086-1090.

4. Clinical Wet Waste Emissions: Department of Climate Change, Energy, the Environment and Water. (2022).