Tidegauge_analysis

Docstrings for the Tidegauge_analysis class

6 minute read

Objects

An analysis class for tide gauge.

TidegaugeAnalysis()

class TidegaugeAnalysis():

This contains analysis methods suitable for use with the dataset structure
of Tidegauge()

TidegaugeAnalysis.match_missing_values()

@classmethod
def TidegaugeAnalysis.match_missing_values(cls, data_array1, data_array2, fill_value=unknown):

Will match any missing values between two tidegauge_multiple datasets.
Where missing values (defined by fill_value) are found in either dataset
they are also placed in the corresponding location in the other dataset.
Returns two new tidegauge objects containing only the new
masked data arrays.

TidegaugeAnalysis.harmonic_analysis_utide()

@classmethod
def TidegaugeAnalysis.harmonic_analysis_utide(cls, data_array, min_datapoints=1000, nodal=False, trend=False, method=ols, conf_int=linear, Rayleigh_min=0.95):

Does a harmonic analysis for each timeseries inside this object using
the utide library. All arguments except min_datapoints are arguments
that are passed to ut.solve(). Please see the utide website for more
information:

                https://pypi.org/project/UTide/

Utide will by default do it's harmonic analysis using a set of harmonics
determined using the Rayleigh criterion. This changes the number of
harmonics depending on the length and frequency of the time series.

Output from this routine is not a new dataset, but a list of utide
analysis object. These are structures containing, amongst other things,
amplitudes, phases, constituent names and confidence intervals. This
list can be passed to reconstruct_tide_utide() in this object to create
a new TidegaugeMultiple object containing reconstructed tide data.

INPUTS
data_array                : Xarray data_array from a coast.Tidegauge() object
                                                                e.g. tidegauge.dataset.ssh
min_datapoints : If a time series has less than this value number of
                                                                datapoints, then omit from the analysis.
: Inputs to utide.solve(). See website above.

OUTPUTS
A list of utide structures from the solve() routine. If a location
is omitted, it will contain [] for it's entry.

TidegaugeAnalysis.reconstruct_tide_utide()

@classmethod
def TidegaugeAnalysis.reconstruct_tide_utide(cls, data_array, utide_solution_list, constit=None, output_name=reconstructed):

Use the tarray of times to reconstruct a time series series using a
list of utide analysis objects. This list can be obtained
using harmonic_analysis_utide(). Specify constituents to use in the
reconstruction by passing a list of strings such as 'M2' to the constit
argument. This won't work if a specified constituent is not present in
the analysis.

TidegaugeAnalysis.calculate_non_tidal_residuals()

@classmethod
def TidegaugeAnalysis.calculate_non_tidal_residuals(cls, data_array_ssh, data_array_tide, apply_filter=True, window_length=25, polyorder=3):

Calculate non tidal residuals by subtracting values in data_array_tide
from data_array_ssh. You may optionally apply a filter to the non
tidal residual data by setting apply_filter = True. This uses the
scipy.signal.savgol_filter function, which you may pass window_length
and poly_order.

TidegaugeAnalysis.threshold_statistics()

@classmethod
def TidegaugeAnalysis.threshold_statistics(cls, dataset, thresholds=unknown, peak_separation=12):

Do some threshold statistics for all variables with a time dimension
inside this tidegauge_multiple object. Specifically, this routine will
calculate:

                                peak_count                                : The number of indepedent peaks over
                                                                                                                each specified threshold. Independent peaks
                                                                                                                are defined using the peak_separation
                                                                                                                argument. This is the number of datapoints
                                                                                                                either side of a peak within which data
                                                                                                                is ommited for further peak search.
                                time_over_threshold : The total time spent over each threshold
                                                                                                                This is NOT an integral, but simple a count
                                                                                                                of all points over threshold.
                                dailymax_count                : A count of the number of daily maxima over
                                                                                                                each threshold
                                monthlymax_count                : A count of the number of monthly maxima
                                                                                                                over each threshold.

Output is a xarray dataset containing analysed variables. The name of
each analysis variable is constructed using the original variable name
and one of the above analysis categories.

TidegaugeAnalysis.demean_timeseries()

@staticmethod
def TidegaugeAnalysis.demean_timeseries(dataset):

Subtract time means from all variables within this tidegauge_multiple
object. This is done independently for each id_dim location.

