source: branches/TSNE/HeuristicLab.Algorithms.DataAnalysis/3.4/TSNE/TSNEAlgorithm.cs @ 14785

#region License Information
/* HeuristicLab
 * Copyright (C) 2002-2016 Heuristic and Evolutionary Algorithms Laboratory (HEAL)
 *
 * This file is part of HeuristicLab.
 *
 * HeuristicLab is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * HeuristicLab is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with HeuristicLab. If not, see <http://www.gnu.org/licenses/>.
 */
#endregion

using System;
using System.Collections.Generic;
using System.Drawing;
using System.Linq;
using System.Threading;
using HeuristicLab.Analysis;
using HeuristicLab.Common;
using HeuristicLab.Core;
using HeuristicLab.Data;
using HeuristicLab.Encodings.RealVectorEncoding;
using HeuristicLab.Optimization;
using HeuristicLab.Parameters;
using HeuristicLab.Persistence.Default.CompositeSerializers.Storable;
using HeuristicLab.Problems.DataAnalysis;
using HeuristicLab.Random;

namespace HeuristicLab.Algorithms.DataAnalysis {
  /// <summary>
  /// t-distributed stochastic neighbourhood embedding (tSNE) projects the data in a low dimensional 
  /// space to allow visual cluster identification.
  /// </summary>
  [Item("tSNE", "t-distributed stochastic neighbourhood embedding projects the data in a low " +
                "dimensional space to allow visual cluster identification.")]
  [Creatable(CreatableAttribute.Categories.DataAnalysis, Priority = 100)]
  [StorableClass]
  public sealed class TSNEAlgorithm : BasicAlgorithm {
    public override bool SupportsPause {
      get { return false; }
    }
    public override Type ProblemType {
      get { return typeof(IDataAnalysisProblem); }
    }
    public new IDataAnalysisProblem Problem {
      get { return (IDataAnalysisProblem)base.Problem; }
      set { base.Problem = value; }
    }

    #region parameter names
    private const string DistanceParameterName = "DistanceFunction";
    private const string PerplexityParameterName = "Perplexity";
    private const string ThetaParameterName = "Theta";
    private const string NewDimensionsParameterName = "Dimensions";
    private const string MaxIterationsParameterName = "MaxIterations";
    private const string StopLyingIterationParameterName = "StopLyingIteration";
    private const string MomentumSwitchIterationParameterName = "MomentumSwitchIteration";
    private const string InitialMomentumParameterName = "InitialMomentum";
    private const string FinalMomentumParameterName = "FinalMomentum";
    private const string EtaParameterName = "Eta";
    private const string SetSeedRandomlyParameterName = "SetSeedRandomly";
    private const string SeedParameterName = "Seed";
    private const string ClassesParameterName = "ClassNames";
    private const string NormalizationParameterName = "Normalization";
    #endregion

    #region parameter properties
    public IFixedValueParameter<DoubleValue> PerplexityParameter {
      get { return Parameters[PerplexityParameterName] as IFixedValueParameter<DoubleValue>; }
    }
    public IFixedValueParameter<DoubleValue> ThetaParameter {
      get { return Parameters[ThetaParameterName] as IFixedValueParameter<DoubleValue>; }
    }
    public IFixedValueParameter<IntValue> NewDimensionsParameter {
      get { return Parameters[NewDimensionsParameterName] as IFixedValueParameter<IntValue>; }
    }
    public IValueParameter<IDistance<double[]>> DistanceParameter {
      get { return Parameters[DistanceParameterName] as IValueParameter<IDistance<double[]>>; }
    }
    public IFixedValueParameter<IntValue> MaxIterationsParameter {
      get { return Parameters[MaxIterationsParameterName] as IFixedValueParameter<IntValue>; }
    }
    public IFixedValueParameter<IntValue> StopLyingIterationParameter {
      get { return Parameters[StopLyingIterationParameterName] as IFixedValueParameter<IntValue>; }
    }
    public IFixedValueParameter<IntValue> MomentumSwitchIterationParameter {
      get { return Parameters[MomentumSwitchIterationParameterName] as IFixedValueParameter<IntValue>; }
    }
    public IFixedValueParameter<DoubleValue> InitialMomentumParameter {
      get { return Parameters[InitialMomentumParameterName] as IFixedValueParameter<DoubleValue>; }
    }
    public IFixedValueParameter<DoubleValue> FinalMomentumParameter {
      get { return Parameters[FinalMomentumParameterName] as IFixedValueParameter<DoubleValue>; }
    }
    public IFixedValueParameter<DoubleValue> EtaParameter {
      get { return Parameters[EtaParameterName] as IFixedValueParameter<DoubleValue>; }
    }
    public IFixedValueParameter<BoolValue> SetSeedRandomlyParameter {
      get { return Parameters[SetSeedRandomlyParameterName] as IFixedValueParameter<BoolValue>; }
    }
    public IFixedValueParameter<IntValue> SeedParameter {
      get { return Parameters[SeedParameterName] as IFixedValueParameter<IntValue>; }
    }
    public IFixedValueParameter<StringValue> ClassesParameter {
      get { return Parameters[ClassesParameterName] as IFixedValueParameter<StringValue>; }
    }
    public IFixedValueParameter<BoolValue> NormalizationParameter {
      get { return Parameters[NormalizationParameterName] as IFixedValueParameter<BoolValue>; }
    }
    #endregion

