clarion.system
Class RuleCollection

java.lang.Object
  extended by java.util.AbstractMap<K,V>
      extended by java.util.HashMap<java.lang.Object,java.util.HashMap<java.lang.Integer,AbstractRule>>
          extended by clarion.system.RuleCollection
All Implemented Interfaces:
InterfaceHandlesFeedback, InterfaceTracksMatchStatistics, java.io.Serializable, java.lang.Cloneable, java.util.Map<java.lang.Object,java.util.HashMap<java.lang.Integer,AbstractRule>>

public class RuleCollection
extends java.util.HashMap<java.lang.Object,java.util.HashMap<java.lang.Integer,AbstractRule>>
implements InterfaceTracksMatchStatistics, InterfaceHandlesFeedback

This class implements a rule collection within CLARION. It extends the HashMap class and implements the InterfaceTracksMatchStatistics and InterfaceHandlesFeedback interfaces.

Usage:

The rule collection acts as a container for rules that are used by a CLARION agent for action decision making. This class is most often used within the ACS as the container for the rule stores.

The rule collection also tracks (or generates): rule variations, child rules, and collection-wide match statistics. In addition, it has the ability to correctly place newly added rules within the collection by determining if the rule should be in the collection or within a child collection.

For all of the rules in the rule collection that are refineable (i.e. they extend from the RefineableRule class), hidden minor variations of those rules are generated automatically and tracked by this class in order to facilitate generalization and specialization.

In addition to tracking match statistics for the hidden variations, the rule collection also keeps track of collection-wide match statistics that are used to for variable level selection within the ACS as well as for performance monitoring and reporting purposes.

This class contains both global (static) and local constants. The default is to use the local constants. If you want to change any of the global constants, you need to do so before any instances of this class are initialized.

Version:
6.0.4.5
Author:
Nick Wilson
See Also:
Serialized Form

Field Summary
protected  HiddenRuleCollection Children
          Contains any existent child rules for the rules in the rule collection.
private  double Feedback
          The immediate feedback (if given).
static double GLOBAL_POSITIVE_MATCH_THRESHOLD
          The threshold that must be passed to meet the positive match criterion.
protected  double NM
          The negative match counter.
protected  double PM
          The positive match counter.
 double POSITIVE_MATCH_THRESHOLD
          The threshold that must be passed to meet the positive match criterion.
private static long serialVersionUID
           
protected  HiddenRuleCollection Variations
          Contains the hidden rule variations for all rules in the rule collection.
 
Constructor Summary
RuleCollection()
          Initializes a rule collection.
RuleCollection(java.util.Collection<? extends AbstractRule> rules)
          Initializes a rule collection with the collection of rules specified.
 
Method Summary
 boolean checkMatchCriterion()
          This method does nothing as it is not used by the CLARION Library for this collection.
 boolean contains(AbstractRule rule)
          Checks to see if the collection contains the specified rule.
 boolean containsCover(AbstractRule rule)
          Checks to see if the collection contains a rule that covers the specified rule.
 void discountMatchStatistics(double Discount)
          Discounts the positive and negative match statistics for all rules in the rule collection and all rule variations.
