Package {TrendSLR}

TrendSLR: A package providing improved techniques to estimate mean sea level (trend), velocity and acceleration from sea level records.

Description

The “TrendSLR” package provides improved estimates of mean sea level (trend) and associated real-time velocities and accelerations from individual, annual average ocean water level data records. Improved trend estimates are based on Singular Spectrum Analysis (SSA) methods. Various gap-filling options are included to accommodate incomplete time series records along with a range of diagnostic tools to investigate the SSA decomposition of the time series. A wide range of screen and plot to file options are available within the package.

TrendSLR functions

The msl.trend function is one of the key functions of the package deconstructing annual average time series into a trend and associated velocities and accelerations, filling necessary internal structures which facilitate all functions in this package. The fixed settings built into this function are based on the detailed research and development summarised in Watson (2016a,b; 2018).

The custom.trend function is the other key function which permits customisation of key input parameters to enable improved isolation of trend components (mean sea level) and estimated associated velocities and accelerations. This function provides more flexibility for the expert analyst than the msl.trend function with fixed inbuilt parameterisation.

Author(s)

Maintainer: Phil Watson philwatson.slr@gmail.com

References

Watson, P.J., 2016a. Identifying the best performing time series analytics for sea-level research. In: Time Series Analysis and Forecasting, Contributions to Statistics, pp. 261-278, ISBN 978-3-319-28725-6. Springer International Publishing.

Watson, P.J., 2016b. How to improve estimates of real-time acceleration in the mean sea level signal. In: Vila-Concejo, A., Bruce, E., Kennedy, D.M., and McCarroll, R.J. (eds.), Proceedings of the 14th International Coastal Symposium (Sydney, Australia). Journal of Coastal Research, Special Issue, No. 75, pp. 780-785. Coconut Creek (Florida), ISSN 0749-0208.

Watson, P.J., 2018. Improved Techniques to Estimate Mean Sea Level, Velocity and Acceleration from Long Ocean Water Level Time Series to Augment Sea Level (and Climate Change) Research. PhD Thesis, University of New South Wales, Sydney, Australia.

Ocean water level data for Baltimore, USA

Description

Annual average ocean water level data from Permanent Service for Mean Sea Level (Holgate et al., 2013).

Usage

data(Balt)

Format

Time series data file with the first column the year and the second column the corresponding annual average ocean water level (in millimetres). File contains 115 records spanning the period from 1904 to 2018 with a single missing value in 1990.

Details

The raw (*.csv) form of this data set when converted to a time series object (refer ts) is used extensively in the examples throughout this manual.

Source

Permanent Service for Mean Sea Level

References

Holgate, S.J., Matthews, A., Woodworth, P.L., Rickards, L.J., Tamisiea, M.E., Bradshaw, E., Foden, P.R., Gordon, K.M., Jevrejeva, S. and Pugh, J., 2013. New data systems and products at the Permanent Service for Mean Sea Level. Journal of Coastal Research, 29(3), pp. 493-504.

See Also

custom.trend, gap.fillview, msl.trend, msl.fileplot, msl.screenplot, summary, s, t.

Examples

data(Balt) # typical data file structure
ts1 <- ts(Balt[2], start = Balt[1, 1]) # convert to time series object
plot(ts1, type = "l", xlab = "Year", ylab = "Annual Average Mean Sea Level (mm)",
main = 'BALTIMORE, USA')
str(Balt) # check structure of data file

Diagnostic tools to inspect SSA decomposition for mean sea level records.

Description

Diagnostic tools to inspect SSA decomposition for mean sea level records.

Usage

check.decomp(
  object,
  station_name = " ",
  option = 1,
  comps = " ",
  trend = c(1),
  DOF = " ",
  wdir = " ",
  save_file = "FALSE"
)

Arguments

Details

This function provides a range of visual diagnostic tools to screen check SSA decomposition of the time series prior to undertaking the customised trend analysis (refer custom.trend). This function permits inspection of the components from the SSA decomposition to inform selection of appropriate components to comprise the trend and to optimise selection of the degrees of freedom (DOF) for the fitted cubic smoothing spline which estimates velocity and acceleration for use in custom.trend.

Value

No return value. Called for side effects, including diagnostic screen plots and optional CSV file outputs when save_file = TRUE. The function invisibly returns NULL.

