de.fu_berlin.ties.eval
Class MultiFMetrics

java.lang.Object
  extended by de.fu_berlin.ties.eval.MultiFMetrics
All Implemented Interfaces:
MultiFMetricsView, RestorableContainer, StorableContainer

public class MultiFMetrics
extends Object
implements MultiFMetricsView, RestorableContainer

Instances of this class manage multiple FMetrics for different types. They also calculate average statistics over all types.

Instances of this class are not thread-safe and must be synchronized externally, if required.

Version:
$Revision: 1.8 $, $Date: 2004/09/06 17:23:00 $, $Author: siefkes $
Author:
Christian Siefkes

Field Summary
static String ALL
          Reserved type used for the calculated sums and averages over all types: <All>.
static String EXT_METRICS
          Extension recommended for files storing metrics.
static String KEY_TYPE
          Serialization key for the type.
 
Constructor Summary
MultiFMetrics()
          Creates a new instance, without calculating summaries.
MultiFMetrics(boolean calcSummaries)
          Creates a new instance.
 
Method Summary
protected  FMetrics createMetrics()
          Helper factory method that creates a new FMetrics instance of the required type.
protected  FMetrics createMetrics(FieldMap fieldMap)
          Helper factory method that creates a new FMetrics instance of the required type from a field map.
 void incFalseNeg(String type)
          Increases the number of false negatives for the given type by 1.
 void incFalsePos(String type)
          Increases the number of false positives for the given type by 1.
 void incTruePos(String type)
          Increases the number of true positives for the given type by 1.
 boolean isCalculatingSummaries()
          Whether summaries are calculated by this type.
protected  FMetrics lookupType(String type)
          Looks up and if necessary initializes the metrics for a given type.
 void restoreEntries(FieldContainer fContainer)
          Restores items stored in a field container and adds them to this instance.
 void storeEntries(FieldContainer fContainer)
          Adds all relevant Storable items in this object to a field container for serialization.
 String toString()
          Returns a string representation of this object.
 Set types()
          Returns the set of all types (Strings) currently stored in this instance.
 void update(MultiFMetricsView multiMetrics)
          Updates the statistics by adding the contents of the given multi-metrics.
 void update(String type, EvalInput input)
          Updates the statistics for a specified type, increasing the stored values as specified.
 void update(String type, long addTruePos, long addFalseNeg, long addFalsePos)
          Updates the statistics for a specified type, increasing the stored values as specified.
 FMetricsView view(String type)
          Returns a read-only view of the FMetrics of the specified type.
 FMetricsView viewAll()
          Returns a read-only view of the FMetrics containing the sums and averages over all types.
 FMetricsSummary viewAllSummary()
          Optional operation that shows statistical summaries of precision, recall, and F1 metrics over all types, if calculated.
 FMetricsSummary viewSummary(String type)
          Optional operation that shows statistical summaries of precision, recall, and F1 metrics of the specified type, if calculated.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

ALL

public static final String ALL
Reserved type used for the calculated sums and averages over all types: <All>. This string is reserved and cannot be used to mark regular types.

See Also:
Constant Field Values

KEY_TYPE

public static final String KEY_TYPE
Serialization key for the type.

See Also:
Constant Field Values

EXT_METRICS

public static final String EXT_METRICS
Extension recommended for files storing metrics.

See Also:
Constant Field Values
Constructor Detail

MultiFMetrics

public MultiFMetrics()
Creates a new instance, without calculating summaries.


MultiFMetrics

public MultiFMetrics(boolean calcSummaries)
Creates a new instance.

Parameters:
calcSummaries - whether this type should calculate summaries
Method Detail

createMetrics

protected FMetrics createMetrics()
Helper factory method that creates a new FMetrics instance of the required type.

Returns:
a SummaryFMetrics instance if isCalculatingSummaries(); a simple FMetrics instance otherwise

createMetrics

protected FMetrics createMetrics(FieldMap fieldMap)
                          throws IllegalArgumentException
Helper factory method that creates a new FMetrics instance of the required type from a field map.

Parameters:
fieldMap - field map used to initialize the new instance
Returns:
a SummaryFMetrics instance if isCalculatingSummaries(); a simple FMetrics instance otherwise
Throws:
IllegalArgumentException - if at least one of the parameters is negative or missing from the field map

incFalseNeg

public void incFalseNeg(String type)
                 throws IllegalArgumentException
Increases the number of false negatives for the given type by 1.

Parameters:
type - the type to update
Throws:
IllegalArgumentException - if type is null or empty or equal to the reserved ALL type

incFalsePos

public void incFalsePos(String type)
                 throws IllegalArgumentException
Increases the number of false positives for the given type by 1.

