From f0125a7bb02b5f305730f1a59eecf178d2541c6f Mon Sep 17 00:00:00 2001 From: Rachel Wegener <35503632+rwegener2@users.noreply.github.com> Date: Fri, 22 Nov 2024 15:34:04 -0500 Subject: [PATCH 1/7] Add test instructions to contributing --- README.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/README.md b/README.md index b277362..9e69da1 100644 --- a/README.md +++ b/README.md @@ -258,6 +258,13 @@ the [GitHub discussion forum](https://github.com/cdjellen/ndbc-api/discussions). #### Contributing The `ndbc-api` is actively maintained, please feel free to open a pull request if you have any suggested improvements, test coverage is strongly preferred. +To run tests, first install the ndbc-api general usage and dev requirments in your environment: + +1. `pip install -r requirements.txt` +2. `pip install -r requirements_dev.txt` + +Run the tests from the root directory using `pytest .`. To run all tests use `pytest . --run-slow --run-private`. + As a reminder, breaking changes will be considered, especially in the current `alpha` state of the package on `PyPi`. As the API further matures, breaking changes will only be considered with new major versions (e.g. `N.0.0`). Alternatively, if you have an idea for a new capability or improvement, feel free to open a feature request issue outlining your suggestion and the ways in which it will empower the atmospheric research community. From 88aafb0c87b24eac007e62223fdece746986529b Mon Sep 17 00:00:00 2001 From: Rachel Wegener <35503632+rwegener2@users.noreply.github.com> Date: Fri, 22 Nov 2024 15:35:21 -0500 Subject: [PATCH 2/7] Fix typo in Station measurements --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 9e69da1..218da1b 100644 --- a/README.md +++ b/README.md @@ -170,7 +170,7 @@ tplm2_historical_df = api.available_historical(station_id='tplm2', as_df=True) ##### Station measurements -The `api` has two public method which support accessing supported NDBC station measurements. +The `api` has two public methods which support accessing supported NDBC station measurements. 1. The `get_modes` method, which returns a list of supported `mode`s, coresponding to the data formats provided by the NDBC data service. From b129655e61a5375e56049fae9f96a4c5abf97dfe Mon Sep 17 00:00:00 2001 From: Chris Jellen Date: Fri, 22 Nov 2024 17:59:59 -0600 Subject: [PATCH 3/7] README cleanup --- README.md | 26 ++++++-------------------- 1 file changed, 6 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index 218da1b..ce56b2d 100644 --- a/README.md +++ b/README.md @@ -58,6 +58,8 @@ The API uses synchronous HTTP requests to compile data matching the user-supplie * pandas * bs4 * html5lib>=1.1 +* xarray +* scipy ##### Development If you would like to contribute to the growth and maintenance of the `ndbc-api`, please feel free to open a PR with tests covering your changes. The tests leverage `pytest` and depend on the above requirements, as well as: @@ -82,12 +84,12 @@ api = NdbcApi() The `api` is a singleton, such that the underlying `RequestHandler` and NDBC station-level `RequestCache`s are shared between instances. Both the singleton metaclass and `RequestHandler` are implemented to reduce the likelihood of repeat requests to the NDBC's data service, and to converse NDBC resources. This is balanced by a station-level `cache_limit`, implemented as an LRU cache, which seeks to respect user resources. -Data made available by the NDBC falls into two broad catagories. +Data made available by the NDBC falls into two broad categories. 1. Station metadata 2. Station measurements -The `api` supports a range of public methods for accessing data from the above catagories. +The `api` supports a range of public methods for accessing data from the above categories. ##### Station metadata @@ -144,7 +146,7 @@ nearby_stations_df = api.radial_search(lat=lat, lon=lon, radius=radius, units=un ###### `station` ```python3 -# get staion metadata +# get station metadata tplm2_meta = api.station(station_id='tplm2') # parse the response as a Pandas DataFrame tplm2_df = api.station(station_id='tplm2', as_df=True) @@ -172,7 +174,7 @@ tplm2_historical_df = api.available_historical(station_id='tplm2', as_df=True) The `api` has two public methods which support accessing supported NDBC station measurements. -1. The `get_modes` method, which returns a list of supported `mode`s, coresponding to the data formats provided by the NDBC data service. +1. The `get_modes` method, which returns a list of supported `mode`s, corresponding to the data formats provided by the NDBC data service. Note that not all stations provide the same set of measurements. The `available_realtime` and `available_historical` methods can be called on a station-by station basis to ensure a station has the desired data available, before building and executing requests with `get_data`. @@ -249,22 +251,6 @@ stdmet_df = api.get_data( #### More Information Please see [the included example notebook](/notebooks/overview.ipynb) for a more detailed walkthrough of the API's capabilities. - #### Questions If you have questions regarding the library please post them into the [GitHub discussion forum](https://github.com/cdjellen/ndbc-api/discussions). - - -#### Contributing -The `ndbc-api` is actively maintained, please feel free to open a pull request if you have any suggested improvements, test coverage is strongly preferred. - -To run tests, first install the ndbc-api general usage and dev requirments in your environment: - -1. `pip install -r requirements.txt` -2. `pip install -r requirements_dev.txt` - -Run the tests from the root directory using `pytest .`. To run all tests use `pytest . --run-slow --run-private`. - -As a reminder, breaking changes will be considered, especially in the current `alpha` state of the package on `PyPi`. As the API further matures, breaking changes will only be considered with new major versions (e.g. `N.0.0`). - -Alternatively, if you have an idea for a new capability or improvement, feel free to open a feature request issue outlining your suggestion and the ways in which it will empower the atmospheric research community. From 06113541fac7f269b10f4174101c2accd77ca194 Mon Sep 17 00:00:00 2001 From: Chris Jellen Date: Fri, 22 Nov 2024 18:00:09 -0600 Subject: [PATCH 4/7] Add new CONTRIBUTING.md guide --- CONTRIBUTING.md | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..053c04f --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,34 @@ +#### Contributing + +The `ndbc-api` is actively maintained, please feel free to open a pull request if you have any suggested improvements, test coverage is strongly preferred. + +##### Testing + +Tests are prepared and executed using the `pytest` framework, and designed to use cached responses rather than making new HTTP requests to the NDBC Data Service. In order to run tests, you will need to install the additional packages in `requirements_dev.txt` (also encoded in the `dev` group in `pyproject.toml`) + +For pip installation, please create a clean virtual environment and run: + +```bash +pip install -r requirements.txt +pip install -r requirements_dev.txt +``` + +For poetry-managed installations, please run: + +```bash +poetry install +``` + +##### Running Tests + +All tests can be run from the root directory using `python3 -m pytest --run-slow --run-private`. + +The two flags in the command above are optional, but can be useful for running all tests, including those marked as slow or private. The `--run-slow` flag will run tests marked with the `@pytest.mark.slow` decorator, and the `--run-private` flag will run tests marked with the `@pytest.mark.private` decorator. Tests which take more than 30 seconds are typically marked as slow, while test for internals are marked as private. + +##### Pull Requests + +In order for a pull request to merge to `main`, all tests must pass, and the code must be reviewed by at least one other contributor. + +Breaking changes will be considered, especially in the current `alpha` state of the package on `PyPi`. As the API further matures, breaking changes will only be considered with new major versions (e.g. `N.0.0`). + +Alternatively, if you have an idea for a new capability or improvement, feel free to open a feature request issue outlining your suggestion and the ways in which it will empower the atmospheric research community. From ceade1b4463d12e4eac5e4925c9747e939a02ac5 Mon Sep 17 00:00:00 2001 From: Chris Jellen Date: Fri, 22 Nov 2024 18:04:17 -0600 Subject: [PATCH 5/7] improve the introduction for the API in the README --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index ce56b2d..3a45660 100644 --- a/README.md +++ b/README.md @@ -82,7 +82,7 @@ from ndbc_api import NdbcApi api = NdbcApi() ``` -The `api` is a singleton, such that the underlying `RequestHandler` and NDBC station-level `RequestCache`s are shared between instances. Both the singleton metaclass and `RequestHandler` are implemented to reduce the likelihood of repeat requests to the NDBC's data service, and to converse NDBC resources. This is balanced by a station-level `cache_limit`, implemented as an LRU cache, which seeks to respect user resources. +The `NdbcApi` provides a unified access point for NDBC data. All methods for obtaining data, metadata, and locating stations are available using the `api` object. The `get_data` method is the primary method for accessing NDBC data, and is used to retrieve measurements from a given station over a specified time range. This method can request data from the NDBC HTTP Data Service or the THREDDS data service, and return the data as a `pandas.DataFrame`, `xarray.Dataset` or python `dict` object. Data made available by the NDBC falls into two broad categories. From b99e214a4c33cd8c0472b83b3f0d4153d202137b Mon Sep 17 00:00:00 2001 From: Chris Jellen Date: Fri, 22 Nov 2024 18:10:45 -0600 Subject: [PATCH 6/7] add mode descriptions --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 3a45660..1fd876d 100644 --- a/README.md +++ b/README.md @@ -174,7 +174,7 @@ tplm2_historical_df = api.available_historical(station_id='tplm2', as_df=True) The `api` has two public methods which support accessing supported NDBC station measurements. -1. The `get_modes` method, which returns a list of supported `mode`s, corresponding to the data formats provided by the NDBC data service. +1. The `get_modes` method, which returns a list of supported `mode`s, corresponding to the data formats provided by the NDBC data service. For example, the `adcp` mode represents "Acoustic Doppler Current Profiler" measurements, providing information about ocean currents at different depths, while `cwind` represents "Continuous winds" data, offering high-frequency wind speed and direction measurements. Note that not all stations provide the same set of measurements. The `available_realtime` and `available_historical` methods can be called on a station-by station basis to ensure a station has the desired data available, before building and executing requests with `get_data`. @@ -207,7 +207,7 @@ print(modes) ###### `get_data` ```python3 -# get all continuous wind measurements for station tplm2 +# get all continuous wind (`cwind`) measurements for station tplm2 cwind_df = api.get_data( station_id='tplm2', mode='cwind', @@ -231,7 +231,7 @@ wspd_df = api.get_data( as_df=True, cols=['WSPD'] ) -# get all standard meterological measurements for stations tplm2 and apam2 +# get all standard meterological (`stdmet`) measurements for stations tplm2 and apam2 stdmet_df = api.get_data( station_ids=['tplm2', 'apam2'], mode='stdmet', From cca6814d41417bcf82f76b42fbd019f26d999727 Mon Sep 17 00:00:00 2001 From: Chris Jellen Date: Fri, 22 Nov 2024 18:14:44 -0600 Subject: [PATCH 7/7] Include mode explainers --- README.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/README.md b/README.md index 1fd876d..786c216 100644 --- a/README.md +++ b/README.md @@ -204,6 +204,19 @@ print(modes) ] ``` +The mode values above map directly to the identifiers used buy the NDBC. Desriptions for each mode are presented below: +* `adcp`: Acoustic Doppler Current Profiler measurements, providing information about ocean currents at different depths. +* `cwind`: Continuous winds data, offering high-frequency wind speed and direction measurements. +* `ocean`: Oceanographic data, including water temperature, salinity, and wave measurements. +* `spec`: Spectral wave data, providing detailed information about wave energy and direction. +* `stdmet`: Standard meteorological data, including air temperature, pressure, wind speed, and visibility. +* `supl`: Supplemental measurements, which can vary depending on the specific buoy and its sensors. +* `swden`: Spectral wave density data, providing information about the distribution of wave energy across different frequencies. +* `swdir`: Spectral wave direction data, indicating the primary direction of wave energy. +* `swdir2`: Secondary spectral wave direction data, capturing additional wave direction information. +* `swr1`: First-order spectral wave data, providing basic wave height and period information. +* `swr2`: Second-order spectral wave data, offering more detailed wave measurements. + ###### `get_data` ```python3