Function CDM_CompareAnnotationSets


Definition:#include <CDM.h>
Prototype:int CDM_CompareAnnotationSets(CDM_AnnotationSet KeySet, CDM_AnnotationSet ResSet, Tcl_Obj *AttributesList, Tcl_Obj *ValuesList, double spanOverlapPercent, int checkValues, int LogInfo);
Arguments:

KeySet: The set holding the Key Annotations (CDM_AnnotationSet)
ResSet: The set holding the Responce Annotations (CDM_AnnotationSet)
AttributesList: A Tcl object containing the Attribute names to be examined (Tcl_Obj *)
ValuesList: A Tcl object containing the values of Attributes to be examined (Tcl_Obj *)
spanOverlapPercent: A double value specifying the overlap the Annotations' spans must have to be considered as equal. If this value is 100.0, then the spans must be identical. (double)
checkValues: A boolean value specifying whether to enable Attribute Value checking (int)
LogInfo: A boolean value specifying whether to generate logging information [LogInfo != 0] or not [LogInfo = 0] (int)

C/C++ API Sections
Tcl API Sections
Description
Return Value
Notes
See Also
Index

Description:

This function can be used to compare two Annotation set objects, and calculate the number of Annoatations that are equal, according to the specified constraints.

As a first step, the two Annotation sets will be sorted internally based on their Spans (by using CDM_SortAnnotationSet). Then, if parameter "checkValues" is true (thus enabling Attribute Value checking) and the Tcl objects "AttributesList" and "ValuesList" are not empty, the Annotations that have Attributes with names from "AttributesList" but not values from the corresponding entries in "ValuesList".

When the initial filtering stage is completed, the two Annotation sets will be compared. Each Annotation from the key set will be compared with each Annotation from the responce set, based on their spans. If the two Annotations share the same spans, then their Attributes (with names from the "AttributesList" list) will be compared, and if Attribute Value checking is enabled the comparison will be also performed on the Attribute values. The return value from this function will be a standart Tcl completion code (of type int) with one of the values TCL_OK and TCL_ERROR. If an error occurs, the return value will be TCL_ERROR and an error message describing the error will be left at the current Tcl interpreter (CDM_Interp). If all annotators run without errors, TCL_OK will be returned.

The results of the Tcl code execution will be placed as the result in the current Tcl interpreter (CDM_Interp), if the command has been succesfully executed. The caller can use Tcl_GetObjResult(CDM_GetActiveInterpreter()) to get the stored result Tcl object.

Return Value:

The return value from this function will be a standart Tcl completion code (of type int) with one of the values TCL_OK and TCL_ERROR. If an error occurs, the return value will be TCL_ERROR and an error message describing the error will be left at the current Tcl interpreter (CDM_Interp). If all annotators run without errors, TCL_OK will be returned.

The result of the comparison will be placed as the result object in the current active Tcl interpreter (CDM_Interp). This object will be a list object with four elements. The first element will be the number of correct Annotations (i.e. the Annotations that matched), the second element will be the number of the key Annotations and the third element will be the number of responce Annotations.

The fourth (last) element is the logging info that will be generated by this function, if the parameter "LogInfo" is true (!= 0). If "LogInfo" is false (0), then this element will be an empty object. If logging information is enabled, this element will hold a list object, where each list element will have three elements: The first and third element will either be an Annotation object or the empty object. The second element will be a flag signaling the relation between the two Annotations. Valid flags are "<" (denoting that the first element is an empty object), "==" (denoting that the two Annotations are equal), "!=" (denoting that the two Annotations span the same regions but differ in Attributes) and "

Notes:

Note that the parameter "checkValues" will be ignored if the parameter "AttributesList" is an empty Tcl list object (i.e. has no elements). Also note that the object "ValuesList" must have exactly the same number of elements with "AttributesList": there must be a correspondance between the two objects, as the N-th element of "ValuesList" should be a list object, holding the allowable value patterns for the Attribute name stored in the N-th element of the "AttributesList" object.

An important limitation of this function is that it may produce incorect results, if any of the Annotations contained in the two sets has more than one Span elements in its Span set.

This function is equivelant to tip_CompareAnnotationSets (Tcl API).

See Also:

CDM_CompareAnnotations, tip_CompareAnnotationSets


Generated by: petasis@aias on Wed Aug 16 10:31:57 PM EEST 2006.