Tidegauge

Objects

Tidegauge()
Tidegauge.read_gesla_v3()
Tidegauge.read_gesla()
Tidegauge._read_gesla_header_v5()
Tidegauge._read_gesla_header_v3()
Tidegauge._read_gesla_data()
Tidegauge.read_hlw()
Tidegauge._read_hlw_header()
Tidegauge._read_hlw_data()
Tidegauge.show()
Tidegauge.get_tide_table_times()
Tidegauge.read_ea_api_to_xarray()
Tidegauge.read_bodc()
Tidegauge._read_bodc_header()
Tidegauge._read_bodc_data()
Tidegauge.plot_timeseries()
Tidegauge.plot_on_map()
Tidegauge.plot_on_map_multiple()
Tidegauge.obs_operator()
Tidegauge.time_slice()
Tidegauge.subset_indices_lonlat_box()

Tide Gauge class

Tidegauge()

class Tidegauge(Timeseries):

This is an object for storage and manipulation of tide gauge data
in a single dataset. This may require some processing of the observations
such as interpolation to a common time step.

This object's dataset should take the form (as with Timeseries):

    Dimensions:
        id_dim   : The locations dimension. Each time series has an index
        time : The time dimension. Each datapoint at each port has an index

    Coordinates:
        longitude (id_dim) : Longitude values for each port index
        latitude  (id_dim) : Latitude values for each port index
        time      (time) : Time values for each time index (datetime)
        id_name   (id_dim)   : Name of index, e.g. port name or mooring id.

An example data variable could be ssh, or ntr (non-tidal residual). This
object can also be used for other instrument types, not just tide gauges.
For example moorings.

Every id index for this object should use the same time coordinates.
Therefore, timeseries need to be aligned before being placed into the
object. If there is any padding needed, then NaNs should be used. NaNs
should also be used for quality control/data rejection.

Tidegauge.read_gesla_v3()

def Tidegauge.read_gesla_v3(self, fn_gesla, date_start=None, date_end=None):

Depreciated method.
Call generalised method.
Returns eiter a tidegauge object or a list of tidegauge objects

Tidegauge.read_gesla()

def Tidegauge.read_gesla(self, fn_gesla, date_start=None, date_end=None, format=v3):

For reading from a GESLA2 (Format version 3.0) or GESLA3 (Format v5.0)
file(s) into an xarray dataset.

v3 formatting according to Woodworth et al. (2017).
v5 formatting ....

Website: https://www.gesla.org/
If no data lies between the specified dates, a dataset is still created
containing information on the tide gauge, but the time dimension will
be empty.
Parameters
----------
fn_gesla (str) : path to gesla tide gauge file, list of files or a glob
date_start (datetime) : start date for returning data
date_end (datetime) : end date for returning data
format (str) : accepts "v3" or "v5"

Returns
-------
Creates xarray.dataset within tidegauge object containing loaded data.
If multiple files are provided then instead returns a list of NEW
tidegauge objects.

Tidegauge._read_gesla_header_v5()

@classmethod
def Tidegauge._read_gesla_header_v5(cls, fn_gesla):

Reads header from a GESLA file (format version 5.0).

Parameters
----------
fn_gesla (str) : path to gesla tide gauge file

Returns
-------
dictionary of attributes

Tidegauge._read_gesla_header_v3()

@classmethod
def Tidegauge._read_gesla_header_v3(cls, fn_gesla):

Reads header from a GESLA file (format version 3.0).

Parameters
----------
fn_gesla (str) : path to gesla tide gauge file

Returns
-------
dictionary of attributes

Tidegauge._read_gesla_data()

@classmethod
def Tidegauge._read_gesla_data(cls, fn_gesla, date_start=None, date_end=None, header_length=32):

Reads observation data from a GESLA file (format version 3.0 and 5.0).

Parameters
----------
fn_gesla (str) : path to gesla tide gauge file
date_start (datetime) : start date for returning data
date_end (datetime) : end date for returning data
header_length (int) : number of lines in header (to skip when reading)

Returns
-------
xarray.Dataset containing times, sealevel and quality control flags

Tidegauge.read_hlw()

