sta (version 0.1.7)

sta: Statistical Seasonal Trend Analysis for numeric vector or RasterStack

Description

Statistical Seasonal Trend Analysis for numeric vector or RasterStack

Usage

sta(
  data,
  freq,
  numFreq = 4,
  delta = 0,
  startYear = 2000,
  endYear = 2018,
  intraAnnualPeriod = c("wetSeason", "drySeason"),
  interAnnualPeriod,
  adhocPeriod = NULL,
  significance = NULL,
  save = FALSE,
  dirToSaveSTA = NULL,
  numCores = 20
)

Arguments

data

numeric vector, matrix or RasterStack object

freq

integer with the number of observations per period. See Details

numFreq

integer with the number of frequencies to employ in harmonic regression fitting. See haRmonics

delta

numeric (positive) controlling regularization and prevent non-invertible hat matrix in harmonic regression model. See haRmonics

startYear

numeric, time series initial year

endYear

numeric, time series last year

intraAnnualPeriod

character indicating seasons (wet or dry) to be considered for additional statistical analysis. See Details

interAnnualPeriod

numeric vector indicating the number of years to be considered in STA. For instance, 1:5, indicates that the first five years will be utilized for STA. Similarly, c(2,6,10) indicates that the second, sixth and tenth years will be utilized for STA. See Details

adhocPeriod

numeric vector with the specific observations to be considered in additional statistical analysis. See Details

significance

numeric in the interval (0,1) to assess statistical significance of trend analysis. NULL by default.

save

logical, should STA output be saved, default is FALSE

dirToSaveSTA

character with full path name used to save sta progress report. When save = TRUE, sta's output is saved on this path.

numCores

integer given the number of cores to use; pertinent when data is a RasterStack or a matrix

Value

When class(data) is a numeric, an object of class "staNumeric" containing:

data

numeric vector

freq

integer with the number of observations per period

startYear

numeric, time series initial year

endYear

numeric, time series last year

intraAnnualPeriod

character indicating seasons (wet or dry)

interAnnualPeriod

numeric vector indicating the number of years considered in STA

ts

time series object; data in ts format

fit

numeric vector with output of haRmonics

sta

a list containing the following elements:

mean a list of 12 elements with STA output for shape parameter mean annual a list of 12 elements with STA output for shape parameter annual semiannual a list of 12 elements with STA output for shape parameter semiannual

significance

numeric in the interval (0,1) or NULL when default used

When class(data) is a RasterStack or a matrix, an object of class "staMatrix" containing:

freq

integer with the number of observations per period

daysUsedFit

integer vector indicating the indices used to fit harmonic regression. see haRmonics

intervalsUsedBasicStats

numeric vector indicating the indices used on calculation of basic statistics

sta

a list containg the following elements:

mean a matrix of 4 columns with STA output for shape parameter mean. First two columns provide geolocation of analyzed pixels, third and fourth columns show p-value and slope estimate of STA, respectively mean_basicStats a matrix of 10 columns with basic statistics for shape parameter mean. First two columns provide geolocation of analyzed pixels, from third to tenth columns show mean, standard deviation, global minimum, and maximum of minimum values, as well as mean, standard deviation, global minimum, and maximum of maximum values, respectively annual a matrix of 4 columns with STA output for shape parameter annual. First two columns provide geolocation of analyzed pixels, third and fourth columns show p-value and slope estimate of STA, respectively annual_basicStats a matrix of 10 columns with basic statistics for shape parameter annual. First two columns provide geolocation of analyzed pixels, from third to tenth columns show mean, standard deviation, global minimum, and maximum of minimum values, as well as mean, standard deviation, global minimum, and maximum of maximum values, respectively semiannual a matrix of 4 columns with STA output for shape parameter semiannual. First two columns provide geolocation of analyzed pixels, third and fourth columns show p-value and slope estimate of STA, respectively semiannual_basicStats a matrix of 10 columns with basic statistics for shape parameter semiannual. First two columns provide geolocation of analyzed pixels, from third to tenth columns show mean, standard deviation, global minimum, and maximum of minimum values, as well as mean, standard deviation, global minimum, and maximum of maximum values, respectively

