---
title: "Working with *clifro* Stations"
author: "Blake Seers"
date: "`r Sys.Date()`"
output: 
  rmarkdown::html_vignette:
    fig_width: 5
    fig_height: 5
vignette: >
  %\VignetteIndexEntry{Working with clifro stations}
  %\VignetteEngine{knitr::rmarkdown}
  \usepackage[utf8]{inputenc}
---

```{r, echo = FALSE}
library(clifro)
```
# Introduction

There are two functions available in `clifro` to create requisite `cfStation`
objects to send queries to retrieve data via `clifro`. The first one is to 
search for stations using the `cf_find_station` function as detailed in the 
[choose stations vignette][chooseStations]. The other function that creates
`cfStation` objects is the `cf_station` function that requires comma separated 
agent numbers as the only input. This vignette covers the construction of a 
`cfStation`  object via the `cf_station` function, and then shows examples of 
plotting and visualising the station's locations using KML files or within R
using the [ggmap](https://cran.r-project.org/package=ggmap)
package.

# Creating a cfStation object from agent numbers

This is the simplest method to create a `cfStation` object, simply supply the 
`cf_station` function the comma separated agent numbers. The following stations 
are (or were) located around Lake Tekapo in Canterbury, in the South Island of 
New Zealand:

1. Coal (Ski Field)
1. Macaulay (Mt Gerald)
1. South Opua
1. Mount John
1. Lake Tekapo Ews
1. Godley Peaks
1. Lilybank

```{r, eval = FALSE}
lake.tekapo.st = cf_station(12709, 35567, 39557, 4630, 24945, 4616, 4602)
lake.tekapo.st[, c("name", "agent", "start", "end", "open")]
```

```
##                      name agent      start        end  open
## 1         Coal @ Skifield 12709 1989-02-01 2018-07-26  TRUE
## 2      Macaulay@Mt Gerald 35567 1990-07-04 2018-07-26  TRUE
## 3         Lake Tekapo Ews 24945 2003-06-18 2018-07-26  TRUE
## 4 South Opua @ South Opua 39557 2011-09-28 2018-07-26  TRUE
## 5        Lilybank Station  4602 1950-01-01 1992-09-30 FALSE
## 6                 Mt John  4630 1962-10-01 1988-01-01 FALSE
## 7    Godley Peaks, Tekapo  4616 1914-01-01 1976-06-01 FALSE
```

We can see that subsetting `lake.tekapo.st` acts just like a `data.frame` 
object, although it is technically a `cfStation` object. All the usual 
`data.frame` methods work on `cfStation` objects to maximise usability.

## Adding more stations
To add more stations to this list the addition sign is used. Any repeated 
stations are removed and the resulting list is ordered by the end dates first 
and then by the stations' start dates.

```{r, eval = FALSE}
added.stations.st = lake.tekapo.st + 
  cf_station() + 
  cf_find_station("lighthouse", status = "all")
added.stations.st[, c("name", "agent", "start", "end", "open")]
```

```
##                       name agent      start        end  open
## 1              Reefton Ews  3925 1960-08-01 2018-07-26  TRUE
## 2          Coal @ Skifield 12709 1989-02-01 2018-07-26  TRUE
## 3       Macaulay@Mt Gerald 35567 1990-07-04 2018-07-26  TRUE
## 4          Lake Tekapo Ews 24945 2003-06-18 2018-07-26  TRUE
## 5  South Opua @ South Opua 39557 2011-09-28 2018-07-26  TRUE
## 6     Tiri Tiri Lighthouse  1401 1946-02-01 2018-07-25  TRUE
## 7  Kapoaiaia At Lighthouse 42673 1998-05-17 2018-07-25  TRUE
## 8         Lilybank Station  4602 1950-01-01 1992-09-30 FALSE
## 9                  Mt John  4630 1962-10-01 1988-01-01 FALSE
## 10   Cape Brett Lighthouse  1197 1934-11-01 1978-10-01 FALSE
## 11     Nugget Lighthouse B  5894 1975-03-01 1977-08-31 FALSE
## 12     Nugget Lighthouse A  5895 1975-03-01 1977-08-31 FALSE
## 13    Godley Peaks, Tekapo  4616 1914-01-01 1976-06-01 FALSE
## 14      Moeraki Lighthouse  5325 1935-10-01 1975-06-01 FALSE
```

The above code chunk adds the 7 stations around Lake Tekapo, the 
subscription-free reefton EWS station (`cf_station()`), and all stations located 
(currently or historically) on a lighthouse. Allowing multiple searches is not
currently available using the web portal, CliFlo, but the above code 
demonstrates how easy it can be in `clifro`.

# Visualising the station locations
CliFlo does not currently have any visualisation tools to aid in the selection 
of stations which can make the task of choosing geographically suitable stations
a hard one.

## Using KML files
The `cf_save_kml` functionality was introduced in the 
[choose stations vignette][chooseStations] and this function can be used on any 
`cfStation` object. To return a KML file showing all the stations within our
`added.stations.st` object we just run `cf_save_kml(added.stations.st)` in R
and the KML file is returned.

## Showing station locations within R
Many useRs may prefer to plot the locations directly in R, or 
export the station information for use in another software. The 
`as(object, "data.frame")` function call is used for returning the station 
information as an R dataframe that can then be used for plotting or exporting.

This example is only one of the many ways to plot GIS data in R, and the 
[ggmap](https://cran.r-project.org/package=ggmap)
package is chosen for it's usability and quality plots. In this example we will 
plot all the past and present Auckland climate stations to assess the density 
of open and closed stations across the region.

```{r, echo = FALSE}
auckland.df = dget(system.file("extdata", "auckStations", package = "clifro"))
auckland.st = new("cfStation", auckland.df)
```

```{r, eval = FALSE}
# Conduct the search
auckland.st = cf_find_station("auckland", search = "region", status = "all")
```

```{r, eval = FALSE}
library(ggmap)

# Add a column to colour the open and closed stations
auckland.st$colour = factor(auckland.st$open, labels = c("Closed", "Open"))

# Coerce to a data.frame and reverse the rows so the open stations get plotted 
# on top of the closed stations
auckland.df = as(auckland.st, "data.frame")[nrow(auckland.st):1, ]

# Obtain the map of the greater Auckland suitably scaled to fit the stations
auckland.map = ggmap(get_map("Auckland", maptype = "hybrid", zoom = 8))

# Plot the resulting map with the stations and station density
auckland.map %+% auckland.df + 
  stat_density2d(aes(colour = colour), alpha = .8) +
  geom_point(aes(colour = colour), alpha = .5) +
  scale_colour_discrete("Status", c("Closed", "Open")) +
  theme(legend.title = element_text(face = "bold"))
```

![Density of open and closed climate stations in the greater Auckland region.](figures/ggmap.png)

Remembering that closed stations in clifro are the ones that have end dates 
over four weeks ago. It appears that the open stations are reasonably confined 
to the city centre, whereas the more historic stations were placed further out
in the rural areas.

[chooseStations]: choose-station.html