References

Watson, P.J., 2018. Improved Techniques to Estimate Mean Sea Level, Velocity and Acceleration from Long Ocean Water Level Time Series to Augment Sea Level (and Climate Change) Research. PhD Thesis, University of New South Wales, Sydney, Australia.

See Also

custom.trend, ts, gap.fillview, ssa, spec.pgram.

Examples

# -------------------------------------------------------------------------
# View application of different diagnostic tools for Baltimore mean sea level record.
# -------------------------------------------------------------------------

data(Balt) # Baltimore mean sea level record
ts1 <- ts(Balt[2], start = Balt[1, 1]) # create time series input object

g <- gap.fillview(ts1, station_name = "Baltimore", fillgaps = 1) # SSA filled gap

check.decomp(g, option = 3) # check screen plot, default settings
check.decomp(g, option = 3, comps = 10) # check screen plot
check.decomp(g, option = 4) # check screen plot
check.decomp(g, option = 5) # check screen plot, default settings
check.decomp(g, option = 5, trend = c(1,2), DOF = 20) # check screen plot
check.decomp(g, option = 5, trend = c(1,2,3), DOF = 30) # check screen plot

Isolate trend component from mean sea level records via customised input parameters and analysis

Description

Isolate trend component from mean sea level records via customised input parameters and analysis

Usage

custom.trend(
  object,
  station_name = " ",
  iter = 10000,
  trend = c(1),
  DOF = " ",
  vlm = " ",
  plot = "TRUE",
  wdir = " ",
  save_summary = "FALSE"
)

Arguments

Details

This function permits the customisation of key input parameters to enable improved isolation of trend components (mean sea level) and estimated associated velocities and accelerations. This function provides more flexibility for the expert analyst than the msl.trend function which has fixed inbuilt parameterisation based on the recommendations espoused in Watson (2018). The selection of the "trend" and "DOF" parameters would be undertaken following diagnostic analysis of the input time series via the check.decomp function. The trend is isolated using Singular Spectrum Analysis, in particular, aggregating components whose spectral energy in the low frequency bands exhibit trend-like characteristics. Associated velocities and accelerations are determined through the fitting of a cubic smoothing spline to the trend.

Value

An object of class “custom.trend” is returned with the following elements:

$Station.Name:

the name of the data record.

$Summary:

a summary data frame of the relevant attributes relating to the trend and the inputted annual average data set, including:

• $Year: input data;

• $MSL: input data;

• $Trend: mean sea level trend;

• $TrendSD: standard deviation of the determined mean sea level trend;

• $Vel: relative velocity (or first derivative) of mean sea level trend (mm/year);

• $VelSD: standard deviation of the velocity of the mean sea level trend;

• $Acc: acceleration (or second derivative) of mean sea level trend (mm/year/year);

• $AccSD: standard deviation of the acceleration of the mean sea level trend;

• $Resids: time series of uncorrelated residuals; and

• $FilledTS: gap-filled time series (where necessary).

• $VelGeo: geocentric velocity (or first derivative) of mean sea level trend (mm/year)(only where vertical land motion has been supplied).

$Relative.Velocity:

outputs the peak relative velocity and the year in which it occurred.

$Vertical.Land.Motion:

outputs the vertical land motion used to convert relative to geocentric velocity (user supplied input).

$Geocentric.Velocity:

outputs the peak geocentric velocity and the year in which it occurred (if vertical land motion supplied).

$Acceleration:

outputs the peak acceleration and the year in which it occurred.

$Record.Length:

outputs details of the start, end and length of the input data set.

$Fillgaps:

outputs the extent of missing data (years) in the original record and the gap filling method used (where necessary).

$Bootstrapping.Iterations:

outputs the number of iterations used to generate the respective standard deviations for error margins.

$Changepoints:

outputs the number and time at which changepoints in the variance of the uncorrelated residuals occur (if any). Where changepoints are identified, block bootstrapping procedures are used with residuals quarantined between changepoints.

$Trend.Components:

outputs the components from the SSA decomposition of the original time series used to estimate the trend.

$DOF.Fitted.Spline:

outputs the degrees of freedom used to fit the cubic smoothing spline to the trend in order to estimate velocity and acceleration.

References

