src.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

src.dynamic_boundary_conditions.tide.tide_data_from_niwa.log
src.dynamic_boundary_conditions.tide.tide_data_from_niwa.TIDE_API_URL_DATA = 'https://api.niwa.co.nz/tides/data'
src.dynamic_boundary_conditions.tide.tide_data_from_niwa.TIDE_API_URL_DATA_CSV = 'https://api.niwa.co.nz/tides/data.csv'
src.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]

src.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.

src.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: src.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 src.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 src.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.

src.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

src.dynamic_boundary_conditions.tide.tide_data_from_niwa.fetch_tide_data_from_niwa(tide_query_loc: geopandas.GeoDataFrame, datum: src.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

src.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

src.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]

src.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]

src.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: src.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

src.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]]

src.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: src.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.

src.dynamic_boundary_conditions.tide.tide_data_from_niwa.get_tide_data(tide_query_loc: geopandas.GeoDataFrame, time_to_peak_mins: int | float, approach: src.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: src.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.