/**
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.apache.mahout.cf.taste.impl.similarity;

import java.util.Collection;
import java.util.Iterator;
import java.util.NoSuchElementException;

import org.apache.mahout.cf.taste.common.Refreshable;
import org.apache.mahout.cf.taste.common.TasteException;
import org.apache.mahout.cf.taste.impl.common.FastByIDMap;
import org.apache.mahout.cf.taste.impl.recommender.TopItems;
import org.apache.mahout.cf.taste.model.DataModel;
import org.apache.mahout.cf.taste.similarity.ItemSimilarity;
import org.apache.mahout.common.RandomUtils;
import org.apache.mahout.common.iterator.IteratorIterable;
import org.apache.mahout.common.iterator.IteratorUtils;

import com.google.common.base.Preconditions;

/**
 * <p>
 * A "generic" {@link ItemSimilarity} which takes a static list of precomputed item similarities and bases its
 * responses on that alone. The values may have been precomputed offline by another process, stored in a file,
 * and then read and fed into an instance of this class.
 * </p>
 * 
 * <p>
 * This is perhaps the best {@link ItemSimilarity} to use with
 * {@link org.apache.mahout.cf.taste.impl.recommender.GenericItemBasedRecommender}, for now, since the point
 * of item-based recommenders is that they can take advantage of the fact that item similarity is relatively
 * static, can be precomputed, and then used in computation to gain a significant performance advantage.
 * </p>
 */
public final class GenericItemSimilarity implements ItemSimilarity {
  
  private final FastByIDMap<FastByIDMap<Double>> similarityMaps = new FastByIDMap<FastByIDMap<Double>>();
  
  /**
   * <p>
   * Creates a  from a precomputed list of {@link ItemItemSimilarity}s. Each
   * represents the similarity between two distinct items. Since similarity is assumed to be symmetric, it is
   * not necessary to specify similarity between item1 and item2, and item2 and item1. Both are the same. It
   * is also not necessary to specify a similarity between any item and itself; these are assumed to be 1.0.
   * </p>
   * 
   * <p>
   * Note that specifying a similarity between two items twice is not an error, but, the later value will win.
   * </p>
   * 
   * @param similarities
   *          set of {@link ItemItemSimilarity}s on which to base this instance
   */
  public GenericItemSimilarity(Iterable<ItemItemSimilarity> similarities) {
    initSimilarityMaps(similarities);
  }
  
  /**
   * <p>
   * Like {@link #GenericItemSimilarity(Iterable)}, but will only keep the specified number of similarities
   * from the given {@link Iterable} of similarities. It will keep those with the highest similarity -- those
   * that are therefore most important.
   * </p>
   * 
   * <p>
   * Thanks to tsmorton for suggesting this and providing part of the implementation.
   * </p>
   * 
   * @param similarities
   *          set of {@link ItemItemSimilarity}s on which to base this instance
   * @param maxToKeep
   *          maximum number of similarities to keep
   */
  public GenericItemSimilarity(Iterable<ItemItemSimilarity> similarities, int maxToKeep) {
    Iterable<ItemItemSimilarity> keptSimilarities = TopItems.getTopItemItemSimilarities(maxToKeep,
      similarities);
    initSimilarityMaps(keptSimilarities);
  }
  
  /**
   * <p>
   * Builds a list of item-item similarities given an {@link ItemSimilarity} implementation and a
   * {@link DataModel}, rather than a list of {@link ItemItemSimilarity}s.
   * </p>
   * 
   * <p>
   * It's valid to build a  this way, but perhaps missing some of the point of an
   * item-based recommender. Item-based recommenders use the assumption that item-item similarities are
   * relatively fixed, and might be known already independent of user preferences. Hence it is useful to
   * inject that information, using {@link #GenericItemSimilarity(Iterable)}.
   * </p>
   * 
   * @param otherSimilarity
   *          other {@link ItemSimilarity} to get similarities from
   * @param dataModel
   *          data model to get items from
   * @throws TasteException
   *           if an error occurs while accessing the {@link DataModel} items
   */
  public GenericItemSimilarity(ItemSimilarity otherSimilarity, DataModel dataModel) throws TasteException {
    long[] itemIDs = IteratorUtils.longIteratorToList(dataModel.getItemIDs());
    Iterator<ItemItemSimilarity> it = new DataModelSimilaritiesIterator(otherSimilarity, itemIDs);
    initSimilarityMaps(new IteratorIterable<ItemItemSimilarity>(it));
  }
  
