package jsat.linear.distancemetrics;

import java.util.List;
import java.util.concurrent.ExecutorService;
import jsat.DataSet;
import jsat.classifiers.ClassificationDataSet;
import jsat.linear.Vec;
import jsat.regression.RegressionDataSet;

/**
 * Some Distance Metrics require information that can be learned from the data set. 
 * Trainable Distance Metrics support this facility, and algorithms that rely on 
 * distance metrics should check if their metric needs training. This is needed 
 * priming the distance metric on the whole data set and then performing cross 
 * validation would bias the results, as the metric would have been trained on
 * the testing set examples. 
 * 
 * @author Edward Raff
 */
abstract public class TrainableDistanceMetric implements DistanceMetric
{
    
    private static final long serialVersionUID = 6356276953152869105L;

    /**
     * Trains this metric on the given data set
     * @param  the type of vectors in the list
     * @param dataSet the data set to train on
     * @throws UnsupportedOperationException if the metric can not be trained from unlabeled data
     */
    public  void train(List dataSet)
    {
        train(dataSet, false);
    }
    
    /**
     * Trains this metric on the given data set
     * @param  the type of vectors in the list
     * @param dataSet the data set to train on
     * @param parallel {@code true} if multiple threads should be used for
     * training. {@code false} if it should be done in a single-threaded manner.
     * @throws UnsupportedOperationException if the metric can not be trained from unlabeled data
     */
    abstract public  void train(List dataSet, boolean parallel);
    
    /**
     * Trains this metric on the given data set
     * @param dataSet the data set to train on
     * @throws UnsupportedOperationException if the metric can not be trained from unlabeled data
     */
    public void train(DataSet dataSet)
    {
        train(dataSet, false);
    }
    
    /**
     * Trains this metric on the given data set
     * @param dataSet the data set to train on
     * @param parallel {@code true} if multiple threads should be used for
     * training. {@code false} if it should be done in a single-threaded manner.
     * @throws UnsupportedOperationException if the metric can not be trained from unlabeled data
     */
    abstract public void train(DataSet dataSet, boolean parallel);
    
    /**
     * Trains this metric on the given classification problem data set
     * @param dataSet the data set to train on 
     * @throws UnsupportedOperationException if the metric can not be trained from classification problems
     */
    public void train(ClassificationDataSet dataSet)
    {
        train(dataSet, false);
    }
    
    /**
     * Trains this metric on the given classification problem data set
     *
     * @param dataSet the data set to train on
     * @param parallel {@code true} if multiple threads should be used for
     * training. {@code false} if it should be done in a single-threaded manner.
     * @throws UnsupportedOperationException if the metric can not be trained
     * from classification problems
     */
    abstract public void train(ClassificationDataSet dataSet, boolean parallel);
    
    /**
     * Some metrics might be special purpose, and not trainable for all types of data sets or tasks. 
     * This method returns true if this metric supports training for classification 
     * problems, and false if it does not. 
* If a metric can learn from unlabeled data, it must return true * for this method. * * @return true if this metric supports training for classification * problems, and false if it does not */ abstract public boolean supportsClassificationTraining(); /** * Trains this metric on the given regression problem data set * @param dataSet the data set to train on * @throws UnsupportedOperationException if the metric can not be trained from regression problems */ abstract public void train(RegressionDataSet dataSet); /** * Trains this metric on the given regression problem data set * @param dataSet the data set to train on * @param parallel {@code true} if multiple threads should be used for * training. {@code false} if it should be done in a single-threaded manner. * @throws UnsupportedOperationException if the metric can not be trained from regression problems */ abstract public void train(RegressionDataSet dataSet, boolean parallel); /** * Some metrics might be special purpose, and not trainable for all types of data sets tasks. * This method returns true if this metric supports training for regression * problems, and false if it does not.
* If a metric can learn from unlabeled data, it must return true * for this method. * * @return true if this metric supports training for regression * problems, and false if it does not */ abstract public boolean supportsRegressionTraining(); /** * Returns true if the metric needs to be trained. This may be false if * the metric allows the parameters to be specified beforehand. If the information * was specified before hand, or does not need training, false is returned. * * @return true if the metric needs training, false if it does not. */ abstract public boolean needsTraining(); @Override abstract public TrainableDistanceMetric clone(); /** * Static helper method for training a distance metric only if it is needed. * This method can be safely called for any Distance Metric. * * @param dm the distance metric to train * @param dataset the data set to train from */ public static void trainIfNeeded(DistanceMetric dm, DataSet dataset) { trainIfNeeded(dm, dataset, false); } /** * Static helper method for training a distance metric only if it is needed. * This method can be safely called for any Distance Metric. * * @param dm the distance metric to train * @param dataset the data set to train from * @param parallel {@code true} if multiple threads should be used for * training. {@code false} if it should be done in a single-threaded manner. */ public static void trainIfNeeded(DistanceMetric dm, DataSet dataset, boolean parallel) { if(!(dm instanceof TrainableDistanceMetric)) return; TrainableDistanceMetric tdm = (TrainableDistanceMetric) dm; if(!tdm.needsTraining()) return; if(dataset instanceof RegressionDataSet) tdm.train((RegressionDataSet) dataset, parallel); else if(dataset instanceof ClassificationDataSet) tdm.train((ClassificationDataSet) dataset, parallel); else tdm.train(dataset, parallel); } /** * Static helper method for training a distance metric only if it is needed. * This method can be safely called for any Distance Metric. * * @param dm the distance metric to train * @param dataset the data set to train from * @param threadpool the source of threads for parallel training. May be * null, in which case {@link #trainIfNeeded(jsat.linear.distancemetrics.DistanceMetric, jsat.DataSet) } * is used instead. * @deprecated I WILL DELETE THIS METHOD SOON */ public static void trainIfNeeded(DistanceMetric dm, DataSet dataset, ExecutorService threadpool) { //TODO I WILL DELETE, JUST STUBBING FOR NOW TO MAKE LIFE EASY AS I DO ONE CODE SECTION AT A TIME trainIfNeeded(dm, dataset); } /** * * @param * @param dm * @param dataset * @param threadpool * @deprecated I WILL DELETE THIS METHOD SOON */ public static void trainIfNeeded(DistanceMetric dm, List dataset, ExecutorService threadpool) { //TODO I WILL DELETE, JUST STUBBING FOR NOW TO MAKE LIFE EASY AS I DO ONE CODE SECTION AT A TIME trainIfNeeded(dm, dataset, false); } /** * Static helper method for training a distance metric only if it is needed. * This method can be safely called for any Distance Metric. * * @param the type of vectors in the list * @param dm the distance metric to train * @param dataset the data set to train from */ public static void trainIfNeeded(DistanceMetric dm, List dataset) { trainIfNeeded(dm, dataset, false); } /** * * @param the type of vectors in the list * @param dm the distance metric to train * @param dataset the data set to train from * @param parallel {@code true} if multiple threads should be used for * training. {@code false} if it should be done in a single-threaded manner. */ public static void trainIfNeeded(DistanceMetric dm, List dataset, boolean parallel) { if(!(dm instanceof TrainableDistanceMetric)) return; TrainableDistanceMetric tdm = (TrainableDistanceMetric) dm; if(!tdm.needsTraining()) return; if(dataset instanceof RegressionDataSet) tdm.train((RegressionDataSet) dataset, parallel); else if(dataset instanceof ClassificationDataSet) tdm.train((ClassificationDataSet) dataset, parallel); else tdm.train(dataset, parallel); } }

Ads help maintain this website.