Package 'som.nn'

Description

The package som.nn provides tools to train self-organising maps and predict class memberships by means of a k-NN-like classifier.

Details

The functions som.nn.train and som.nn.continue are used train and re-train self-organising maps. The training can be performed with functions of the packages kohonen, som, class or with pure-R-implementations with distance function bubble (kernel internal) or gaussian (kernel gaussian). (Remark: The pure-R-impelementations actually are faster as the external calls to C implementations in the above-mentioned packages!).

In contrast to a normal som training, class lables are required for all training samples. These class lables are used to assign classes to the codebook vectors (i.e. the neurons of the map) after the training and build the set of reference vectors. This reference is used for nearest-neigbour classification.

The nearest neighbour classifier is implemented as predict method. It is controlled by the following parameters:

• dist.fun: the distance function to weight the distance of reference vectors and the sample to be predicted.

• max.dist: the maximum distance to be considered.

Some distance functions are provided in the package (linear, bubble, inverse and tricubic) but any custom function scan be defined as well.

The prediction differs significantly from a standard nearest-neighbour classifier, because the neighbourhood is not defined by the distance between reference vectors and unknown sample vector. Instead the neighbourhood of the neurons on the self-oranising map is used.

Because the som have been generated by an unsupervised training, the classifier is robust against overtraining.

In addition the abstract model can be visualised as 2-dimensional map, using the plot method.

Description

The function is used as distance-dependent weight $w$ for k-NN voting.

Usage

dist.fun.bubble(x, sigma = 1.1)

Arguments

Details

The function returns 1.0 for $0 < x \le \sigma$ and 0.0 for $x > \sigma$.

Value

  Distance-dependent weight.

Description

The function is used as distance-dependent weight $w$ for k-NN voting.

Usage

dist.fun.inverse(x, sigma = 1.1)

Arguments

Details

The function returns 1.0 for $x = 0$, 0.0 for $x \ge \sigma$ and

$1 / (x+1)^(1/sigma)$

for $0 < x < \sigma$.

Value

  Distance-dependent weight.

Description

The function is used as distance-dependent weight $w$ for k-NN voting.

Usage

dist.fun.linear(x, sigma = 1.1)

Arguments

Details

The function returns 1.0 for $x = 0$, 0.0 for $x \ge \sigma$ and

$1 - x / \sigma$

for $0 < x < \sigma$.

Value

  Distance-dependent weight.

Description

The tricubic function is used as distance-dependent weight $w$ for k-NN voting.

Usage

dist.fun.tricubic(x, sigma = 1)

Arguments

Details

The function returns 1.0 for $x = 0$, 0.0 for $x \ge \sigma$ and

$w(x) = (1 - x^3 / \sigma^3)^3$

for $0 < x < \sigma$.

Value

  Distance-dependent weight.

Description

Calculates the distance matrix of points on the surface of a torus.

Usage

dist.torus(coors)

Arguments

Details

A rectangular plane is considered as torus (i.e. on an endless plane that contimues on the left, when leaving at the right side, and in the same way connects top and bottom border). Distances between two points on the plane are calculated as the shortest distance between the points on the torus surface.

Value

 Complete distance matrix with diagonal and upper triangle values.

Description

The constructor creates a new object of type SOMnn.

Usage

## S4 method for signature 'SOMnn'
initialize(
  .Object,
  name,
  codes,
  qerror,
  class.idx,
  classes,
  class.counts,
  class.freqs,
  confusion,
  measures,
  accuracy,
  xdim,
  ydim,
  len.total,
  toroidal,
  norm,
  norm.center,
  norm.scale,
  dist.fun,
  max.dist,
  strict
)

Arguments

Details

The constructor needs not to be called directly, because the normal way to create a SOMnn object is to use som.nn.train.

Examples

