/*
 * Copyright (C) 2015 Edward Raff
 *
 * This program 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.
 *
 * This program 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 this program.  If not, see .
 */
package jsat.parameters;

import java.util.ArrayList;
import java.util.List;
import jsat.classifiers.CategoricalResults;
import jsat.classifiers.Classifier;
import jsat.classifiers.DataPoint;
import jsat.classifiers.evaluation.Accuracy;
import jsat.classifiers.evaluation.ClassificationScore;
import jsat.exceptions.FailedToFitException;
import jsat.exceptions.UntrainedModelException;
import jsat.regression.Regressor;
import jsat.regression.evaluation.MeanSquaredError;
import jsat.regression.evaluation.RegressionScore;

/**
 * This abstract class provides boilerplate for algorithms that search a model's
 * parameter space to find the parameters that provide the best overall
 * performance.
 *
 * @author Edward Raff
 */
abstract public class ModelSearch implements Classifier, Regressor
{
    protected Classifier baseClassifier;
    protected Classifier trainedClassifier;

    protected ClassificationScore classificationTargetScore = new Accuracy();
    protected RegressionScore regressionTargetScore = new MeanSquaredError(true);

    protected Regressor baseRegressor;
    protected Regressor trainedRegressor;

    /**
     * The list of parameters we will search for, currently only Int and Double
     * params should be used
     */
    protected List searchParams;

    /**
     * The number of CV folds
     */
    protected int folds;

    /**
     * If true, parallelism will be obtained by training the models in parallel.
     * If false, parallelism is obtained from the model itself.
     */
    protected boolean trainModelsInParallel = true;

    /**
     * If true, trains the final model on the parameters used
     */
    protected boolean trainFinalModel = true;

    /**
     * If true, create the CV splits once and re-use them for all parameters
     */
    protected boolean reuseSameCVFolds = true;

    public ModelSearch(Regressor baseRegressor, int folds)
    {
        if (!(baseRegressor instanceof Parameterized))
            throw new FailedToFitException("Given regressor does not support parameterized alterations");
        this.baseRegressor = baseRegressor;
        if (baseRegressor instanceof Classifier)
            this.baseClassifier = (Classifier) baseRegressor;
        searchParams = new ArrayList();
        this.folds = folds;
    }

    public ModelSearch(Classifier baseClassifier, int folds)
    {
        if (!(baseClassifier instanceof Parameterized))
            throw new FailedToFitException("Given classifier does not support parameterized alterations");
        this.baseClassifier = baseClassifier;
        if (baseClassifier instanceof Regressor)
            this.baseRegressor = (Regressor) baseClassifier;
        searchParams = new ArrayList();
        this.folds = folds;
    }

    /**
     * Copy constructor
     * @param toCopy the object to copy
     */
    public ModelSearch(ModelSearch toCopy)
    {
        if (toCopy.baseClassifier != null)
        {
            this.baseClassifier = toCopy.baseClassifier.clone();
            if (this.baseClassifier instanceof Regressor)
                this.baseRegressor = (Regressor) this.baseClassifier;
        }
        else
        {
            this.baseRegressor = toCopy.baseRegressor.clone();
            if (this.baseRegressor instanceof Classifier)
                this.baseClassifier = (Classifier) this.baseRegressor;
        }
        if (toCopy.trainedClassifier != null)
            this.trainedClassifier = toCopy.trainedClassifier.clone();
        if (toCopy.trainedRegressor != null)
            this.trainedRegressor = toCopy.trainedRegressor.clone();
        this.searchParams = new ArrayList();
        for (Parameter p : toCopy.searchParams)
            this.searchParams.add(getParameterByName(p.getName()));
        this.folds = toCopy.folds;
    }

