Skip to content

Commit 499554f

Browse files
SorooshMani-NOAAabdu558
SorooshMani-NOAA
and
abdu558
authored
Add CHS data source (#173)
* Implement CHS API methods * Implement examples for the CHS API methods * Add CHS tests * Update COOPS test stations due to removed data * Updates to CHS API to make it similar to COOPS and IOC --------- Co-authored-by: abdu558 <arefabdu55@gmail.com>
1 parent b375eae commit 499554f

File tree

9 files changed

+517
-7
lines changed

9 files changed

+517
-7
lines changed

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,8 @@ Searvey aims to provide the following functionality:
1717
- Flanders Marine Institute (VLIZ); Intergovernmental Oceanographic Commission (IOC)
1818
- U.S. Geological Survey (USGS)
1919
- National Data Buoy Center (NDBC)
20+
- Canadian Hydrographic Service (CHS)
21+
2022

2123
## Installation
2224

‎docs/source/chs.rst‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
CHS
2+
===
3+
4+
The `Canadian Hydrographic Service (CHS) <https://www.charts.gc.ca/index-eng.html>`_
5+
provides water level and forecast data for Canadian waters. This module offers functions
6+
to interact with the CHS API and retrieve station information and water level data.
7+
8+
A DataFrame with the CHS station metadata can be retrieved with ``get_chs_stations()``,
9+
while station data can be fetched with ``fetch_chs_station()`` and ``_fetch_chs()``.
10+
11+
.. autofunction:: searvey.get_chs_stations
12+
13+
.. autofunction:: searvey.fetch_chs_station

‎docs/source/index.rst‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66
coops
77
ioc
88
usgs
9+
chs
910
utils
1011

1112
`searvey`
@@ -25,5 +26,7 @@ Overview
2526
- U.S. Center for Operational Oceanographic Products and Services (CO-OPS)
2627
- Flanders Marine Institute (VLIZ); Intergovernmental Oceanographic Commission (IOC)
2728
- U.S. Geological Survey (USGS)
29+
- Canadian Hydrographic Service (CHS)
30+
2831

2932
For installation and usage instructions, please check the menu.

‎examples/chs_data.ipynb‎

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
{
2+
"cells": [
3+
{
4+
"cell_type": "markdown",
5+
"metadata": {},
6+
"source": [
7+
"## Get the stations"
8+
]
9+
},
10+
{
11+
"cell_type": "code",
12+
"execution_count": null,
13+
"metadata": {},
14+
"outputs": [],
15+
"source": [
16+
"from searvey._chs_api import get_chs_stations\n",
17+
"\n",
18+
"all_stations = get_chs_stations()"
19+
]
20+
},
21+
{
22+
"cell_type": "markdown",
23+
"metadata": {},
24+
"source": [
25+
"## Plot them in a map"
26+
]
27+
},
28+
{
29+
"cell_type": "code",
30+
"execution_count": null,
31+
"metadata": {},
32+
"outputs": [],
33+
"source": [
34+
"import geopandas as gpd\n",
35+
"import hvplot.pandas\n",
36+
"import pandas as pd\n",
37+
"def plot_map(data, title):\n",
38+
" # Plot the world map\n",
39+
" world_plot = data.hvplot(geo=True, tiles=True, hover_cols=[\"id\",\"officialName\"], title=title)\n",
40+
" return world_plot.opts(width=800, height=500)\n",
41+
"\n",
42+
"plot_map(all_stations, 'CHS Stations')"
43+
]
44+
},
45+
{
46+
"cell_type": "markdown",
47+
"metadata": {},
48+
"source": [
49+
"## Get stations from a specific region and plot them"
50+
]
51+
},
52+
{
53+
"cell_type": "code",
54+
"execution_count": null,
55+
"metadata": {},
56+
"outputs": [],
57+
"source": [
58+
"from shapely.geometry import box\n",
59+
"# Define a rectangular region\n",
60+
"region = box(-150, 40, -110, 60) # Longitude range, Latitude range\n",
61+
"\n",
62+
"# Get stations within the region\n",
63+
"east_coast_stations = get_chs_stations(region=region)\n",
64+
"plot_map(east_coast_stations, 'CHS Stations on the East Coast of Canada')"
65+
]
66+
},
67+
{
68+
"cell_type": "markdown",
69+
"metadata": {},
70+
"source": [
71+
"## Get data from a specific CHS station\n",
72+
"To get data from a specific station you need to input one of the codes below:\n",
73+
"\n",
74+
"- wlo - Observed water level\n",
75+
"- wlf or wlf-spine - predicted water levels (at operational stations only)\n",
76+
"- wlp - Predicted water levels\n",
77+
"- wlp-hilo High and low sea predictions (Tide tables)\n",
78+
"\n",
79+
"Note: Some stations may not support a specific code/type of data"
80+
]
81+
},
82+
{
83+
"cell_type": "code",
84+
"execution_count": null,
85+
"metadata": {},
86+
"outputs": [],
87+
"source": [
88+
"from searvey._chs_api import fetch_chs_station\n",
89+
"# Get data for selected stations\n",
90+
"data_df = fetch_chs_station(\n",
91+
" station_id=\"5cebf1e33d0f4a073c4bc23e\",\n",
92+
" time_series_code=\"wlo\",\n",
93+
" start_date=\"2023-01-08\",\n",
94+
" end_date=\"2023-01-10\",\n",
95+
")\n",
96+
"\n",
97+
"data_df"
98+
]
99+
},
100+
{
101+
"cell_type": "markdown",
102+
"metadata": {},
103+
"source": [
104+
"## Get data from multiple stations"
105+
]
106+
},
107+
{
108+
"cell_type": "code",
109+
"execution_count": null,
110+
"metadata": {},
111+
"outputs": [],
112+
"source": [
113+
"import pandas as pd\n",
114+
"from searvey._chs_api import _fetch_chs\n",
115+
"\n",
116+
"multiple_data_df = _fetch_chs(\n",
117+
" station_ids=[\"5cebf1de3d0f4a073c4bbad5\",\"5cebf1e33d0f4a073c4bc23e\"],\n",
118+
" time_series_code=\"wlo\",\n",
119+
" start_dates=pd.DatetimeIndex([\"2023-01-08\"]*2),\n",
120+
" end_dates=pd.DatetimeIndex([\"2023-01-11\"]*2),\n",
121+
")\n",
122+
"\n",
123+
"multiple_data_df[\"5cebf1de3d0f4a073c4bbad5\"]"
124+
]
125+
},
126+
{
127+
"cell_type": "markdown",
128+
"metadata": {},
129+
"source": [
130+
"## Plot the data"
131+
]
132+
},
133+
{
134+
"cell_type": "code",
135+
"execution_count": null,
136+
"metadata": {},
137+
"outputs": [],
138+
"source": [
139+
"data_df[\"value\"].hvplot(title=\"CHS values\", xlabel=\"Index\", ylabel=\"Value\")\n"
140+
]
141+
}
142+
],
143+
"metadata": {
144+
"kernelspec": {
145+
"display_name": "Python 3 (ipykernel)",
146+
"language": "python",
147+
"name": "python3"
148+
},
149+
"language_info": {
150+
"codemirror_mode": {
151+
"name": "ipython",
152+
"version": 3
153+
},
154+
"file_extension": ".py",
155+
"mimetype": "text/x-python",
156+
"name": "python",
157+
"nbconvert_exporter": "python",
158+
"pygments_lexer": "ipython3",
159+
"version": "3.10.16"
160+
}
161+
},
162+
"nbformat": 4,
163+
"nbformat_minor": 4
164+
}

‎examples/coops_data.ipynb‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -180,7 +180,7 @@
180180
"cell_type": "markdown",
181181
"metadata": {},
182182
"source": [
183-
"# retrieve a CO-OPS data product from a lsit of stations"
183+
"# retrieve a CO-OPS data product from a list of stations"
184184
]
185185
},
186186
{

‎searvey/__init__.py‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22

33
import importlib.metadata
44

5+
from searvey._chs_api import fetch_chs_station
6+
from searvey._chs_api import get_chs_stations
57
from searvey._coops_api import fetch_coops_station
68
from searvey._ioc_api import fetch_ioc_station
79
from searvey._ndbc_api import fetch_ndbc_station
@@ -26,6 +28,8 @@
2628
"get_stations",
2729
"get_usgs_stations",
2830
"get_ndbc_stations",
31+
"get_chs_stations",
32+
"fetch_chs_station",
2933
"Provider",
3034
"__version__",
3135
]

0 commit comments

Comments
 (0)