Parameters:
type - the type to update
Throws:
IllegalArgumentException - if type is null or empty or equal to the reserved ALL type

incTruePos

public void incTruePos(String type)
                throws IllegalArgumentException
Increases the number of true positives for the given type by 1.

Parameters:
type - the type to update
Throws:
IllegalArgumentException - if type is null or empty or equal to the reserved ALL type

isCalculatingSummaries

public boolean isCalculatingSummaries()
Whether summaries are calculated by this type.

Returns:
the value of the attribute

lookupType

protected FMetrics lookupType(String type)
                       throws IllegalArgumentException
Looks up and if necessary initializes the metrics for a given type. Also checks that the given type is valid, i.e. neither null nor empty nor equal to the reserved ALL type.

Parameters:
type - the type to check
Returns:
the metrics for this type
Throws:
IllegalArgumentException - if type is null or empty or equal to the reserved ALL type

restoreEntries

public void restoreEntries(FieldContainer fContainer)
                    throws IllegalArgumentException
Restores items stored in a field container and adds them to this instance. The provided field container must have been filled by calling storeEntries(FieldContainer) on a object of this type. Any values already contained in this instance are added to, they are not replaced. The sums and averages are recalculated from the provided values, it is not directly read from the container. Summary information cannot be restored.

Specified by:
restoreEntries in interface RestorableContainer
Parameters:
fContainer - the field container to read
Throws:
IllegalArgumentException - if fContainer contains a wrong kind of FieldMaps

storeEntries

public void storeEntries(FieldContainer fContainer)
Adds all relevant Storable items in this object to a field container for serialization.

Specified by:
storeEntries in interface StorableContainer
Parameters:
fContainer - the field container to fill

toString

public String toString()
Returns a string representation of this object.

Overrides:
toString in class Object
Returns:
a textual representation

types

public Set types()
Returns the set of all types (Strings) currently stored in this instance. The set is immutable and cannot modified.

Specified by:
types in interface MultiFMetricsView
Returns:
the set of type names

update

public void update(MultiFMetricsView multiMetrics)
Updates the statistics by adding the contents of the given multi-metrics.

Parameters:
multiMetrics - the metrics to add

update

public void update(String type,
                   EvalInput input)
            throws IllegalArgumentException
Updates the statistics for a specified type, increasing the stored values as specified.

Parameters:
type - the type to update
input - contains the number of true and false positives and false negatives to add
Throws:
IllegalArgumentException - if type is null or empty or equal to the reserved ALL type or if at least one of the input values is negative

update

public void update(String type,
                   long addTruePos,
                   long addFalseNeg,
                   long addFalsePos)
            throws IllegalArgumentException
Updates the statistics for a specified type, increasing the stored values as specified.

Parameters:
type - the type to update
addTruePos - the number of new true positives to add
addFalseNeg - the number of new false negatives to add
addFalsePos - the number of new false positives to add
Throws:
IllegalArgumentException - f type is null or empty or equal to the reserved ALL type or if at least one of the parameters is negative

view

public FMetricsView view(String type)
Returns a read-only view of the FMetrics of the specified type. This is not a snapshot but will change whenever the underlying counts are changed.

Specified by:
view in interface MultiFMetricsView
Parameters:
type - the type to check
Returns:
a view of the counts and evaluation metrics for the given type; or null if no metrics exist for the given type

viewAll

public FMetricsView viewAll()
Returns a read-only view of the FMetrics containing the sums and averages over all types. This is not a snapshot but will change whenever the underlying counts are changed.

Specified by:
viewAll in interface MultiFMetricsView
Returns:
a view of the sums and averages over all types

viewAllSummary

public FMetricsSummary viewAllSummary()
                               throws UnsupportedOperationException
Optional operation that shows statistical summaries of precision, recall, and F1 metrics over all types, if calculated. This is not a snapshot but will change whenever the underlying values are changed.

Specified by:
viewAllSummary in interface MultiFMetricsView
Returns:
a statistical summery over the metrics of all types, if calculated
Throws:
UnsupportedOperationException - if isCalculatingSummaries() is false

viewSummary

public FMetricsSummary viewSummary(String type)
                            throws UnsupportedOperationException
Optional operation that shows statistical summaries of precision, recall, and F1 metrics of the specified type, if calculated. This is not a snapshot but will change whenever the underlying values are changed.

Specified by:
viewSummary in interface MultiFMetricsView
Parameters:
type - the type to check
Returns:
a statistical summery over the metrics of the given type, if calculated
Throws:
UnsupportedOperationException - if isCalculatingSummaries() is false


Copyright © 2003-2004 Christian Siefkes. All Rights Reserved.