def Tidegauge.read_hlw(self, fn_hlw, date_start=None, date_end=None):

For reading from a file of tidetable High and Low Waters (HLW) data into an
xarray dataset. File contains high water and low water heights and times

If no data lies between the specified dates, a dataset is still created
containing information on the tide gauge, but the time dimension will
be empty.

The data takes the form:
LIVERPOOL (GLADSTONE DOCK)                TZ: UT(GMT)/BST                Units: METRES                Datum: Chart Datum
01/10/2020 06:29                1.65
01/10/2020 11:54                9.01
01/10/2020 18:36                1.87
...

Parameters
----------
fn_hlw (str) : path to tabulated High Low Water file
date_start (datetime) : start date for returning data
date_end (datetime) : end date for returning data

Returns
-------
xarray.Dataset object.

Tidegauge._read_hlw_header()

@classmethod
def Tidegauge._read_hlw_header(cls, filnam):

Reads header from a HWL file.

The data takes the form:
LIVERPOOL (GLADSTONE DOCK) TZ: UT(GMT)/BST Units: METRES Datum: Chart Datum
01/10/2020 06:29                1.65
01/10/2020 11:54                9.01
01/10/2020 18:36                1.87
...

Parameters
----------
filnam (str) : path to file

Returns
-------
dictionary of attributes

Tidegauge._read_hlw_data()

@classmethod
def Tidegauge._read_hlw_data(cls, filnam, header_dict, date_start=None, date_end=None, header_length=1):

Reads HLW data from a tidetable file.

Parameters
----------
filnam (str) : path to HLW tide gauge file
date_start (np.datetime64) : start date for returning data.
date_end (np.datetime64) : end date for returning data.
header_length (int) : number of lines in header (to skip when reading)

Returns
-------
xarray.Dataset containing times, High and Low water values

Tidegauge.show()

def Tidegauge.show(self, timezone=None):

Print out the values in the xarray
Displays with specified timezone

Tidegauge.get_tide_table_times()

def Tidegauge.get_tide_table_times(self, time_guess=None, time_var=time, measure_var=ssh, method=window, winsize=None):

Get tide times and heights from tide table.
input:
time_guess : np.datetime64 or datetime
                                assumes utc
time_var : name of time variable [default: 'time']
measure_var : name of ssh variable [default: 'ssh']

method =
                window: +/- hours window size, winsize, (int) return values in that window
                                uses additional variable winsize (int) [default 2hrs]
                nearest_1: return only the nearest event, if in winsize [default:None]
                nearest_2: return nearest event in future and the nearest in the past (i.e. high and a low), if in winsize [default:None]
                nearest_HW: return nearest High Water event (computed as the max of `nearest_2`), if in winsize [default:None]

returns: xr.DataArray( measure_var, coords=time_var)
                E.g. ssh (m), time (utc)
                If value is not found, it returns a NaN with time value as the
                guess value.

Tidegauge.read_ea_api_to_xarray()

@classmethod
def Tidegauge.read_ea_api_to_xarray(cls, n_days=5, date_start=None, date_end=None, station_id=E70124):

load gauge data via environment.data.gov.uk EA API
Either loads last n_days, or from date_start:date_end

API Source:
https://environment.data.gov.uk/flood-monitoring/doc/reference

Details of available tidal stations are recovered with:
https://environment.data.gov.uk/flood-monitoring/id/stations?type=TideGauge
Recover the "stationReference" for the gauge of interest and pass as
station_id:str. The default station_id="E70124" is Liverpool.

INPUTS:
                n_days : int. Extact the last n_days from now.
                date_start : datetime. UTC format string "yyyy-MM-dd" E.g 2020-01-05
                date_end : datetime
                station_id : int. Station id. Also referred to as stationReference in
                EA API. Default value is for Liverpool.
OUTPUT:
                ssh, time : xr.Dataset

Tidegauge.read_bodc()

def Tidegauge.read_bodc(self, fn_bodc, date_start=None, date_end=None):

For reading from a single BODC (processed) file into an
xarray dataset.
If no data lies between the specified dates, a dataset is still created
containing information on the tide gauge, but the time dimension will
be empty.

