Class CategorizationModule

  • All Implemented Interfaces:
    IServiceProvider

    public class CategorizationModule
    extends java.lang.Object
    implements IServiceProvider
    The DiffModule computes differences and similarities between concepts.

    Type comparison

    Let's consider the following hierarchie:
                      +-------+
                      | Thing |
                    .'+-------._
                 .-'            ``-._
          +----.'----+         +-----`-------+
          | Artifact |         | WhiteObject |
          +--.-----.-+         +------+--,---+
            /       `-.               /   \
      +---.'---+      +`-.--+        |     \
      | Animal |      | Car |        /      \
      +----+---+      +-----+       |        |
           \               `.      /        '.
            \                `-.  |          |
        +-----+-------+      +---`------+     |
        | WhiteAnimal |      | WhiteCar |      |
        +-------------+      +----------+     /
                   `'--...__                ,'
                            ``---........,-'
     
    If you're looking for the similarities between concepts WhiteAnimal and WhiteCar, the getSimilarities(OntResource, OntResource) method would return the set {Artifact, WhiteObject}, ie the set of classes that belong to the intersection of the super-classes of both the concepts and without sub- classes in this intersection (the common ancestors). On the contrary, the getDifferences(OntResource, OntResource) method returns {Animal, Car} and {WhiteAnimal, WhiteCar}, ie the direct subclasses of the common ancestors that belongs to the hierarchies of the compared concepts.

    Algo principle for common ancestors

     We want S2 such as:
     S1 = superclasses(A) ∩ superclasses(B)
     S2 = { c / c ∈ S1 AND subclasses(c) ∩ S1 = ∅ }
     
    In the example above, S2 = {Artifact, WhiteObject}

    Algo principle for first different ancestors

     We want S3 such as:
     S3 = ∪ { c / c ∈ S2,  
                    (directsubclasses(c) ∩ superclasses(A)) ∪ 
                    (directsubclasses(c) ∩ superclasses(B))
                    }
     
    In the example above, S3 = {{Animal, Car}, {WhiteAnimal, WhiteCar}} The getDifferences(OntResource, OntResource) method would actually return a set of sets of statements, sorting by parent types the values for the two concepts (for instance, [[a type Animal, b type Car], [a type WhiteAnimal, b type WhiteCar]]).

    Comparison of other properties

    The getSimilarities(OntResource, OntResource) method will return as well the list of properties that are shared with the same object by both the concepts. The getDifferences(OntResource, OntResource) returns on the contrary properties shared by both concept but with different objects.
    Since:
    0.6.4
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      java.util.List<java.util.Set<java.lang.String>> discriminate​(java.util.Set<java.lang.String> rawConcepts)  
      java.util.Set<java.util.Set<java.lang.String>> getDifferences​(com.hp.hpl.jena.ontology.OntResource conceptA, com.hp.hpl.jena.ontology.OntResource conceptB)
      Returns the computed differences between two concepts, relying on asserted and inferred fact in the ontology.
      java.util.Set<java.util.Set<java.lang.String>> getDifferences​(java.lang.String conceptA, java.lang.String conceptB)
      Returns the differences between two concepts (in their literal representation).
      java.util.List<java.util.Set<com.hp.hpl.jena.rdf.model.Property>> getDiscriminent​(java.util.Set<com.hp.hpl.jena.ontology.OntResource> individuals)
      Returns a list of properties that helps to differentiate individuals.
      java.util.Set<java.lang.String> getSimilarities​(com.hp.hpl.jena.ontology.OntResource conceptA, com.hp.hpl.jena.ontology.OntResource conceptB)
      Returns the computed similarities between two concepts, relying on asserted and inferred fact in the ontology.
      java.util.Set<java.lang.String> getSimilarities​(java.lang.String conceptA, java.lang.String conceptB)
      Returns the similarities between two concepts (in their literal representation).
      java.util.Map<com.hp.hpl.jena.ontology.OntClass,​java.util.Set<com.hp.hpl.jena.ontology.Individual>> makeCategories​(java.util.Set<com.hp.hpl.jena.ontology.OntResource> resources)
      Try to build a categories from a set of individuals.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Constructor Detail

    • Method Detail

      • getDifferences

        public java.util.Set<java.util.Set<java.lang.String>> getDifferences​(com.hp.hpl.jena.ontology.OntResource conceptA,
                                                                             com.hp.hpl.jena.ontology.OntResource conceptB)
                                                                      throws NotComparableException
        Returns the computed differences between two concepts, relying on asserted and inferred fact in the ontology.
        Parameters:
        conceptA - First concept to compare
        conceptB - Second concept to compare
        Returns:
        Computed differences between two concepts as a set of sets of stringified statements: for each different property (including type), a set of statement that explain for each concept its relation (for instance, [[a type Animal, b type Car], [a type WhiteAnimal, b type WhiteCar]])
        Throws:
        NotComparableException
        See Also:
        Detailled explanations with a diagram., Same "stringified" method.
      • getDifferences

        @RPCMethod(category="concept comparison",
                   desc="given two concepts, return the list of relevant differences (types, properties...) between these concepts.")
        public java.util.Set<java.util.Set<java.lang.String>> getDifferences​(java.lang.String conceptA,
                                                                             java.lang.String conceptB)
                                                                      throws com.hp.hpl.jena.shared.NotFoundException,
                                                                             NotComparableException
        Returns the differences between two concepts (in their literal representation).
        Parameters:
        conceptA - The first concept to compare
        conceptB - The second concept to compare
        Returns:
        computed differences between two concepts as a set of sets of stringified statements: for each different property (including type), a set of statement that explain for each concept its relation.
        Throws:
        com.hp.hpl.jena.shared.NotFoundException
        NotComparableException
        See Also:
        Detailled explanations with a diagram., getDifferences(OntResource, OntResource)
      • getDiscriminent

        public java.util.List<java.util.Set<com.hp.hpl.jena.rdf.model.Property>> getDiscriminent​(java.util.Set<com.hp.hpl.jena.ontology.OntResource> individuals)
                                                                                          throws NotComparableException
        Returns a list of properties that helps to differentiate individuals. For instance, let consider the following ontology, with four instances (plant1, animal1, animal2, animal3) :
                     +-------+
                     | Thing |
                     +--,'.--+
                     .-'   `-.
                   ,'         `.
                 ,'             `-.
              .-'                  `.
        +----+--+                 +--+-----+
        | Plant |                 | Animal |
        +---+---+                 +--+++---+
            |                   _,-"  |  `--.._
            |                .-'      |        ``--..
          plant1         animal1    animal2        animal3
            |               |         / `.            \
            |               |        /    `-.          \
         hasColor         eats     eats  hasColor   hasColor
            |               |        |      |          |
            |               |        |      |          |
          green          banana    grass   blue       red
         

        Let's imagine the robot wants to answer an ambigious order like Give me the thing!: we need a way to disambiguate the different possible individuals in the Thing class.

        The method return two things:

        • a first set of properties that totally discriminate the set of individual. It means that if we get the value of this property, we can distinguish the individuals. Quite often, this set is empty because the set can not be split by a single property.
        • a second set that contains the best property that can be used to split the set of individuals (of the set of best properties if several properties have the same efficiency). If the first set is not empty, the second set should obviously contain the same property/ies.

        The method proceeds as follows:

        1. Build a list of properties for each individuals, and sum their occurrence:
            
                      p1        p2        p3
          -------------------------------------
          plant1:    {hasClass, hasColor}
          animal1:   {hasClass,           eats}
          animal2:   {hasClass, hasColor, eats}
          animal3:   {hasClass, hasColor}
          -------------------------------------
                |p|=  4         3         2
          
        2. For each property, count the number of groups it forms (ie, the number of distinct values)
        3.          | p1:hasClass | p2:hasColor | p3:eats
          ---------+-------------+-------------+--------
          plant1   | Plant       | green       |
          animal1  | Animal      |             | banana
          animal2  | Animal      | blue        | grass
          animal3  | Animal      | red         |
          ---------+-------------+-------------+--------
          |≠ elem.|= 2             3             2
          
        4. Remove properties that lead to only 1 group (ie, non selective properties)
        5. Return the property that has the highest occurrence, and then the best selectivity (ie the biggest amount of groups). If several properties are equal, return all of them.
        In our example, we would return hasClass.

        If we apply the method to the instances of the Animal class, it would return {hasColor, eats}.

        It should be noted that this way of proceeding doesn't respect the OWL open world assumption: in OWA, the animal2 and the animal3 could possibly eat bananas as well, and thus, the eats property isn't selective.
        This rule is not enforced on purpose in this implementation: we stand on the viewpoint of a human-robot interaction where a robot only reason with what he positively knows.

        Parameters:
        individuals - A set of concepts
        Returns:
        A list of two sets: first, a set of properties - if they exist - that are individually sufficient to differentiate all the individuals in the provided set from the values (objects) of these properties. Then a set of properties that are sufficient OR NOT to distinguish the individuals. If they are sufficient, it's the same as the first set. Else, it's the most discriminating properties.
        Throws:
        NotComparableException
      • discriminate

        @RPCMethod(category="concept comparison",
                   desc="returns a list of properties that helps to differentiate individuals.")
        public java.util.List<java.util.Set<java.lang.String>> discriminate​(java.util.Set<java.lang.String> rawConcepts)
                                                                     throws com.hp.hpl.jena.shared.NotFoundException,
                                                                            NotComparableException
        Throws:
        com.hp.hpl.jena.shared.NotFoundException
        NotComparableException
      • getSimilarities

        public java.util.Set<java.lang.String> getSimilarities​(com.hp.hpl.jena.ontology.OntResource conceptA,
                                                               com.hp.hpl.jena.ontology.OntResource conceptB)
                                                        throws NotComparableException
        Returns the computed similarities between two concepts, relying on asserted and inferred fact in the ontology. Only relevant features are returned. For instance, only the closest common ancestor is returned, not all the shared hierarchy of two concepts.
        Parameters:
        conceptA - First concept to compare
        conceptB - Second concept to compare
        Returns:
        computed similarities between two concepts as a set of stringified partial statements: for each similar property (including type), a string of form "? prop obj" is returned. that are relevant common features of the two compared concepts.
        Throws:
        NotComparableException
        See Also:
        Detailled explanations with a diagram., Same "stringified" method.
      • getSimilarities

        @RPCMethod(category="concept comparison",
                   desc="given two concepts, return the list of relevant similarities (types, properties...) between these concepts.")
        public java.util.Set<java.lang.String> getSimilarities​(java.lang.String conceptA,
                                                               java.lang.String conceptB)
                                                        throws com.hp.hpl.jena.shared.NotFoundException,
                                                               NotComparableException
        Returns the similarities between two concepts (in their literal representation).
        Parameters:
        conceptA - The first concept to compare
        conceptB - The second concept to compare
        Returns:
        the computed similarities between two concepts as a set of stringified partial statements: for each similar property (including type), a string of form "? prop obj" is returned.
        Throws:
        com.hp.hpl.jena.shared.NotFoundException
        NotComparableException
        See Also:
        Detailled explanations with a diagram., getSimilarities(OntResource, OntResource)
      • makeCategories

        public java.util.Map<com.hp.hpl.jena.ontology.OntClass,​java.util.Set<com.hp.hpl.jena.ontology.Individual>> makeCategories​(java.util.Set<com.hp.hpl.jena.ontology.OntResource> resources)
                                                                                                                                 throws NotComparableException
        Try to build a categories from a set of individuals. This method does a fair amount of processing to compute possible categories in a set of individuals :
        Throws:
        NotComparableException