  /**
   * <p>
   * Like {@link #GenericItemSimilarity(ItemSimilarity, DataModel)} )}, but will only keep the specified
   * number of similarities from the given {@link DataModel}. It will keep those with the highest similarity
   * -- those that are therefore most important.
   * </p>
   * 
   * <p>
   * Thanks to tsmorton for suggesting this and providing part of the implementation.
   * </p>
   * 
   * @param otherSimilarity
   *          other {@link ItemSimilarity} to get similarities from
   * @param dataModel
   *          data model to get items from
   * @param maxToKeep
   *          maximum number of similarities to keep
   * @throws TasteException
   *           if an error occurs while accessing the {@link DataModel} items
   */
  public GenericItemSimilarity(ItemSimilarity otherSimilarity,
                               DataModel dataModel, int maxToKeep) throws TasteException {
    long[] itemIDs = IteratorUtils.longIteratorToList(dataModel.getItemIDs());
    Iterator<ItemItemSimilarity> it = new DataModelSimilaritiesIterator(otherSimilarity, itemIDs);
    Iterable<ItemItemSimilarity> keptSimilarities = TopItems.getTopItemItemSimilarities(maxToKeep,
      new IteratorIterable<ItemItemSimilarity>(it));
    initSimilarityMaps(keptSimilarities);
  }
  
  private void initSimilarityMaps(Iterable<ItemItemSimilarity> similarities) {
    for (ItemItemSimilarity iic : similarities) {
      long similarityItemID1 = iic.getItemID1();
      long similarityItemID2 = iic.getItemID2();
      if (similarityItemID1 != similarityItemID2) {
        // Order them -- first key should be the "smaller" one
        long itemID1;
        long itemID2;
        if (similarityItemID1 < similarityItemID2) {
          itemID1 = similarityItemID1;
          itemID2 = similarityItemID2;
        } else {
          itemID1 = similarityItemID2;
          itemID2 = similarityItemID1;
        }
        FastByIDMap<Double> map = similarityMaps.get(itemID1);
        if (map == null) {
          map = new FastByIDMap<Double>();
          similarityMaps.put(itemID1, map);
        }
        map.put(itemID2, iic.getValue());
      }
      // else similarity between item and itself already assumed to be 1.0
    }
  }
  
  /**
   * <p>
   * Returns the similarity between two items. Note that similarity is assumed to be symmetric, that
   * <code>itemSimilarity(item1, item2) == itemSimilarity(item2, item1)</code>, and that
   * <code>itemSimilarity(item1,
   * item1) == 1.0</code> for all items.
   * </p>
   * 
   * @param itemID1
   *          first item
   * @param itemID2
   *          second item
   * @return similarity between the two
   */
  @Override
  public double itemSimilarity(long itemID1, long itemID2) {
    if (itemID1 == itemID2) {
      return 1.0;
    }
    long firstID;
    long secondID;
    if (itemID1 < itemID2) {
      firstID = itemID1;
      secondID = itemID2;
    } else {
      firstID = itemID2;
      secondID = itemID1;
    }
    FastByIDMap<Double> nextMap = similarityMaps.get(firstID);
    if (nextMap == null) {
      return Double.NaN;
    }
    Double similarity = nextMap.get(secondID);
    return similarity == null ? Double.NaN : similarity;
  }