    /**
     * When set to {@code true} (the default) parallelism is obtained by
     * training as many models in parallel as possible. If {@code false},
     * parallelsm will be obtained by training the model using the {@link Classifier#train(jsat.classifiers.ClassificationDataSet, java.util.concurrent.ExecutorService)
     * } and {@link Regressor#train(jsat.regression.RegressionDataSet, java.util.concurrent.ExecutorService)
     * } methods.
*
* When a model supports {@link #setUseWarmStarts(boolean) warms starts}, * parallelism obtained by training the models in parallel is intrinsically * reduced, as a model can not be warms started until another model has * finished. In the case that one of the parameters is annotated as a * {@link Parameter.WarmParameter warm paramter} , that parameter will be * the one rained sequential, and for every other parameter combination * models will be trained in parallel. If there is no warm parameter, the * first parameter added will be used for warm training. If there is only * one parameter and warm training is occurring, no parallelism will be * obtained. * * @param trainInParallel {@code true} to get parallelism from training many * models at the same time, {@code false} to get parallelism from getting * the model's implicit parallelism. */ public void setTrainModelsInParallel(boolean trainInParallel) { this.trainModelsInParallel = trainInParallel; } /** * * @return {@code true} if parallelism is obtained from training many models * at the same time, {@code false} if parallelism is obtained from using the * model's implicit parallelism. */ public boolean isTrainModelsInParallel() { return trainModelsInParallel; } /** * If {@code true} (the default) the model that was found to be best is * trained on the whole data set at the end. If {@code false}, the final * model will not be trained. This means that this Object will not be usable * for predictoin. This should only be set if you know you will not be using * this model but only want to get the information about which parameter * combination is best. * * @param trainFinalModel {@code true} to train the final model after grid * search, {@code false} to not do that. */ public void setTrainFinalModel(boolean trainFinalModel) { this.trainFinalModel = trainFinalModel; } /** * * @return {@code true} to train the final model after grid search, * {@code false} to not do that. */ public boolean isTrainFinalModel() { return trainFinalModel; } /** * Sets whether or not one set of CV folds is created and re used for every * parameter combination (the default), or if a difference set of CV folds * will be used for every parameter combination. * * @param reuseSameSplit {@code true} if the same split is re-used for every * combination, {@code false} if a new CV set is used for every parameter * combination. */ public void setReuseSameCVFolds(boolean reuseSameSplit) { this.reuseSameCVFolds = reuseSameSplit; } /** * * @return {@code true} if the same split is re-used for every combination, * {@code false} if a new CV set is used for every parameter combination. */ public boolean isReuseSameCVFolds() { return reuseSameCVFolds; } /** * Returns the base classifier that was originally passed in when * constructing this GridSearch. If this was not constructed with a * classifier, this may return null. * * @return the original classifier object given */ public Classifier getBaseClassifier() { return baseClassifier; } /** * Returns the resultant classifier trained on the whole data set after * performing parameter tuning. * * @return the trained classifier after a call to {@link #train(jsat.regression.RegressionDataSet, * java.util.concurrent.ExecutorService) }, or null if it has not been * trained. */ public Classifier getTrainedClassifier() { return trainedClassifier; } /** * Returns the base regressor that was originally passed in when * constructing this GridSearch. If this was not constructed with a * regressor, this may return null. * * @return the original regressor object given */ public Regressor getBaseRegressor() { return baseRegressor; } /** * Returns the resultant regressor trained on the whole data set after * performing parameter tuning. * * @return the trained regressor after a call to {@link #train(jsat.regression.RegressionDataSet, * java.util.concurrent.ExecutorService) }, or null if it has not been * trained. */ public Regressor getTrainedRegressor() { return trainedRegressor; } /** * Sets the score to attempt to optimize when performing grid search on a * classification problem. * * @param classifierTargetScore the score to optimize via grid search */ public void setClassificationTargetScore(ClassificationScore classifierTargetScore) { this.classificationTargetScore = classifierTargetScore; } /** * Returns the classification score that is trying to be optimized via grid * search * * @return the classification score that is trying to be optimized via grid * search */ public ClassificationScore getClassificationTargetScore() { return classificationTargetScore; } /** * Sets the score to attempt to optimize when performing grid search on a * regression problem. * * @param regressionTargetScore */ public void setRegressionTargetScore(RegressionScore regressionTargetScore) { this.regressionTargetScore = regressionTargetScore; } /** * Returns the regression score that is trying to be optimized via grid * search * * @return the regression score that is trying to be optimized via grid * search */ public RegressionScore getRegressionTargetScore() { return regressionTargetScore; } /** * Finds the parameter object with the given name, or throws an exception if * a parameter with the given name does not exist. * * @param name the name to search for * @return the parameter object in question * @throws IllegalArgumentException if the name is not found */ protected Parameter getParameterByName(String name) throws IllegalArgumentException { Parameter param; if (baseClassifier != null) param = ((Parameterized) baseClassifier).getParameter(name); else param = ((Parameterized) baseRegressor).getParameter(name); if (param == null) throw new IllegalArgumentException("Parameter " + name + " does not exist"); return param; } @Override public CategoricalResults classify(DataPoint data) { if (trainedClassifier == null) throw new UntrainedModelException("Model has not yet been trained"); return trainedClassifier.classify(data); } @Override public double regress(DataPoint data) { if (trainedRegressor == null) throw new UntrainedModelException("Model has not yet been trained"); return trainedRegressor.regress(data); } @Override public boolean supportsWeightedData() { return baseClassifier != null ? baseClassifier.supportsWeightedData() : baseRegressor.supportsWeightedData(); } @Override abstract public ModelSearch clone(); }

Ads help maintain this website.