Details

When the input is a matrix, its first two columns must correspond to geographic coordinates. For instance, the matrix resulting from applying rasterToPoints to a RasterStack has this format.

freq must be either 12 (monthly observations), 23 (Landsat annual scale) or 36 (10-day composite) as this version implements STA for time series with these frequencies.

This version sets intraAnnualPeriod to either the wetSeason or the drySeason of Mexico. Empirical evidence suggests that while wet season runs from May to October, dry season runs from November to April. Should a desired STA require specific months/days, these must be provided through adhocPeriod.

When interAnnualPeriod is not specified and class(data)=numeric, interAnnualPeriod = 1:(length(data)/freq); when class(data) is either RasterStack or matrix, interAnnualPeriod = 1:((ncol(data)-2)/freq).

Since adhocPeriod defines an inter annual period "ad-hoc", the specific days of this ad-hoc season must be known in advance and consequently, the specific time-points (with respect to the time series under consideration) must be provided in a numeric vector.

When save=T, a valid dirToSaveSTA must be provided, that is, this folder should have been created previously. In this case, sta's output is saved on dirToSaveSTA. This version saves arrays of STA of the mean, annual and semi-annual parameters (along with their corresponding basic statistics) in the file sta_matrix_output.RData inside dirToSaveSTA. Also, in the same directory, the file sta_progress.txt records the progress of the STA process.

save=T, dirToSaveSTA, numCores and master are required when data is either a RasterStack or a matrix. The aforementioned basic statistics are: mean and standard deviation of the time series of annual maximum and minimum as well as the global minima and maxima.

References

Eastman, R., Sangermano, F., Ghimine, B., Zhu, H., Chen, H., Neeti, N., Cai, Y., Machado E., Crema, S. (2009). Seasonal trend analysis of image time series, International Journal of Remote Sensing, 30(10), 2721--2726.

Examples

# NOT RUN {
sta_marismas <- sta(data=marismas, freq=36)
str(sta_marismas)
plot(sta_marismas)
plot(sta_marismas, significance=0.09)

# Use of interAnnualPeriod
sta_21016 <- sta(data = marismas, freq = 36, interAnnualPeriod = c(2, 10, 16))
plot(sta_21016)

# Use of intraAnnualPeriod
sta_drySeason_218 <- sta(data = marismas, freq = 36,
                     interAnnualPeriod = 2:18, intraAnnualPeriod = "drySeason")
plot(sta_drySeason_218)

# Use of adhocPeriod and significance
adhoc <- list()
beginPeriod <- (1:17) * 36
endPeriod <- 2:18 * 36 
adhoc$partial <- c( sapply(1:length(beginPeriod), 
                 function(s) c(beginPeriod[s]+1, endPeriod[s]) ) )
adhoc$full <- c( sapply(1:length(beginPeriod), 
              function(s) (beginPeriod[s]+1):endPeriod[s]) )
sta_adhoc_218 <- sta(data = marismas, freq = 36, interAnnualPeriod = 2:18,
                 startYear = 2000, endYear = 2018, adhocPeriod = adhoc, significance=0.05)
plot(sta_adhoc_218)

# Use of ndmi RasterStack
# }
# NOT RUN {
ndmi_path = system.file("extdata", "ndmi.tif", package = "sta")
ndmiSTACK <- stack(ndmi_path)
dir.create(path=paste0(system.file("extdata", package="sta"), "/output_ndmi"),
          showWarnings=FALSE)
outputDIR = paste0(system.file("extdata", package="sta"), "/output_ndmi")

sta_ndmi_21016 <- sta(data = ndmiSTACK, freq = 36,
                  numFreq = 4, delta = 0.2, intraAnnualPeriod = "wetSeason",
                  startYear = 2000, endYear = 2018, interAnnualPeriod = c(2,10,16),
                  save = TRUE, numCores = 2L, dirToSaveSTA = outputDIR)
# }
# NOT RUN {
 
# }