1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18 package org.apache.commons.math4.neuralnet.twod.util;
19
20 import org.apache.commons.math4.neuralnet.DistanceMeasure;
21 import org.apache.commons.math4.neuralnet.Neuron;
22 import org.apache.commons.math4.neuralnet.twod.NeuronSquareMesh2D;
23
24 /**
25 * <a href="http://en.wikipedia.org/wiki/U-Matrix">U-Matrix</a>
26 * visualization of high-dimensional data projection.
27 * The 8 individual inter-units distances will be
28 * {@link #computeImage(NeuronSquareMesh2D) computed}. They will be
29 * stored in additional pixels around each of the original units of the
30 * 2D-map. The additional pixels that lie along a "diagonal" are shared
31 * by <em>two</em> pairs of units: their value will be set to the average
32 * distance between the units belonging to each of the pairs. The value
33 * zero will be stored in the pixel corresponding to the location of a
34 * unit of the 2D-map.
35 *
36 * @since 3.6
37 * @see org.apache.commons.math4.neuralnet.twod.NeuronSquareMesh2D.DataVisualization#getUMatrix()
38 */
39 public class UnifiedDistanceMatrix implements MapVisualization {
40 /** Distance. */
41 private final DistanceMeasure distance;
42
43 /**
44 * @param distance Distance.
45 */
46 public UnifiedDistanceMatrix(DistanceMeasure distance) {
47 this.distance = distance;
48 }
49
50 /**
51 * Computes the distances between a unit of the map and its
52 * neighbours.
53 * The image will contain more pixels than the number of neurons
54 * in the given {@code map} because each neuron has 8 neighbours.
55 * The value zero will be stored in the pixels corresponding to
56 * the location of a map unit.
57 *
58 * @param map Map.
59 * @return an image representing the individual distances.
60 */
61 @Override
62 public double[][] computeImage(NeuronSquareMesh2D map) {
63 final int numRows = map.getNumberOfRows();
64 final int numCols = map.getNumberOfColumns();
65
66 final double[][] uMatrix = new double[numRows * 2 + 1][numCols * 2 + 1];
67
68 // 1.
69 // Fill right and bottom slots of each unit's location with the
70 // distance between the current unit and each of the two neighbours,
71 // respectively.
72 for (int i = 0; i < numRows; i++) {
73 // Current unit's row index in result image.
74 final int iR = 2 * i + 1;
75
76 for (int j = 0; j < numCols; j++) {
77 // Current unit's column index in result image.
78 final int jR = 2 * j + 1;
79
80 final double[] current = map.getNeuron(i, j).getFeatures();
81 Neuron neighbour;
82
83 // Right neighbour.
84 neighbour = map.getNeuron(i, j,
85 NeuronSquareMesh2D.HorizontalDirection.RIGHT,
86 NeuronSquareMesh2D.VerticalDirection.CENTER);
87 if (neighbour != null) {
88 uMatrix[iR][jR + 1] = distance.applyAsDouble(current,
89 neighbour.getFeatures());
90 }
91
92 // Bottom-center neighbour.
93 neighbour = map.getNeuron(i, j,
94 NeuronSquareMesh2D.HorizontalDirection.CENTER,
95 NeuronSquareMesh2D.VerticalDirection.DOWN);
96 if (neighbour != null) {
97 uMatrix[iR + 1][jR] = distance.applyAsDouble(current,
98 neighbour.getFeatures());
99 }
100 }
101 }
102
103 // 2.
104 // Fill the bottom-right slot of each unit's location with the average
105 // of the distances between
106 // * the current unit and its bottom-right neighbour, and
107 // * the bottom-center neighbour and the right neighbour.
108 for (int i = 0; i < numRows; i++) {
109 // Current unit's row index in result image.
110 final int iR = 2 * i + 1;
111
112 for (int j = 0; j < numCols; j++) {
113 // Current unit's column index in result image.
114 final int jR = 2 * j + 1;
115
116 final Neuron current = map.getNeuron(i, j);
117 final Neuron right = map.getNeuron(i, j,
118 NeuronSquareMesh2D.HorizontalDirection.RIGHT,
119 NeuronSquareMesh2D.VerticalDirection.CENTER);
120 final Neuron bottom = map.getNeuron(i, j,
121 NeuronSquareMesh2D.HorizontalDirection.CENTER,
122 NeuronSquareMesh2D.VerticalDirection.DOWN);
123 final Neuron bottomRight = map.getNeuron(i, j,
124 NeuronSquareMesh2D.HorizontalDirection.RIGHT,
125 NeuronSquareMesh2D.VerticalDirection.DOWN);
126
127 final double current2BottomRight = bottomRight == null ?
128 0 :
129 distance.applyAsDouble(current.getFeatures(),
130 bottomRight.getFeatures());
131 final double right2Bottom = (right == null ||
132 bottom == null) ?
133 0 :
134 distance.applyAsDouble(right.getFeatures(),
135 bottom.getFeatures());
136
137 // Bottom-right slot.
138 uMatrix[iR + 1][jR + 1] = 0.5 * (current2BottomRight + right2Bottom);
139 }
140 }
141
142 // 3. Copy last row into first row.
143 final int lastRow = uMatrix.length - 1;
144 uMatrix[0] = uMatrix[lastRow];
145
146 // 4.
147 // Copy last column into first column.
148 final int lastCol = uMatrix[0].length - 1;
149 for (int r = 0; r < lastRow; r++) {
150 uMatrix[r][0] = uMatrix[r][lastCol];
151 }
152
153 return uMatrix;
154 }
155 }