Metadata-Version: 2.1
Name: noaa-coops
Version: 0.1
Summary: Python wrapper for NOAA Tides & Currents Data and Metadata
Home-page: https://github.com/GClunies/noaa_coops
Author: Greg Clunies
Author-email: greg.clunies@gmail.com
License: GNU GPL
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Description-Content-Type: text/markdown
Requires-Dist: requests
Requires-Dist: numpy
Requires-Dist: pandas

# noaa_coops

`noaa_coops` is a Python wrapper for the NOAA CO-OPS Tides &amp; Currents [Data](https://tidesandcurrents.noaa.gov/api/)
and [Metadata](https://tidesandcurrents.noaa.gov/mdapi/latest/) APIs.


This package is an evolution of [py_noaa](https://github.com/GClunies/py_noaa), the main addition being the creation of a `Station` class that is central to 
 `noaa_coops` and provides distinct advantages over `py_noaa`.

## Use
---
All data and metadata is handled using a `Station` class with methods and 
attributes for retrieving metadata, observed data, and predicted data.

### Getting Metadata

All available metadata for a desired station (identifed by unique `stationid`) 
is automagically generated when a `Station` object is initialzed. Station IDs 
can be found using the mapping interface at https://tidesandcurrents.noaa.gov/.
All metadata is stored as a dictionary in the `.metadata` attribute of a 
`Station` object for easy exploration. 

In the example below, we initialze a `Station` object for Seattle, WA 
(`stationid`=9447130) and then print the dictionary keys of the metadata 
attribute to see what type of metadata information is available.

```python
>>> from pprint import pprint
>>> import noaa_coops as nc
>>> seattle = nc.Station(9447130)
>>> pprint(list(seattle.metadata.keys())[:5]) # doctest: +NORMALIZE_WHITESPACE
['tidal', 'greatlakes', 'shefcode', 'details', 'sensors']

```

Additionally, the keys of the metadata attribute dictionary are also assigned 
as attribites of the station object itself. For example:

```python
>>> from pprint import pprint  # For pretty printing
>>> import noaa_coops as nc
>>> seattle = nc.Station(9447130)
>>> pprint(seattle.lat_lon['lat'])
47.601944
>>> pprint(seattle.lat_lon['lon'])
-122.339167

```

### Getting Observed or Predicted Data
Station data can be retrieved using the `.get_data` method on a `Station` 
class object. Data is returned as a Pandas DataFrame for easy use and analysis. 
Data types are listed on the [NOAA CO-OPS Data API](https://tidesandcurrents.noaa.gov/api/#products). The data types currently supported for retrieval with `noaa_coops` are:

    - Currents
    - Observed water levels
    - Observered daily high and low water levels (use `product="high_low"`)
    - Predicted water levels
    - Predicted high and low water levels
    - Winds
    - Air pressure
    - Air temperature
    - Water temperature

Compatibility with other data products may exist, but is not guaranteed at this 
time. Feel free to submit a pull request if you would like to add addtional 
functionality.

In the example below, water level data is retrieved for the Seattle station (`stationid`=9447130) for a 3 month period.

```python
>>> import noaa_coops as nc
>>> seattle = nc.Station(9447130)
>>> df_water_levels = seattle.get_data(
...     begin_date="20150101",
...     end_date="20150331",
...     product="water_level",
...     datum="MLLW",
...     units="metric",
...     time_zone="gmt")
>>> df_water_levels.head()  # doctest: +NORMALIZE_WHITESPACE
                       flags QC  sigma  water_level
date_time
2015-01-01 00:00:00  0,0,0,0  v  0.023        1.799
2015-01-01 01:00:00  0,0,0,0  v  0.014        0.977
2015-01-01 02:00:00  0,0,0,0  v  0.009        0.284
2015-01-01 03:00:00  0,0,0,0  v  0.010       -0.126
2015-01-01 04:00:00  0,0,0,0  v  0.013       -0.161

```

## Requirements

For use:
- requests
- numpy
- pandas

For development/contributions:
- pytest
- pytest-cov


## TODO
See [issues](https://github.com/GClunies/py_noaa/issues) for a list of issues 
and to add issues of your own.

## Contribution
All contributions are welcome, feel free to submit a pull request if you have a valuable addition to the package or constructive feedback.

**Many thanks to the following contributors!**
- [@delgadom](https://github.com/delgadom)
- [@CraigHarter](https://github.com/CraigHarter)
- [@jcconnel](https://github.com/jcconnell)
- [@fabaff](https://github.com/fabaff)