private  void generateVariations(RefineableRule R)
          Generates variations for the rule r and adds any variations that are not already in the variations list to that list.
 AbstractRule get(GeneralizedConditionChunk cond, AbstractAction act)
          Gets a rule in the collection that matches the specified condition and action.
 java.util.Collection<AbstractRule> getChildren()
          Gets the child rules from the rule collection.
 AbstractRule getCover(GeneralizedConditionChunk cond, AbstractAction act)
          Gets a rule in the collection that covers the specified condition and action.
 double getFeedback()
          Gets the feedback.
 double getNM()
          Gets the negative match statistic.
 double getPM()
          Gets the positive match statistic.
 java.util.Collection<AbstractRule> getRules()
          Gets all of the rules in the rule collection.
 java.util.Collection<AbstractRule> getVariations()
          Gets the rule variations from the rule collection.
 void incrementNM()
          Increments the negative match statistic.
 void incrementPM()
          Increments the positive match statistic.
 int numChildren()
          Gets the number of children being tracked by this collection.
 int numVariations()
          Gets the number of variations being tracked by this collection.
 void put(AbstractRule R)
          Puts a rule into the rule collection.
 java.util.HashMap<java.lang.Integer,AbstractRule> put(java.lang.Object key, java.util.HashMap<java.lang.Integer,AbstractRule> map)
          This method does nothing.
 void putAll(java.util.Collection<? extends AbstractRule> R)
          Puts a collection of rules into the rule collection.
 void putAll(java.util.Map<? extends java.lang.Object,? extends java.util.HashMap<java.lang.Integer,AbstractRule>> map)
          This method does nothing.
 AbstractRule remove(GeneralizedConditionChunk cond, AbstractAction act)
          Removes the rule from this rule collection with the specified condition and action.
 java.util.HashMap<java.lang.Integer,AbstractRule> remove(java.lang.Object key)
          This method does nothing.
 void removeChild(AbstractRule CR)
          Removes the specified rule from the child rule collection (if it is in the child rule collection).
 void removeVariations(RefineableRule R)
          Removes the variations from the variations list for all variations of the specified rule that are not also a variation for another rule in the rule collection.
 void resetMatchStatistics()
          Resets the match statistics.
 void setFeedback(double feedback)
          Sets the feedback.
 void setNM(double nm)
          Sets the negative match statistic.
 void setPM(double pm)
          Sets the positive match statistic.
 int size()
          Returns the number of rules in the rule collection.
 java.lang.String toString()
           
 void updateMatchStatistics(AbstractMatchCalculator MatchCalculator)
          Updates the positive or negative match statistics based on the feedback.
 
Methods inherited from class java.util.HashMap
clear, clone, containsKey, containsValue, entrySet, get, isEmpty, keySet, values
 
Methods inherited from class java.util.AbstractMap
equals, hashCode
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface java.util.Map
equals, hashCode
 

Field Detail

serialVersionUID

private static final long serialVersionUID
See Also:
Constant Field Values

Variations

protected HiddenRuleCollection Variations
Contains the hidden rule variations for all rules in the rule collection.


Children

protected HiddenRuleCollection Children
Contains any existent child rules for the rules in the rule collection.


Feedback

private double Feedback
The immediate feedback (if given).


PM

protected double PM
The positive match counter.


NM

protected double NM
The negative match counter.


GLOBAL_POSITIVE_MATCH_THRESHOLD

public static double GLOBAL_POSITIVE_MATCH_THRESHOLD
The threshold that must be passed to meet the positive match criterion.


POSITIVE_MATCH_THRESHOLD

public double POSITIVE_MATCH_THRESHOLD
The threshold that must be passed to meet the positive match criterion.

Constructor Detail

RuleCollection

public RuleCollection()
Initializes a rule collection.


RuleCollection

public RuleCollection(java.util.Collection<? extends AbstractRule> rules)
Initializes a rule collection with the collection of rules specified.

Parameters:
rules - The rules for the collection.
Method Detail

get

public AbstractRule get(GeneralizedConditionChunk cond,
                        AbstractAction act)
Gets a rule in the collection that matches the specified condition and action. If the collection does not contain a rule with the specified condition and action, this method returns null.

Parameters:
cond - The condition of the rule to get.
act - The action of the rules to get.
Returns:
A rules with the specified condition and action.

getCover

public AbstractRule getCover(GeneralizedConditionChunk cond,
                             AbstractAction act)
Gets a rule in the collection that covers the specified condition and action. If the collection does not contain a rule that covers the specified condition and action, this method returns null.

This method does NOT guarantee that the rule returned is the only rule in the collection that covers the specified condition and action.

Parameters:
cond - The condition the rule to get must cover.
act - The action of the rules to get.
Returns:
A rules that covers the specified condition and action.

contains

public boolean contains(AbstractRule rule)
Checks to see if the collection contains the specified rule.

Parameters:
rule - The rule object you wish to check for within this collection.
Returns:
True if the collection contains the rule specified, otherwise false.

containsCover