TidegaugeAnalysis.difference()

@classmethod
def TidegaugeAnalysis.difference(cls, dataset1, dataset2, absolute_diff=True, square_diff=True):

Calculates differences between two tide gauge objects datasets. Will calculate
differences, absolute differences and square differences between all
common variables within each object. Each object should have the same
sized dimensions. When calling this routine, the differencing is done
as follows:

dataset1.difference(dataset2)

This will do dataset1 - dataset2.

Output is a new tidegauge object containing differenced variables.

TidegaugeAnalysis.find_high_and_low_water()

@staticmethod
def TidegaugeAnalysis.find_high_and_low_water(data_array, method=comp, **kwargs):

Finds high and low water for a given variable.
Returns in a new TIDEGAUGE object with similar data format to
a TIDETABLE. If this Tidegauge object contains more than one location
(id_dim > 1) then a list of Tidegauges will be returned.

Methods:
'comp' :: Find maxima by comparison with neighbouring values.
                                Uses scipy.signal.find_peaks. **kwargs passed to this routine
                                will be passed to scipy.signal.find_peaks.
'cubic':: Find the maxima using the roots of cubic spline.
                                Uses scipy.interpolate.InterpolatedUnivariateSpline
                                and scipy.signal.argrelmax. **kwargs are not activated.
NOTE: Currently only the 'comp' and 'cubic' methods implemented. Future
                                methods include linear interpolation or refinements.

TidegaugeAnalysis.doodson_x0_filter()

@staticmethod
def TidegaugeAnalysis.doodson_x0_filter(dataset, var_str):

Applies doodson X0 filter to a specified TIDEGAUGE variable
Input ius expected to be hourly. Use resample_mean to average data
to hourly frequency.

TidegaugeAnalysis.crps()

@classmethod
def TidegaugeAnalysis.crps(cls, tidegauge_data, gridded_data, nh_radius=20, time_interp=linear):

Comparison of observed variable to modelled using the Continuous
Ranked Probability Score. This is done using this TIDEGAUGE object.
This method specifically performs a single-observation neighbourhood-
forecast method.

Parameters
----------
model_object (model) : Model object (NEMO) containing model data
model_var_name (str) : Name of model variable to compare.
obs_var_name (str) : Name of observed variable to compare.
nh_radius (float)                : Neighbourhood rad
cdf_type (str)                : Type of cumulative distribution to use for the
                                                                                model data ('empirical' or 'theoretical').
                                                                                Observations always use empirical.
time_interp (str)                : Type of time interpolation to use (s)
create_new_obj (bool): If True, save output to new TIDEGAUGE obj.
                                                                                Otherwise, save to this obj.

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

Example Useage
-------
# Compare modelled 'sossheig' with 'ssh' using CRPS
crps = altimetry.crps(nemo, 'sossheig', 'ssh')

TidegaugeAnalysis.time_mean()

@classmethod
def TidegaugeAnalysis.time_mean(cls, dataset, date0=None, date1=None):

Time mean of all variables between dates date0, date1

TidegaugeAnalysis.time_std()

@classmethod
def TidegaugeAnalysis.time_std(cls, dataset, date0=None, date1=None):

Time st. dev of variable var_str between dates date0 and date1

TidegaugeAnalysis.time_slice()

@classmethod
def TidegaugeAnalysis.time_slice(cls, dataset, date0=None, date1=None):

None

TidegaugeAnalysis.resample_mean()

@classmethod
def TidegaugeAnalysis.resample_mean(cls, dataset, time_freq, **kwargs):

Resample a TIDEGAUGE variable in time by calculating the mean
                of all data points at a given frequency.

Parameters
----------
time_freq (str) : Time frequency. e.g. '1H' for hourly, '1D' for daily
                                                                Can also be a timedelta object. See Pandas resample
                                                                method for more info.
**kwargs (other) : Other arguments to pass to xarray.Dataset.resample
(http://xarray.pydata.org/en/stable/generated/xarray.Dataset.resample.html)

Returns
-------
New Tidegauge() object containing resampled data

Feedback

Was this page helpful?

Glad to hear it!

Sorry to hear that. Please tell us how we can improve.

Last modified November 23, 2022: Updated docstrings from coast repo. (9daee18)