Choosing clifro stations is made easy with the single cf_find_station
function. This function is all that is required to find clifro stations. This
function is equivalent to conducting the same search on the
find stations page when
conducting a query online at CliFlo, except without some of the errors and bugs.
This means that the searches and the types of searches possible are exactly the
same however, clifro extends functionality to exploring the spatial nature of
stations via KML files that can be opened by Google Earth™, or plotting
directly in R. This is the main advantage in searching for stations using
clifro as locating suitable stations on a map is generally the preferred
search tool.
There are four possible types of searches:
For each of these searches either all, open or closed stations may be returned
and these searches also may only return stations where given datatypes are
available. The primary goal in searching for stations is to find the
unique station agent number required to create a cfStation object. This
vignette details the various search options in clifro and ways to find these
requisite agent numbers, primarily by way of example.
The following examples detail how to use the cf_find_station search function
ignoring any datatypes.
Both of these searches use pattern matching to find the appropriate stations. The station name search is useful for searching stations in certain towns or suburbs or maybe even streets and parks. The network ID is a number that is assigned to the stations which makes this search useful to look up stations where these are known.
These searches are used when part or all of the station name or netword ID is
known. For example, consider we are looking for open stations located in Takaka,
at the southeastern end of Golden Bay at the northern end of the South Island,
New Zealand. The default for the cf_find_station function is to search open
station names matching the string.
At the time of writing this, CliFlo ignores the status argument in the name and
network ID search whereas clifro does not. Searching open stations with the
station name matching “takaka” on CliFlo will return these stations.
# Equivalent to searching for status = "open" on CliFro
# Note the search string is not case sensitive
cf_find_station("takaka", status = "all")
## name network agent start end open distance lat lon
## 1) Takaka, Kotinga Road F02882 3788 1970-08-01 2015-03-01 TRUE 0 -40.87200 172.8090
## 2) Takaka Pohara F02884 3790 1986-07-01 2015-03-01 TRUE 0 -40.84500 172.8670
## 3) Upper Takaka 2 F12083 11519 1995-07-12 2015-03-01 TRUE 0 -41.01516 172.8258
## 4) Takaka Ews F02885 23849 2002-04-30 2015-03-01 TRUE 0 -40.86364 172.8057
## 5) Takaka, Kotinga 2 F02883 3789 1985-11-30 2012-07-01 FALSE 0 -40.88200 172.8010
## 6) Upper Takaka F12082 7316 1991-10-31 1992-10-31 FALSE 0 -41.05100 172.8330
## 7) Takaka,Patons Rock F02772 3779 1969-10-01 1975-01-01 FALSE 0 -40.78900 172.7570
## 8) Takaka,Kotinga 1 F02971 3794 1961-12-01 1971-08-01 FALSE 0 -40.90000 172.7750
## 9) Takaka Aero F02871 3785 1936-11-01 1970-04-01 FALSE 0 -40.81600 172.7720
## 10) Takaka Hill F12081 3833 1947-09-01 1959-11-01 FALSE 0 -41.01700 172.8670
## 11) Takaka,Bu Bu F02872 3786 1933-04-01 1945-11-30 FALSE 0 -40.85000 172.7330
## 12) Takaka F02881 3787 1904-01-01 1927-10-01 FALSE 0 -40.81700 172.8000
This shows that 8 of these 12 stations are closed. The search in clifro does
not ignore the station status.
cf_find_station("takaka", status = "open")
## name network agent start end open distance lat lon
## 1) Takaka, Kotinga Road F02882 3788 1970-08-01 2015-03-01 TRUE 0 -40.87200 172.8090
## 2) Takaka Pohara F02884 3790 1986-07-01 2015-03-01 TRUE 0 -40.84500 172.8670
## 3) Upper Takaka 2 F12083 11519 1995-07-12 2015-03-01 TRUE 0 -41.01516 172.8258
## 4) Takaka Ews F02885 23849 2002-04-30 2015-03-01 TRUE 0 -40.86364 172.8057
Stations are considered open in clifro if the final date returned from the
search is within four weeks of the current date. This gives the user a better
idea on the stations that are currently collecting data.
The same can be done for searching stations using network ID although
search = "network" needs to be added to the function call. Assume we knew
that the only stations we were interested in were the open stations whose
network ID's match F028.
cf_find_station("f028", search = "network", status = "all")
## name network agent start end open distance lat lon
## 1) Takaka, Kotinga Road F02882 3788 1970-08-01 2015-03-01 TRUE 0 -40.87200 172.8090
## 2) Takaka Pohara F02884 3790 1986-07-01 2015-03-01 TRUE 0 -40.84500 172.8670
## 3) Takaka Ews F02885 23849 2002-04-30 2015-03-01 TRUE 0 -40.86364 172.8057
## 4) Takaka, Kotinga 2 F02883 3789 1985-11-30 2012-07-01 FALSE 0 -40.88200 172.8010
## 5) Nelson,Mckay Hut F02821 3780 1983-04-01 1993-08-16 FALSE 0 -40.89000 172.2130
## 6) Gouland Downs F02831 3781 1984-10-31 1993-08-16 FALSE 0 -40.89200 172.3510
## 7) Golden Bay,Table Hl I F02852 3783 1977-06-01 1991-11-23 FALSE 0 -40.80700 172.5560
## 8) Golden Bay,Table Hl 2 F02853 3784 1977-06-01 1991-11-23 FALSE 0 -40.80700 172.5560
## 9) Tarakohe F02891 3791 1932-05-01 1989-01-01 FALSE 0 -40.82500 172.8980
## 10) Takaka Aero F02871 3785 1936-11-01 1970-04-01 FALSE 0 -40.81600 172.7720
## 11) Totaranui F02892 3792 1957-01-01 1960-08-31 FALSE 0 -40.82300 173.0020
## 12) Takaka,Bu Bu F02872 3786 1933-04-01 1945-11-30 FALSE 0 -40.85000 172.7330
## 13) Takaka F02881 3787 1904-01-01 1927-10-01 FALSE 0 -40.81700 172.8000
## 14) Quartz Ranges F02851 3782 1901-01-01 1902-08-31 FALSE 0 -40.86700 172.5170
Notice that the resulting dataframes in all of these searches are first ordered by the date they last received data then by the date they opened to give the longest-running open stations first and the most historic, closed stations last.
This broad search returns all, open or closed stations within one of the 29
preselected New Zealand regions (note that stations can belong to more than
one region). The search = "region" argument must be
added to the cf_find_station function to conduct these searches. If the region
is unknown then the search argument may be missing which brings up an
interactive menu of the 29 regions for the user to select
(cf_find_station(search = "region")), otherwise partial matching is used.
# Partial match for the Queenstown region
open.queenstown.stations = cf_find_station("queen", search = "region")
Typing open.queenstown.stations into R will then return all the
220 open Queenstown stations. This
is clearly a burden to choose stations based on a large list of numbers hence
plotting them on a map (covered below) to assess their spatial extent will make
this task much easier.
Conducting this same search on CliFlo returns 476 stations where some of these
'open' stations haven't had any data input since November 2001.
If these stations are of interest then add the status = "all" argument
to the cf_find_station function call.
This location based search is conducted by including the
search = "latlong" argument to the cf_find_station function. There are
three parameters needed for this search; latitude, longitude and radius
(kilometres). Just like any other function in R, if these arguments aren't
named then the order matters and should be written in the order specified above.
The latitude and longitude must be given in decimal degrees.
We are (still) interested in finding all open stations around the small town of Takaka. From GeoHack we can see that the latitude is -40.85 and the longitude is 172.8. We are interested in all open stations within a 10km radius of the main township.
takaka.town.st = cf_find_station(lat = -40.85, long = 172.8, rad = 10, search = "latlong")
takaka.town.st[, -c(8, 9)]
## name network agent start end open distance
## 1 Takaka, Kotinga Road F02882 3788 1970-08-01 2015-03-01 TRUE 2.6
## 2 Takaka Pohara F02884 3790 1986-07-01 2015-03-01 TRUE 5.7
## 3 Takaka Ews F02885 23849 2002-04-30 2015-03-01 TRUE 1.6
# We may rather order the stations by distance from the township
takaka.town.st[order(takaka.town.st$distance), -c(8, 9)]
## name network agent start end open distance
## 3 Takaka Ews F02885 23849 2002-04-30 2015-03-01 TRUE 1.6
## 1 Takaka, Kotinga Road F02882 3788 1970-08-01 2015-03-01 TRUE 2.6
## 2 Takaka Pohara F02884 3790 1986-07-01 2015-03-01 TRUE 5.7
All the above searches did not include a datatype therefore they ignore the datatypes available at these stations. Imagine we are looking for hourly rain data at an open station in Takaka (using any of the aforementioned searches), we would need to include the hourly rain datatype in the search for it to return a suitable station.
Unless the Reefton EWS station is the only CliFlo station of interest, the user will need a CliFlo account to get data from other stations.
# Create a clifro datatype for hourly rain
hourly.rain.dt = cf_datatype(3, 1, 2)
hourly.rain.dt
## dt.name dt.type dt.options dt.combo
## dt1 Precipitation Rain (fixed periods) [Hourly]
# Conduct the search
cf_find_station("takaka", datatype = hourly.rain.dt)
## name network agent start end open distance lat lon
## 1) Takaka Ews F02885 23849 2002-06-02 2015-01-30 TRUE 0 -40.86364 172.8057
This tells us that the only open station in Takaka where hourly rain data is available is at the Takaka Ews station.
Since the cf_find_station function returns cfStation objects, any of these
methods work on objects created from the cf_station function (see the
working with clifro stations vignette for more details). We can
conduct two or more seaches at a time using the addition sign, just like we did
for cfDatatypes (see the choose datatypes vignette).
We would like to return all open stations within a 10km radius of the Takaka township in the South Island, and the open stations in Kaitaia, in the North Island that collect hourly rain data.
my.composite.search = takaka.town.st + cf_find_station("kaitaia",
search = "region",
datatype = hourly.rain.dt)
my.composite.search
## name network agent start end open
## 1) Kaitaia Aero Ews A53026 18183 2000-06-15 2015-03-03 TRUE
## 2) Trounson Cws A53762 37131 2009-06-04 2015-03-03 TRUE
## 3) Kaikohe Aws A53487 1134 1985-11-14 2015-03-02 TRUE
## 4) Purerua Aws A54101 1196 1995-01-01 2015-03-02 TRUE
## 5) Cape Reinga Aws A42462 1002 1995-01-01 2015-03-02 TRUE
## 6) Kerikeri Aerodrome Aws A53295 37258 2008-06-26 2015-03-02 TRUE
## 7) Takaka, Kotinga Road F02882 3788 1970-08-01 2015-03-01 TRUE
## 8) Takaka Pohara F02884 3790 1986-07-01 2015-03-01 TRUE
## 9) Takaka Ews F02885 23849 2002-04-30 2015-03-01 TRUE
## 10) Kaitaia Ews A53127 17067 1998-12-17 2015-02-25 TRUE
## 11) Kerikeri Ews A53191 1056 2002-06-28 2015-02-14 TRUE
## 12) Dargaville 2 Ews A53987 25119 2003-10-30 2015-02-13 TRUE
## distance lat lon
## 1) 0.0 -35.06770 173.2874
## 2) 0.0 -35.72035 173.6515
## 3) 0.0 -35.42400 173.8220
## 4) 0.0 -35.12900 174.0150
## 5) 0.0 -34.43200 172.6820
## 6) 0.0 -35.26200 173.9110
## 7) 2.6 -40.87200 172.8090
## 8) 5.7 -40.84500 172.8670
## 9) 1.6 -40.86364 172.8057
## 10) 0.0 -35.13500 173.2620
## 11) 0.0 -35.18300 173.9260
## 12) 0.0 -35.93145 173.8532
# How long have these stations been open for?
transform(my.composite.search, ndays = round(end - start))[, c(1, 10)]
## name ndays
## 1 Kaitaia Aero Ews 5374 days
## 2 Trounson Cws 2098 days
## 3 Kaikohe Aws 10700 days
## 4 Purerua Aws 7365 days
## 5 Cape Reinga Aws 7365 days
## 6 Kerikeri Aerodrome Aws 2440 days
## 7 Takaka, Kotinga Road 16283 days
## 8 Takaka Pohara 10470 days
## 9 Takaka Ews 4688 days
## 10 Kaitaia Ews 5914 days
## 11 Kerikeri Ews 4614 days
## 12 Dargaville 2 Ews 4124 days
Up until now there probably hasn't been any good reason to choose clifro to search for stations instead of the 'Choose Stations' form on CliFlo. However, the real advantage of using clifro is to visualise the station locations on a map by returning a KML file, particularly when there are lots of stations returned by the search. This Keyhole Markup Language (KML) is an XML-based language provided by Google™ for defining the graphic display of spatial data in applications such as Google Earth™ and Google Maps™.
To return the stations as a KML file simply use the cf_save_kml function on
any cfStation object. The cf_find_station function returns cfStation
objects therefore it's very easy to plot these on a map. To assess the
geographic extent of the Auckland stations we can return a KML file from the
search and open it using our preferred KML-friendly software.
# First, search for the stations
all.auckland.st = cf_find_station("auckland", search = "region", status = "all")
Now all.auckland.st contains all the 522
Auckland stations where data have been recorded on CliFlo.
# Then save these as a KML
cf_save_kml(all.auckland.st, file_name = "all_auckland_stations")
The green markers represent the open stations and the red markers indicate
closed stations. The resulting KML file is saved to the current R session's
working directory by default. Have a look at the
clifro station vignette for more methods and plotting of
cfStation objects.
Note on the left of the map, the cf_save_kml function has organised the
stations into 'open' and 'closed' stations so removing all the open/closed
stations is easily done.