The cf_datatype
function is all that is required to select clifro
datatypes.
This function can be called without any arguments that takes the user through
interactive menus, otherwise the datatypes may be chosen programmatically if the
menu options are known in advance. Whether the intention is to choose one
datatype or many, this vignette details the various methods in choosing them.
Those familiar with the cliflo datatype selection menu
will recall the myriad datatypes and options available in the National Climate
Database. Selection of a datatype requires navigation through trees of menus,
check boxes and combo boxes. The cf_datatype
function mimics this (tedious)
behaviour by default, i.e. when no arguments are passed to the function and the
datatypes, menus and options are all identical to (actually scraped from)
the datatype selection menu.
Let's say the datatype we are interested in is 9am surface wind in knots.
library(clifro) library(pander) surfaceWind.dt = new("cfDatatype" , dt_name = "Wind" , dt_type = "Surface wind" , dt_sel_option_names = list("9amWind") , dt_sel_combo_name = "knots" , dt_param = structure("ls_sfw,1,2,3,4,5", .Names = "dt1") , dt_sel_option_params = list(structure(c("132", "knots"), .Names = c("prm4", "prm5"))) , dt_selected_options = list(c(4, 5)) , dt_option_length = 5 ) menu.opts = function(title, options){ cat(paste(title, "", paste(seq_along(options), options, sep = ": ", collapse = "\n"), sep = "\n")) }
surfaceWind.dt = cf_datatype() # If you prefer pointing and clicking - turn the graphics option on: surfaceWind.dt = cf_datatype(graphics = TRUE)
menu.opts("Daily and Hourly Observations", c("Combined Observations", "Wind", "Precipitation", "Temperature and Humidity", "Sunshine and Radiation", "Weather", "Pressure", "Clouds", "Evaporation / soil moisture"))
The first menu that appears when the above line of code is run in R is the
'Daily and Hourly Observations'. We are interested in 'Wind', therefore we
would type in the number of our selection (or select it using the mouse if
graphics = TRUE
), in this case option 2.
menu.opts("Wind", c("Surface wind", "Max Gust"))
The next menu prompts us for the type of wind we are interested in, in this case we are interested in surface wind which is option 1.
menu.opts("Surface wind options", c("WindRun", "HlyWind", "3HlyWind", "9amWind") )
The next menu is the options for the chosen datatype, for which we may choose more than one. If more than one option for a given datatype is sought, options must be chosen one at a time. This is made possible by a menu prompting whether or not we would like to select another datatype every time an option is chosen.
menu.opts("Choose another option?", c("yes", "no"))
We are interested only in the surface wind at 9am in this example therefore we don't choose another option after we choose option 4.
menu.opts("Units", c("m/s", "km/hr", "knots"))
This final options menu is typically associated with the units of the datatype (although not always) and is sometimes not necessary, depending on the datatype. For this example we do have a final menu and it prompts us for the units that we are interested in where we choose option 3.
The surface wind datatype and the associated options are now saved in R as an
object called surfaceWind.dt
.
surfaceWind.dt
The bold numbers in the minimal example above are emphasised specifically to show the menu order and selections needed to choose the strength of the 9am surface wind in knots datatype, i.e. 2 $\rightarrow$ 1 $\rightarrow$ 4 $\rightarrow$ 3. In general, if we know the selections needed for each of the four menus then we can choose any datatype without using the menus making datatype selection a lot faster and a much less tedious.
To repeat our minimal example without the use of the menus we would just pass
them as arguments to the cf_datatype
function. These arguments are the
selections of each of the four menus (in order) separated by a comma.
surfaceWind.dt = cf_datatype(2, 1, 4, 3) surfaceWind.dt
surfaceWind.dt
Recall that we may choose more than one option at the third menu, equivalent to the check boxes on the cliflo database query form. Using the menu to choose more than one option is an iterative process however we can just update our third function argument to deal with this in a more time-efficient manner.
surfaceWind.dt = new("cfDatatype" , dt_name = "Wind" , dt_type = "Surface wind" , dt_sel_option_names = list(c("HlyWind", "9amWind")) , dt_sel_combo_name = "knots" , dt_param = structure("ls_sfw,1,2,3,4,5", .Names = "dt1") , dt_sel_option_params = list(structure(c("134", "132", "knots"), .Names = c("prm2", "prm4", "prm5"))) , dt_selected_options = list(c(2, 4, 5)) , dt_option_length = 5 ) rainfall.dt = new("cfDatatype" , dt_name = "Precipitation" , dt_type = "Rain (fixed periods)" , dt_sel_option_names = list(c("Daily ", "Hourly")) , dt_sel_combo_name = NA_character_ , dt_param = structure("ls_ra,1,2,3,4", .Names = "dt1") , dt_sel_option_params = list(structure(c("181", "182"), .Names = c("prm1", "prm2"))) , dt_selected_options = list(c(1, 2)) , dt_option_length = 4 ) lightning.dt = new("cfDatatype" , dt_name = "Weather" , dt_type = "Lightning" , dt_sel_option_names = list("Ltng") , dt_sel_combo_name = NA_character_ , dt_param = structure("ls_light,1", .Names = "dt1") , dt_sel_option_params = list(structure("271", .Names = "prm1")) , dt_selected_options = list(1) , dt_option_length = 1 ) temperatureExtremes.dt = new("cfDatatype" , dt_name = "Temperature and Humidity" , dt_type = "Max_min_temp" , dt_sel_option_names = list(c("DlyGrass", "HlyGrass")) , dt_sel_combo_name = NA_character_ , dt_param = structure("ls_mxmn,1,2,3,4,5,6", .Names = "dt1") , dt_sel_option_params = list(structure(c("202", "204"), .Names = c("prm5", "prm6"))) , dt_selected_options = list(c(5, 6)) , dt_option_length = 6 )
surfaceWind.dt = cf_datatype(2, 1, c(2, 4), 3) surfaceWind.dt
surfaceWind.dt
surfaceWind.dt
now contains the surface wind datatype (in knots) with both
9am wind and hourly wind. Notice how all the other function arguments remain the
same.
Most applications involving the environmental data contained within the National
Climate Database will require selection of more than one option for more than
one datatype. This is where the true advantages in using the clifro
package
become apparent.
Let us consider an application where we are now interested in hourly and 9am surface wind along with hourly and daily rainfall, hourly counts of lightning flashes and daily and hourly grass temperature extremes.
There are a few ways to choose all of these datatypes. Firstly, you could go through the menu options one by one, selecting the corresponding datatypes and options and saving the resulting datatypes as different R objects. A less laborious alternative is to create each of these datatypes without the menus. This does of course assume we know the selections at each branch of the datatype selection menus.
# Hourly and 9am surface wind (knots) surfaceWind.dt = cf_datatype(2, 1, c(2, 4), 3) surfaceWind.dt
surfaceWind.dt
# Hourly and daily rainfall rainfall.dt = cf_datatype(3, 1, c(1, 2)) rainfall.dt
rainfall.dt
# Hourly counts of lightning flashes lightning.dt = cf_datatype(6, 1, 1) lightning.dt
lightning.dt
# Daily and hourly grass temperature extremes temperatureExtremes.dt = cf_datatype(4, 2, c(5, 6)) temperatureExtremes.dt # Note: only the surface wind datatype requires combo options
temperatureExtremes.dt
This results in 4 separate objects in R containing the datatypes and their corresponding options. If we were wanting to submit a query using all of these datatypes at once, having four separate datatypes is less than optimal. The following table shows the options for each of the menus that we are interested in.
d = data.frame(Menu = c("First selection", "Second selection", "Third selection(s)", "combo box options"), `Surface wind` = c(2, 1, "2 & 4", 3), Rainfall = c(3, 1, "1 & 2", NA), Lightning = c(6, 1, 1, NA), Temperature = c(4, 2, "5 & 6", NA), check.names = FALSE) pandoc.table(d, style = "simple")
We can read across the columns to see the selections that are needed to return
an R object containing the datatypes we are interested in. We can then just pass
these values into the cf_datatype
function to return a single R object
containing all of our datatypes and options.
query1.dt = new("cfDatatype" , dt_name = c("Wind", "Precipitation", "Weather", "Temperature and Humidity" ) , dt_type = c("Surface wind", "Rain (fixed periods)", "Lightning", "Max_min_temp" ) , dt_sel_option_names = list(c("HlyWind", "9amWind"), c("Daily ", "Hourly"), "Ltng", c("DlyGrass", "HlyGrass")) , dt_sel_combo_name = c("knots", NA, NA, NA) , dt_param = structure(c("ls_sfw,1,2,3,4,5", "ls_ra,6,7,8,9", "ls_light,10", "ls_mxmn,11,12,13,14,15,16"), .Names = c("dt1", "dt2", "dt3", "dt4")) , dt_sel_option_params = list(structure(c("134", "132", "knots"), .Names = c("prm2", "prm4", "prm5")), structure(c("181", "182"), .Names = c("prm6", "prm7" )), structure("271", .Names = "prm10"), structure(c("202", "204" ), .Names = c("prm15", "prm16"))) , dt_selected_options = list(c(2, 4, 5), c(1, 2), 1, c(5, 6)) , dt_option_length = c(5, 4, 1, 6) )
query1.dt = cf_datatype(c(2, 3, 6, 4), c(1, 1, 1, 2), list(c(2, 4), c(1, 2), 1, c(5, 6)), c(3, NA, NA, NA)) query1.dt
query1.dt
We can also easily combine separate cfDatatype
objects in R using the addition
symbol +
, to produce an identical result. This may be useful when you want
to conduct multiple queries which include a subset of these datatypes.
query1.dt = surfaceWind.dt + rainfall.dt + lightning.dt + temperatureExtremes.dt query1.dt
# To add another datatype using the menu: query1.dt + cf_datatype() # Is equivalent to: query1.dt + cf_datatype(NA, NA, NA, NA) # Therefore is equivalent to adding a column of NA's to the above table: query1.dt = cf_datatype(c(2, 3, 6, 4, NA), c(1, 1, 1, 2, NA), list(c(2, 4), c(1, 2), 1, c(5, 6), NA), c(3, NA, NA, NA, NA)) # Half an unknown wind datatype i.e. we know first selection = 2 but nothing # further: rain.dt = cf_datatype(2) # Or cf_datatype(2, NA, NA, NA)
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.