capabilities.java

Java 编写的多种数据挖掘算法 包括聚类、分类、预处理等

  
  /**
   * Tests the given data, whether it can be processed by the handler,
   * given its capabilities. Classifiers implementing the 
   * <code>MultiInstanceCapabilitiesHandler</code> interface are checked 
   * automatically for their multi-instance Capabilities (if no bags, then
   * only the bag-structure, otherwise only the first bag).
   *
   * @param data 	the data to test
   * @return		true if all the tests succeeded
   * @see MultiInstanceCapabilitiesHandler
   */
  public boolean test(Instances data) {
    return test(data, 0, data.numAttributes() - 1);
  }
  
  /**
   * Tests a certain range of attributes of the given data, whether it can be 
   * processed by the handler, given its capabilities. Classifiers 
   * implementing the <code>MultiInstanceCapabilitiesHandler</code> interface 
   * are checked automatically for their multi-instance Capabilities (if no 
   * bags, then only the bag-structure, otherwise only the first bag).
   *
   * @param data 	the data to test
   * @param fromIndex	the range of attributes - start (incl.)
   * @param toIndex	the range of attributes - end (incl.)
   * @return		true if all the tests succeeded
   * @see MultiInstanceCapabilitiesHandler
   */
  public boolean test(Instances data, int fromIndex, int toIndex) {
    int         i;
    int         n;
    Attribute   att;
    Instance    inst;
    boolean     noClass;
    boolean     tmpResult;
    boolean	testClass;
    
    // no Capabilities? -> warning
    if (    (m_Capabilities.size() == 0) 
	 || ((m_Capabilities.size() == 1) && handles(Capability.NO_CLASS)) )
      System.err.println(createMessage("No capabilities set!"));
    
    // any attributes?
    if (toIndex - fromIndex < 0) {
      m_FailReason = new WekaException(
                          createMessage("No attributes!"));
      return false;
    }

    // do wee need to test the class attribute, i.e., is the class attribute
    // within the range of attributes?
    testClass =    (data.classIndex() > -1) 
    		&& (data.classIndex() >= fromIndex)
    		&& (data.classIndex() <= toIndex);
    
    // attributes
    for (i = fromIndex; i <= toIndex; i++) {
      att = data.attribute(i);
      
      // class is handled separately
      if (i == data.classIndex())
        continue;
      
      // check attribute types
      if (!test(att))
	return false;
    }

    // class
    if (testClass && !handles(Capability.NO_CLASS)) {
      if (data.classIndex() == -1) {
        m_FailReason = new UnassignedClassException(
                            createMessage("Class attribute not set!"));
        return false;
      }
      
      att = data.classAttribute();
      if (!test(att, true))
	return false;

      // special handling of RELATIONAL class
      if (att.type() == Attribute.RELATIONAL) {
	// test recursively (but add ability to handle NO_CLASS)
	noClass = handles(Capability.NO_CLASS);
	if (!noClass)
	  enable(Capability.NO_CLASS);
	tmpResult = test(att.relation());
	if (!noClass) 
	  disable(Capability.NO_CLASS);
	if (!tmpResult)
	  return false;
      }
      
      // missing class labels
      if (!handles(Capability.MISSING_CLASS_VALUES)) {
        for (i = 0; i < data.numInstances(); i++) {
          if (data.instance(i).classIsMissing()) {
            m_FailReason = new WekaException(
                createMessage("Cannot handle missing class values!"));
            return false;
          }
        }
      }
      else {
        int hasClass = 0;

        for (i = 0; i < data.numInstances(); i++) {
          if (!data.instance(i).classIsMissing())
            hasClass++;
        }
        
        // not enough instances with class labels?
        if (hasClass < getMinimumNumberInstances()) {
          m_FailReason = new WekaException(
                              createMessage("Not enough training instances with class labels (required: " 
                                          + getMinimumNumberInstances() 
                                          + ", provided: " 
                                          + hasClass + ")!"));
          return false;
        }
      }
    }

    // missing values
    if (!handles(Capability.MISSING_VALUES)) {
      for (i = 0; i < data.numInstances(); i++) {
        inst = data.instance(i);
        for (n = fromIndex; n <= toIndex; n++) {
          // skip class
          if (n == inst.classIndex())
            continue;

          if (inst.isMissing(n)) {
            m_FailReason = new NoSupportForMissingValuesException(
                                createMessage("Cannot handle missing values!"));
            return false;
          }
        }
      }
    }
    
    // instances
    if (data.numInstances() < getMinimumNumberInstances()) {
      m_FailReason = new WekaException(
                          createMessage("Not enough training instances (required: " 
                                      + getMinimumNumberInstances() 
                                      + ", provided: " 
                                      + data.numInstances() + ")!"));
      return false;
    }

    // Multi-Instance? -> check structure (regardless of attribute range!)
    if (handles(Capability.ONLY_MULTIINSTANCE)) {
      // number of attributes?
      if (data.numAttributes() != 3) {
        m_FailReason = new WekaException(
                            createMessage("Incorrect Multi-Instance format, must be 'bag-id, bag, class'!"));
        return false;
      }
      
      // type of attributes and position of class?
      if (    !data.attribute(0).isNominal() 
           || !data.attribute(1).isRelationValued() 
           || (data.classIndex() != data.numAttributes() - 1) ) {
        m_FailReason = new WekaException(
            createMessage("Incorrect Multi-Instance format, must be 'NOMINAL att, RELATIONAL att, CLASS att'!"));
        return false;
      }

      // check data immediately
      if (getOwner() instanceof MultiInstanceCapabilitiesHandler) {
	MultiInstanceCapabilitiesHandler handler = (MultiInstanceCapabilitiesHandler) getOwner();
	Capabilities cap = handler.getMultiInstanceCapabilities();
	boolean result;
	if (data.numInstances() > 0)
	  result = cap.test(data.attribute(1).relation(1));
	else
	  result = cap.test(data.attribute(1).relation());
	
	if (!result) {
	  m_FailReason = cap.m_FailReason;
	  return false;
	}
      }
    }
    
    // passed all tests!
    return true;
  }

  /**
   * tests the given attribute by calling the test(Attribute,boolean) method 
   * and throws an exception if the test fails. The method assumes that the
   * specified attribute is not the class attribute.
   *
   * @param att        	the attribute to test
   * @throws Exception  in case the attribute doesn't pass the tests
   * @see #test(Attribute,boolean)
   */
  public void testWithFail(Attribute att) throws Exception {
    test(att, false);
  }

  /**
   * tests the given attribute by calling the test(Attribute,boolean) method 
   * and throws an exception if the test fails.
   *
   * @param att        	the attribute to test
   * @param isClass	whether this attribute is the class attribute
   * @throws Exception  in case the attribute doesn't pass the tests
   * @see #test(Attribute,boolean)
   */
  public void testWithFail(Attribute att, boolean isClass) throws Exception {
    if (!test(att, isClass))
      throw m_FailReason;
  }

  /**
   * tests the given data by calling the test(Instances,int,int) method and 
   * throws an exception if the test fails.
   *
   * @param data        the data to test
   * @param fromIndex	the range of attributes - start (incl.)
   * @param toIndex	the range of attributes - end (incl.)
   * @throws Exception  in case the data doesn't pass the tests
   * @see #test(Instances)
   */
  public void testWithFail(Instances data, int fromIndex, int toIndex) throws Exception {
    if (!test(data, fromIndex, toIndex))
      throw m_FailReason;
  }

  /**
   * tests the given data by calling the test(Instances) method and throws 
   * an exception if the test fails.
   *
   * @param data        the data to test
   * @throws Exception  in case the data doesn't pass the tests
   * @see #test(Instances)
   */
  public void testWithFail(Instances data) throws Exception {
    if (!test(data))
      throw m_FailReason;
  }
  
  /**
   * returns a string representation of the capabilities
   * 
   * @return 	a string representation of this object
   */
  public String toString() {
    Vector		sorted;
    StringBuffer	result;
    
    result = new StringBuffer();

    // capabilities
    sorted = new Vector(m_Capabilities);
    Collections.sort(sorted);
    result.append("Capabilities: " + sorted.toString() + "\n");

    // dependencies
    sorted = new Vector(m_Dependencies);
    Collections.sort(sorted);
    result.append("Dependencies: " + sorted.toString() + "\n");
    
    // other stuff
    result.append("min # Instance: " + getMinimumNumberInstances() + "\n");
    
    return result.toString();
  }
  
  /**
   * returns a Capabilities object specific for this data. The multi-instance
   * capability is not checked as well as the minimum number of instances
   * is not set.
   * 
   * @param data	the data to base the capabilities on
   * @return		a data-specific capabilities object
   * @throws Exception	in case an error occurrs, e.g., an unknown attribute 
   * 			type
   */
  public static Capabilities forInstances(Instances data) throws Exception {
    return forInstances(data, false);
  }
  
  /**
   * returns a Capabilities object specific for this data. The minimum number 
   * of instances is not set, the check for multi-instance data is optional.
   * 
   * @param data	the data to base the capabilities on
   * @param multi	if true then the structure is checked, too
   * @return		a data-specific capabilities object
   * @throws Exception	in case an error occurrs, e.g., an unknown attribute 
   * 			type
   */
  public static Capabilities forInstances(Instances data, boolean multi) throws Exception {
    Capabilities	result;
    Capabilities	multiInstance;
    int			i;
    int			n;
    
    result = new Capabilities(null);
    
    // class
    if (data.classIndex() == -1) {
      result.enable(Capability.NO_CLASS);
    }
    else {
      switch (data.classAttribute().type()) {
	case Attribute.NOMINAL:
	  if (data.classAttribute().numValues() == 2)
	    result.enable(Capability.BINARY_CLASS);
	  else
	    result.enable(Capability.NOMINAL_CLASS);
	  break;
	  
	case Attribute.NUMERIC:
	  result.enable(Capability.NUMERIC_CLASS);
	  break;
	  
	case Attribute.STRING:
	  result.enable(Capability.STRING_CLASS);
	  break;
	  
	case Attribute.DATE:
	  result.enable(Capability.DATE_CLASS);
	  break;
	  
	case Attribute.RELATIONAL:
	  result.enable(Capability.RELATIONAL_CLASS);
	  break;
	  
	default:
	  throw new UnsupportedAttributeTypeException("Unknown class attribute type '" + data.classAttribute() + "'!");
      }
      
      // missing class values
      for (i = 0; i < data.numInstances(); i++) {
	if (data.instance(i).classIsMissing()) {
	  result.enable(Capability.MISSING_CLASS_VALUES);
	  break;
	}
      }
    }
    
    // attributes
    if (data.checkForAttributeType(Attribute.NOMINAL)) {
      result.enable(Capability.BINARY_ATTRIBUTES);
      
      for (i = 0; i < data.numAttributes(); i++) {
	// skip class
	if (i == data.classIndex())
	  continue;

	// non-binary attributes?
	if (data.attribute(i).isNominal()) {
	  if (data.attribute(i).numValues() != 2) {
	    result.enable(Capability.NOMINAL_ATTRIBUTES);
	    break;
	  }
	}
      }
    }

    if (data.checkForAttributeType(Attribute.NUMERIC))
      result.enable(Capability.NUMERIC_ATTRIBUTES);
    
    if (data.checkForAttributeType(Attribute.STRING))
      result.enable(Capability.STRING_ATTRIBUTES);

    if (data.checkForAttributeType(Attribute.DATE))
      result.enable(Capability.DATE_ATTRIBUTES);

    if (data.checkForAttributeType(Attribute.RELATIONAL))
      result.enable(Capability.RELATIONAL_ATTRIBUTES);
    
    // missing values
    for (n = 0; n < data.numAttributes(); n++) {
      if (n == data.classIndex())
	continue;
      
      for (i = 0; i < data.numInstances(); i++) {
	if (data.instance(i).isMissing(n)) {
	  result.enable(Capability.MISSING_VALUES);
	  break;
	}
      }
    }

    // multi-instance data?
    if (multi) {
      if (    (data.numAttributes() == 3)
	   && (data.attribute(0).isNominal())		// bag-id
	   && (data.attribute(1).isRelationValued()) 	// bag
	   && (data.classIndex() == data.numAttributes() - 1) ) {
	multiInstance = new Capabilities(null);
	multiInstance.or(result.getClassCapabilities());
	multiInstance.enable(Capability.NOMINAL_ATTRIBUTES);
	multiInstance.enable(Capability.RELATIONAL_ATTRIBUTES);
	multiInstance.enable(Capability.ONLY_MULTIINSTANCE);
	result.assign(multiInstance);
      }
    }
    
    return result;
  }
}