Developed by: Georgii Bocharov

E-Mail: bocharovgeorgii@gmail.com

coastlib: https://github.com/georgebv/coastlib

License: GNU General Public License v3.0

Introduction

This notebook provides examples for the noaa_coops module of the coastlib library. Source code for this module can be found here.

The noaa_coops module is a part of the coastlib.data package. This module provides interface to the NOAA CO-OPS data portal via the CO-OPS API. It allows retrieval of environmental data collected by CO-OPS sensors such as wind, water levels, currents, salinity, air pressure, etc. in the form of pandas DataFrame. With the help of this tool one can automate extraction of large amounts of data from NOAA stations for further processing and storing.

Basic Uusage

Let's start by extracting water level data for the New York City the Battery station for the October 2012 time period (Hurricane Sandy):

In [1]:
%matplotlib inline

from coastlib.data import coops_api, coops_api_batch, coops_datum
df = coops_api(station=8518750, begin_date='20121025', end_date='20121101', product='water_level', datum='NAVD')
df.dropna().head()
Out[1]:
v s f q
Time (gmt)
2012-10-25 00:00:00 0.466 0.157 0,0,0,0 v
2012-10-25 00:06:00 0.358 0.095 0,0,0,0 v
2012-10-25 00:12:00 0.249 0.190 0,0,0,0 v
2012-10-25 00:18:00 0.135 0.105 0,0,0,0 v
2012-10-25 00:24:00 0.033 0.144 0,0,0,0 v
In [2]:
df['v'].plot(color='k', lw=1)
Out[2]:
<matplotlib.axes._subplots.AxesSubplot at 0x1de297a61c8>

Let's also get tidal datum for this station:

In [3]:
datum = coops_api(station=8518750, begin_date='20121025', end_date='20121101', product='datums', datum='MLLW', units='metric')
datum
Out[3]:
Value
Datum
MHHW 2.543
MHW 2.445
DTL 1.773
MTL 1.755
MSL 1.785
MLW 1.065
MLLW 1.002
GT 1.542
MN 1.380
DHQ 0.099
DLQ 0.063
NAVD 1.848
LWI 7.210
HWI 0.840

The coops_api is the most direct way of interfacing with the CO-OPS API. Its drawback is that it allows for extraction of data for only a relatively small window (see CO-OPS API documentation). Serious applications require many years of data. That's where the coops_api_batch function becomes much more convenient.

Batch Data Extraction

Let's get 10 years of wind data for the Eagle Point, Galveston Bay, TX station:

In [4]:
wind = coops_api_batch(station=8771013, begin_date='20050101', end_date='20150101', product='wind', datum='NAVD')
wind.dropna().head()
Out[4]:
s d dr g f
Time (gmt)
2005-01-01 00:00:00 0.00 114.0 ESE 3.11 0,0
2005-01-01 00:06:00 0.19 95.0 E 2.14 0,0
2005-01-01 00:12:00 3.89 99.0 E 4.47 0,0
2005-01-01 00:18:00 6.41 104.0 ESE 7.39 0,0
2005-01-01 00:24:00 6.80 99.0 E 8.16 0,0
In [5]:
wind['s'].plot(lw=.5, color='k')
Out[5]:
<matplotlib.axes._subplots.AxesSubplot at 0x1de2a141e48>
In [6]:
wind['s'].plot(kind='hist', bins=40, facecolor='None', edgecolor='k')
Out[6]:
<matplotlib.axes._subplots.AxesSubplot at 0x1de29e87bc8>

Let's save this wind data for future use. pandas also allows saving DataFrame objects to csv or xlsx formats by using built-in DataFrame methods.

In [7]:
wind.to_csv(r'../../data/wind_speed.csv')

Datum Extraction

Though the coops_api function provides a way to extract tidal datums, the recommended way to do so is through the coops_datum function. This function requires less arguments and provides a more detailed output and, optionally, station metadata. These methods are demonstrated for the Arena Cove station, located in California.

In [8]:
datum, meta = coops_datum(station=9416841, units='english', metadata=True)
In [9]:
datum
Out[9]:
Value Description
Datum
STND 0.00 Station Datum
MHHW 34.81 Mean Higher-High Water
MHW 34.14 Mean High Water
DTL 31.88 Mean Diurnal Tide Level
MTL 32.12 Mean Tide Level
MSL 32.08 Mean Sea Level
MLW 30.10 Mean Low Water
MLLW 28.94 Mean Lower-Low Water
GT 5.86 Great Diurnal Range
MN 4.04 Mean Range of Tide
DHQ 0.67 Mean Diurnal High Water Inequality
DLQ 1.15 Mean Diurnal Low Water Inequality
HWI 6.84 Greenwich High Water Interval (in hours)
LWI 0.51 Greenwich Low Water Interval (in hours)
NAVD88 29.07 North American Vertical Datum of 1988
In [10]:
meta
Out[10]:
Value
Property
accepted Dec 6 2011
superseded
epoch 1983-2001
units feet
OrthometricDatum NAVD88
LAT 26.755
LATdate 19900525
LATtime 13:36
HAT 36.587
HATdate 19861231
HATtime 18:06
min 26.302
mindate 20030518
mintime 14:48
max 37.601
maxdate 19980206
maxtime 14:36
DatumAnalysisPeriod [05/01/1991 - 04/30/2008, 05/01/2009 - 04/30/2...
NGSLink http://www.ngs.noaa.gov/Tidal_Elevation/diagra...
ctrlStation 9415020 Point Reyes, CA

Final Remarks

This tutorial doesn't cover all functionality and ways of using the noaa_coops module. Please refer to the module source code and the API reference for more information on arguments not covered here.