## Not run: 
new.som <- new("SOMnn", name = name,
              codes = codes,
              qerror = qerror,
              classes = classes, 
              class.idx = class.idx,
              class.counts = class.counts, 
              class.freqs = class.freqs,
              confusion = confusion, 
              measures = measures,
              accuracy = accuracy,
              xdim = xdim, 
              ydim = ydim, 
              len.total = len.total, 
              toroidal = toroidal,
              norm = norm, 
              norm.center = norm.center, 
              norm.scale = norm.scale,
              dist.fun = dist.fun, 
              max.dist = max.dist.
              strict = strict)

## End(Not run)

Description

Calculates a linear normalisation for the class frequencies.

Usage

norm.linear(x)

Arguments

Details

The function is applied to a vector to squeeze the values in a way that they sum up to 1.0:

som.nn.linnorm(x) = x / sum(x)

Linear normalisation is used to normalise class distrubution during prediction. Results seems often more reasonable, compared to softmax. The S4 predict function for Class SOMnn allows to specify the normalisation function as parameter.

Value

Vector of normalised values.

Description

Calculates a softmax-like normalisation for the class frequencies.

Usage

norm.softmax(x, t = 0.2)

Arguments

Details

Softmax function is applied to a vector to squeeze the values in a way that they sum up to 1.0:

som.nn.softmax(x) = exp(x/T) / sum(exp(x/T))

Low values for T result in a strong separation of output values. High values for T make output values more equal.

Value

Vector of softmax normalised values.

Description

Creates a plot of the hexagonal som in the model of type SOMnn.

Usage

## S4 method for signature 'SOMnn,ANY'
plot(
  x,
  title = TRUE,
  col = NA,
  onlyDefCols = FALSE,
  edit.cols = FALSE,
  show.legend = TRUE,
  legend.loc = "bottomright",
  legend.width = 4,
  window.width = NA,
  window.height = NA,
  show.box = TRUE,
  show.counter.border = 0.98,
  predict = NULL,
  add = FALSE,
  pch.col = "black",
  pch = 19,
  ...
)

Arguments

Details

In addition to the required parameters, many options can be specified to plot predicted samples and to modify colours, legend and scaling.

Examples

## get example data and add class labels:
data(iris)
species <- iris$Species

## train with default radius = diagonal / 2:
rlen <- 500
som <- som.nn.train(iris, class.col = "Species", kernel = "internal",
                    xdim = 15, ydim = 9, alpha = 0.2, len = rlen, 
                    norm = TRUE, toroidal = FALSE)


## continue training with different alpha and radius;
som <- som.nn.continue(som, iris, alpha = 0.02, len=500, radius = 5)
som <- som.nn.continue(som, iris, alpha = 0.02, len=500, radius = 2)

## predict some samples:
unk <- iris[,!(names(iris) %in% "Species")]

setosa <- unk[species=="setosa",]
setosa <- setosa[sample(nrow(setosa), 20),]

versicolor <- unk[species=="versicolor",]
versicolor <- versicolor[sample(nrow(versicolor), 20),]

virginica <- unk[species=="virginica",]
virginica <- virginica[sample(nrow(virginica), 20),]

p <- predict(som, unk)
head(p)

## plot:
plot(som)
dev.off()
plot(som, predict = predict(som, setosa))
plot(som, predict = predict(som, versicolor), add = TRUE, pch.col = "magenta", pch = 17)
plot(som, predict = predict(som, virginica), add = TRUE, pch.col = "white", pch = 8)

Description

Predicts categories for a table of data, based on the hexagonal som in the model. This S4 method is a wrapper for the predict method stored in the slot predict of a model of type SOMnn.

Usage

## S4 method for signature 'SOMnn'
predict(object, x)

Arguments

Details

The function returns the winner neuron in codes for each test vector in x. x is organised as one vector per row and must have the same number of columns (i.e. dimensions) and the identical column names as stored in the SOMnn object.

If data have been normalised during training, the same normalisation is applied to the unknown data to be predicted.

Probablilities are softmax normalised by default.

