rnoaa v0.2.0

0

Monthly downloads

0th

Percentile

by Edmund Hart

NOAA climate data from R.

This is an R wrapper to many NOAA APIs including the NCDC climate API at http://www.ncdc.noaa.gov/cdo-web/webservices/v2. There are functions for each of the API endpoints: data, data categories, data sets, data types, locations, location categories, and stations. In addition, we have an interface for NOAA sea ice data that is not part of the climate data API, the NOAA severe weather inventory, and ERDDAP data. NOAA buoy data is only on the buoy branch in the Github repository for this package (see url below).

Readme

rnoaa

Build Status

IMPORTANT - BUOY DATA

NOAA buoy data requires an R pacakage ncdf4 that is difficult to use on Windows. Therefore, we have moved functions for working with buoy data into a separate branch called buoy, and the CRAN version does not include buoy functions. Thus, if you're on a Linux machine or on OSX you should be able to use the buoy branch just fine after installing the netcdf as:

OSX

brew install netcdf

Linux (Ubuntu)

sudo apt-get install netcdf*

Then rnoaa with the buoy functions should install and load correctly. See this stackoverflow post and this blog post for more Linux/OSX netcdf installation help.

Help

There is a tutorial on the rOpenSci website, and there are many tutorials in the package itself, available in your R session, or on CRAN. The tutorials:

  • NOAA Buoy vignette
  • NOAA ERDDAP vignette
  • NOAA NCDC vignette (examples)
  • NOAA NCDC attributes vignette
  • NOAA NCDC workflow vignette
  • Sea ice vignette
  • Severe Weather Data Inventory vignette

Data sources used in rnoaa

The majority of functions in this package work with NOAA NCDC data.

NOAA NCDC Datasets

There are many NOAA NCDC datasets. Each is available throughout most functions in this package by using the datasetid parameter, except NEXRAD2 and NEXRAD3, which don't work.

Dataset Description Start date End date
ANNUAL Annual Summaries 1831-02-01 2013-11-01
GHCND Daily Summaries 1763-01-01 2014-03-15
GHCNDMS Monthly Summaries 1763-01-01 2014-01-01
NORMAL_ANN Normals Annual/Seasonal 2010-01-01 2010-01-01
NORMAL_DLY Normals Daily 2010-01-01 2010-12-31
NORMAL_HLY Normals Hourly 2010-01-01 2010-12-31
NORMAL_MLY Normals Monthly 2010-01-01 2010-12-01
PRECIP_15 Precipitation 15 Minute 1970-05-12 2013-03-01
PRECIP_HLY Precipitation Hourly 1900-01-01 2013-03-01
NEXRAD2 Nexrad Level II 1991-06-05 2014-03-14
NEXRAD3 Nexrad Level III 1994-05-20 2014-03-11

NOAA NCDC Attributes

Each NOAA dataset has a different set of attributes that you can potentially get back in your search. See the NOAA docs for detailed info on each dataset. We provide some information on the attributes in this package; see the vignette for attributes to find out more

Authentication

You'll need an API key to use the NOAA NCDC functions (those starting with noaa*) in this package (essentially a password). Go here to get one. You can't use this package without an API key.

Once you obtain a key, there are two ways to use it.

a) Pass it inline with each function call (somewhat cumbersome)

ncdc(datasetid = 'PRECIP_HLY', locationid = 'ZIP:28801', datatypeid = 'HPCP', limit = 5, token =  "YOUR_TOKEN")

b) Alternatively, you might find it easier to set this as an option, either by adding this line to the top of a script or somewhere in your .rprofile

options(noaakey = "KEY_EMAILED_TO_YOU")

c) You can always store in permamently in your .Rprofile file.

Installation

Stable version from CRAN

install.packages("rnoaa")

or development version from GitHub

install.packages("devtools")
devtools::install_github("rnoaa", "ropensci")
library('rnoaa')

or version with buoy functions on Github

install.packages("devtools")
devtools::install_github("rnoaa", "ropensci", ref="buoy")
library('rnoaa')

Quick start

Fetch list of city locations in descending order

ncdc_locs(locationcategoryid='CITY', sortfield='name', sortorder='desc')
$atts
$atts$totalCount
[1] 1654

$atts$pageCount
[1] 25

$atts$offset
[1] 1


$data
              id                  name datacoverage    mindate    maxdate
