clifro (version 3.2-5)

cf_query: Retrieve Data from the National Climate Database

Description

Query the National Climate Database via CliFlo based on the clifro user and selected datatypes, stations and dates.

Usage

cf_query(
  user,
  datatype,
  station,
  start_date,
  end_date = now(tz),
  date_format = "ymd_h",
  tz = "Pacific/Auckland",
  output_tz = c("local", "NZST", "UTC"),
  quiet = FALSE
)

Arguments

user

a cfUser object.

datatype

a cfDatatype object containing the datatypes to be retrieved.

station

a cfStation object containing the stations where the datatypes will be retrieved from.

start_date

a character, Date or POSIXt object indicating the start date. If a character string is supplied the date format should be in the form yyyy-mm-dd-hh unless date_format is specified.

end_date

same as start_date. Defaults to now.

date_format

a character string matching one of "ymd_h", "mdy_h", "ydm_h" or "dmy_h" representing the lubridate-package date parsing function.

tz

the timezone for which the start and end dates refer to. Conversion to Pacific/Auckland time is done automatically through the with_tz function. Defaults to "Pacific/Auckland".

output_tz

the timezone of the output. This can be one of either "local", "UTC", or "NZST".

quiet

logical. When TRUE the function evaluates without displaying customary messages. Messages from CliFlo are still displayed.

Value

a cfData or cfDataList object.

CfData Subclasses

There are 8 cfData subclasses that are returned from cf_query depending on the datatype requested. Each of these subclasses have default plot methods for usability and efficiency in exploring and plotting clifro data.

The following table summarises these subclasses and how they are created, see also the examples on how to automatically create some of these subclasses.

Subclass	CliFlo Datatype
cfWind	Any 'Wind' data
cfRain	Any 'Precipitation' data
cfScreen Obs	'Temperature and Humidity' data measured in a standard screen
cfTemp	Maximum and minimum 'Temperature and Humidity' data
cfEarthTemp	'Temperature and Humidity' data at a given depth
cfSunshine	Any 'Sunshine & Radiation' data
cfPressure	Any 'Pressure' data
cfOther	Any other CliFlo 'Daily and Hourly Observations'

Details

The cf_query function is used to combine the clifro user (cfUser), along with the desired datatypes (cfDatatype) and stations (cfStation). The query is 'built up' using these objects, along with the necessary dates. The function then uses all these data to query the National Climate Database via the CliFlo web portal and returns one of the many cfData objects if one dataframe is returned, or a cfDataList object if there is more than one dataframe returned from CliFlo. If a cfDataList is returned, each element in the list is a subclass of the cfData class, see the 'cfData Subclasses' section.

See Also

cf_user, cf_datatype and cf_station for creating the objects needed for a query. See plot,cfDataList,missing-method for general information on default plotting of cfData and cfDataList objects, and the links within.

Examples

# NOT RUN {
# Retrieve daily rain data from Reefton Ews
daily.rain = cf_query(cf_user("public"), cf_datatype(3, 1, 1),
                      cf_station(), "2012-01-01 00")
daily.rain

# returns a cfData object as there is only one datatype
class(daily.rain) # 'cfRain' object - inherits 'cfData'

# Look up the help page for cfRain plot methods
?plot.cfRain

# Retrieve daily rain and wind data from Reefton Ews

daily.dts = cf_query(cf_user("public"),
                     cf_datatype(c(2, 3), c(1, 1), list(4, 1), c(1, NA)),
                     cf_station(), "2012-01-01 00", "2013-01-01 00")
daily.dts

# returns a cfDataList object as there is more than one datatype. Each
# element of the cfDataList is an object inheriting from the cfData class.
class(daily.dts)     # cfDataList
class(daily.dts[1])  # cfRain
class(daily.dts[2])  # cfWind

# Create a cfSunshine object (inherits cfData)
# Retrieve daily global radiation data at Reefton Ews
rad.data = cf_query(cf_user(), cf_datatype(5,2,1), cf_station(),
                    "2012-01-01 00")
rad.data

# The cf_query function automatically creates the appropriate cfData subclass
class(rad.data)

# The advantage of having these subclasses is that it makes plotting very easy
plot(rad.data)
plot(daily.rain)
plot(daily.rain, include_runoff = FALSE)
plot(daily.dts)
plot(daily.dts, 2)
# }