---
title: "Examples of {openair} Functionality"
---

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

This vignette outlines some core functionality in `{openair}`. For further examples, please see the [online book](https://bookdown.org/david_carslaw/openair/).

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

# Import data from the UK Automatic Urban and Rural Network

It is easy to import hourly data from 100s of sites and to import several sites at one time and several years of data.

```{r import}
kc1 <- importAURN(site = "kc1", year = 2020)
kc1
```

# Utility functions

Using the `selectByDate()` function it is easy to select quite complex time-based periods. For example, to select weekday (Monday to Friday) data from June to September for 2012 and for the hours 7am to 7pm inclusive:

```{r utility}
sub <- selectByDate(
  kc1,
  day = "weekday",
  year = 2020,
  month = 6:9,
  hour = 7:19
)
sub
```

Similarly it is easy to time-average data in many flexible ways. For example, 2-week means can be calculated as

```{r timeavg}
sub2 <- timeAverage(kc1, avg.time = "2 week")
sub2
```

# The `type` option

One of the key aspects of openair is the use of the `type` option, which is available for almost all `{openair}` functions. The `type` option partitions data by different categories of variable. There are many built-in options that `type` can take based on splitting your data by different date values. A summary of in-built values of type are:

- `"year"` splits data by year

- `"month"` splits variables by month of the year

- `"monthyear"` splits data by year and month

- `"season"` splits variables by season. Note in this case the user can also supply a `hemisphere` option that can be either `"northern"` (default) or `"southern"`

- `"weekday"` splits variables by day of the week

- `"weekend"` splits variables by Saturday, Sunday, weekday

- `"daylight"` splits variables by nighttime/daytime. Note the user must supply a longitude and latitude

- `"dst"` splits variables by daylight saving time and non-daylight saving time

- `"wd"` if wind direction (`wd`) is available. `type = "wd"` will split the data up into 8 sectors: N, NE, E, SE, S, SW, W, NW.

- `"seasonyear"` (or `"yearseason"`) will split the data into year-season intervals, keeping the months of a season together. For example, December 2010 is considered as part of winter 2011 (with January and February 2011). This makes it easier to consider contiguous seasons. In contrast, `type = "season"` will just split the data into four seasons regardless of the year.

`type` can also use variables already in the data frame:

- If a categorical variable is specified, e.g., `site` then that variables can be used directly e.g. `type = "site"`.

- If a numeric numeric variable is specified it is split up into 4 quantiles, i.e., four partitions containing equal numbers of points. Note the user can supply the option `n.levels` to indicate how many quantiles to use.

# Example directional analysis

`{openair}` can plot basic wind roses very easily provided the variables `ws` (wind speed) and `wd` (wind direction) are available.

```{r windrose}
windRose(mydata)
```

However, the real flexibility comes from being able to use the type option.

```{r windrose2}
windRose(mydata,
  type = "year",
  layout = c(4, 2)
)
```

Wind roses summarising the wind conditions at a monitoring station per year, demonstrating the `{openair}` type option.

There are many flavours of bivariate polar plots, as described [here](https://bookdown.org/david_carslaw/openair/sections/directional-analysis/polar-plots.html) that are useful for understanding air pollution sources.

```{r polarplot}
polarPlot(mydata,
  pollutant = "so2",
  statistic = "cpf",
  percentile = 90,
  cols = "YlGnBu"
)
```