public boolean containsCover(AbstractRule rule)
Checks to see if the collection contains a rule that covers the specified rule.

Parameters:
rule - The rule object you wish to check within this collection.
Returns:
True if the collection contains a rule that covers the rule specified, otherwise false.

put

public java.util.HashMap<java.lang.Integer,AbstractRule> put(java.lang.Object key,
                                                             java.util.HashMap<java.lang.Integer,AbstractRule> map)
This method does nothing. It has been overridden from HashMap to return null without performing an operation. Instead, use the overloaded put method that takes an AbstractRule.

Specified by:
put in interface java.util.Map<java.lang.Object,java.util.HashMap<java.lang.Integer,AbstractRule>>
Overrides:
put in class java.util.HashMap<java.lang.Object,java.util.HashMap<java.lang.Integer,AbstractRule>>
Parameters:
key -
map -
Returns:
null

putAll

public void putAll(java.util.Map<? extends java.lang.Object,? extends java.util.HashMap<java.lang.Integer,AbstractRule>> map)
This method does nothing. It has been overridden from HashMap return without performing an operation. Instead, use the overloaded putAll method that takes a collection of AbstractRule.

Specified by:
putAll in interface java.util.Map<java.lang.Object,java.util.HashMap<java.lang.Integer,AbstractRule>>
Overrides:
putAll in class java.util.HashMap<java.lang.Object,java.util.HashMap<java.lang.Integer,AbstractRule>>
Parameters:
map -

remove

public java.util.HashMap<java.lang.Integer,AbstractRule> remove(java.lang.Object key)
This method does nothing. It has been overridden from HashMap to return null without performing an operation. Instead, use the overloaded remove method that takes an AbstractRule.

Specified by:
remove in interface java.util.Map<java.lang.Object,java.util.HashMap<java.lang.Integer,AbstractRule>>
Overrides:
remove in class java.util.HashMap<java.lang.Object,java.util.HashMap<java.lang.Integer,AbstractRule>>
Parameters:
key -
Returns:
null

put

public void put(AbstractRule R)
Puts a rule into the rule collection. If the specified rule is covered by any rules currently in this collection, then the rule will be added to the collection of child rules for that rule. If the specified rule covers any rules in this collection, those rules will be added to the child rules of the specified rule and the specified rule will replace those rules in this collection. If the specified rule is equal to any rules currently in this collection the rule will NOT be added.

Parameters:
R - The rule to add.

putAll

public void putAll(java.util.Collection<? extends AbstractRule> R)
Puts a collection of rules into the rule collection. If a rule in the specified collection is equal to any rules currently in this collection, the rule will NOT be added.

Parameters:
R - The rules to put in the collection.

remove

public AbstractRule remove(GeneralizedConditionChunk cond,
                           AbstractAction act)
Removes the rule from this rule collection with the specified condition and action. This method also removes all of the rule variations associated with the rule being removed as long as the variation is not also a variation for a different rule in the rule store.

If the rule collection does not contain a rule with the specified condition and action, this method returns null.

Parameters:
cond - The condition of the rule you want to remove.
act - The action of the rule you want to remove.
Returns:
The rule that was removed. If no rule was found in the collection, then null.

getRules

public java.util.Collection<AbstractRule> getRules()
Gets all of the rules in the rule collection.

Returns:
A collection containing the rules in the rule collection.

removeVariations

public void removeVariations(RefineableRule R)
Removes the variations from the variations list for all variations of the specified rule that are not also a variation for another rule in the rule collection. In addition, this method also removes the variations from the specified rule.

Parameters:
R - The rule whose variations you wish to remove.

generateVariations

private void generateVariations(RefineableRule R)
Generates variations for the rule r and adds any variations that are not already in the variations list to that list. This method also adds the variations for the specified rule to that rule's internal variations list.

Parameters:
R - The rule from which to generate variations.

removeChild

public void removeChild(AbstractRule CR)
Removes the specified rule from the child rule collection (if it is in the child rule collection).

Parameters:
CR - The rule to remove from the child rule collection.

discountMatchStatistics

