README.md

In lhmet-forks/ecmwfr: Interface to the public 'ECMWF' Web Services

ecmwfr

Programmatic interface to the 'ECMWF' web API services. Allows for easy downloads of ECMWF public data.

Installation

To install the toolbox in R run the following commands in a R terminal

if(!require(devtools)){install.packages(devtools)}
devtools::install_github("khufkens/ecmwfr")
library("ecmwfr")

Create a ECMWF account by self registering and retrieving your key at https://api.ecmwf.int/v1/key/ after you log in. The key is a long series of numbers and characters (X in the example below).

{
    "url"   : "https://api.ecmwf.int/v1",
    "key"   : "XXXXXXXXXXXXXXXXXXXXXX",
    "email" : "[e-mail]"
}

Use

Setup

Before starting save the provided key to your local keychain. The package does not allow you to use your key inline in scripts to limit security issues when sharing scripts on github or otherwise.

# set a key to the keychain
wf_set_key(email = "[e-mail]", key = "XXXXXXXXXXXXXXXXXXXXXX")

# you can retrieve the key using
wf_get_key(email = "[e-mail]")

# the output should be the key you provided
# "XXXXXXXXXXXXXXXXXXXXXX"

Data Requests

To download data use the wf_request() function, together with your email and a request string syntax as documented. Instead of json formatting the function uses a simple R list for all the arguments.

# this is an example of a request
my_request <- list(stream = "oper",
                  levtype = "sfc",
                  param = "165.128/166.128/167.128",
                  dataset = "interim",
                  step = "0",
                  grid = "0.75/0.75",
                  time = "00/06/12/18",
                  date = "2014-07-01/to/2014-07-31",
                  type = "an",
                  class = "ei",
                  area = "73.5/-27/33/45",
                  format = "netcdf",
                  target = "tmp.nc")

# an example download using fw_request()
# using the above request list()
# 
# data will be transferred to disk
# and saved in your home directory (~)
# set by the path argument

wf_request(
  email = "[e-mail]",
  transfer = TRUE,
  path = "~",
  request = my_request)

This operation might take a while. A progress indicator will keep you informed on the status of your request. Keep in mind that all data downloaded will be buffered in memory limiting the downloads to ~6GB on low end systems.

Acknowledgements

This project was in part supported by the Belgian Science Policy office COBECORE project (BELSPO; grant BR/175/A3/COBECORE) and a "Fonds voor Wetenschappelijk Onderzoek" travel grant (FWO; V438318N).

lhmet-forks/ecmwfr documentation built on April 21, 2020, 1:24 a.m.