Package 'TrendSLR'

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 (2019)

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

object	an annual average mean sea level time series (refer ts) with water levels (in millimetres). Objects of class "gap.fillview" can also be parsed directly to this function (refer gap.fillview). Warning: Input data files are not permitted to contain missing values in order to perform necessary Singular Spectrum Analysis (SSA) or other spectral functions. If the input files contain missing data, the analysis will be terminated. For this reason, this function permits the direct use of objects from the gap.fillview function. Similarly, the analysis will be terminated if input files are less than 30 years in length. Whilst it is not generally recommended to use time series less than 80 years in length for mean sea level analyses (Watson, 2018)(and a warning will appear accordingly), it is recognised that this collection of diagnostic tools are valuable for decomposing and understanding the type of signals present in shorter datasets.
station_name	character string, providing the name of the data record. Note: This field can be left blank, however, it is retained for use in banner labelling of plotting and associated outputs.
option	numeric, provides a range of diagnostic tools for inspecting mean sea level time series. Available options include: 1: A tabular summary is displayed of the spectral density distribution within each component from an SSA decomposition of the time series (refer ssa with default settings). Values are based on a spectogram of individual components (refer spec.pgram). This table can be used to readily identify the frequency bands associated with the peak spectral density for each component. Trends are readily identfiable as components in which the peak spectral density resides in the lowest frequency band. This tabular summary can be exported direct to the working directory by setting the "save_file" argument to "TRUE" where the file will be saved as "spec_summary.csv". Option 1 is the default setting; 2: A tabular summary is displayed based on the spectral density distribution observed via Option 1 (above) converted to percentages which are based on the sum of the spectral density for each component. This analysis can be used to gain an insight into the proportion of energy residing in each frequency band for each component. This tabular summary can be exported direct to the working directory by setting the "save_file" argument to "TRUE" where the file will be saved as "spec_summary_percent.csv"; 3: A screen plot of the components from the SSA decomposition. A tabular summary of the component time series can be exported direct to the working directory by setting the "save_file" argument to "TRUE" where the file will be saved as "comps_timeseries.csv"; 4: A screen plot of the relative contribution of each component from the SSA decomposition in the low frequency band [0-0.01]. A tabular summary of the relative contributions can be exported direct to the working directory by setting the "save_file" argument to "TRUE" where the file will be saved as "low_freq_contributions.csv"; 5: A screen plot to look at the sensitivity of the smoothing parameter for the cubic smoothing spline fitted to the trend in order to estimate mean sea level velocity and acceleration over the length of the record. The function requires the trend components to be advised via the "trend" argument and similarly, the degrees of freedom for the fitted spline to be input via the "DOF" argument. Defaults are provided for both the "trend" and "DOF" if not supplied. Refer further details on each argument. A tabular summary of the time series of both the trend and the fitted smooth spline can be exported direct to the working directory by setting the "save_file" argument to "TRUE" where the file will be saved as "trend_smooth.csv";
comps	numeric, enables the user to specify the number of components to be considered or displayed with this range of diagnostic tools. The default is the maximum number available within the ssa function of the Rssa package, which in turn is governed by the length of the time series (maximum possible is 50). This parameter is only used in options 1 to 3.
trend	numeric, enables the user to select the trend components directly in the form of a single component or multiple components (eg., c(1) or c(1,2,3)). The default setting is c(1) as the first component will always be trend, however, other components might also have trend characteristics which can be diagnostically observed via options 1 to 4. This parameter is only used in option 5.
DOF	numeric, enables the user to optimise the degrees of freedom for the fitted cubic smoothing spline applied to the trend. The default setting is based on 1 degree of freedom every 8 years (Watson, 2018) and this default is written to the console to enable the user to directly compare with manually entered DOF. This parameter is only used in option 5.
wdir	character string, providing the name of the directory to send output files (e.g., “C:/myproject/”) when the save_file argument is set to "TRUE". If this field is left blank the save_file argument is switched off and a message will be sent to the console.
save_file	logical, if "TRUE". Default setting is "FALSE". Refer individual option setting for detail on the respective files that are saved.

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.

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