public void discountMatchStatistics(double Discount)
Discounts the positive and negative match statistics for all rules in the rule collection and all rule variations.

Parameters:
Discount - The discount factor to be applied to the match statistics of the rules.

getPM

public double getPM()
Gets the positive match statistic.

Specified by:
getPM in interface InterfaceTracksMatchStatistics
Returns:
The positive match statistic.

getNM

public double getNM()
Gets the negative match statistic.

Specified by:
getNM in interface InterfaceTracksMatchStatistics
Returns:
The negative match statistic.

setPM

public void setPM(double pm)
Sets the positive match statistic. This method can be used to update the positive match statistic if the user wishes to provide their own match criterion function.

Specified by:
setPM in interface InterfaceTracksMatchStatistics
Parameters:
pm - The value to set as the positive match statistic.

setNM

public void setNM(double nm)
Sets the negative match statistic. This method can be used to update the negative match statistic if the user wishes to provide their own match criterion function.

Specified by:
setNM in interface InterfaceTracksMatchStatistics
Parameters:
nm - The value to set as the negative match statistic.

getFeedback

public double getFeedback()
Gets the feedback. This method is only used if feedback is being provided.

Specified by:
getFeedback in interface InterfaceHandlesFeedback
Returns:
The feedback.

setFeedback

public void setFeedback(double feedback)
Sets the feedback. This method should be called before the updateMatchStatistics method is called. This method is only used if feedback is being provided.

Specified by:
setFeedback in interface InterfaceHandlesFeedback
Parameters:
feedback - The value of the feedback.

updateMatchStatistics

public void updateMatchStatistics(AbstractMatchCalculator MatchCalculator)
Updates the positive or negative match statistics based on the feedback.

This update is usually performed after the feedback has been set.

Specified by:
updateMatchStatistics in interface InterfaceTracksMatchStatistics
Parameters:
MatchCalculator - The match calculator to use to determine positivity.

resetMatchStatistics

public void resetMatchStatistics()
Resets the match statistics.

Specified by:
resetMatchStatistics in interface InterfaceTracksMatchStatistics

incrementPM

public void incrementPM()
Increments the positive match statistic. This method can be used to update the positive match statistic if the user wishes to provide their own match criterion function.

Specified by:
incrementPM in interface InterfaceTracksMatchStatistics

incrementNM

public void incrementNM()
Increments the negative match statistic. This method can be used to update the negative match statistic if the user wishes to provide their own match criterion function.

Specified by:
incrementNM in interface InterfaceTracksMatchStatistics

checkMatchCriterion

public boolean checkMatchCriterion()
This method does nothing as it is not used by the CLARION Library for this collection.

Specified by:
checkMatchCriterion in interface InterfaceHandlesFeedback
Returns:
False

size

public int size()
Returns the number of rules in the rule collection.

Specified by:
size in interface java.util.Map<java.lang.Object,java.util.HashMap<java.lang.Integer,AbstractRule>>
Overrides:
size in class java.util.HashMap<java.lang.Object,java.util.HashMap<java.lang.Integer,AbstractRule>>
Returns:
The number of rules.

numVariations

public int numVariations()
Gets the number of variations being tracked by this collection.

Returns:
The number of variations.

numChildren

public int numChildren()
Gets the number of children being tracked by this collection.

Returns:
The number of children.

getVariations

public java.util.Collection<AbstractRule> getVariations()
Gets the rule variations from the rule collection. This method is used mainly for internal purposes and for reporting the rule variations (if desired).

This method should NOT be used to manipulate the rule variations from outside of the CLARION library.

Returns:
A collection containing the rule variations in this rule collection.

getChildren

public java.util.Collection<AbstractRule> getChildren()
Gets the child rules from the rule collection. This method is used mainly for internal purposes and for reporting the rule variations (if desired).

This method should NOT be used to manipulate the child rules from outside of the CLARION library.

Returns:
A collection containing the child rule in this rule collection.

toString

public java.lang.String toString()
Overrides:
toString in class java.util.AbstractMap<java.lang.Object,java.util.HashMap<java.lang.Integer,AbstractRule>>