/*
 *
 *  * Copyright 2015 Skymind,Inc.
 *  *
 *  *    Licensed 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.deeplearning4j.models.embeddings.wordvectors;

import org.deeplearning4j.models.embeddings.WeightLookupTable;
import org.deeplearning4j.models.word2vec.wordstore.VocabCache;
import org.nd4j.linalg.api.ndarray.INDArray;

import java.io.Serializable;
import java.util.Collection;
import java.util.List;
import java.util.Map;

/**
 * Word vectors. Handles operations based on the lookup table
 * and vocab.
 *
 * @author Adam Gibson
 */
public interface WordVectors extends Serializable {


    /**
     * Returns true if the model has this word in the vocab
     * @param word the word to test for
     * @return true if the model has the word in the vocab
     */
    boolean hasWord(String word);

    Collection<String> wordsNearest(INDArray words, int top);

    Collection<String> wordsNearestSum(INDArray words, int top);

    /**
     * Get the top n words most similar to the given word
     * @param word the word to compare
     * @param n the n to get
     * @return the top n words
     */
    Collection<String> wordsNearestSum(String word,int n);


    /**
     * Words nearest based on positive and negative words
     * @param positive the positive words
     * @param negative the negative words
     * @param top the top n words
     * @return the words nearest the mean of the words
     */
    Collection<String> wordsNearestSum(List<String> positive,List<String> negative,int top);

    /**
     * Accuracy based on questions which are a space separated list of strings
     * where the first word is the query word, the next 2 words are negative,
     * and the last word is the predicted word to be nearest
     * @param questions the questions to ask
     * @return the accuracy based on these questions
     */
    Map<String,Double> accuracy(List<String> questions);

    int indexOf(String word);

    /**
     * Find all words with a similar characters
     * in the vocab
     * @param word the word to compare
     * @param accuracy the accuracy: 0 to 1
     * @return the list of words that are similar in the vocab
     */
    List<String> similarWordsInVocabTo(String word,double accuracy);

    /**
     * Get the word vector for a given matrix
     * @param word the word to get the matrix for
     * @return the ndarray for this word
     */
    double[] getWordVector(String word);

    /**
     * Returns the word vector divided by the norm2 of the array
     * @param word the word to get the matrix for
     * @return the looked up matrix
     */
    INDArray getWordVectorMatrixNormalized(String word);

    /**
     * Get the word vector for a given matrix
     * @param word the word to get the matrix for
     * @return the ndarray for this word
     */
    INDArray getWordVectorMatrix(String word);
    /**
     * Words nearest based on positive and negative words
     * @param positive the positive words
     * @param negative the negative words
     * @param top the top n words
     * @return the words nearest the mean of the words
     */
    Collection<String> wordsNearest(List<String> positive,List<String> negative,int top);


    /**
     * Get the top n words most similar to the given word
     * @param word the word to compare
     * @param n the n to get
     * @return the top n words
     */
    Collection<String> wordsNearest(String word,int n);



    /**
     * Returns the similarity of 2 words
     * @param word the first word
     * @param word2 the second word
     * @return a normalized similarity (cosine similarity)
     */
    double similarity(String word,String word2);

    /**
     * Vocab for the vectors
     * @return
     */
    VocabCache vocab();

    /**
     * Lookup table for the vectors
     * @return
     */
    WeightLookupTable lookupTable();

}

@@ -2021,20 +2021,26 @@
 restSum(
-List
+Collection
 %3CString%3E
@@ -2041,36 +2041,42 @@
 tring%3E positive,
-List
+Collection
 %3CString%3E negativ
@@ -3712,20 +3712,26 @@
 Nearest(
-List
+Collection
 %3CString%3E
@@ -3740,20 +3740,26 @@
 ositive,
-List
+Collection
 %3CString%3E

Support other collections of words such as Set