deltamm: Merge and/or Match Identified Features Within Two Fields
In SpatialVx: Spatial Forecast Verification
deltamm R Documentation
Merge and/or Match Identified Features Within Two Fields
Description
Merge and/or match identified features within two fields using the delta metric method described in Gilleland et al. (2008), or the matching only method of Davis et al. (2006a).
Usage
deltamm(x, p = 2, max.delta = Inf, const = Inf, type = c( "sqcen", "original" ),
N = NULL, verbose = FALSE, ...)
centmatch(x, criteria = 1, const = 14, distfun = "rdist", areafac = 1,
verbose = FALSE, ...)
## S3 method for class 'matched'
plot(x, mfrow = c(1, 2), ...)
## S3 method for class 'matched'
print(x, ...)
## S3 method for class 'matched'
summary(object, ...)
Arguments
x
For deltamm and centmatch, an object of class “features” with components X.labeled, Y.labeled (matrices with numbered features), as well as, X.feats and Y.feats, each of which are list objects containing numbered components within which are objects of class “owin” containing logical matrices that define features for the forecast (Y) and verification (X) fields, resp. For example, as returned by the FeatureFinder function. For plot an object of class “matched”. Argument y is used if it is not NULL, otherwise argument x is used (but only one of x or y is used). If x and y are missing, but not object, then object will be used, in which case it must be of class “features”.
object
list object of class “matched”.
p
Baddeley delta metric parameter. A value of 1 gives arithmetic averages, Inf gives the Hausdorff metric and -Inf gives a minimum. The default of 2 is most common.
max.delta
single numeric giving a cut-off value for delta that disallows two features to be merged or matched if the delta between them is larger than this value.
const
deltamm: a constant value over which the shortest distances in a distance map are set. See Gilleland (2011) and Schwedler and Baldwin (2011) for more information about this parameter.
type
character specifying whether Baddeley's delta metric should be calculated after centering object pairs on a new square grid (default) or performed in their original positions on the original grid.
N
If type is “sqcen”, then N is the argument to censqdelta that specifies the common grid size. If not specified the maximum side of the original domain is used (possibly adding one first to make it an odd number). It is possible that values could be pushed off the new grid, and making N larger might alleviate the issue.
centmatch numeric giving the number of grid squares whereby if the centroid distance (D) is less than this value, a match is declared (only used if criteria is 3.
criteria
1, 2 or 3 telling which criteria for determining a match based on centroid distance, D, to use. The first (1) is a match if D is less than the sum of the sizes of the two features in question (size is the square root of the area of the feature). The second is a match if D is less than the average size of the two features in question. The third is a match if D is less than a constant given by the argument const.
distfun
character string naming a distance function. Default uses rdist from the fields package.
areafac
single numeric used to multiply by grid-space based area in order to at least approximate the correct distance (e.g., using the ICP test cases, 4 would make the areas approximately square km instead of grid points). This should not be used unless distfun is “rdist.earth” in which case it will use the locations given in the call to make.SpatialVx, which are assumed to be lat/lon coordinates.
mfrow
mfrow parameter (see help file for par). If NULL, then the parameter is not re-set.
verbose
logical, should progress information be printed to the screen?
...
For deltamm: additional optional arguments to the distmap function from package spatstat. For centmatch: optional arguments to distfun. For plot.matched, additional arguments to image.plot concerning the color legend bar only.
Details
deltamm:
Gilleland et al. (2008) describe a method for automatically merging, and simultaneously, matching identified features within two fields (a verification set). The method was proposed with the general method for spatial forecast verification introduced by Davis et al. (2006 a,b) in mind. It relies heavily on use of a binary image metric introduced by Baddeley (1992a,b) for comparing binary images; henceforth referred to as the delta metric, or just delta.
The procedure is as follows. Suppose there are m identified forecast features and n identified verification features.
1. Compute delta for each feature identified in the forecast field against each feature identified in the verification field. Store these values in an m by n matrix, Upsilon.
2. For each of the m rows of Upsilon, rank the values of delta to identify the features, j_1, ..., j_n that provide the lowest (best) to highest (worst) value, and do the same for each of the n columns to find the forecast features i1, ...,i_m that yield the lowest to highest values for each verification feature.
3. Create a new m by n matrix, Psi, whose columns contain delta computed between each of the individual features in the forecast and (first column) the corresponding j_1 feature from the verification field, and each successive column, k, has delta between the i-th forecast feature and the union of j_1, j_2, ..., j_k.
4. Create a similar m by n matrix, Ksi, that has delta computed between each individual feature in the verification field and the successively bigger unions i_1, ..., i_l for the l-th column.
5. Let Q=[Upsilon, Psi, Ksi], and merge and match features based on the rankings of delta in Q. That is, find the smallest delta in Q, and determine which mergings (if any) and matchings correspond to this value. Remove the appropriate row(s) and column(s) of Q corresponding to the already determined matchings and/or mergings. Repeat this until all features in at least one field have been exhausted.
The above algorithm suffers from two deficiencies. First, features that are merged in one field cannot be matched to merged features in another field. One possible remedy for this is to run this algorithm twice, though this is not a universally good solution. Second, features can be merged and/or matched to features that are very different from each other. A possible remedy for this is to use the cut-off argument, max.delta, to disallow mergings or matchings between features whose delta value is not <= this cut-off. In practice, these two deficiencies are not likely very problematic.
centmatch:
This function works similarly as deltamm, though it does not merge features. It is based on the method proposed by Davis et al. (2006a). It is possible for more than one object to be matched to the same object in another field. As a result, when plotting, it might appear that features have been merged, but they have not been. For informational purposes, the criteria, appelled criteria.values (as determined by the criteria argument), along with the centroid distance matrix, appelled centroid.distances, are returned.
plot: The plot method function for matched features plots matched features across fields in the same color using rainbow. Unmatched features in either field are all colored gray. Zero values are colored white. The function MergeForce must first be called, however, in order to organize the object into a format that allows the plot method function to determine the correct color coding.
The print method function will tell you which features matched between fields, so one can plot the originally derived features (e.g., from FeatureFinder) to identify matched features.
summary:
The summary method function so far simply reverts the class back to “features” and calls that summary function.
Value
A list object of class “matched” is returned by both centmatch and deltamm containing several components added to the value of x or y passed in, and possibly with attributes inhereted from object.
match.message
A character string stating how features were matched.
match.type
character string naming the matching function used.
matches
two-column matrix with forecast object numbers in the first column and corresponding matched observed features in the second column. If no matches, this will have value integer(0) for each column giving a matrix with dimension 0 by 2.
unmatched
list with components X and Xhat giving the unmatched object numbers, if any, from the observed and forecast fields, resp. If none, the value will be integer(0).
Q
(deltamm only) an array of dimension n by m by 3 giving all of the delta values that were computed in determining the mergings and matchings.
criteria
(centmatch only) 1, 2, or 3 as given by the criteria argument.
criteria.values, centroid.distances
(centmatch only) matrices giving the forecast by observed object criteria and centroid distances.
implicit.merges
(centmatch only) list displaying multiple matches for each field (this could define potential merges). Each component of the list is a unified set of matched features in the form of two-column matrices analogous to the matches component. If there are no implicit mergings or no matched features, this component will be named, but also NULL. Note: such implicit mergings may or may not make physical sense, and are not considered to be merged generally, but will show up as having been merged/clustered when plotted.
If the argument ‘object’ is passed in, then the list object will also contain nearly the same attributes, with the data.name attribute possibly changed to reflect the specific model used. It will also contain a time.point and model attribute.
Author(s)
Eric Gilleland
References
Baddeley, A. (1992a) An error metric for binary images. In Robust Computer Vision Algorithms, W. Forstner and S. Ruwiedel, Eds., Wichmann, 59–78.
Baddeley, A. (1992b) Errors in binary images and an Lp version of the Hausdorff metric. Nieuw Arch. Wiskunde, 10, 157–183.
Davis, C. A., Brown, B. G. and Bullock, R. G. (2006a) Object-based verification of precipitation forecasts, Part I: Methodology and application to mesoscale rain areas. Mon. Wea. Rev., 134, 1772–1784.
Davis, C. A., Brown, B. G. and Bullock, R. G. (2006b) Object-based verification of precipitation forecasts, Part II: Application to convective rain systems. Mon. Wea. Rev., 134, 1785–1795.
Gilleland, E. (2011) Spatial Forecast Verification: Baddeley's Delta Metric Applied to the ICP Test Cases. Wea. Forecasting, 26 (3), 409–415.
Gilleland, E., Lee, T. C. M., Halley Gotway, J., Bullock, R. G. and Brown, B. G. (2008) Computationally efficient spatial forecast verification using Baddeley's delta image metric. Mon. Wea. Rev., 136, 1747–1757.
Schwedler, B. R. J. and Baldwin, M. E. (2011) Diagnosing the sensitivity of binary image measures to bias, location, and event frequency within a forecast verification framework. Wea. Forecasting, 26, 1032–1044.
See Also
To identify features: FeatureFinder
minboundmatch is another feature matching function.
To force merges (implicit or otherwise): MergeForce,
Other functions used to identify features within the above mentioned functions (all from spatstat):
disjointer, deltametric, owin, tess, tiles, connected
Examples
## Not run:
x <- y <- matrix(0, 100, 100)
x[2:3,c(3:6, 8:10)] <- 1
y[c(4:7, 9:10),c(7:9, 11:12)] <- 1
x[30:50,45:65] <- 1
y[c(22:24, 99:100),c(50:52, 99:100)] <- 1
hold <- make.SpatialVx( x, y, field.type = "contrived", units = "none",
data.name = "Example", obs.name = "x", model.name = "y" )
look <- FeatureFinder( hold, smoothpar = 0.5 )
# The next line fails because the centering pushes one object out of the new domain.
# look2 <- deltamm( look )
# Setting N larger fixes the problem.
look2 <- deltamm( look, N = 300 )
look2 <- MergeForce( look2 )
look2
plot( look2 )
FeatureTable(look2)
look3 <- centmatch(look)
FeatureTable(look3)
look3 <- MergeForce( look3 )
plot( look3 )
## End(Not run)
SpatialVx documentation built on Nov. 10, 2022, 5:56 p.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| deltamm | R Documentation |
Merge and/or Match Identified Features Within Two Fields
Description
Merge and/or match identified features within two fields using the delta metric method described in Gilleland et al. (2008), or the matching only method of Davis et al. (2006a).
Usage
deltamm(x, p = 2, max.delta = Inf, const = Inf, type = c( "sqcen", "original" ),
N = NULL, verbose = FALSE, ...)
centmatch(x, criteria = 1, const = 14, distfun = "rdist", areafac = 1,
verbose = FALSE, ...)
## S3 method for class 'matched'
plot(x, mfrow = c(1, 2), ...)
## S3 method for class 'matched'
print(x, ...)
## S3 method for class 'matched'
summary(object, ...)
Arguments
x |
For |
object |
list object of class “matched”. |
p |
Baddeley delta metric parameter. A value of 1 gives arithmetic averages, Inf gives the Hausdorff metric and -Inf gives a minimum. The default of 2 is most common. |
max.delta |
single numeric giving a cut-off value for delta that disallows two features to be merged or matched if the delta between them is larger than this value. |
const |
|
type |
character specifying whether Baddeley's delta metric should be calculated after centering object pairs on a new square grid (default) or performed in their original positions on the original grid. |
N |
If |
centmatch numeric giving the number of grid squares whereby if the centroid distance (D) is less than this value, a match is declared (only used if criteria is 3.
criteria |
1, 2 or 3 telling which criteria for determining a match based on centroid distance, D, to use. The first (1) is a match if D is less than the sum of the sizes of the two features in question (size is the square root of the area of the feature). The second is a match if D is less than the average size of the two features in question. The third is a match if D is less than a constant given by the argument |
distfun |
character string naming a distance function. Default uses |
areafac |
single numeric used to multiply by grid-space based area in order to at least approximate the correct distance (e.g., using the ICP test cases, 4 would make the areas approximately square km instead of grid points). This should not be used unless |
mfrow |
mfrow parameter (see help file for |
verbose |
logical, should progress information be printed to the screen? |
... |
For |
Details
deltamm:
Gilleland et al. (2008) describe a method for automatically merging, and simultaneously, matching identified features within two fields (a verification set). The method was proposed with the general method for spatial forecast verification introduced by Davis et al. (2006 a,b) in mind. It relies heavily on use of a binary image metric introduced by Baddeley (1992a,b) for comparing binary images; henceforth referred to as the delta metric, or just delta.
The procedure is as follows. Suppose there are m identified forecast features and n identified verification features.
1. Compute delta for each feature identified in the forecast field against each feature identified in the verification field. Store these values in an m by n matrix, Upsilon.
2. For each of the m rows of Upsilon, rank the values of delta to identify the features, j_1, ..., j_n that provide the lowest (best) to highest (worst) value, and do the same for each of the n columns to find the forecast features i1, ...,i_m that yield the lowest to highest values for each verification feature.
3. Create a new m by n matrix, Psi, whose columns contain delta computed between each of the individual features in the forecast and (first column) the corresponding j_1 feature from the verification field, and each successive column, k, has delta between the i-th forecast feature and the union of j_1, j_2, ..., j_k.
4. Create a similar m by n matrix, Ksi, that has delta computed between each individual feature in the verification field and the successively bigger unions i_1, ..., i_l for the l-th column.
5. Let Q=[Upsilon, Psi, Ksi], and merge and match features based on the rankings of delta in Q. That is, find the smallest delta in Q, and determine which mergings (if any) and matchings correspond to this value. Remove the appropriate row(s) and column(s) of Q corresponding to the already determined matchings and/or mergings. Repeat this until all features in at least one field have been exhausted.
The above algorithm suffers from two deficiencies. First, features that are merged in one field cannot be matched to merged features in another field. One possible remedy for this is to run this algorithm twice, though this is not a universally good solution. Second, features can be merged and/or matched to features that are very different from each other. A possible remedy for this is to use the cut-off argument, max.delta, to disallow mergings or matchings between features whose delta value is not <= this cut-off. In practice, these two deficiencies are not likely very problematic.
centmatch:
This function works similarly as deltamm, though it does not merge features. It is based on the method proposed by Davis et al. (2006a). It is possible for more than one object to be matched to the same object in another field. As a result, when plotting, it might appear that features have been merged, but they have not been. For informational purposes, the criteria, appelled criteria.values (as determined by the criteria argument), along with the centroid distance matrix, appelled centroid.distances, are returned.
plot: The plot method function for matched features plots matched features across fields in the same color using rainbow. Unmatched features in either field are all colored gray. Zero values are colored white. The function MergeForce must first be called, however, in order to organize the object into a format that allows the plot method function to determine the correct color coding.
The print method function will tell you which features matched between fields, so one can plot the originally derived features (e.g., from FeatureFinder) to identify matched features.
summary:
The summary method function so far simply reverts the class back to “features” and calls that summary function.
Value
A list object of class “matched” is returned by both centmatch and deltamm containing several components added to the value of x or y passed in, and possibly with attributes inhereted from object.
match.message |
A character string stating how features were matched. |
match.type |
character string naming the matching function used. |
matches |
two-column matrix with forecast object numbers in the first column and corresponding matched observed features in the second column. If no matches, this will have value integer(0) for each column giving a matrix with dimension 0 by 2. |
unmatched |
list with components X and Xhat giving the unmatched object numbers, if any, from the observed and forecast fields, resp. If none, the value will be integer(0). |
Q |
(deltamm only) an array of dimension n by m by 3 giving all of the delta values that were computed in determining the mergings and matchings. |
criteria |
(centmatch only) 1, 2, or 3 as given by the criteria argument. |
criteria.values, centroid.distances |
(centmatch only) matrices giving the forecast by observed object criteria and centroid distances. |
implicit.merges |
(centmatch only) list displaying multiple matches for each field (this could define potential merges). Each component of the list is a unified set of matched features in the form of two-column matrices analogous to the matches component. If there are no implicit mergings or no matched features, this component will be named, but also NULL. Note: such implicit mergings may or may not make physical sense, and are not considered to be merged generally, but will show up as having been merged/clustered when plotted. |
If the argument ‘object’ is passed in, then the list object will also contain nearly the same attributes, with the data.name attribute possibly changed to reflect the specific model used. It will also contain a time.point and model attribute.
Author(s)
Eric Gilleland
References
Baddeley, A. (1992a) An error metric for binary images. In Robust Computer Vision Algorithms, W. Forstner and S. Ruwiedel, Eds., Wichmann, 59–78.
Baddeley, A. (1992b) Errors in binary images and an Lp version of the Hausdorff metric. Nieuw Arch. Wiskunde, 10, 157–183.
Davis, C. A., Brown, B. G. and Bullock, R. G. (2006a) Object-based verification of precipitation forecasts, Part I: Methodology and application to mesoscale rain areas. Mon. Wea. Rev., 134, 1772–1784.
Davis, C. A., Brown, B. G. and Bullock, R. G. (2006b) Object-based verification of precipitation forecasts, Part II: Application to convective rain systems. Mon. Wea. Rev., 134, 1785–1795.
Gilleland, E. (2011) Spatial Forecast Verification: Baddeley's Delta Metric Applied to the ICP Test Cases. Wea. Forecasting, 26 (3), 409–415.
Gilleland, E., Lee, T. C. M., Halley Gotway, J., Bullock, R. G. and Brown, B. G. (2008) Computationally efficient spatial forecast verification using Baddeley's delta image metric. Mon. Wea. Rev., 136, 1747–1757.
Schwedler, B. R. J. and Baldwin, M. E. (2011) Diagnosing the sensitivity of binary image measures to bias, location, and event frequency within a forecast verification framework. Wea. Forecasting, 26, 1032–1044.
See Also
To identify features: FeatureFinder
minboundmatch is another feature matching function.
To force merges (implicit or otherwise): MergeForce,
Other functions used to identify features within the above mentioned functions (all from spatstat):
disjointer, deltametric, owin, tess, tiles, connected
Examples
## Not run:
x <- y <- matrix(0, 100, 100)
x[2:3,c(3:6, 8:10)] <- 1
y[c(4:7, 9:10),c(7:9, 11:12)] <- 1
x[30:50,45:65] <- 1
y[c(22:24, 99:100),c(50:52, 99:100)] <- 1
hold <- make.SpatialVx( x, y, field.type = "contrived", units = "none",
data.name = "Example", obs.name = "x", model.name = "y" )
look <- FeatureFinder( hold, smoothpar = 0.5 )
# The next line fails because the centering pushes one object out of the new domain.
# look2 <- deltamm( look )
# Setting N larger fixes the problem.
look2 <- deltamm( look, N = 300 )
look2 <- MergeForce( look2 )
look2
plot( look2 )
FeatureTable(look2)
look3 <- centmatch(look)
FeatureTable(look3)
look3 <- MergeForce( look3 )
plot( look3 )
## End(Not run)
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.