  @Override
  public double[] itemSimilarities(long itemID1, long[] itemID2s) {
    int length = itemID2s.length;
    double[] result = new double[length];
    for (int i = 0; i < length; i++) {
      result[i] = itemSimilarity(itemID1, itemID2s[i]);
    }
    return result;
  }
  
  @Override
  public void refresh(Collection<Refreshable> alreadyRefreshed) {
  // Do nothing
  }
  
  /** Encapsulates a similarity between two items. Similarity must be in the range [-1.0,1.0]. */
  public static final class ItemItemSimilarity implements Comparable<ItemItemSimilarity> {
    
    private final long itemID1;
    private final long itemID2;
    private final double value;
    
    /**
     * @param itemID1
     *          first item
     * @param itemID2
     *          second item
     * @param value
     *          similarity between the two
     * @throws IllegalArgumentException
     *           if value is NaN, less than -1.0 or greater than 1.0
     */
    public ItemItemSimilarity(long itemID1, long itemID2, double value) {
      Preconditions.checkArgument(value >= -1.0 && value <= 1.0, "Illegal value: %s", value);
      this.itemID1 = itemID1;
      this.itemID2 = itemID2;
      this.value = value;
    }
    
    public long getItemID1() {
      return itemID1;
    }
    
    public long getItemID2() {
      return itemID2;
    }
    
    public double getValue() {
      return value;
    }
    
    @Override
    public String toString() {
      return "ItemItemSimilarity[" + itemID1 + ',' + itemID2 + ':' + value + ']';
    }
    
    /** Defines an ordering from highest similarity to lowest. */
    @Override
    public int compareTo(ItemItemSimilarity other) {
      double otherValue = other.getValue();
      return value > otherValue ? -1 : value < otherValue ? 1 : 0;
    }
    
    @Override
    public boolean equals(Object other) {
      if (!(other instanceof ItemItemSimilarity)) {
        return false;
      }
      ItemItemSimilarity otherSimilarity = (ItemItemSimilarity) other;
      return (otherSimilarity.getItemID1() == itemID1) && (otherSimilarity.getItemID2() == itemID2)
             && (otherSimilarity.getValue() == value);
    }
    
    @Override
    public int hashCode() {
      return (int) itemID1 ^ (int) itemID2 ^ RandomUtils.hashDouble(value);
    }
    
  }
  
  private static final class DataModelSimilaritiesIterator implements Iterator<ItemItemSimilarity> {
    
    private final ItemSimilarity otherSimilarity;
    private final long[] itemIDs;
    private int i;
    private long itemID1;
    private int j;
    private ItemItemSimilarity next;
    
    private DataModelSimilaritiesIterator(ItemSimilarity otherSimilarity, long[] itemIDs) {
      this.otherSimilarity = otherSimilarity;
      this.itemIDs = itemIDs;
      i = 0;
      itemID1 = itemIDs[0];
      j = 1;
      goToNext();
    }
    
    private void goToNext() {
      next = null;
      int size = itemIDs.length;
      while ((next == null) && (i < size - 1)) {
        long itemID2 = itemIDs[j];
        double similarity;
        try {
          similarity = otherSimilarity.itemSimilarity(itemID1, itemID2);
        } catch (TasteException te) {
          // ugly:
          throw new IllegalStateException(te);
        }
        if (!Double.isNaN(similarity)) {
          next = new ItemItemSimilarity(itemID1, itemID2, similarity);
        }
        if (++j == size) {
          itemID1 = itemIDs[++i];
          j = i + 1;
        }
      }
    }
    
    @Override
    public boolean hasNext() {
      return next != null;
    }
    
    @Override
    public ItemItemSimilarity next() {
      if (next == null) {
        throw new NoSuchElementException();
      }
      ItemItemSimilarity result = next;
      goToNext();
      return result;
    }
    
    @Override
    public void remove() {
      throw new UnsupportedOperationException();
    }
    
  }
  
}