Value

       \code{data.frame} with columns: 
               \code{winner}, \code{x}, \code{y}, the predicted probabilities
               for all categories and the prediction 
               as category index (column name \code{prediction}) and
               class label (column name \code{pred.class}).

Description

Rounds a vector of probabilities preserving their sum.

Usage

## S3 method for class 'probabilities'
round(x, digits = 2)

Arguments

Details

In general, if a vector of floating point values is rounded, the sum is not preserverd. For a vector of probabilities (which sum up to 1.0), this may lead to strange results. This function rounds all values of the vector and takes care, that the sum ist not changed (with a precision given in digits).

Description

Calculates the sensitivity, specificity and overall accuracy for a prediction result if the corresponding vector of true class labels is provided.

Usage

som.nn.accuracy(x, class.labels)

Arguments

Details

Sensitivity is the classifier's ability to correctly identify samples of a specific class A. It is defined as

$sens_{A} = TP_{A} / (TP_{A} + FN_{A})$

with TP = true positives and FN = false negatives. This is equivalent to the ratio of (correctly identified samples of class A) / (total number of samples of class A).

Specificity is the classifier's ability to correctly identify samples not of a specific class A. It is defined as

$spec_{A} = TN_{A} / (TN_{A} + FP_{A})$

with TN = true negatives and FP = false positives. This is equivalent to the ratio of (correctly identified samples not in class A) / (total number of samples not in class A).

Accuracy is the classifier's ability to correctly classify samples of a specific class A. It is defined as

$acc_{A} = (TP_{A} + TN_{A}) / total$

with TP = true positives, TN = true negatives and total = total number of samples of a class. This is equivalent to the ratio of (correctly classified samples) / (total number of samples).

Value

data.frame containing sensitivity, specificity and accuracy for all class labels in the data set.

Description

Calculates the accuracy over all class lables for a prediction result if the corresponding vector of true class labels is provided.

Usage

som.nn.all.accuracy(x, class.labels)

Arguments

Details

It is defined as

$acc = (TP + TN) / total = sum(diag(cmat)) / sum(cmat)$

with TP = true positives, TN = true negatives and total = total number of samples of a class. This is equivalent to the ratio of (correctly classified samples) / (total number of samples).

Value

one value overall accuracy.

Description

Calculates the confusion matrix for a prediction result if the corresponding vector of true class labels is provided.

Usage

som.nn.confusion(x, class.labels)

Arguments

Details

The confusion matrix (also called table of confusion) displays the number of predicted class labels for each actual class. Example:

The confusion matrix includes a column unknown displaying the samples for which no unambiguous prediction is possible.

Value

data.frame containing the confusion matrix.

Description

An existing self-organising map with hexagonal tolology is further trained and a model created for prediction of unknown samples. In contrast to a "normal" som, class-labels for all samples of the training set are required to build the model.

Usage

som.nn.continue(
  model,
  x,
  kernel = "internal",
  len = 0,
  alpha = 0.2,
  radius = 0
)

Arguments

Details

Any specified custom kernel function is used for som training. The function must match the signature kernel(data, grid, rlen, alpha, radius, init, toroidal), with arguments:

• data numeric matrix of training data; one sample per row

• classes: optional charater vector of classes for training data

• grid somgrid, generated with somgrid

• rlen number of training steps

• alpha training rate

• radius training radius

• init numeric matrix of initial codebook vectors; one code per row

• toroidal logical; TRUE, if the topology of grid is toroidal

The returned value must be a list with at minimum one element

• codes: numeric matrix of result codebook vectors; one code per row

Value

    S4 object of type \code{\link{SOMnn}} with the trained model

Examples

## get example data and add class labels:
data(iris)
species <- iris$Species

## train with default radius = diagonal / 2:
rlen <- 500
som <- som.nn.train(iris, class.col = "Species", kernel = "internal",
                    xdim = 15, ydim = 9, alpha = 0.2, len = rlen, 
                    norm = TRUE, toroidal = FALSE)