    #region  Properties
    public IDistance<double[]> Distance {
      get { return DistanceParameter.Value; }
    }
    public double Perplexity {
      get { return PerplexityParameter.Value.Value; }
      set { PerplexityParameter.Value.Value = value; }
    }
    public double Theta {
      get { return ThetaParameter.Value.Value; }
      set { ThetaParameter.Value.Value = value; }
    }
    public int NewDimensions {
      get { return NewDimensionsParameter.Value.Value; }
      set { NewDimensionsParameter.Value.Value = value; }
    }
    public int MaxIterations {
      get { return MaxIterationsParameter.Value.Value; }
      set { MaxIterationsParameter.Value.Value = value; }
    }
    public int StopLyingIteration {
      get { return StopLyingIterationParameter.Value.Value; }
      set { StopLyingIterationParameter.Value.Value = value; }
    }
    public int MomentumSwitchIteration {
      get { return MomentumSwitchIterationParameter.Value.Value; }
      set { MomentumSwitchIterationParameter.Value.Value = value; }
    }
    public double InitialMomentum {
      get { return InitialMomentumParameter.Value.Value; }
      set { InitialMomentumParameter.Value.Value = value; }
    }
    public double FinalMomentum {
      get { return FinalMomentumParameter.Value.Value; }
      set { FinalMomentumParameter.Value.Value = value; }
    }
    public double Eta {
      get { return EtaParameter.Value.Value; }
      set { EtaParameter.Value.Value = value; }
    }
    public bool SetSeedRandomly {
      get { return SetSeedRandomlyParameter.Value.Value; }
      set { SetSeedRandomlyParameter.Value.Value = value; }
    }
    public int Seed {
      get { return SeedParameter.Value.Value; }
      set { SeedParameter.Value.Value = value; }
    }
    public string Classes {
      get { return ClassesParameter.Value.Value; }
      set { ClassesParameter.Value.Value = value; }
    }
    public bool Normalization {
      get { return NormalizationParameter.Value.Value; }
      set { NormalizationParameter.Value.Value = value; }
    }
    [Storable]
    public TSNE<double[]> tsne;
    #endregion

    #region Constructors & Cloning
    [StorableConstructor]
    private TSNEAlgorithm(bool deserializing) : base(deserializing) { }
    private TSNEAlgorithm(TSNEAlgorithm original, Cloner cloner) : base(original, cloner) { }
    public override IDeepCloneable Clone(Cloner cloner) { return new TSNEAlgorithm(this, cloner); }
    public TSNEAlgorithm() {
      Problem = new RegressionProblem();
      Parameters.Add(new ValueParameter<IDistance<double[]>>(DistanceParameterName, "The distance function used to differentiate similar from non-similar points", new EuclideanDistance()));
      Parameters.Add(new FixedValueParameter<DoubleValue>(PerplexityParameterName, "Perplexity-Parameter of tSNE. Comparable to k in a k-nearest neighbour algorithm. Recommended value is floor(number of points /3) or lower", new DoubleValue(25)));
      Parameters.Add(new FixedValueParameter<DoubleValue>(ThetaParameterName, "Value describing how much appoximated gradients my differ from exact gradients. Set to 0 for exact calculation and in [0,1] otherwise \n CAUTION: exact calculation of forces requires building a non-sparse N*N matrix where N is the number of data points\n This may exceed memory limitations", new DoubleValue(0)));
      Parameters.Add(new FixedValueParameter<IntValue>(NewDimensionsParameterName, "Dimensionality of projected space (usually 2 for easy visual analysis)", new IntValue(2)));
      Parameters.Add(new FixedValueParameter<IntValue>(MaxIterationsParameterName, "Maximum number of iterations for gradient descent", new IntValue(1000)));
      Parameters.Add(new FixedValueParameter<IntValue>(StopLyingIterationParameterName, "Number of iterations after which p is no longer approximated", new IntValue(0)));
      Parameters.Add(new FixedValueParameter<IntValue>(MomentumSwitchIterationParameterName, "Number of iterations after which the momentum in the gradient descent is switched", new IntValue(0)));
      Parameters.Add(new FixedValueParameter<DoubleValue>(InitialMomentumParameterName, "The initial momentum in the gradient descent", new DoubleValue(0.5)));
      Parameters.Add(new FixedValueParameter<DoubleValue>(FinalMomentumParameterName, "The final momentum", new DoubleValue(0.8)));
      Parameters.Add(new FixedValueParameter<DoubleValue>(EtaParameterName, "Gradient descent learning rate", new DoubleValue(200)));
      Parameters.Add(new FixedValueParameter<BoolValue>(SetSeedRandomlyParameterName, "If the seed should be random", new BoolValue(true)));
      Parameters.Add(new FixedValueParameter<IntValue>(SeedParameterName, "The seed used if it should not be random", new IntValue(0)));
      Parameters.Add(new FixedValueParameter<StringValue>(ClassesParameterName, "name of the column specifying the class lables of each data point. \n if the lable column can not be found training/test is used as labels", new StringValue("none")));
      Parameters.Add(new FixedValueParameter<BoolValue>(NormalizationParameterName, "Whether the data should be zero centered and have variance of 1 for each variable, so different scalings are ignored", new BoolValue(true)));

      MomentumSwitchIterationParameter.Hidden = true;
      InitialMomentumParameter.Hidden = true;
      FinalMomentumParameter.Hidden = true;
      StopLyingIterationParameter.Hidden = true;
      EtaParameter.Hidden = true;
    }
    #endregion

