Package 'MultivariateTrendAnalysis' reference manual

Title:	Univariate and Multivariate Trend Testing
Description:	With foundations on the work by Goutali and Chebana (2024) <doi:10.1016/j.envsoft.2024.106090>, this package contains various univariate and multivariate trend tests. The main functions regard the Multivariate Dependence Trend and Multivariate Overall Trend tests as proposed by Goutali and Chebana (2024), as well as a plotting function that proves useful as a summary and complement of the tests. Although many packages and methods carry univariate tests, the Mann-Kendall and Spearman's rho test implementations are included in the package with an adapted version to hydrological formulation (e.g. as in Rao and Hamed 1998 <doi:10.1016/S0022-1694(97)00125-X> or Chebana 2022 <doi:10.1016/C2021-0-01317-1>). For better understanding of the example use of the functions, three datasets are included. These are synthetic data and shouldn't be used beyond that purpose.
Authors:	Dorsaf Goutali [aut, cre], Fateh Chebana [aut]
Maintainer:	Dorsaf Goutali <[email protected]>
License:	GPL (>= 3)
Version:	0.1.3
Built:	2026-05-31 08:37:11 UTC
Source:	https://github.com/cran/MultivariateTrendAnalysis

Generate Synthetic data

Description

Synthetic data generated using copulas and marginal distributions, with the purpose of exampling the functions of the package. Three options are given: "noTrend", "marginalTrend", and "dependenceStructure".

The generated "noTrend" data follows a Clayton copula with fixed Kendall Tau ( $\tau=0.2$ ). "marginalTrend", follows the same copula, however the variables follow a Generalized Extreme Value distribution with fixed scale and shape parameters ( $\sigma=1, \xi=-0.1$ ), the location is linearly non-stationary with $\mu_X = 0.05\cdot t$ and $\mu_Y = 0.07\cdot t$ . Finally "dependenceStructure" presents trend in the dependence structure, the data was generated from a Clayton copula with a linear non-stationary $\tau$ parameter. For more information we refer the reader to the source material by Goutali and Chebana (2024).

Usage

generate_data(
  trend = c("noTrend", "marginalTrend", "dependenceStructure"),
  n = 100
)
generate_data(
  trend = c("noTrend", "marginalTrend", "dependenceStructure"),
  n = 100
)

Arguments

trend

Character vector, the trend of the generated data. Options are "noTrend", "marginalTrend", and "dependenceStructure".

n

Integer, the number of data points to be generated. Must be between 10 and 200, default is 100.

Value

A dataset of dimensions $n \times 2$ with the generated data.

References

Goutali, D., and Chebana, F. (2024). Multivariate overall and dependence trend tests, applied to hydrology, Environmental Modelling & Software, 179, doi:10.1016/j.envsoft.2024.106090

Examples

# NO TREND
generate_data("noTrend", n = 50)

# TREND IN BOTH MARGINALS
generate_data("marginalTrend", n = 50)

# TREND IN DEPENDENCE STRUCTURE
generate_data("dependenceStructure", n = 50)

# NO TREND
generate_data("noTrend", n = 50)

# TREND IN BOTH MARGINALS
generate_data("marginalTrend", n = 50)

# TREND IN DEPENDENCE STRUCTURE
generate_data("dependenceStructure", n = 50)

Multivariate Dependence Trend Test

Description

Computes the test statistic for the multivariate dependence trend (MDT) test and the p-value.

Usage

MDT_test(data, width, alpha = 0.05, Nbs = 1000)
MDT_test(data, width, alpha = 0.05, Nbs = 1000)

Arguments

data

Numeric matrix, a two dimensional data set where each column is a variable.

width

Numeric value, the width to be used for the moving window algorithm. Should be bigger than 1 and smaller than the number of observations, see details.

alpha

Numeric value, significance level for the test. Must be between 0 and 1, default is 0.05

Nbs

Positive Integer, number of samples to be used for bootstrapping. Default is 1000.

Details

The multivariate dependence trend (MDT) test allows to check for trend in the data series dependence structure. The moving window technique has been employed in order to take into account the dependence evolution, represented by Kendall's $\tau$ , according to time.

The test proposes a null hypothesis of no trend, against an alternative hypothesis of a monotonic trend in the dependence structure. Goutali and Chebana (2024) propose the following test statistic:

Let $X = (x_1, x_2, ..., x_n)$ and $Y = (y_1, y_2, ..., y_n)$ be two variables of a data series, the test statistic of the MDT test is given by:

$T_{MDT}=\tau_n(\tau_{nw}(X,Y),T')$

where $\tau_n$ is the empirical version of bivariate Kendall's $\tau$ . The series of the Kendall's $\tau$ obtained through moving window with width $w$ is $\tau_{nw}(X, Y)$ , this series has length $q = n - w +1$ . $T' = (1, 2, ..., q)$ is the time order of the rolling window series.

The choice of width is a trade-off. A small $w$ increases the number of rolling windows for reliable analysis, while a large $w$ is necessary to have sufficient values to identify the dependence structure. The p-value is computed using a bootstrap procedure.

Value

Named list containing:

statistic, the MDT test statistic.
p.value, computed p-value computed using bootstrap.
result, the result of the test. If TRUE the trend is considered significant.

References

Goutali, D., and Chebana, F. (2024). Multivariate overall and dependence trend tests, applied to hydrology, Environmental Modelling & Software, 179, doi:10.1016/j.envsoft.2024.106090

Examples



# CASE 1: Only trend in the dependence structure
# Sample data:
DependenceStructure <- generate_data("dependenceStructure")

width <- 10

# Perform the mdt test:
mdt <- MDT_test(DependenceStructure, width, alpha = 0.05, Nbs = 1000)
print(mdt)


# CASE 2: Only trend in the marginal distributions
# Sample data:
MarginalTrend <- generate_data("marginalTrend")

# Perform the mdt test:
mdt <- MDT_test(MarginalTrend, width)
print(mdt)


# CASE 3: No trend
# Sample data:
NoTrend <- generate_data("noTrend")

# Perform the mdt test:
mdt <- MDT_test(NoTrend, width)
print(mdt)



# CASE 1: Only trend in the dependence structure
# Sample data:
DependenceStructure <- generate_data("dependenceStructure")

width <- 10

# Perform the mdt test:
mdt <- MDT_test(DependenceStructure, width, alpha = 0.05, Nbs = 1000)
print(mdt)


# CASE 2: Only trend in the marginal distributions
# Sample data:
MarginalTrend <- generate_data("marginalTrend")

# Perform the mdt test:
mdt <- MDT_test(MarginalTrend, width)
print(mdt)


# CASE 3: No trend
# Sample data:
NoTrend <- generate_data("noTrend")

# Perform the mdt test:
mdt <- MDT_test(NoTrend, width)
print(mdt)

Component Wise Mann-Kendall Test Statistic

Description

The functions performs the univariate Mann-Kendall test statistic to each variable of a data series.

Usage

mkComponent(data)
mkComponent(data)

Arguments

data

Numeric matrix representing the data series, each column should be a component.

Details

Let $M$ be a dataset of $m$ components and $n$ observations. The Mann-Kendall's (MK) test statistic for a variable of the dataset $M^{(u)}$ is given by:

$M^{(u)} = \sum_{1 \leq i \leq j \leq n} sgn(x_j^{(u)} - x_i^{(u)})$

where $sgn(\cdot)$ is the sign function:

$sgn(x)=\begin{cases} -1 \quad \text{if } x<0, \\ 0 \quad \text{if } x=0, \\ +1 \quad \text{if } x>0 \end{cases}$

This test statistic is normal distributed, with mean and variance:

$E(M^{(u)}) = 0$

$\text{var}(M^{(u)}) = \frac{n(n-1)(2n+5)}{18}$

Value

A numeric vector with the univariate MK test statistic for each component of the data series.

References

Hamed, K.H., Rao, A.R., 1998. A modified Mann-Kendall trend test for autocorrelated data. J. Hydrol. 204 (1–4), 182–196.
Kendall, M., (1975). Rank Correlation Methods; Griffin: London.

Examples

# Sample data (Both marginal distributions have trend):
dataMarginalTrend <- generate_data("marginalTrend", n = 50)

# Perform multivariate MK test on sample data:
mkComponent(dataMarginalTrend)

# Sample data (Both marginal distributions have trend):
dataMarginalTrend <- generate_data("marginalTrend", n = 50)

# Perform multivariate MK test on sample data:
mkComponent(dataMarginalTrend)

Univariate Mann-Kendall Test

Description

The functions performs the univariate Mann-Kendall test.

Usage

mkUnivariate(x)
mkUnivariate(x)

Arguments

x

Numeric vector representing a data series.

Details

The univariate Mann-Kendall (MK) test is used to detect monotonic trends in a univariate data series. It tests the null hypothesis ( $h_0$ ) of no trend, against an alternative.

Let $(x_1, x_2, ..., x_n)$ be a data series of length $n$ , the MK test statistic is given by:

$M = \sum_{i=1}^{n-1} \sum_{j=i+1}^{n} sgn(x_j-x_i)$

where $sgn(\cdot)$ is the sign function:

$sgn(x)=\begin{cases} -1 \quad \text{if } x<0, \\ 0 \quad \text{if } x=0, \\ +1 \quad \text{if } x>0 \end{cases}$

Under $H_0$ the test statistic is asymptotically normally distributed with mean and variance:

$E(M) = 0$

$\text{Var}(M)=\frac{n(n-1)(n+5)}{18}$

Value

A named list

statistic, the estimated Mann-Kendall test statistics.
p.value, the estimated p-value for the test.

References

Hamed, K.H., Rao, A.R., 1998. A modified Mann-Kendall trend test for autocorrelated data. J. Hydrol. 204 (1–4), 182–196.
Kendall, M., (1975). Rank Correlation Methods; Griffin: London.

Examples

# Sample data (Both marginal distributions have trend):
dataMarginalTrend <- generate_data("marginalTrend", n = 50)

# Perform two tailed MK test on sample data:
mkUnivariate(dataMarginalTrend[, 1])
mkUnivariate(dataMarginalTrend[, 2])

# Sample data (Both marginal distributions have trend):
dataMarginalTrend <- generate_data("marginalTrend", n = 50)

# Perform two tailed MK test on sample data:
mkUnivariate(dataMarginalTrend[, 1])
mkUnivariate(dataMarginalTrend[, 2])

Multivariate Overall Trend Test

Description

Computes the test statistic for the multivariate overall trend (MOT) test and the p-value.

Usage

MOT_test(data, covar = NULL, width, alpha = 0.05, Nbs = 1000)
MOT_test(data, covar = NULL, width, alpha = 0.05, Nbs = 1000)

Arguments

data

Numeric matrix, a two dimensional data set where each column is a variable of the series.

covar

Numeric vector, time order of the data series. If none given $covar = 1, 2, ..., n$ .

width

Integer, the width to be used for the moving window algorithm. Should be bigger than 1 and smaller than the number of observations, see details.

alpha

Numeric value, significance level for the test. Must be between 0 and 1, default is 0.05

Nbs

Positive Integer, number of samples to be used for bootstrapping. Default is 1000.

Details

The multivariate overall trend (MOT) test allows to check for trend in the marginals and dependence structure of a multivariate distribution. The moving window technique has been employed in order to take into account the dependence evolution, represented by Kendall's $\tau$ , according to time.

The test evaluates a null hypothesis of no trend in the data series, against an alternative hypothesis of a monotonic trend. Goutali and Chebana (2024) propose the following test statistic:

Let $X = (x_1, x_2, ..., x_n)$ and $Y = (y_1, y_2, ..., y_n)$ be variables in a data series, and $T$ the time order, the test statistic is given by:

$T_{MOT}=\frac{1}{3}\left(\tau_n(X,T)^2 + \tau_n(Y,T)^2 + \tau_n(\tau_{nw}(X,Y),T')^2 \right)$

where $\tau_n$ is the empirical version of bivariate Kendall's $\tau$ . The series of the Kendall's $\tau$ obtained through moving window is $\tau_{nw}(X, Y)$ , and $T'$ is the time order of the moving window series.

Value

A named list:

statistic, computed MOT test statistic.
p.value, computed p-value computed using bootstrap.
result, the result of the test. If TRUE the trend is considered significant.

References

Goutali, D., and Chebana, F. (2024). Multivariate overall and dependence trend tests, applied to hydrology, Environmental Modelling & Software, 179, doi:10.1016/j.envsoft.2024.106090

Examples


# CASE 1: Only trend in the dependence structure
# Sample data:
DependenceStructure <- generate_data("dependenceStructure", n = 50)

width <- 10

# Perform the mot test:
mot <- MOT_test(DependenceStructure, covar = NULL, width, alpha = 0.05, Nbs = 1000)
print(mot)


# CASE 2: Only trend in the marginal distributions
# Sample data:
MarginalTrend <- generate_data("marginalTrend", n = 50)

# Perform the mot test:
mot <- MOT_test(MarginalTrend, width = width)
print(mot)


# CASE 3: No trend
# Sample data:
NoTrend <- generate_data("noTrend", n = 50)

# Perform the mot test:
mot <- MOT_test(NoTrend, width = width)
print(mot)



# CASE 1: Only trend in the dependence structure
# Sample data:
DependenceStructure <- generate_data("dependenceStructure", n = 50)

width <- 10

# Perform the mot test:
mot <- MOT_test(DependenceStructure, covar = NULL, width, alpha = 0.05, Nbs = 1000)
print(mot)


# CASE 2: Only trend in the marginal distributions
# Sample data:
MarginalTrend <- generate_data("marginalTrend", n = 50)

# Perform the mot test:
mot <- MOT_test(MarginalTrend, width = width)
print(mot)


# CASE 3: No trend
# Sample data:
NoTrend <- generate_data("noTrend", n = 50)

# Perform the mot test:
mot <- MOT_test(NoTrend, width = width)
print(mot)

Trend Tests Plots

Description

Informative plots on the given data series in regards to univariate and multivariate trend testing.

Usage

plotTrend(
  data,
  covar = NULL,
  width,
  graph = c("summary", "variable1", "variable2", "window"),
  color = c("blue", "dark", "green", "warm")
)
plotTrend(
  data,
  covar = NULL,
  width,
  graph = c("summary", "variable1", "variable2", "window"),
  color = c("blue", "dark", "green", "warm")
)

Arguments

data

Numeric matrix, a two dimensional data set where each column is a variable.

covar

Numeric vector, optional covariate vector, must be the same length as data. Default is NULL.

width

Integer, the width to be used for the moving window algorithm. Should be bigger than 1 and smaller than the number of observations.

graph

Character vector, what will be plotted. Options are:

"summary", creates line plots of each variable, Kendall tau with moving window, and the results from the tests.
"variable1", creates a line plot of the first variable.
"variable2", creates a line plot of the second variable.
"window", creates scatter plot of Kendall tau using moving window.

Default is "summary".

color

Character vector, plot color theme. Options are: "blue", "dark", "green", and "warm".

Details

The function is able to do three plots: "window" returns the scatter plot of Kendall $\tau$ with the moving window technique, "variable1" and "variable2" return the line plots for each variable against the covariate or "Time", finally "summary" returns the previous plot combined in the same display. Four color profiles are available .

Value

The specified plot.

References

Goutali, D., and Chebana, F. (2024). Multivariate overall and dependence trend tests, applied to hydrology, Environmental Modelling & Software, 179, doi:10.1016/j.envsoft.2024.106090

Examples



# Sample data:
dataDependenceStructure <- generate_data("dependenceStructure", 50)
dataMarginalTrend <- generate_data("marginalTrend", 50)
dataNoTrend <- generate_data("noTrend", 50)

# Plot Trend summary:
plotTrend(dataDependenceStructure, covar = NULL, width = 10, graph = "summary", color = "blue")

plotTrend(dataMarginalTrend, covar = NULL, width = 10, graph = "summary", color = "green")

plotTrend(dataNoTrend, covar = NULL, width = 10, graph = "summary", color = "warm")

# Plot a variable
plotTrend(dataMarginalTrend, width = 10, graph = "variable1", color = "green")

# Plot the evolution of Kendall tau
plotTrend(dataDependenceStructure, width = 10, graph = "window", color = "warm")



# Sample data:
dataDependenceStructure <- generate_data("dependenceStructure", 50)
dataMarginalTrend <- generate_data("marginalTrend", 50)
dataNoTrend <- generate_data("noTrend", 50)

# Plot Trend summary:
plotTrend(dataDependenceStructure, covar = NULL, width = 10, graph = "summary", color = "blue")

plotTrend(dataMarginalTrend, covar = NULL, width = 10, graph = "summary", color = "green")

plotTrend(dataNoTrend, covar = NULL, width = 10, graph = "summary", color = "warm")

# Plot a variable
plotTrend(dataMarginalTrend, width = 10, graph = "variable1", color = "green")

# Plot the evolution of Kendall tau
plotTrend(dataDependenceStructure, width = 10, graph = "window", color = "warm")

Univariate Spearman's Rho Test

Description

The functions performs the univariate Spearman's rho test.

Usage

srUnivariate(x)
srUnivariate(x)

Arguments

x

Numeric vector representing a data series.

Details

The Spearman's Rank test is a non-parametric trend test based on rank-order, It tests a null hypothesis of no trend against an alternative. Given a data series $X = (x_1, x_2, ..., x_n)$ of length $n$ , the test statistic is given by

$D = 1 - \frac{6 \sum_{i=1}^n [R(x_i) - i]^2}{n(n^2 - 1)}$

where $R(x_i)$ is the rank of the i-th observation in the data series.

Under the null hypothesis D has asymptotically normal distribution, with $E(D)=0$ , and variance

$\text{Var}(D) = \frac{1}{n-1}$

Value

A named list

statistic, the estimated Spearman's rho test statistics
p.value, the estimated p-value for the test.

References

Sneyers, R., 1990. On the Statistical Analysis of Series of Observations. World Meteorol. Organ.

Examples

# Sample data (Both marginal distributions have trend):
dataMarginalTrend <- generate_data("marginalTrend", n = 50)

# Perform SR test on sample data:
srUnivariate(dataMarginalTrend[, 1])

srUnivariate(dataMarginalTrend[, 2])

# Sample data (Both marginal distributions have trend):
dataMarginalTrend <- generate_data("marginalTrend", n = 50)

# Perform SR test on sample data:
srUnivariate(dataMarginalTrend[, 1])

srUnivariate(dataMarginalTrend[, 2])

Trend Tests Summary

Description

Performs multivariate and univariate trend tests on the given data series and returns a data frame with the results.

Usage

summaryTrend(data, width, covar = NULL)
summaryTrend(data, width, covar = NULL)

Arguments

data

Numeric matrix, a two dimensional data set where each column is a variable.

width

Numeric value, the width to be used for the moving window algorithm. Should be bigger than 1 and smaller than the number of observations.

covar

Numeric vector, time order of the data series. If none give $covar = 1, 2, ..., n$ .

Details

The function performs the Multivariate Dependence Trend and Multivariate Overall Trend tests as described by Goutali and Chebana (2024), as well as the univariate Mann-Kendall (MK) test to each variable and returns a data frame with the results.

This functions performs the test with the default values for alpha = 0.05 and Nbs = 1000, for a more precise testing you can use the functions described in see also.

Value

The results dataframe, a column for the respective test statistic, a column for the p-value, and four rows each for a test MDT, MOT, and MK for each variable.

References

Goutali, D., and Chebana, F. (2024). Multivariate overall and dependence trend tests, applied to hydrology, Environmental Modelling & Software, 179, doi:10.1016/j.envsoft.2024.106090

Examples



# Summary for data with trend in the Dependence Structure:
DependenceStructure <- generate_data("dependenceStructure", 50)
summaryTrend(DependenceStructure, covar = NULL, width = 10)

# Summary for data with trend in the Marginals:
MarginalTrend <- generate_data("marginalTrend", 50)
summaryTrend(MarginalTrend, covar = NULL, width = 10)

# Summary for data without trend:
NoTrend <- generate_data("noTrend", 50)
summaryTrend(NoTrend, covar = NULL, width = 10)


# Summary for data with trend in the Dependence Structure:
DependenceStructure <- generate_data("dependenceStructure", 50)
summaryTrend(DependenceStructure, covar = NULL, width = 10)

# Summary for data with trend in the Marginals:
MarginalTrend <- generate_data("marginalTrend", 50)
summaryTrend(MarginalTrend, covar = NULL, width = 10)

# Summary for data without trend:
NoTrend <- generate_data("noTrend", 50)
summaryTrend(NoTrend, covar = NULL, width = 10)

Package 'MultivariateTrendAnalysis'

Help Index

Generate Synthetic data

Description

Usage

Arguments

Value

References

Examples

Multivariate Dependence Trend Test

Description

Usage

Arguments

Details

Value

References

See Also

Examples

Component Wise Mann-Kendall Test Statistic

Description

Usage

Arguments

Details

Value

References

Examples

Univariate Mann-Kendall Test

Description

Usage

Arguments

Details

Value

References

See Also

Examples

Multivariate Overall Trend Test

Description

Usage

Arguments

Details

Value

References

See Also

Examples

Trend Tests Plots

Description

Usage

Arguments

Details

Value

References

See Also

Examples

Univariate Spearman's Rho Test

Description

Usage

Arguments

Details

Value

References

Examples

Trend Tests Summary

Description

Usage

Arguments

Details

Value

References

See Also

Examples