Chambers, D.P., Merrifield, M.A., and Nerem, R.S., 2012. Is there a 60 year oscillation in global mean sea level? Geophysical Research Letters, 39(18).

Minobe, S., 1999. Resonance in bidecadal and pentadecadal climate oscillations over the North Pacific: Role in climatic regime shifts. Geophysical Research Letters, 26(7), pp.855-858.

Watson, P.J., 2018. Improved Techniques to Estimate Mean Sea Level, Velocity and Acceleration from Long Ocean Water Level Time Series to Augment Sea Level (and Climate Change) Research. PhD Thesis, University of New South Wales, Sydney, Australia.

See Also

msl.trend, gap.fillview, check.decomp, t, ts, msl.fileplot, msl.screenplot, summary, Balt.

Examples

data(Balt) # Baltimore mean sea level record
ts1 <- ts(Balt[2], start = Balt[1, 1]) # create time series input object
g <- gap.fillview(ts1, station_name = "Baltimore", fillgaps = 1) # SSA gap fill
t <- custom.trend(g, station_name = "Baltimore (USA)", iter = 500, trend = c(1,2),
vlm = 0.6)

data(t)
str(t) # check structure of object

Inspect gap-filling options for mean sea level records.

Description

Inspect gap-filling options for mean sea level records.

Usage

gap.fillview(object, station_name = " ", fillgaps = 1)

Arguments

Details

This function permits visual screen checking of various gap-filling options prior to undertaking the full trend analysis (refer msl.trend). The returned object can also be used directly as input to the custom.trend function.

Value

An object of class “gap.fillview” is returned with the following elements:

$Station.Name:

the name of the data record.

$Summary:

a summary data frame of relevant parameters relating to the inputted annual average data set and filled time series, including:

• $Year: input data;

• $MSL: input data;

• $FilledTS: gap-filled time series.

$Fillgaps:

the procedure used to fill the time series.

References

Chambers, D.P., Merrifield, M.A., and Nerem, R.S., 2012. Is there a 60 year oscillation in global mean sea level? Geophysical Research Letters, 39(18).

Minobe, S., 1999. Resonance in bidecadal and pentadecadal climate oscillations over the North Pacific: Role in climatic regime shifts. Geophysical Research Letters, 26(7), pp.855-858.

Watson, P.J., 2018. Improved Techniques to Estimate Mean Sea Level, Velocity and Acceleration from Long Ocean Water Level Time Series to Augment Sea Level (and Climate Change) Research. PhD Thesis, University of New South Wales, Sydney, Australia.

See Also

msl.trend, igapfill, na.approx, na.interpolation, na.ma, ts.

Examples

# -------------------------------------------------------------------------
# View different options for filling the Baltimore annual mean sea level record.
# -------------------------------------------------------------------------

data(Balt) # Baltimore mean sea level record
ts1 <- ts(Balt[2], start = Balt[1, 1]) # create time series input object

g <- gap.fillview(ts1, station_name = "Baltimore", fillgaps = 1) # SSA
g <- gap.fillview(ts1, station_name = "Baltimore", fillgaps = 2) # Linear interpolation
g <- gap.fillview(ts1, station_name = "Baltimore", fillgaps = 3) # Cubic spline interpolation
g <- gap.fillview(ts1, station_name = "Baltimore", fillgaps = 4) # Stineman's interpolation
g <- gap.fillview(ts1, station_name = "Baltimore", fillgaps = 5) # Weighted moving average

str(g) # Check structure of outputted object

Plotting to file options in JPEG format.

Description

Plotting to file options in JPEG format.

Usage

msl.fileplot(
  x,
  resol = 1800,
  wdir = " ",
  file_name = " ",
  type = 1,
  ci = 1,
  header = TRUE
)

Arguments

Details

This function provides report quality JPEG format summary plots for both “msl.trend” (see msl.trend) and “custom.trend” (see custom.trend) objects. The same range of alternative screen plotting options are available via msl.screenplot.

Value

No return value. Called for side effects, including creation of JPEG files in the specified directory. The function invisibly returns NULL.

See Also

msl.trend, custom.trend, msl.screenplot

Examples

# Plot to file from "custom.trend" object

data(t) # "custom.trend" object
str(t) # check object

