applyMask: Removes neighbors that share (or not) group membership with targets.

Description

Some of the nearest neighbors found using yai or newtargets are removed using this function. This is possible when there are several reference observations for each target as is the case with k>1. The function removes neighbor reference observations for a given target if the reference and target are in (a) the same group or (b) from different groups, depending on the method used. Group membership is identified for reference and target observations using two vectors, refGroups for references and trgGroups for targets. If the group membership code is the same for a refernece and a target, then they are in the same group while different codes mean a lack of common group membership.

Usage

applyMask(object,refGroups=NULL, trgGroups=NULL, method="removeWhenCommon", k=1)

Value

An object of class yai, that is a copy of the first argument with the following elements replaced:

call: the call.
neiDstTrgs: a matrix of distances between a target (identified by its row name) and the k references. There are k columns.
neiIdsTrgs: a matrix of reference identifications that correspond to neiDstTrgs.
neiDstRefs: set NULL as if noRefs=TRUE in the original call to yai.
neiIdsRefs: set NULL as if noRefs=TRUE in the original call to yai.
noRefs: set TRUE regardless of original value.
k: the value of k.

Arguments

object

an object of class yai.

refGroups

a vector, with length equal to the number of reference observations, of codes that indicate group membership.

trgGroups

a vector, with length equal to the number of target observations, of codes that indicate group membership. The data type and coding scheme of refGroups and trgGroups must be the same.

method

is the strategy used for removing neighbors from the object, as follows:

removeWhenCommon remove neighbors where the group membership of a target is the same as the group membership of the near neighbor reference (that is, keep near neighbors if they are not in the same group).
keepWhenCommon keep near neighbors only when the reference is in the same group as the target (that is, remove near neighbors if they are not in the same group).

k

the number of nearest neighbors to keep.

Author

Nicholas L. Crookston ncrookston.fs@gmail.com
Acknowledgement: This function was inspired by correspondence with Clara Anton Fernandez.

Examples

Run this code


require (yaImpute)

data(iris)

# build a base case, there are no targets, 
#    turn off getting references neighbors.
mal <- yai(x=iris[,-5],method="mahalanobis", noRefs = TRUE)

# create a new data, just a copy of the old with new row names.
iris2 <- iris
rownames(iris2) <- paste0("new.",rownames(iris))

# do an imputation with k=55
m55 <- newtargets(mal,newdata=iris2,k=55)

# get the 2 closest where the species codes don't match by
#  removing neighbors when the ref group membership is 
#  in common with the target group membership (same species),
#  thereby forcing neighbors to be from different species. 

#  in this case, the groups are species codes. 

applyMask(m55,refGroups=iris$Species,trgGroups=iris2$Species,
          method="removeWhenCommon",k=2)

# get the 2 closest where the species codes do match by
#  removing neighbors when the ref group membership is 
#  different than the target group membership (different species),
#  thereby forcing neighbors to be from the same species (this
#  is generally true anyway using the iris data). 

applyMask(m55,iris$Species,trgGroups=iris2$Species,
          method="keepWhenCommon",k=2)