object	an annual average mean sea level time series (refer ts) with NO missing data or an object of class "gap.fillview" (refer gap.fillview) with water levels (in millimetres). Warning: If input data files do not conform to these pre-conditions, the analysis will be terminated. It should be further noted that the existence of long period oscillations in global mean sea level have been well recognised in the literature (eg. Chambers et al. (2012); Minobe (1999)). Therefore, in order to be effective for climate change and sea level research, time series input files are recommended to have a minimum length of at least 80 years in order that the analysis can identify and isloate such signals. Time series less than 80 years in length will be analysed but a warning will be displayed. Time series less than 30 years are not permitted though.
station_name	character string, providing the name of the data record. Note: This field can be left blank, however, it is retained for use in banner labelling of graphical outputs.
iter	numeric, enables a user defined number of iterations for bootstrapping to determine error margins. The user range is [500 to 10000] where 10000 is the default setting. Warning: Although the default setting provides a more accurate basis for estimating error margins, the degree of iterations slows the analysis and can take several minutes to run.
trend	numeric, enables the user to select the trend components directly in the form of a single component or multiple components (eg., c(1) or c(1,2,3)). The default setting is c(1) as the first component will always be trend, however, other components might also have trend characteristics which can be diagnostically observed and optimised via the check.decomp function.
DOF	numeric, enables the user to optimise the degrees of freedom for the fitted cubic smoothing spline to be applied to the trend. The default setting is based on 1 degree of freedom every 8 years (Watson, 2018) and this default is written to the console to enable the user to directly compare with manually entered DOF settings. The DOF can be diagnostically observed and optimised via the check.decomp function.
vlm	numeric, enables a user defined quantum for vertical land motion in mm/year within the range [-20 to 20]. This rate is used to convert the rate of relative sea level rise to an estimate of geocentric sea level rise. Positive rates of vlm are associated with land uplift, while conversely negative rates of vlm are associated with subsidence. This can be left blank in which case only estimates of relative mean sea level will be determined.
plot	logical, if “TRUE” then the original time series is plotted to the screen along with the trend component and the result of gap filling (where necessary). 95% confidence intervals have also been applied. Default = “TRUE”.
wdir	character string, providing the name of the directory to send output files (e.g., “C:/myproject/”) when the save_summary argument is set to “TRUE”. If this field is left blank the save_summary argument is switched off and a message will be sent to the console.
save_summary	logical, if “TRUE” the object$Summary portion of the returned value is exported direct to the defined directory (wdir) and saved as "detailed_summary_output.csv". Default = “FALSE”.

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

object	an annual average mean sea level time series (refer ts) with water levels (in millimetres). Missing data must be denoted by “NA”. Missing data and maximum missing data gap are limited to 15% and 5%, respectively, of the data record. These data input constraints have been based on the research work of Watson (2018) to best preserve the integrity and primary characteristics of the data set for mean sea level analysis. To ensure maximum flexibility for the data analyst, gaps beyond these margins are permitted to be filled but a warning will appear at the console when these advised limits are exceeded. Warning: If input data files do not conform to these pre-conditions, the analysis will be terminated. It should be further noted that the existence of long period oscillations in global mean sea level have been well recognised in the literature (eg. Chambers et al. (2012); Minobe (1999)). Therefore, in order to be effective for climate change and sea level research, time series input files are recommended to have a minimum length of at least 80 years in order that the analysis can identify and isloate such signals. Time series less than 80 years in length will be analysed but a warning will be displayed.
station_name	character string, providing the name of the data record. Note: This field can be left blank, however, it is retained for use in banner labelling of all plotting and pdf outputs.
fillgaps	numeric, provides 5 alternative gap filling procedures for missing data. The following options are available: 1: The default procedure is based on iterative gap filling using Singular Spectrum Analysis (refer igapfill); 2: linear interpolation (refer na.approx); 3: Cubic spline interpolation (refer na.approx); 4: Stineman's interpolation (refer na.interpolation); and 5: Weighted moving average (refer na.ma). Note: Gap filled portions of the time series are denoted in red on the default screen plot. This is done specifically to provide ready visual observation to discern if the selected gap filling method provides an appropriate estimate within the gaps in keeping with the remainder of the historical record. Depending on the nature of the record and extent of gaps, some trial and error between alternatives might be necessary to optimise gap filling.

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

x	object of class “msl.trend” (see msl.trend) or “custom.trend” (see custom.trend).
resol	numeric, enables a user defined resolution in dpi from [300 to 1800] where 1800 is the default setting.
wdir	character string, providing the name of the directory to send output files (e.g., “C:/myproject/”). If this field is left blank the function will terminate with a warning message sent to the console.
file_name	is a character string indicating the name of the output file. There is no need to include the file extension *.jpeg. If this field is left blank the output file will be automatically saved in the defined directory (wdir) under the default name “Plot1.jpeg”.
type	numeric, enables a user defined input to select the type of chart to be plotted. 5 seperate options are available: 1: The default setting provides a single 3 panel chart with the time series in the top panel, velocity in the middle panel and acceleration in the bottom panel (width = 160 mm, height = 210 mm); 2: Single panel plot of time series (width = 160 mm, height = 80 mm); 3: Single panel plot of velocity (width = 160 mm, height = 80 mm); 4: Single panel plot of acceleration (width = 160 mm, height = 80 mm); and 5: Alternative 2 panel chart with the time series in the top panel and velocity in the bottom panel (width = 160 mm, height = 150 mm).
ci	numeric, enables a user defined input to select the type of confidence interval to be displayed on the plots. The default setting (ci = 1) corresponds to a 95% confidence interval whilst ci = 2 provides a 99% confidence interval.
header	logical, if ‘TRUE’ then the station_name (if provided) in the “msl.trend” (see msl.trend) or “custom.trend” (see custom.trend) object will be passed to the main banner printed above the plot. If set to ‘FALSE’ then the banner header will be excluded. Default = TRUE.

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.

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