# -------------------------------------------------------------------------
# The following call to msl.fileplot can be found in the temporary
# directory under the file name "Plot1.jpeg".
# -------------------------------------------------------------------------

wd <- tempdir() # find temp directory
msl.fileplot(t, wdir = wd) # default screen plot output

Plotting to filescreen options.

Description

Plotting to filescreen options.

Usage

msl.screenplot(x, type = 1, ci = 1)

Arguments

Details

This function provides summary plots direct to the screen for both “msl.trend” (see msl.trend) and “custom.trend” (see custom.trend) objects. The same range of alternative plotting to file options (in JPEG format) are available via msl.fileplot.

Value

No return value. Called for side effects, including creation of summary plots displayed on the screen. The function invisibly returns NULL.

See Also

msl.trend, custom.trend, msl.fileplot

Examples

# Plot to screen from "msl.trend" object

data(s) # "msl.trend" object
str(s) # check object

msl.screenplot(s) # default screen plot output, 3 panels, 95% confidence intervals
msl.screenplot(s, type=2) # plot time series, 95% confidence intervals
msl.screenplot(s, type=3) # plot velocity, 95% confidence intervals
msl.screenplot(s, type=4, ci=2) # plot acceleration, 99% confidence intervals
msl.screenplot(s, type=5, ci=2) # 2 panels, 99% confidence intervals

Isolate trend component from mean sea level records.

Description

Isolate trend component from mean sea level records.

Usage

msl.trend(
  object,
  station_name = " ",
  fillgaps = 1,
  iter = 10000,
  vlm = " ",
  plot = TRUE,
  wdir = " ",
  save_summary = "TRUE"
)

Arguments

Details

This function deconstructs annual average time series data into a trend and associated velocities and accelerations, filling necessary internal structures to facilitate all other functions in this package. The trend is isloated using Singular Spectrum Analysis, in particular, aggregating components whose low frequency band 0-0.01 exceed a threshold contribution of 75\ velocities and accelerations are determined through the fitting of a cubic smoothing spline to the trend with 1 degree of freedom per every 8 years of record length. The fixed settings built into this function are based on the detailed research and development summarised in Watson (2016a,b; 2018).

Value

An object of class “msl.trend” is returned with the following elements:

$Station.Name:

the name of the data record.

$Summary:

a summary data frame of the relevant attributes relating to the trend and the inputted annual average data set, including:

• $Year: input data;

• $MSL: input data;

• $Trend: mean sea level trend;

• $TrendSD: standard deviation of the determined mean sea level trend;

• $Vel: relative velocity (or first derivative) of mean sea level trend (mm/year);

• $VelSD: standard deviation of the velocity of the mean sea level trend;

• $Acc: acceleration (or second derivative) of mean sea level trend (mm/year/year);

• $AccSD: standard deviation of the acceleration of the mean sea level trend;

• $Resids: time series of uncorrelated residuals; and

• $FilledTS: gap-filled time series (where necessary).

• $VelGeo: geocentric velocity (or first derivative) of mean sea level trend (mm/year)(only where vertical land motion has been supplied).

$Relative.Velocity:

outputs the peak relative velocity and the year in which it occurred.

$Vertical.Land.Motion:

outputs the vertical land motion used to convert relative to geocentric velocity (user supplied input).

$Geocentric.Velocity:

outputs the peak geocentric velocity and the year in which it occurred (if vertical land motion supplied).

$Acceleration:

outputs the peak acceleration and the year in which it occurred.

$Record.Length:

outputs details of the start, end and length of the input data set.

$Fillgaps:

outputs the extent of missing data (years) in the original record and the gap filling method used (where necessary).

$Bootstrapping.Iterations:

outputs the number of iterations used to generate the respective standard deviations for error margins.

$Changepoints:

outputs the number and time at which changepoints in the variance of the uncorrelated residuals occur (if any). Where changepoints are identified, block bootstrapping procedures are used with residuals quarantined between changepoints.

References

Chambers, D.P., Merrifield, M.A., and Nerem, R.S., 2012. Is there a 60 year oscillation in global mean sea level? Geophysical Research Letters, 39(18).

Minobe, S., 1999. Resonance in bidecadal and pentadecadal climate oscillations over the North Pacific: Role in climatic regime shifts. Geophysical Research Letters, 26(7), pp.855-858.

