/* Copyright (C) 2002 Univ. of Massachusetts Amherst, Computer Science Dept.
   This file is part of "MALLET" (MAchine Learning for LanguagE Toolkit).
   http://www.cs.umass.edu/~mccallum/mallet
   This software is provided under the terms of the Common Public License,
   version 1.0, as published by http://www.opensource.org.  For further
   information, see the file `LICENSE' included with this distribution. */




/** 
   @author Andrew McCallum <a href="mailto:mccallum@cs.umass.edu">mccallum@cs.umass.edu</a>
 */

package cc.mallet.classify;

import java.util.ArrayList;
import java.util.List;
import java.util.logging.*;
import java.io.PrintWriter;
import java.io.Serializable;

import cc.mallet.pipe.Pipe;
import cc.mallet.types.Alphabet;
import cc.mallet.types.AlphabetCarrying;
import cc.mallet.types.FeatureVector;
import cc.mallet.types.Instance;
import cc.mallet.types.InstanceList;
import cc.mallet.types.Label;
import cc.mallet.types.LabelAlphabet;
import cc.mallet.types.Labeling;
import cc.mallet.types.FeatureSelection;

/**
 * Abstract parent of all Classifiers.
 * <p>
 * All classification techniques in MALLET are implemented as two classes:
 * a trainer and a classifier.  The trainer injests the training data
 * and creates a classifier that holds the parameters set during training.
 * The classifier applies those parameters to an Instance to produce
 * a classification of the Instance.
 * <p>
 * A concrete classifier is required only to be able to classify an instance.
 * <p>
 * Methods for classifying an InstanceList are here. There are
 * also methods for calculating precison, recall, and f1 from either
 * InstanceLists (which are classified first) or an ArrayList of
 * classifications. Similar functionality is also in
 * {@link cc.mallet.classify.Trial}
 *
 * <p> A classifier holds a reference to the pipe that was used to
 * create the Instances being classified.  Most classifiers use
 * this to make sure the Alphabets of the instances being classified
 * are the same Alphabet objects used during training.
 * <p>
 * Alphabets are allowed to between training and classification.
 * @see ClassifierTrainer
 * @see Instance
 * @see InstanceList
 * @see Classification
 * @see Trial
 */
public abstract class Classifier implements AlphabetCarrying, Serializable
{
	private static Logger logger = Logger.getLogger(Classifier.class.getName());

	protected Pipe instancePipe;

	/** For serialization only. */
	protected Classifier()
	{
	}

	public Classifier (Pipe instancePipe)
	{
		this.instancePipe = instancePipe;
		// All classifiers must have set of labels.
		assert (instancePipe.getTargetAlphabet() != null);
		assert (instancePipe.getTargetAlphabet().getClass().isAssignableFrom(LabelAlphabet.class));
		// Not all classifiers require a feature dictionary, however.
	}

	// TODO Change this method name to getPipe();
	public Pipe getInstancePipe ()
	{
		return instancePipe;
	}

	public Alphabet getAlphabet ()
	{
		return (Alphabet) instancePipe.getDataAlphabet();
	}

	public LabelAlphabet getLabelAlphabet ()
	{
		return (LabelAlphabet) instancePipe.getTargetAlphabet();
	}
	
	public Alphabet[] getAlphabets() 
	{
		return new Alphabet[] {getAlphabet(), getLabelAlphabet()};
	}
	
	public boolean alphabetsMatch (AlphabetCarrying object)
	{
		Alphabet[] otherAlphabets = object.getAlphabets();
		if (otherAlphabets.length == 2 && otherAlphabets[0] == getAlphabet() && otherAlphabets[1] == getLabelAlphabet())
			return true;
		return false;
	}

	

	// TODO Make argument List<Instance>
	public ArrayList<Classification> classify (InstanceList instances)
	{
		ArrayList<Classification> ret = new ArrayList<Classification> (instances.size());
		for (Instance inst : instances)
			ret.add (classify (inst));
		return ret;
	}

	public Classification[] classify (Instance[] instances)
	{
		Classification[] ret = new Classification[instances.length];
		for (int i = 0; i < instances.length; i++)
			ret[i] = classify (instances[i]);
		return ret;
	}

	public abstract Classification classify (Instance instance);

	/** Pipe the object through this classifier's pipe, then classify the resulting instance. */
	public Classification classify (Object obj)
	{
		if (obj instanceof Instance)
			return classify ((Instance)obj);
		return classify (instancePipe.instanceFrom(new Instance (obj, null, null, null)));
	}
	
	
	public FeatureSelection getFeatureSelection () { return null; }
	public FeatureSelection[] getPerClassFeatureSelection () { return null; }

	
	// Various evaluation methods
	
	public double getAccuracy (InstanceList ilist) { return new Trial(this, ilist).getAccuracy(); }
	public double getPrecision (InstanceList ilist, int index) { return new Trial(this, ilist).getPrecision(index); }
	public double getPrecision (InstanceList ilist, Labeling labeling) { return new Trial(this, ilist).getPrecision(labeling); }
	public double getPrecision (InstanceList ilist, Object labelEntry) { return new Trial(this, ilist).getPrecision(labelEntry); }
	public double getRecall (InstanceList ilist, int index) { return new Trial(this, ilist).getRecall(index); }
	public double getRecall (InstanceList ilist, Labeling labeling) { return new Trial(this, ilist).getRecall(labeling); }
	public double getRecall (InstanceList ilist, Object labelEntry) { return new Trial(this, ilist).getRecall(labelEntry); }
	public double getF1 (InstanceList ilist, int index) { return new Trial(this, ilist).getF1(index); }
	public double getF1 (InstanceList ilist, Labeling labeling) { return new Trial(this, ilist).getF1(labeling); }
	public double getF1 (InstanceList ilist, Object labelEntry) { return new Trial(this, ilist).getF1(labelEntry); }
	public double getAverageRank (InstanceList ilist) { return new Trial(this, ilist).getAverageRank(); }
	

	/**
	 * Outputs human-readable description of classifier (e.g., list of weights, decision tree)
	 *  to System.out
	 */
	public void print () {
		System.out.println ("Classifier "+getClass().getName()+"\n  Detailed printout not yet implemented.");
	}

	public void print (PrintWriter out) {
		out.println ("Classifier "+getClass().getName()+"\n  Detailed printout not yet implemented.");
	}

}