1  CITY:NL000012            Zwolle, NL       1.0000 1892-08-01 2013-08-31
2  CITY:SZ000007            Zurich, SZ       1.0000 1901-01-01 2013-11-17
3  CITY:NG000004            Zinder, NG       0.8678 1906-01-01 1980-12-31
4  CITY:UP000025         Zhytomyra, UP       0.9725 1938-01-01 2013-11-17
5  CITY:KZ000017        Zhezkazgan, KZ       0.9275 1948-03-01 2013-11-17
6  CITY:CH000045         Zhengzhou, CH       1.0000 1951-01-01 2013-11-17
7  CITY:SP000021          Zaragoza, SP       1.0000 1941-01-01 2012-08-31
8  CITY:UP000024      Zaporiyhzhya, UP       0.9739 1936-01-01 2009-06-16
9  CITY:US390029     Zanesville, OH US       1.0000 1893-01-01 2013-11-19
10 CITY:LE000004             Zahle, LE       0.7811 1912-01-01 1971-12-31
11 CITY:IR000019           Zahedan, IR       0.9930 1951-01-01 2010-05-19
12 CITY:HR000002            Zagreb, HR       1.0000 1860-12-01 2008-12-31
13 CITY:RS000081 Yuzhno-Sakhalinsk, RS       1.0000 1947-01-01 2013-11-15
14 CITY:US040015           Yuma, AZ US       1.0000 1893-01-01 2013-11-19
15 CITY:US060048   Yucca Valley, CA US       1.0000 1942-02-01 2013-11-19
16 CITY:US060047      Yuba City, CA US       1.0000 1893-01-01 2013-11-19
17 CITY:US390028     Youngstown, OH US       1.0000 1893-01-01 2013-11-19
18 CITY:US420024           York, PA US       1.0000 1941-01-01 2013-11-19
19 CITY:US360031        Yonkers, NY US       1.0000 1876-01-01 2013-11-19
20 CITY:JA000017          Yokohama, JA       1.0000 1949-01-01 2013-11-17
21 CITY:CH000044          Yinchuan, CH       1.0000 1951-01-01 2013-11-17
22 CITY:AM000001           Yerevan, AM       0.9751 1885-06-01 2006-12-31
23 CITY:US280020     Yazoo City, MS US       1.0000 1948-01-01 2013-11-19
24 CITY:RS000080         Yaroslavl, RS       0.9850 1959-07-01 1987-05-20
25 CITY:US460009        Yankton, SD US       1.0000 1932-01-01 2013-11-19

attr(,"class")
[1] "ncdc_locs"

Get info on a station by specifcying a dataset, locationtype, location, and station

ncdc_stations(datasetid='GHCND', locationid='FIPS:12017', stationid='GHCND:USC00084289')
                 id                  name datacoverage    mindate    maxdate
1 GHCND:USC00084289 INVERNESS 3 SE, FL US            1 1899-02-01 2013-11-17

Search for data

out <- ncdc(datasetid='NORMAL_DLY', stationid='GHCND:USW00014895', datatypeid='dly-tmax-normal', startdate = '2010-05-01', enddate = '2010-05-10')
See a data.frame
head( out$data )
             station value        datatype                date fl_c
1  GHCND:USW00014895   652 DLY-TMAX-NORMAL 2010-05-01T00:00:00    S
2  GHCND:USW00014895   655 DLY-TMAX-NORMAL 2010-05-02T00:00:00    S
3  GHCND:USW00014895   658 DLY-TMAX-NORMAL 2010-05-03T00:00:00    S
4  GHCND:USW00014895   661 DLY-TMAX-NORMAL 2010-05-04T00:00:00    S
5  GHCND:USW00014895   663 DLY-TMAX-NORMAL 2010-05-05T00:00:00    S
6  GHCND:USW00014895   666 DLY-TMAX-NORMAL 2010-05-06T00:00:00    S

Plot data, super simple, but it's a start

out <- ncdc(datasetid='GHCND', stationid='GHCND:USW00014895', datatypeid='PRCP', startdate = '2010-05-01', enddate = '2010-10-31', limit=500)
ncdc_plot(out, breaks="1 month", dateformat="%d/%m")

More plotting

You can pass many outputs from calls to the noaa function in to the ncdc_plot function.

out1 <- ncdc(datasetid='GHCND', stationid='GHCND:USW00014895', datatypeid='PRCP', startdate = '2010-03-01', enddate = '2010-05-31', limit=500)
out2 <- ncdc(datasetid='GHCND', stationid='GHCND:USW00014895', datatypeid='PRCP', startdate = '2010-09-01', enddate = '2010-10-31', limit=500)
ncdc_plot(out1, out2, breaks="45 days")

Get table of all datasets

ncdc_datasets()
$meta
$meta$limit
[1] 25

$meta$count
[1] 11

$meta$offset
[1] 1


$data
                    uid         id                    name datacoverage    mindate    maxdate
1  gov.noaa.ncdc:C00040     ANNUAL        Annual Summaries         1.00 1831-02-01 2013-12-01
2  gov.noaa.ncdc:C00861      GHCND         Daily Summaries         1.00 1763-01-01 2014-05-02
3  gov.noaa.ncdc:C00841    GHCNDMS       Monthly Summaries         1.00 1763-01-01 2014-03-01
4  gov.noaa.ncdc:C00345    NEXRAD2         Nexrad Level II         0.95 1991-06-05 2014-04-22
5  gov.noaa.ncdc:C00708    NEXRAD3        Nexrad Level III         0.95 1994-05-20 2014-04-19
6  gov.noaa.ncdc:C00821 NORMAL_ANN Normals Annual/Seasonal         1.00 2010-01-01 2010-01-01
7  gov.noaa.ncdc:C00823 NORMAL_DLY           Normals Daily         1.00 2010-01-01 2010-12-31
8  gov.noaa.ncdc:C00824 NORMAL_HLY          Normals Hourly         1.00 2010-01-01 2010-12-31
9  gov.noaa.ncdc:C00822 NORMAL_MLY         Normals Monthly         1.00 2010-01-01 2010-12-01
10 gov.noaa.ncdc:C00505  PRECIP_15 Precipitation 15 Minute         0.25 1970-05-12 2013-05-01
11 gov.noaa.ncdc:C00313 PRECIP_HLY    Precipitation Hourly         1.00 1900-01-01 2013-05-01