Watson, P.J., 2016a. Identifying the best performing time series analytics for sea-level research. In: Time Series Analysis and Forecasting, Contributions to Statistics, pp. 261-278, ISBN 978-3-319-28725-6. Springer International Publishing.

Watson, P.J., 2016b. How to improve estimates of real-time acceleration in the mean sea level signal. In: Vila-Concejo, A., Bruce, E., Kennedy, D.M., and McCarroll, R.J. (eds.), Proceedings of the 14th International Coastal Symposium (Sydney, Australia). Journal of Coastal Research, Special Issue, No. 75, pp. 780-785. Coconut Creek (Florida), ISSN 0749-0208.

Watson, P.J., 2018. Improved Techniques to Estimate Mean Sea Level, Velocity and Acceleration from Long Ocean Water Level Time Series to Augment Sea Level (and Climate Change) Research. PhD Thesis, University of New South Wales, Sydney, Australia.

See Also

custom.trend, gap.fillview, check.decomp, s, ts, msl.fileplot, msl.screenplot, summary, Balt, na.approx, na.interpolation, na.ma.

Examples

data(Balt) # Baltimore mean sea level record
ts1 <- ts(Balt[2], start = Balt[1, 1]) # create time series input object
s <- msl.trend(ts1, fillgaps = 3, iter = 500, 'BALTIMORE, USA')

data(s)
str(s) # check structure of object
msl.screenplot(s) # check screen output

sample 'msl.trend' object

Description

Output of call to msl.trend used in examples throughout this Manual.

Usage

data(s)

Format

msl.trend object

Details

This msl.trend object is used extensively in the examples throughout this manual in order to call the object direct rather than producing the same via original code which can be computationally expensive. This object results from a decomposition of the Baltimore (USA) record, filling gaps with spline interpolation and using 500 iterations to generate error margins via bootstrapping.

Note: Ordinarily the user would first create an annaul average time series object from the data, to then create an msl.trend object using the general form of sample code advised in the example (see below).

See Also

msl.trend, msl.fileplot, msl.screenplot, summary, Balt.

Examples

data(Balt) # Baltimore mean sea level record
ts1 <- ts(Balt[2], start = Balt[1, 1]) # create time series input object
s <- msl.trend(ts1, fillgaps = 3, iter = 500, 'BALTIMORE, USA')

data(s)
str(s) # check structure of object
msl.screenplot(s) # check screen output

Summary outputs of decomposed time series.

Description

Summary outputs of decomposed time series.

Usage

summary(object, wdir = " ", save_summary = "FALSE")

Arguments

Details

This routine provides a screen summary of the respective outputs from a msl.trend or custom.trend object. The summary produced is identical to str( ) for an object of class “msl.trend” (see msl.trend) or “custom.trend” (see custom.trend).

Value

Invisibly returns the input object after printing a structured summary to the console. If save_summary = TRUE, the printed summary is also written to a text file in the specified directory.

See Also

msl.trend, custom.trend, Balt, s, t.

Examples

data(s) # msl.trend object
data(t) # custom.trend object
summary(s) # summary for object of class 'msl.trend'
summary(t) # summary for object of class 'custom.trend'

sample 'custom.trend' object

Description

Output of call to custom.trend used in examples throughout this Manual.

Usage

data(t)

Format

custom.trend object

Details

This custom.trend object is used extensively in the examples throughout this manual in order to call the object direct rather than producing the same via original code which can be computationally expensive. This object results from a decomposition of the Baltimore (USA) record, filling gaps firstly with the default SSA option in the gap.fillview function. The gap.fillview object has then been used to otimise the trend and DOF settings via the check.decomp function. The custom.trend function is then applied with the desired settings.

Note: The above-mentioned workflow is used to create the custom.trend object using the general form of sample code advised in the example (see below).

See Also

custom.trend, msl.fileplot, msl.screenplot, summary, Balt.

Examples

data(Balt) # Baltimore mean sea level record
ts1 <- ts(Balt[2], start = Balt[1, 1]) # create time series input object
g <- gap.fillview(ts1, station_name = "Baltimore", fillgaps = 1) # SSA gap fill
t <- custom.trend(g, station_name = "Baltimore (USA)", iter = 500, trend = c(1,2),
vlm = 0.6)

data(t)
str(t) # check structure of object