## continue training with different alpha and radius;
som <- som.nn.continue(som, iris, alpha = 0.02, len=500, radius = 5)
som <- som.nn.continue(som, iris, alpha = 0.02, len=500, radius = 2)

## predict some samples:
unk <- iris[,!(names(iris) %in% "Species")]

setosa <- unk[species=="setosa",]
setosa <- setosa[sample(nrow(setosa), 20),]

versicolor <- unk[species=="versicolor",]
versicolor <- versicolor[sample(nrow(versicolor), 20),]

virginica <- unk[species=="virginica",]
virginica <- virginica[sample(nrow(virginica), 20),]

p <- predict(som, unk)
head(p)

## plot:
plot(som)
dev.off()
plot(som, predict = predict(som, setosa))
plot(som, predict = predict(som, versicolor), add = TRUE, pch.col = "magenta", pch = 17)
plot(som, predict = predict(som, virginica), add = TRUE, pch.col = "white", pch = 8)

Description

An existing model of type SOMnn is exported as object of type kohonen for use with the tools of the package kohonen.

Usage

som.nn.export.kohonen(model, train)

Arguments

Details

Training data is necessary to generate the kohonen object.

Value

    Vist of type \code{kohonen} with the trained som.
            See \code{\link[kohonen]{som}} for details.

Description

An existing model of type SOMnn is exported as object of type SOM for use with the tools of the package class.

Usage

som.nn.export.som(model)

Arguments

Value

    List of type \code{SOM} with the trained som.
            See \code{\link[class]{SOM}} for details.

Description

A self-organising map with hexagonal tolology is trained in several steps and a model of Type SOMnn created for prediction of unknown samples. In contrast to a "normal" som, class-labels for all samples of the training set are required to build the topological model after SOM training.

Usage

som.nn.multitrain(
  x,
  class.col = 1,
  kernel = "internal",
  xdim = 7,
  ydim = 5,
  toroidal = FALSE,
  len = c(0),
  alpha = c(0.2),
  radius = c(0),
  focus = 1,
  norm = TRUE,
  dist.fun = dist.fun.inverse,
  max.dist = 1.1,
  name = "som.nn job"
)

Arguments

Details

Besides of the predefined kernels "bubble", "gaussian", "SOM", "kohonen" or "som", any specified custom kernel function can be used for som training. The function must match the signature kernel(data, grid, rlen, alpha, radius, init, toroidal), with arguments:

• data: numeric matrix of training data; one sample per row

• classes: optional charater vector of classes for training data

• grid: somgrid, generated with somgrid

• rlen: number of training steps

• alpha: training rate

• radius: training radius

• init: numeric matrix of initial codebook vectors; one code per row

• toroidal: logical; TRUE, if the topology of grid is toroidal

The returned value must be a list with at minimum one element

• codes: numeric matrix of result codebook vectors; one code per row

If focus > 1 enhancement of dirty samples is activated: Training samples, mapped to neuron with >1 classes, are preferred in the next training step.

Value

    S4 object of type \code{\link{SOMnn}} with the trained model

Examples

## get example data and add class labels:
data(iris)
species <- iris$Species

## train with default radius = diagonal / 2:
rlen <- 500
som <- som.nn.train(iris, class.col = "Species", kernel = "internal",
                    xdim = 15, ydim = 9, alpha = 0.2, len = rlen, 
                    norm = TRUE, toroidal = FALSE)


## continue training with different alpha and radius;
som <- som.nn.continue(som, iris, alpha = 0.02, len=500, radius = 5)
som <- som.nn.continue(som, iris, alpha = 0.02, len=500, radius = 2)

## predict some samples:
unk <- iris[,!(names(iris) %in% "Species")]

setosa <- unk[species=="setosa",]
setosa <- setosa[sample(nrow(setosa), 20),]