    public override void Stop() {
      base.Stop();
      if (tsne != null) tsne.Running = false;
    }

    protected override void Run(CancellationToken cancellationToken) {
      var dataRowNames = new Dictionary<string, List<int>>();
      var rows = new Dictionary<string, ScatterPlotDataRow>();
      var problemData = Problem.ProblemData;

      //color datapoints acording to classes variable (be it double or string)
      if (problemData.Dataset.VariableNames.Contains(Classes)) {
        if ((problemData.Dataset as Dataset).VariableHasType<string>(Classes)) {
          var classes = problemData.Dataset.GetStringValues(Classes).ToArray();
          for (var i = 0; i < classes.Length; i++) {
            if (!dataRowNames.ContainsKey(classes[i])) dataRowNames.Add(classes[i], new List<int>());
            dataRowNames[classes[i]].Add(i);
          }
        } else if ((problemData.Dataset as Dataset).VariableHasType<double>(Classes)) {
          var classValues = problemData.Dataset.GetDoubleValues(Classes).ToArray();
          var max = classValues.Max() + 0.1;     // TODO consts
          var min = classValues.Min() - 0.1;
          const int contours = 8;
          for (var i = 0; i < contours; i++) {
            var contourname = GetContourName(i, min, max, contours);
            dataRowNames.Add(contourname, new List<int>());
            rows.Add(contourname, new ScatterPlotDataRow(contourname, "", new List<Point2D<double>>()));
            rows[contourname].VisualProperties.Color = GetHeatMapColor(i, contours);
            rows[contourname].VisualProperties.PointSize = i + 3;
          }
          for (var i = 0; i < classValues.Length; i++) {
            dataRowNames[GetContourName(classValues[i], min, max, contours)].Add(i);
          }
        }
      } else {
        dataRowNames.Add("Training", problemData.TrainingIndices.ToList());
        dataRowNames.Add("Test", problemData.TestIndices.ToList());
      }

      // set up and run tSNE
      if (SetSeedRandomly) Seed = new System.Random().Next();
      var random = new MersenneTwister((uint)Seed);
      tsne = new TSNE<double[]>(Distance, random, Results, MaxIterations, StopLyingIteration, MomentumSwitchIteration, InitialMomentum, FinalMomentum, Eta, dataRowNames, rows);
      var dataset = problemData.Dataset;
      var allowedInputVariables = problemData.AllowedInputVariables.ToArray();
      var data = new double[dataset.Rows][];
      for (var row = 0; row < dataset.Rows; row++) data[row] = allowedInputVariables.Select(col => dataset.GetDoubleValue(col, row)).ToArray();
      if (Normalization) data = NormalizeData(data);
      tsne.Run(data, NewDimensions, Perplexity, Theta);
    }

    private static double[][] NormalizeData(IReadOnlyList<double[]> data) {
      var n = data[0].Length;
      var mean = new double[n];
      var sd = new double[n];
      var nData = new double[data.Count][];
      for (var i = 0; i < n; i++) {
        var i1 = i;
        sd[i] = Enumerable.Range(0, data.Count).Select(x => data[x][i1]).StandardDeviation();
        mean[i] = Enumerable.Range(0, data.Count).Select(x => data[x][i1]).Average();
      }
      for (var i = 0; i < data.Count; i++) {
        nData[i] = new double[n];
        for (var j = 0; j < n; j++) nData[i][j] = (data[i][j] - mean[j]) / sd[j];
      }
      return nData;
    }
    private static Color GetHeatMapColor(int contourNr, int noContours) {
      var q = (double)contourNr / noContours;  // q in [0,1]
      var c = q < 0.5 ? Color.FromArgb((int)(q * 2 * 255), 255, 0) : Color.FromArgb(255, (int)((1 - q) * 2 * 255), 0);
      return c;
    }
    private static string GetContourName(double value, double min, double max, int noContours) {
      var size = (max - min) / noContours;
      var contourNr = (int)((value - min) / size);
      return GetContourName(contourNr, min, max, noContours);
    }
    private static string GetContourName(int i, double min, double max, int noContours) {
      var size = (max - min) / noContours;
      return "[" + (min + i * size) + ";" + (min + (i + 1) * size) + ")";
    }
  }
}