x	object of class “msl.trend” (see msl.trend) or “custom.trend” (see custom.trend).
type	numeric, enables a user defined input to select the type of chart to be plotted. 5 seperate options are available: 1: The default setting provides a single 3 panel chart with the time series in the top panel, velocity in the middle panel and acceleration in the bottom panel; 2: Single panel plot of time series; 3: Single panel plot of velocity; 4: Single panel plot of acceleration; and 5: Alternative 2 panel chart with the time series in the top panel and velocity in the bottom panel.
ci	numeric, enables a user defined input to select the type of confidence interval to be displayed on the plots. The default setting (ci = 1) corresponds to a 95% confidence interval whilst ci = 2 provides a 99% confidence interval.

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.

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

object	an annual average mean sea level time series (refer ts) with water levels (in millimetres). Missing data and maximum missing data gap are limited to 15% and 5%, respectively, of the data record. Warning: If input data files do not conform to these pre-conditions, the analysis will be terminated. It should be further noted that the existence of long period oscillations in global mean sea level have been well recognised in the literature (eg. Chambers et al. (2012); Minobe (1999)). Therefore, in order to be effective for climate change and sea level research, time series input files are recommended to have a minimum length of at least 80 years in order that the package can identify and isloate such signals. Time series less than 80 years in length will be analysed but a warning will be displayed.
station_name	character string, providing the name of the data record. Note: This field can be left blank, however, it is retained for use in banner labelling of plotting and associated outputs.
fillgaps	numeric, provides 5 alternative gap filling procedures for missing data. The following options are available: 1: The default procedure is based on iterative gap filling using Singular Spectrum Analysis (refer igapfill); 2: linear interpolation (refer na.approx); 3: Cubic spline interpolation (refer na.approx); 4: Stineman's interpolation (refer na.interpolation); and 5: Weighted moving average (refer na.ma). Note: Gap filled portions of the time series are denoted in red on the default screen plot. This is done specifically to provide ready visual observation to discern if the selected gap filling method provides an appropriate estimate within the gaps in keeping with the remainder of the historical record. Depending on the nature of the record and extent of gaps, some trial and error between alternatives might be necessary to optimise gap filling. This is best achieved via the gap.fillview function which permits visual screen checking of various gap-filling options prior to undertaking the full trend analysis.
iter	numeric, enables a user defined number of iterations for bootstrapping to determine error margins. The user range is [500 to 10000] where 10000 is the default setting. Warning: Although the default setting provides a more accurate basis for estimating error margins, the degree of iterations slows the analysis and can take several minutes to run.
vlm	numeric, enables a user defined quantum for vertical land motion in mm/year within the range [-20 to 20]. This rate is used to convert the rate of relative sea level rise to an estimate of geocentric sea level rise. Positive rates of vlm are associated with land uplift, while conversely negative rates of vlm are associated with subsidence. This can be left blank in which case only estimates of relative mean sea level will be determined.
plot	logical, if “TRUE” then the original time series is plotted to the screen along with the trend component and the result of gap filling (where necessary). 95% confidence intervals have also been applied. Default = “TRUE”.
wdir	character string, providing the name of the directory to send output files (e.g., “C:/myproject/”) when the save_summary argument is set to "TRUE". If this field is left blank the save_summary argument is switched off and a message will be sent to the console.
save_summary	logical, if “TRUE” the object$Summary portion of the returned value is exported direct to the defined directory (wdir) and saved as "detailed_summary_output.csv". Default = “FALSE”.

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 to 0.01] exceed a threshold contribution of 75%. Associated 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

object	of class “msl.trend” (see msl.trend) or “custom.trend” (see custom.trend).
wdir	character string, providing the name of the directory to send output files (e.g., “C:/myproject/”) when the save_summary argument is set to "TRUE". If this field is left blank the save_summary argument is switched off and a message will be sent to the console.
save_summary	logical, if “TRUE” the printed summary of the returned object is exported direct to the working directory and saved as "summary_information.txt". Default = “FALSE”.

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

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

---

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.

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.

---