versicolor <- unk[species=="versicolor",]
versicolor <- versicolor[sample(nrow(versicolor), 20),]

virginica <- unk[species=="virginica",]
virginica <- virginica[sample(nrow(virginica), 20),]

p <- predict(som, unk)
head(p)

## plot:
plot(som)
dev.off()
plot(som, predict = predict(som, setosa))
plot(som, predict = predict(som, versicolor), add = TRUE, pch.col = "magenta", pch = 17)
plot(som, predict = predict(som, virginica), add = TRUE, pch.col = "white", pch = 8)

Description

Parameters for the k-NN-like classification can be set for an existing model of type SOMnn after training.

Usage

som.nn.set(
  model,
  x,
  dist.fun = NULL,
  max.dist = NULL,
  strict = NULL,
  name = NULL
)

Arguments

Details

The distance function defines the behaviour of the k-nearest-neighbour algorithm. Choices for the distance function include dist.fun.inverse or dist.fun.tricubic, as defined in this package, or any other function that accepts exactly two arguments x (the distance) and sigma (a parameter defined by max.distance).

A data set must be presented to calculate the accuracy statistics of the modified predictor.

Value

    S4 object of type \code{\link{SOMnn}} with the updated model.

See Also

dist.fun.bubble, dist.fun.linear, dist.fun.inverse, dist.fun.tricubic.

Description

A self-organising map with hexagonal tolology is trained and a model of Type SOMnn created for prediction of unknown samples. In contrast to a "normal" som, class-labels for all samples of the training set are required to build the topological model after SOM training.

Usage

som.nn.train(
  x,
  class.col = 1,
  kernel = "internal",
  xdim = 7,
  ydim = 5,
  toroidal = FALSE,
  len = 0,
  alpha = 0.2,
  radius = 0,
  norm = TRUE,
  dist.fun = dist.fun.inverse,
  max.dist = 1.1,
  strict = 0.8,
  name = "som.nn job"
)

Arguments

Details

Besides of the predefined kernels "internal", "gaussian", "SOM", "kohonen" or "som", any specified custom kernel function can be used for som training. The function must match the signature kernel(data, grid, rlen, alpha, radius, init, toroidal), with arguments:

• data: numeric matrix of training data; one sample per row

• classes: optional charater vector of classes for training data

• grid: somgrid, generated with somgrid

• rlen: number of training steps

• alpha: training rate

• radius: training radius

• init: numeric matrix of initial codebook vectors; one code per row

• toroidal: logical; TRUE, if the topology of grid is toroidal

The returned value must be a list with at minimum one element

• codes: numeric matrix of result codebook vectors; one code per row

Value

    S4 object of type \code{\link{SOMnn}} with the trained model

Examples

## get example data and add class labels:
data(iris)
species <- iris$Species

## train with default radius = diagonal / 2:
rlen <- 500
som <- som.nn.train(iris, class.col = "Species", kernel = "internal",
                    xdim = 15, ydim = 9, alpha = 0.2, len = rlen, 
                    norm = TRUE, toroidal = FALSE)


## continue training with different alpha and radius;
som <- som.nn.continue(som, iris, alpha = 0.02, len=500, radius = 5)
som <- som.nn.continue(som, iris, alpha = 0.02, len=500, radius = 2)

## predict some samples:
unk <- iris[,!(names(iris) %in% "Species")]

setosa <- unk[species=="setosa",]
setosa <- setosa[sample(nrow(setosa), 20),]

versicolor <- unk[species=="versicolor",]
versicolor <- versicolor[sample(nrow(versicolor), 20),]

virginica <- unk[species=="virginica",]
virginica <- virginica[sample(nrow(virginica), 20),]

p <- predict(som, unk)
head(p)

## plot:
plot(som)
dev.off()
plot(som, predict = predict(som, setosa))
plot(som, predict = predict(som, versicolor), add = TRUE, pch.col = "magenta", pch = 17)
plot(som, predict = predict(som, virginica), add = TRUE, pch.col = "white", pch = 8)