Data name: UK Tide Gauge Network, processed data.
Source: https://www.bodc.ac.uk/
See data notes from source for description of QC flags.

The data takes the form:
                Port:                                                P234
                Site:                                                Liverpool, Gladstone Dock
                Latitude:                                53.44969
                Longitude:                                -3.01800
                Start Date:                                01AUG2020-00.00.00
                End Date:                                31AUG2020-23.45.00
                Contributor:                National Oceanography Centre, Liverpool
                Datum information: The data refer to Admiralty Chart Datum (ACD)
                Parameter code:                ASLVBG02 = Surface elevation (unspecified datum)
                of the water body by bubbler tide gauge (second sensor)
                Cycle                Date                Time                ASLVBG02 Residual
                Number yyyy mm dd hh mi ssf                                f                                f
                                1) 2020/08/01 00:00:00                5.354M                0.265M
                                2) 2020/08/01 00:15:00                5.016M                0.243M
                                3) 2020/08/01 00:30:00                4.704M                0.241M
                                4) 2020/08/01 00:45:00                4.418M                0.255M
                                5) 2020/08/01 01:00:00                4.133                0.257
                                ...

Parameters
----------
fn_bodc (str) : path to bodc tide gauge file
date_start (datetime) : start date for returning data
date_end (datetime) : end date for returning data

Returns
-------
xarray.Dataset object.

Tidegauge._read_bodc_header()

@staticmethod
def Tidegauge._read_bodc_header(fn_bodc):

Reads header from a BODC file (format version 3.0).

Parameters
----------
fn_bodc (str) : path to bodc tide gauge file

Returns
-------
dictionary of attributes

Tidegauge._read_bodc_data()

@staticmethod
def Tidegauge._read_bodc_data(fn_bodc, date_start=None, date_end=None, header_length=11):

Reads observation data from a BODC file.

Parameters
----------
fn_bodc (str) : path to bodc tide gauge file
date_start (datetime) : start date for returning data
date_end (datetime) : end date for returning data
header_length (int) : number of lines in header (to skip when reading)

Returns
-------
xarray.Dataset containing times, sealevel and quality control flags

Tidegauge.plot_timeseries()

def Tidegauge.plot_timeseries(self, var_list=unknown, date_start=None, date_end=None, plot_line=False):

Quick plot of time series stored within object's dataset
Parameters
----------
date_start (datetime) : Start date for plotting
date_end (datetime) : End date for plotting
var_list (str) : List of variables to plot. Default: just ssh
plot_line (bool) : If true, draw line between markers

Returns
-------
matplotlib figure and axes objects

Tidegauge.plot_on_map()

def Tidegauge.plot_on_map(self):

Show the location of a tidegauge on a map.
Example usage:
--------------
# For a TIDEGAUGE object tg
tg.plot_map()

Tidegauge.plot_on_map_multiple()

@classmethod
def Tidegauge.plot_on_map_multiple(cls, tidegauge_list, color_var_str=None):

Show the location of a tidegauge on a map.
Example usage:
--------------
# For a TIDEGAUGE object tg
tg.plot_map()

Tidegauge.obs_operator()

def Tidegauge.obs_operator(self, gridded, time_interp=nearest):

Regrids a Gridded object onto a tidegauge_multiple object. A nearest
neighbour interpolation is done for spatial interpolation and time
interpolation can be specified using the time_interp argument. This
takes any scipy interpolation string. If Gridded object contains a
landmask variables, then the nearest WET point is taken for each tide
gauge.

Output is a new tidegauge_multiple object containing interpolated data.

Tidegauge.time_slice()

def Tidegauge.time_slice(self, date0, date1):

Return new Gridded object, indexed between dates date0 and date1

Tidegauge.subset_indices_lonlat_box()

def Tidegauge.subset_indices_lonlat_box(self, lonbounds, latbounds):

Get a subset of this Profile() object in a spatial box.

lonbounds -- Array of form [min_longitude=-180, max_longitude=180]
latbounds -- Array of form [min_latitude, max_latitude]

return: A new profile object containing subsetted data