attr(,"class")
[1] "ncdc_datasets"

Get data category data and metadata

ncdc_datacats(locationid='CITY:US390029')
$meta
$meta$totalCount
[1] 37

$meta$pageCount
[1] 25

$meta$offset
[1] 1


$data
              id                  name
1         ANNAGR   Annual Agricultural
2          ANNDD    Annual Degree Days
3        ANNPRCP  Annual Precipitation
4        ANNTEMP    Annual Temperature
5          AUAGR   Autumn Agricultural
6           AUDD    Autumn Degree Days
7         AUPRCP  Autumn Precipitation
8         AUTEMP    Autumn Temperature
9           COMP              Computed
10       COMPAGR Computed Agricultural
11            DD           Degree Days
12 DUALPOLMOMENT      Dual-Pol Moments
13       ECHOTOP             Echo Tops
14   HYDROMETEOR      Hydrometeor Type
15         OTHER                 Other
16       OVERLAY               Overlay
17          PRCP         Precipitation
18  REFLECTIVITY          Reflectivity
19           SKY    Sky cover & clouds
20         SPAGR   Spring Agricultural
21          SPDD    Spring Degree Days
22        SPPRCP  Spring Precipitation
23        SPTEMP    Spring Temperature
24         SUAGR   Summer Agricultural
25          SUDD    Summer Degree Days

attr(,"class")
[1] "ncdc_datacats"

Please report any issues or bugs.

License: MIT

This package is part of the rOpenSci project.

To cite package rnoaa in publications use:

  Hart Edmund, Scott Chamberlain and Karthik Ram (2014). rnoaa: NOAA climate data
  from R.. R package version 0.1.9.99. https://github.com/ropensci/rnoaa

A BibTeX entry for LaTeX users is

  @Manual{,
    title = {rnoaa: NOAA climate data from R.},
    author = {Hart Edmund and Scott Chamberlain and Karthik Ram},
    year = {2014},
    note = {R package version 0.1.9.99},
    url = {https://github.com/ropensci/rnoaa},
  }

Get citation information for rnoaa in R doing citation(package = 'rnoaa')

Functions in rnoaa

Name Description
check_response Check response from NOAA, including status codes, server error messages, mime-type, etc.
noaa_stations This function is defunct.
ncdc_datasets Search NOAA datasets
ncdc_datacats Get possible data categories for a particular datasetid, locationid, stationid, etc.
rnoaa-defunct Defunct functions in rnoaa
ncdc_locs Get metadata about NOAA NCDC locations.
rnoaa-package General purpose R interface to noaa.
fipscodes FIPS codes for US states.
noaa_plot This function is defunct.
erddap_search Search for ERDDAP datasets.
swdi Get NOAA data for the severe weather data inventory (swdi).
is.ncdc_data Check object class
check_response_swdi Check response from NOAA SWDI service, including status codes, server error messages,
ncdc_plot Plot NOAA climate data.
ncdc_stations Get metadata about NOAA NCDC stations.
noaa_seaice This function is defunct.
check_response_erddap Check response from NOAA, including status codes, server error messages, mime-type, etc.
ncdc_combine Coerce multiple outputs to a single data.frame object.
seaice Get sea ice data.
noaa_datacats This function is defunct.
ncdc_locs_cats Get metadata about NOAA location categories.
readshpfile Function to read shapefiles
erddap_data Get ERDDAP data.
theme_ice ggplot2 map theme
erddap_info Get information on an ERDDAP dataset.
noaa_locs This function is defunct.
noaa This function is defunct.
ncdc Search for and get NOAA NCDC data.
seaiceeurls Make all urls for sea ice data
noaa_combine This function is defunct.
long2utm Function to get UTM zone from a single longitude and latitude pair
noaa_datatypes This function is defunct.
ncdc_theme Theme for plotting NOAA data
noaa_datasets This function is defunct.
ncdc_datatypes Get possible data types for a particular dataset
latlong2bbox Function to calculate bounding box for the extent parameter in ncdc_stations function.
noaa_locs_cats This function is defunct.
No Results!

Last month downloads

Details

Date 2014-07-21
License MIT + file LICENSE
URL https://github.com/ropensci/rnoaa
BugReports http://www.github.com/ropensci/rnoaa/issues
LazyLoad yes
LazyData yes
Roxygen list(wrap = FALSE)
VignetteBuilder knitr

Include our badge in your README

[![Rdoc](http://www.rdocumentation.org/badges/version/rnoaa)](http://www.rdocumentation.org/packages/rnoaa)