# Merge and/or Match Identified Features Within Two Fields 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). ```r 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. ## Returns 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. ## 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. ## Author(s) Eric Gilleland ## Examples ```r ## 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) ```

deltamm function