001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017
018package org.apache.commons.math4.ml.neuralnet.twod.util;
019
020import java.util.List;
021import org.apache.commons.math4.ml.neuralnet.MapRanking;
022import org.apache.commons.math4.ml.neuralnet.Neuron;
023import org.apache.commons.math4.ml.neuralnet.twod.NeuronSquareMesh2D;
024import org.apache.commons.math4.ml.distance.DistanceMeasure;
025import org.apache.commons.math4.exception.NumberIsTooSmallException;
026
027/**
028 * Visualization of high-dimensional data projection on a 2D-map.
029 * The method is described in
030 * <blockquote>
031 *  <em>Using Smoothed Data Histograms for Cluster Visualization in Self-Organizing Maps</em>
032 *  <br>
033 *  by Elias Pampalk, Andreas Rauber and Dieter Merkl.
034 * </blockquote>
035 * @since 3.6
036 */
037public class SmoothedDataHistogram implements MapDataVisualization {
038    /** Smoothing parameter. */
039    private final int smoothingBins;
040    /** Distance. */
041    private final DistanceMeasure distance;
042    /** Normalization factor. */
043    private final double membershipNormalization;
044
045    /**
046     * @param smoothingBins Number of bins.
047     * @param distance Distance.
048     */
049    public SmoothedDataHistogram(int smoothingBins,
050                                 DistanceMeasure distance) {
051        this.smoothingBins = smoothingBins;
052        this.distance = distance;
053
054        double sum = 0;
055        for (int i = 0; i < smoothingBins; i++) {
056            sum += smoothingBins - i;
057        }
058
059        this.membershipNormalization = 1d / sum;
060    }
061
062    /**
063     * {@inheritDoc}
064     *
065     * @throws NumberIsTooSmallException if the size of the {@code map}
066     * is smaller than the number of {@link #SmoothedDataHistogram(int,DistanceMeasure)
067     * smoothing bins}.
068     */
069    @Override
070    public double[][] computeImage(NeuronSquareMesh2D map,
071                                   Iterable<double[]> data) {
072        final int nR = map.getNumberOfRows();
073        final int nC = map.getNumberOfColumns();
074
075        final int mapSize = nR * nC;
076        if (mapSize < smoothingBins) {
077            throw new NumberIsTooSmallException(mapSize, smoothingBins, true);
078        }
079
080        final LocationFinder finder = new LocationFinder(map);
081        final MapRanking rank = new MapRanking(map.getNetwork(), distance);
082
083        // Histogram bins.
084        final double[][] histo = new double[nR][nC];
085
086        for (double[] sample : data) {
087            final List<Neuron> sorted = rank.rank(sample);
088            for (int i = 0; i < smoothingBins; i++) {
089                final LocationFinder.Location loc = finder.getLocation(sorted.get(i));
090                final int row = loc.getRow();
091                final int col = loc.getColumn();
092                histo[row][col] += (smoothingBins - i) * membershipNormalization;
093            }
094        }
095
096        return histo;
097    }
098}