floodresilience.dynamic_boundary_conditions.tide.tide_data_from_niwa

Fetch tide data from NIWA using the Tide API based on the specified approach, datum, etc.

Attributes

`log`
`TIDE_API_URL_DATA`
`TIDE_API_URL_DATA_CSV`

Functions

`get_query_loc_coords_position`(→ Tuple[float, float, str])	Get the latitude, longitude, and position of a query location.
`get_date_ranges`(, total_days, days_per_call, int])	Get the start date and duration, measured in days, for each API call used to fetch tide data for the
`gen_tide_query_param_list`(→ List[Dict[str, Union[str, ...)	Generate a list of API query parameters used to retrieve tide data for the requested period.
`fetch_tide_data`(→ geopandas.GeoDataFrame)	Fetch tide data using the provided query parameters within a single API call.
`fetch_tide_data_for_requested_period`(...)	Iterate over the list of API query parameters to fetch tide data for the requested period.
`convert_to_nz_timezone`(→ geopandas.GeoDataFrame)	Convert the time column in the initially retrieved tide data for the requested period from UTC to NZ timezone.
`fetch_tide_data_from_niwa`(, total_days, interval_mins)	Retrieve tide data from NIWA for the requested time period using the Tide API.
`get_highest_tide_datetime`(→ pandas.Timestamp)	Get the datetime of the most recent highest tide that occurred within the requested time period.
`get_highest_tide_datetime_span`(...)	Get the start and end datetimes of a tide event centered around the datetime of the highest tide.
`get_highest_tide_date_span`(→ Tuple[datetime.date, int])	Get the start date and duration in days of a tide event centered around the datetime of the highest tide.
`fetch_tide_data_around_highest_tide`(...)	Fetch tide data around the highest tide from NIWA for the specified tide length and interval.
`get_time_mins_to_add`(→ List[Union[float, int]])	Get the time values in minutes to add to the tide data.
`add_time_information`(→ geopandas.GeoDataFrame)	Add time information (seconds, minutes, hours) to the tide data.
`get_tide_data`(, total_days, tide_length_mins, ...)	Fetch tide data from NIWA using the Tide API based on the specified approach, datum, and other parameters.

Module Contents

floodresilience.dynamic_boundary_conditions.tide.tide_data_from_niwa.log

floodresilience.dynamic_boundary_conditions.tide.tide_data_from_niwa.TIDE_API_URL_DATA = 'https://api.niwa.co.nz/tides/data'

floodresilience.dynamic_boundary_conditions.tide.tide_data_from_niwa.TIDE_API_URL_DATA_CSV = 'https://api.niwa.co.nz/tides/data.csv'

floodresilience.dynamic_boundary_conditions.tide.tide_data_from_niwa.get_query_loc_coords_position(query_loc_row: geopandas.GeoDataFrame) → Tuple[float, float, str]

Get the latitude, longitude, and position of a query location.

Parameters:: query_loc_row (gpd.GeoDataFrame) – A GeoDataFrame representing a query location used to fetch tide data from NIWA using the tide API.
Returns:: A tuple containing the latitude, longitude, and position of the query location.
Return type:: Tuple[float, float, str]

floodresilience.dynamic_boundary_conditions.tide.tide_data_from_niwa.get_date_ranges(start_date: datetime.date = date.today(), total_days: int = 365, days_per_call: int = 31) → Dict[datetime.date, int]

Get the start date and duration, measured in days, for each API call used to fetch tide data for the requested period.

Parameters:

start_date (date = date.today()) – The start date for retrieving tide data. It can be in the past or present. Default is today’s date.
total_days (int = 365) – The total number of days of tide data to retrieve. Default is 365 days (one year).
days_per_call (int = 31) – The number of days to fetch in each API call. Must be between 1 and 31 inclusive. Default is 31, which represents the maximum number of days that can be fetched per API call.

Returns:

A dictionary containing the start date as the key and the duration, in days, for each API call as the value.

Return type:

Dict[date, int]

Raises:

ValueError –

If ‘total_days’ is less than 1.
If ‘days_per_call’ is not between 1 and 31 inclusive.

floodresilience.dynamic_boundary_conditions.tide.tide_data_from_niwa.gen_tide_query_param_list(lat: int | float, long: int | float, date_ranges: Dict[datetime.date, int], interval_mins: int | None = None, datum: floodresilience.dynamic_boundary_conditions.tide.tide_enum.DatumType = DatumType.LAT) → List[Dict[str, str | int]]

Generate a list of API query parameters used to retrieve tide data for the requested period.

Parameters:

lat (Union[int, float]) – Latitude in the range of -29 to -53 (e.g., -30.876).
long (Union[int, float]) – Longitude in the range of 160 to 180 and -175 to -180 (e.g., -175.543).
date_ranges (Dict[date, int]) – Dictionary of start date and number of days for each API call needed to retrieve tide data for the requested period.
interval_mins (Optional[int] = None) – Output time interval in minutes, range from 10 to 1440 minutes (1 day). Omit to retrieve only the highest and lowest tide data.
datum (DatumType = DatumType.LAT) – Datum used for fetching tide data from NIWA. Default value is LAT. Valid options are LAT for the Lowest Astronomical Tide and MSL for the Mean Sea Level.

Returns:

A list of API query parameters used to retrieve tide data for the requested period.

Return type:

List[Dict[str, Union[str, int]]]

Raises:

ValueError –

If the latitude is outside the range of -29 to -53.
If the longitude is outside the range of 160 to 180 or -175 to -180.
If the time interval is provided and outside the range of 10 to 1440.

async floodresilience.dynamic_boundary_conditions.tide.tide_data_from_niwa.fetch_tide_data(session: aiohttp.ClientSession, query_param: Dict[str, str | int], url: str = TIDE_API_URL_DATA) → geopandas.GeoDataFrame

Fetch tide data using the provided query parameters within a single API call.

Parameters:

session (aiohttp.ClientSession) – An instance of aiohttp.ClientSession used for making HTTP requests.
query_param (Dict[str, Union[str, int]]) – The query parameters used to retrieve tide data for a specific location and time period.
url (str = TIDE_API_URL_DATA) – Tide API HTTP request URL. Defaults to TIDE_API_URL_DATA. Can be either TIDE_API_URL_DATA or TIDE_API_URL_DATA_CSV.

Returns:

A GeoDataFrame containing the fetched tide data.

Return type:

gpd.GeoDataFrame

async floodresilience.dynamic_boundary_conditions.tide.tide_data_from_niwa.fetch_tide_data_for_requested_period(query_param_list: List[Dict[str, str | int]], url: str = TIDE_API_URL_DATA) → geopandas.GeoDataFrame

Iterate over the list of API query parameters to fetch tide data for the requested period.

Parameters:

query_param_list (List[Dict[str, Union[str, int]]]) – A list of API query parameters used to retrieve tide data for the requested period.
url (str = TIDE_API_URL_DATA) – Tide API HTTP request URL. Defaults to TIDE_API_URL_DATA. Can be either TIDE_API_URL_DATA or TIDE_API_URL_DATA_CSV.

Returns:

A GeoDataFrame containing the fetched tide data for the requested period.

Return type:

gpd.GeoDataFrame

Raises:

ValueError – If an invalid URL is specified for the Tide API HTTP request.
RuntimeError – If failed to fetch tide data.

floodresilience.dynamic_boundary_conditions.tide.tide_data_from_niwa.convert_to_nz_timezone(tide_data_utc: geopandas.GeoDataFrame) → geopandas.GeoDataFrame

Convert the time column in the initially retrieved tide data for the requested period from UTC to NZ timezone.

Parameters:: tide_data_utc (gpd.GeoDataFrame) – The original tide data obtained for the requested period with the time column expressed in UTC.
Returns:: The tide data with the time column converted to NZ timezone.
Return type:: gpd.GeoDataFrame

floodresilience.dynamic_boundary_conditions.tide.tide_data_from_niwa.fetch_tide_data_from_niwa(tide_query_loc: geopandas.GeoDataFrame, datum: floodresilience.dynamic_boundary_conditions.tide.tide_enum.DatumType = DatumType.LAT, start_date: datetime.date = date.today(), total_days: int = 365, interval_mins: int | None = None) → geopandas.GeoDataFrame

Retrieve tide data from NIWA for the requested time period using the Tide API.

Parameters:

tide_query_loc (gpd.GeoDataFrame) – A GeoDataFrame containing the query coordinates and their positions.
datum (DatumType = DatumType.LAT) – Datum used for fetching tide data from NIWA. Default value is LAT. Valid options are LAT for the Lowest Astronomical Tide and MSL for the Mean Sea Level.
start_date (date = date.today()) – The start date for retrieving tide data. It can be in the past or present. Default is today’s date.
total_days (int = 365) – The total number of days of tide data to retrieve. Default is 365 days (one year).
interval_mins (Optional[int] = None) – Output time interval in minutes, range from 10 to 1440 minutes (1 day). Omit to retrieve only the highest and lowest tide data.

Returns:

A GeoDataFrame containing the fetched tide data from NIWA for the requested time period.

Return type:

gpd.GeoDataFrame

floodresilience.dynamic_boundary_conditions.tide.tide_data_from_niwa.get_highest_tide_datetime(tide_data: geopandas.GeoDataFrame) → pandas.Timestamp

Get the datetime of the most recent highest tide that occurred within the requested time period.

Parameters:: tide_data (gpd.GeoDataFrame) – The tide data fetched from NIWA for the requested time period. The time column is expressed in NZ timezone, which was converted from UTC.
Returns:: The datetime of the most recent highest tide that occurred within the requested time period.
Return type:: pd.Timestamp

floodresilience.dynamic_boundary_conditions.tide.tide_data_from_niwa.get_highest_tide_datetime_span(highest_tide_datetime: pandas.Timestamp, tide_length_mins: int) → Tuple[pandas.Timestamp, pandas.Timestamp]

Get the start and end datetimes of a tide event centered around the datetime of the highest tide.

Parameters:

highest_tide_datetime (pd.Timestamp) – The datetime of the most recent highest tide that occurred within the requested time period.
tide_length_mins (int) – The length of the tide event in minutes.

Returns:

A tuple containing the start and end datetimes of the tide event centered around the datetime of the highest tide.

Return type:

Tuple[pd.Timestamp, pd.Timestamp]

floodresilience.dynamic_boundary_conditions.tide.tide_data_from_niwa.get_highest_tide_date_span(start_datetime: pandas.Timestamp, end_datetime: pandas.Timestamp) → Tuple[datetime.date, int]

Get the start date and duration in days of a tide event centered around the datetime of the highest tide.

Parameters:

start_datetime (pd.Timestamp) – The start datetime of the tide event centered around the datetime of the highest tide.
end_datetime (pd.Timestamp) – The end datetime of the tide event centered around the datetime of the highest tide.

Returns:

A tuple containing the start date and the duration in days of a tide event centered around the datetime of the highest tide.

Return type:

Tuple[date, int]

floodresilience.dynamic_boundary_conditions.tide.tide_data_from_niwa.fetch_tide_data_around_highest_tide(tide_data: geopandas.GeoDataFrame, tide_length_mins: int, interval_mins: int = 10, datum: floodresilience.dynamic_boundary_conditions.tide.tide_enum.DatumType = DatumType.LAT) → geopandas.GeoDataFrame

Fetch tide data around the highest tide from NIWA for the specified tide length and interval.

Parameters:

tide_data (gpd.GeoDataFrame) – The tide data fetched from NIWA for the requested time period. The time column is expressed in NZ timezone, which was converted from UTC.
tide_length_mins (int) – The length of the tide event in minutes.
interval_mins (int = 10) – The time interval, in minutes, between each recorded tide data point. The default value is 10 minutes.
datum (DatumType = DatumType.LAT) – Datum used for fetching tide data from NIWA. Default value is LAT. Valid options are LAT for the Lowest Astronomical Tide and MSL for the Mean Sea Level.

Returns:

The tide data around the highest tide, fetched from NIWA, for the specified tide length and interval.

Return type:

gpd.GeoDataFrame

floodresilience.dynamic_boundary_conditions.tide.tide_data_from_niwa.get_time_mins_to_add(tide_data: pandas.DataFrame, tide_length_mins: int, time_to_peak_mins: int | float, interval_mins: int = 10) → List[float | int]

Get the time values in minutes to add to the tide data.

Parameters:

tide_data (pd.DataFrame) – The tide data for which time values in minutes will be calculated.
tide_length_mins (int) – The length of the tide event in minutes.
time_to_peak_mins (Union[int, float]) – The time in minutes when the tide is at its greatest (reaches maximum).
interval_mins (int = 10) – The time interval, in minutes, between each recorded tide data point. The default value is 10 minutes.

Returns:

A list containing the time values in minutes to add to the tide data.

Return type:

List[Union[float, int]]

floodresilience.dynamic_boundary_conditions.tide.tide_data_from_niwa.add_time_information(tide_data: geopandas.GeoDataFrame, time_to_peak_mins: int | float, interval_mins: int = 10, tide_length_mins: int | None = None, total_days: int | None = None, approach: floodresilience.dynamic_boundary_conditions.tide.tide_enum.ApproachType = ApproachType.KING_TIDE) → geopandas.GeoDataFrame

Add time information (seconds, minutes, hours) to the tide data.

Parameters:

tide_data (gpd.GeoDataFrame) – The tide data for which time information will be added.
time_to_peak_mins (Union[int, float]) – The time in minutes when the tide is at its greatest (reaches maximum).
interval_mins (int = 10) – The time interval, in minutes, between each recorded tide data point. The default value is 10 minutes.
tide_length_mins (Optional[int] = None) – The length of the tide event in minutes. Only required if the ‘approach’ is KING_TIDE.
total_days (Optional[int] = None) – The total number of days for the tide event. Only required if the ‘approach’ is PERIOD_TIDE.
approach (ApproachType = ApproachType.KING_TIDE) – The approach used to get the tide data. Default is KING_TIDE.

Returns:

The tide data with added time information in seconds, minutes, and hours.

Return type:

gpd.GeoDataFrame

Raises:

ValueError – If ‘time_to_peak_mins’ is less than the minimum time to peak.

Notes

The minimum time to peak is calculated differently depending on the approach used: - For the KING_TIDE approach, it is half of the ‘tide_length_mins’. - For the PERIOD_TIDE approach, it is half of the ‘total_days’ converted to minutes.

floodresilience.dynamic_boundary_conditions.tide.tide_data_from_niwa.get_tide_data(tide_query_loc: geopandas.GeoDataFrame, time_to_peak_mins: int | float, approach: floodresilience.dynamic_boundary_conditions.tide.tide_enum.ApproachType = ApproachType.KING_TIDE, start_date: datetime.date = date.today(), total_days: int | None = None, tide_length_mins: int | None = None, interval_mins: int = 10, datum: floodresilience.dynamic_boundary_conditions.tide.tide_enum.DatumType = DatumType.LAT) → geopandas.GeoDataFrame

Fetch tide data from NIWA using the Tide API based on the specified approach, datum, and other parameters.

Parameters:

tide_query_loc (gpd.GeoDataFrame) – A GeoDataFrame containing the query coordinates and their positions.
time_to_peak_mins (Union[int, float]) – The time in minutes when the tide is at its greatest (reaches maximum).
approach (ApproachType = ApproachType.KING_TIDE) – The approach used to get the tide data. Default is KING_TIDE.
start_date (date = date.today()) – The start date for retrieving tide data. It can be in the past or present. Default is today’s date.
total_days (Optional[int] = None) – The total number of days for the tide event. Only required if the ‘approach’ is PERIOD_TIDE.
tide_length_mins (Optional[int] = None) – The length of the tide event in minutes. Only required if the ‘approach’ is KING_TIDE.
interval_mins (int = 10) – The time interval, in minutes, between each recorded tide data point. The default value is 10 minutes.
datum (DatumType = DatumType.LAT) – Datum used for fetching tide data from NIWA. Default value is LAT. Valid options are LAT for the Lowest Astronomical Tide and MSL for the Mean Sea Level.

Returns:

The tide data with added time information in seconds, minutes, and hours.

Return type:

gpd.GeoDataFrame

Raises:

ValueError –

If ‘interval_mins’ is None.
If the ‘approach’ is KING_TIDE and ‘tide_length_mins’ is None or ‘total_days’ is not None.
If the ‘approach’ is PERIOD_TIDE and ‘total_days’ is None or ‘tide_length_mins’ is not None.