weka.filters
Class Filter

java.lang.Object
  |
  +--weka.filters.Filter

All Implemented Interfaces:

java.io.Serializable

Direct Known Subclasses:

AbstractTimeSeries, Add, AddCluster, AddExpression, AddNoise, AllFilter, AttributeSelection, ClassOrder, ClusterMembership, Copy, Discretize, FirstOrder, MakeIndicator, MergeTwoValues, NominalToBinary, NominalToBinary, NonSparseToSparse, NullFilter, NumericTransform, Obfuscate, PotentialClassIgnorer, Randomize, RandomProjection, Remove, RemoveFolds, RemoveMisclassified, RemovePercentage, RemoveRange, RemoveType, RemoveUseless, RemoveWithValues, Resample, Resample, SparseToNonSparse, SpreadSubsample, StratifiedRemoveFolds, StringToNominal, StringToWordVector, SwapValues

public abstract class Filter

extends java.lang.Object

implements java.io.Serializable

An abstract class for instance filters: objects that take instances as input, carry out some transformation on the instance and then output the instance. The method implementations in this class assume that most of the work will be done in the methods overridden by subclasses.

A simple example of filter use. This example doesn't remove instances from the output queue until all instances have been input, so has higher memory consumption than an approach that uses output instances as they are made available:

  Filter filter = ..some type of filter..
  Instances instances = ..some instances..
  for (int i = 0; i < data.numInstances(); i++) {
    filter.input(data.instance(i));
  }
  filter.batchFinished();
  Instances newData = filter.outputFormat();
  Instance processed;
  while ((processed = filter.output()) != null) {
    newData.add(processed);
  }
  ..do something with newData..
 

Version:

$Revision: 1.23 $

Author:

Len Trigg (trigg@cs.waikato.ac.nz)

See Also:

Serialized Form

Constructor Summary

Filter()

Method Summary

static void	batchFilterFile(Filter filter, java.lang.String[] options) Method for testing filters ability to process multiple batches.
boolean	batchFinished() Signify that this batch of input to the filter is finished.
static void	filterFile(Filter filter, java.lang.String[] options) Method for testing filters.
Instances	getOutputFormat() Gets the format of the output instances.
boolean	input(Instance instance) Input an instance for filtering.
boolean	inputFormat(Instances instanceInfo) Deprecated. use setInputFormat(Instances) instead.
boolean	isOutputFormatDefined() Returns whether the output format is ready to be collected
static void	main(java.lang.String[] args) Main method for testing this class.
int	numPendingOutput() Returns the number of instances pending output
Instance	output() Output an instance after filtering and remove from the output queue.
Instances	outputFormat() Deprecated. use getOutputFormat() instead.
Instance	outputPeek() Output an instance after filtering but do not remove from the output queue.
boolean	setInputFormat(Instances instanceInfo) Sets the format of the input instances.
static Instances	useFilter(Instances data, Filter filter) Filters an entire set of instances through a filter and returns the new set.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Filter

public Filter()

Method Detail

inputFormat

public boolean inputFormat(Instances instanceInfo)
                    throws java.lang.Exception

Deprecated. use setInputFormat(Instances) instead.

java.lang.Exception

setInputFormat

public boolean setInputFormat(Instances instanceInfo)
                       throws java.lang.Exception

Sets the format of the input instances. If the filter is able to determine the output format before seeing any input instances, it does so here. This default implementation clears the output format and output queue, and the new batch flag is set. Overriders should call super.setInputFormat(Instances)

Parameters:

instanceInfo - an Instances object containing the input instance structure (any instances contained in the object are ignored - only the structure is required).

Returns:

true if the outputFormat may be collected immediately

Throws:

java.lang.Exception - if the inputFormat can't be set successfully

outputFormat

public Instances outputFormat()

Deprecated. use getOutputFormat() instead.

getOutputFormat

public Instances getOutputFormat()

Gets the format of the output instances. This should only be called after input() or batchFinished() has returned true. The relation name of the output instances should be changed to reflect the action of the filter (eg: add the filter name and options).

Returns:

an Instances object containing the output instance structure only.

Throws:

java.lang.NullPointerException - if no input structure has been defined (or the output format hasn't been determined yet)

input

public boolean input(Instance instance)
              throws java.lang.Exception

Input an instance for filtering. Ordinarily the instance is processed and made available for output immediately. Some filters require all instances be read before producing output, in which case output instances should be collected after calling batchFinished(). If the input marks the start of a new batch, the output queue is cleared. This default implementation assumes all instance conversion will occur when batchFinished() is called.

Parameters:

instance - the input instance

Returns:

true if the filtered instance may now be collected with output().

Throws:

java.lang.NullPointerException - if the input format has not been defined.

java.lang.Exception - if the input instance was not of the correct format or if there was a problem with the filtering.

batchFinished

public boolean batchFinished()
                      throws java.lang.Exception

Signify that this batch of input to the filter is finished. If the filter requires all instances prior to filtering, output() may now be called to retrieve the filtered instances. Any subsequent instances filtered should be filtered based on setting obtained from the first batch (unless the inputFormat has been re-assigned or new options have been set). This default implementation assumes all instance processing occurs during inputFormat() and input().

Returns:

true if there are instances pending output

Throws:

java.lang.NullPointerException - if no input structure has been defined,

java.lang.Exception - if there was a problem finishing the batch.

output

public Instance output()

Output an instance after filtering and remove from the output queue.

Returns:

the instance that has most recently been filtered (or null if the queue is empty).

Throws:

java.lang.NullPointerException - if no output structure has been defined

outputPeek

public Instance outputPeek()

Output an instance after filtering but do not remove from the output queue.

Returns:

the instance that has most recently been filtered (or null if the queue is empty).

Throws:

java.lang.NullPointerException - if no input structure has been defined

numPendingOutput

public int numPendingOutput()

Returns the number of instances pending output

Returns:

the number of instances pending output

Throws:

java.lang.NullPointerException - if no input structure has been defined

isOutputFormatDefined

public boolean isOutputFormatDefined()

Returns whether the output format is ready to be collected

Returns:

true if the output format is set

useFilter

public static Instances useFilter(Instances data,
                                  Filter filter)
                           throws java.lang.Exception

Filters an entire set of instances through a filter and returns the new set.

Parameters:

data - the data to be filtered

filter - the filter to be used

Returns:

the filtered set of data

Throws:

java.lang.Exception - if the filter can't be used successfully

filterFile

public static void filterFile(Filter filter,
                              java.lang.String[] options)
                       throws java.lang.Exception

Method for testing filters.

Throws:

java.lang.Exception - if something goes wrong or the user requests help on command options

batchFilterFile

public static void batchFilterFile(Filter filter,
                                   java.lang.String[] options)
                            throws java.lang.Exception

Method for testing filters ability to process multiple batches.

Throws:

java.lang.Exception - if something goes wrong or the user requests help on command options

main

public static void main(java.lang.String[] args)

Main method for testing this class.