Decor.pField: Decorrelation of field

In EarthSystemDiagnostics/pfields: An R Package to Analyse Gridded Field Data

Description

Calculate the decorrelation length of a "pField" data set for given target locations.

Usage

Decor.pField(
  field,
  lat1,
  lon1,
  lat2,
  lon2,
  return.scatter = FALSE,
  verbose = FALSE,
  print.progress = NULL,
  ...
)

Arguments

field	a "pField" object.
lat1	numeric vector of length 1 with the latitude of the target location for which the decorrelation length is to be calculated. Omit to analyse the entire field.
lon1	numeric vector of length 1 with the longitude of the target location for which the decorrelation length is to be calculated. Omit to analyse the entire field.
lat2	optional numeric vector of length 1 with a second latitude to define a coordinate region for which decorrelation lengths are to be correlated. OBS! Method to select a region from the "pField" object is not yet implemented!
lon2	Same as lat2 for a second longitude value.
return.scatter	logical; if TRUE, a data frame with distance- correlation pairs is returned for each target location additionally to the decorrelation length. Defaults to FALSE.
verbose	logical; if TRUE, informative messages are printed on the target location selection and the decorrelation length estimation. Defaults to FALSE.
print.progress	numeric value to specify an index interval at which messages on the computation progress are printed (useful for large analysed fields). Ignored for NULL (the default).
...	further arguments passed on to the correlation function cor.pTs.

Details

The decorrelation length estimation is based on fitting an exponential of the form exp(-x/tau), where x is distance and tau the fit parameter, i.e. the decorrelation length, to the distance-correlation relationship as obtained from correlating the time series at the target location with the time series from all other grid points of the input "pField". The fit is performed using the built-in R function nlm.

Value

Decorrelation lengths are returned in units of km. The return structure depends on the supplied input:

• For a single target point (lat1-lon1 pair specified), the returned decorrelation length is a numeric length-1 vector.

• For analysing a region (via specifying lat2 and lon2) or the entire field (no lat-lon's specified), the returned decorrelation length is an object of class "pField" of the same coordinate structure as the analysed region/field.

• For return.scatter = TRUE, the return object is a 2-element list where the first list element is the decorrelation length result as defined above, and the second list element is a list of data frames for each analysed location where each data frame has elements d and cor with all distance-correlation value pairs for this location.

Author(s)

Thomas Münch

See Also

cor.pTs

EarthSystemDiagnostics/pfields documentation built on Jan. 10, 2022, 10:37 p.m.