Description

A model of type SOMnn is tested with a validation dataset. The dataset must include a column with correct class labels. The model is used to predict class labels. Confusion table, specificity, sensitivity and accuracy for each class are calculated.

Usage

som.nn.validate(model, x)

Arguments

Details

Parameters stored in the model are applied for k-NN-like prediction. If necessary the parameters can be changed by som.nn.set before testing.

The funcion is only a wrapper and actually calls som.nn.continue with the test data and without training (i.e. len = 0).

Value

    S4 object of type \code{\link{SOMnn}} with the unchanged model and the
            test statistics for the test data.

Examples

## get example data and add class labels:
data(iris)
species <- iris$Species

## train with default radius = diagonal / 2:
rlen <- 500
som <- som.nn.train(iris, class.col = "Species", kernel = "internal",
                    xdim = 15, ydim = 9, alpha = 0.2, len = rlen, 
                    norm = TRUE, toroidal = FALSE)


## continue training with different alpha and radius;
som <- som.nn.continue(som, iris, alpha = 0.02, len=500, radius = 5)
som <- som.nn.continue(som, iris, alpha = 0.02, len=500, radius = 2)

## predict some samples:
unk <- iris[,!(names(iris) %in% "Species")]

setosa <- unk[species=="setosa",]
setosa <- setosa[sample(nrow(setosa), 20),]

versicolor <- unk[species=="versicolor",]
versicolor <- versicolor[sample(nrow(versicolor), 20),]

virginica <- unk[species=="virginica",]
virginica <- virginica[sample(nrow(virginica), 20),]

p <- predict(som, unk)
head(p)

## plot:
plot(som)
dev.off()
plot(som, predict = predict(som, setosa))
plot(som, predict = predict(som, versicolor), add = TRUE, pch.col = "magenta", pch = 17)
plot(som, predict = predict(som, virginica), add = TRUE, pch.col = "white", pch = 8)

Description

Maps a sample of unknown category to a self-organising map (SOM) stored in a object of type SOMnn.

Usage

som.nn.visual(codes, data)

Arguments

Details

The function returns the winner neuron in codes for each test vector in x. codes and x are one vector per row and must have the same number of columns (i.e. dimensions) and the identical column names.

som.nn.visual is the work horse for the k-NN-like classifier and normally used from predict.

Value

   \code{data.frame} with 2 columns:
           \itemize{
           \item Index of the winner neuron for each row (index starting at 1).
           \item Distance between winner and row.
           }

Description

Objects of type SOMnn can be created by training a self-organising map with som.nn.train.

Slots

name

optional name of the model.

date

time and date of creation.

codes

data.frame with codebook vectors of the som.

qerror

sum of the mapping errors of the training data.

class.idx

column index of column with class labels in input data.

classes

character vector with names of categories.

class.counts

data.frame with class hits for each neuron.

class.freqs

data.frame with class frequencies for each neuron (freqs sum up to 1).

norm

logical; if TRUE, data is normalised before training and mapping. Parameters for normalisation of training data is stored in the model and applied before mapping of test data.

norm.center

vector of centers for each column of training data.

norm.scale

vector of scale factors for each column of training data.

confusion

data.frame with confusion matrix for training data.

measures

data.frame with classes as rows and the columns sensitivity, specificity and accuracy for each class.

accuracy

The overall accuracy calculated based on the confusion matrix cmat: $acc = sum(diag(cmat)) / sum(cmat)$.

xdim

number of neurons in x-direction of the som.

ydim

number of neurons in y-direction of the som.

len.total

total number of training steps, performed to create the model.

toroidal

logical; if TRUE, the map is toroidal (i.e. borderless).

dist.fun

function; kernel for the kNN classifier.

max.dist

maximum distance for the kNN classifier.

strict

Minimum vote for the winner (if the winner's vote is smaller than strict, "unknown" is reported as class label (default = 0.8).