Main Page   Class Hierarchy   Compound List   Compound Members  

TreeAPI Interface Reference

Treebank API interface. More...

List of all members.

Public Types

typedef string Id
 Generic identifier (can be from any of AGSetId, AGId, AnnotationId, TimelineId, SignalId).

typedef string AGSetId
 AGSet identifier.

typedef string AGId
 AG identifier.

typedef string AnnotationId
 Annotation identifier.

typedef string AnnotationType
 Annotation type.

typedef string AnchorId
 Anchor identifier.

typedef string TimelineId
 Timeline identifier.

typedef string SignalId
 Signal identifier.

typedef string FeatureName
 feature name

typedef string FeatureValue
 feature value

typedef string URI
 a uniform resource identifier

typedef string MimeClass
 the MIME class

typedef string MimeType
 the MIME type

typedef string Encoding
 the signal encoding

typedef string Unit
 the unit for offsets

typedef double Offset
 the offset into a signal

typedef string Track
 the track of a signal


Public Methods

AnnotationId tree_init_tree (AnnotationType type, Id id="AGTree")
 Create an empty tree, a tree with only one node.

bool tree_move_down (AnnotationId anno, AnnotationType type="syn", AnnotationId new_anno="")
 Move the given node down, creating a new node above it.

bool tree_move_up (AnnotationId anno)
 Move the given node up, deleting the parent node.

bool tree_promote_right (AnnotationId anno)
 Make the given node a right sibling of parent node.

bool tree_promote_left (AnnotationId anno)
 Make the given node a left sibling of parent node.

bool tree_demote_right (AnnotationId anno)
 Make the given node a rightmost child of the left sibling.

bool tree_demote_left (AnnotationId anno)
 Make the given node a leftmost child of the right sibling.

AnnotationId tree_first_tree (AGId agId)
 Find the first tree (root) in a given annotation graph.

AnnotationId tree_last_tree (AGId agId)
 Find the last tree (root) in a given annotation graph.

bool tree_move (AnnotationId x, AnnotationId y)
 Move a subtree under a certain node.

AnnotationId tree_insert_node_left (AnnotationId x, AnnotationType type="wrd", AnnotationId annoId="")
 Insert a new terminal node on the left.

AnnotationId tree_insert_node_right (AnnotationId x, AnnotationType type="wrd", AnnotationId annoId="")
 Insert a new terminal node on the right.

bool tree_delete_node_left (AnnotationId x)
 Delete a node on the left.

bool tree_delete_node_right (AnnotationId x)
 Delete a node on the left.

AnnotationId tree_root (AnnotationId x, int depth=1)
 Find the root node.

AnnotationId tree_parent (AnnotationId x)
 Find the parent node.

sequence< AnnotationId > tree_children (AnnotationId x)
 Find children.

AnnotationId tree_left (AnnotationId x)
 Find a left sibling.

AnnotationId tree_right (AnnotationId x)
 Find a right sibling.

sequence< AnnotationId > tree_path (AnnotationId x)
 Find a path from the root to the given node.

AnnotationId tree_common_ancestor (AnnotationId x, AnnotationId y)
 Find the nearest common ancestor of the two nodes.

AnnotationId tree_insert_node (AnnotationId x, AnnotationId y, AnnotationType type="syn", AnnotationId annoId="")
 Insert a non-terminal node.

bool tree_delete_node (AnnotationId x)
 Delete a non-terminal node.

Detailed Description

Treebank API interface.

This is a description of Tree API. In this description, although function signatures are represented in C++ style, it's straightforward to translate them to other languages. C++ programmers should check the exact argument types and return types in agtree.h for some functions return or accept pointer types, and set and list should be distinguished. Java programmers also should check the exact types to use in jag.java for the similar reasons.

Here is how functions are represented in this desctiption: 

 <return type> TreeAPI::<function name> ( <arg list> )

 <arg list> :=
        _empty_string_
      | <arg type> <arg name>
      | <arg type> <arg name> = <default value>
      | <arg type> <arg name> , <arg list>
      | <arg list> , <arg type> <arg name> = <default value>

 <arg type> :=
        <base type>
      | <compound type>

 <return type> :=
        <base type>
      | <compound type>

 <compound type> :=
        sequence< <base type> >
      | hash< <base type> , <base type> >

 <base type> :=
        (one of the types listed in typedef statements above)
       | bool | int | float | double | string

  • <default value> is the value assigned to the argument when the argument is not present in the function call.
  • sequence<t1> is a list type, in which elements are of t1 type.
  • hash<t1,t2> is a hash table type, in which keys are of t1 type and values are t2 type.

    Here is an example: 

     AnnotationId
 TreeAPI::tree_insert_node(
         AnnotationId x,
         AnnotationId y,
         AnnotationType type="syn",
         AnnotationId annoId=""
 )

    Function tree_insert_node returns an AnnotationId. It takes two AnnotationIds as arguments. AnnotationType can be given optionally. If it is not given, default value for type is `syn'. annoId is also an optional argument. If it is not present, an empty string will be assumed for the value.

    Member Function Documentation

    sequence<AnnotationId> TreeAPI::tree_children (  AnnotationId    x ) 
     

    Find children.

    Parameters:
    x  Id of an annotation (node) whose children will be searched.
    Returns:
    A list of children from the leftmost to the rightmost child.

    AnnotationId TreeAPI::tree_common_ancestor (  AnnotationId    x,
    AnnotationId    y
    ) 
     

    Find the nearest common ancestor of the two nodes.

    Parameters:
    x, y  Annotation (node) ids.
    Returns:
    Id of the nearest common ancestor of x and y.

    bool TreeAPI::tree_delete_node (  AnnotationId    x ) 
     

    Delete a non-terminal node.

    Parameters:
    x  Id of an annotation (node) to be deleted.
    Returns:
    true on success, false on fail.

    bool TreeAPI::tree_delete_node_left (  AnnotationId    x ) 
     

    Delete a node on the left.

    Parameters:
    x  Id of the annotation (node) whose left sibling is deleted. x must be a terminal node.
    Returns:
    true on success, false on fail.

    bool TreeAPI::tree_delete_node_right (  AnnotationId    x ) 
     

    Delete a node on the left.

    Parameters:
    x  Id of the annotation (node) whose right sibling is deleted. x must be a terminal node.
    Returns:
    true on success, false on fail.

    bool TreeAPI::tree_demote_left (  AnnotationId    anno ) 
     

    Make the given node a leftmost child of the right sibling.

    Parameters:
    anno  Id of the annotation (node) to be moved. The node must have a right sibling. Otherwise the operation fails.
    Returns:
    true on success, false on fail

    bool TreeAPI::tree_demote_right (  AnnotationId    anno ) 
     

    Make the given node a rightmost child of the left sibling.

    Parameters:
    anno  Id of the annotation (node) to be moved. The node must have a left sibling. Otherwise the operation fails.
    Returns:
    true on success, false on fail

    AnnotationId TreeAPI::tree_first_tree (  AGId    agId ) 
     

    Find the first tree (root) in a given annotation graph.

    Parameters:
    agId  Id of an annotation graph.
    Returns:
    The id of the root node of the first tree in the annotation graph.

    AnnotationId TreeAPI::tree_init_tree (  AnnotationType    type,
    Id    id = "AGTree"
    ) 
     

    Create an empty tree, a tree with only one node.

    Parameters:
    type  Type of the annotation (node) to be created.
    id  Agset, ag or annotation id. It's an error to give an id of an existing annotation. If the specified ag already exists, new annotation will be attached to the last annotation in the ag. If objects (agset, ag, annotation) specified in the id don't exist, appropriate objects will be created.
    Returns:
    Id of created annotation (node) upon success.

    AnnotationId TreeAPI::tree_insert_node (  AnnotationId    x,
    AnnotationId    y,
    AnnotationType    type = "syn",
    AnnotationId    annoId = ""
    ) 
     

    Insert a non-terminal node.

    Parameters:
    x, y  Ids of annotations (nodes) which are children of a node. It's an error that y precedes x. A non-terminal will be added in the following way. x is moved down, creating a non-terminal x'. All nodes which are right siblings of x, and left siblings of y, including y, become the children of x'.
    type  Type of newly created annotation (node).
    annoId  Specifies the id of newly created annotation (node).
    Returns:
    Id of the newly created node.

    AnnotationId TreeAPI::tree_insert_node_left (  AnnotationId    x,
    AnnotationType    type = "wrd",
    AnnotationId    annoId = ""
    ) 
     

    Insert a new terminal node on the left.

    Parameters:
    x  Id of the annotation (node) on the left of which the new node is inserted. x itself should be a terminal node.
    type  Type of the new annotation (node).
    annoId  Specifies the id of the new annotation (node).
    Returns:
    Id of the new annotation (node).

    AnnotationId TreeAPI::tree_insert_node_right (  AnnotationId    x,
    AnnotationType    type = "wrd",
    AnnotationId    annoId = ""
    ) 
     

    Insert a new terminal node on the right.

    Parameters:
    x  Id of the annotation (node) on the right of which the new node is inserted. x itself should be a terminal node.
    type  Type of the new annotation (node).
    annoId  Specifies the id of the new annotation (node).
    Returns:
    Id of the new annotation (node).

    AnnotationId TreeAPI::tree_last_tree (  AGId    agId ) 
     

    Find the last tree (root) in a given annotation graph.

    Parameters:
    agId  Id of an annotation graph.
    Returns:
    The id of the root node of the last tree in the annotation graph.

    AnnotationId TreeAPI::tree_left (  AnnotationId    x ) 
     

    Find a left sibling.

    Parameters:
    x  Id of an annotation (node) whose left sibling will be searched.
    Returns:
    Id of the left sibling.

    bool TreeAPI::tree_move (  AnnotationId    x,
    AnnotationId    y
    ) 
     

    Move a subtree under a certain node.

    Parameters:
    x  Id of the annotation (node) to be moved. Actually the subtree rooted at x is moved. x must be a leftmost or rightmost child, and can't be an only child.
    y  x is moved under y. x should be able to reach under y by some promote and demote operations.
    Returns:
    true on success, false on fail

    bool TreeAPI::tree_move_down (  AnnotationId    anno,
    AnnotationType    type = "syn",
    AnnotationId    new_anno = ""
    ) 
     

    Move the given node down, creating a new node above it.

    Parameters:
    anno  Id of the annotation (node) to be moved.
    type  Type of the newly created annotation (node).
    new_anno  Specifies the id of created annotation.
    Returns:
    true on success, false on fail

    bool TreeAPI::tree_move_up (  AnnotationId    anno ) 
     

    Move the given node up, deleting the parent node.

    Parameters:
    anno  Id of the annotation (node) to be moved. The node must be an only child. Otherwise the operation fails.
    Returns:
    true on success, false on fail

    AnnotationId TreeAPI::tree_parent (  AnnotationId    x ) 
     

    Find the parent node.

    Parameters:
    x  Id of an annotation (node) whose parent will be searched.
    Returns:
    Id of the parent annotation (node).

    sequence<AnnotationId> TreeAPI::tree_path (  AnnotationId    x ) 
     

    Find a path from the root to the given node.

    Parameters:
    x  An annotation (node) id. The function finds the path from the root to x.
    Returns:
    A list of annotations (nodes) in the path from the root.

    bool TreeAPI::tree_promote_left (  AnnotationId    anno ) 
     

    Make the given node a left sibling of parent node.

    Parameters:
    anno  Id of the annotation (node) to be moved. The node must be the leftmost child, and it can't be an only child. Otherwise the operation fails.
    Returns:
    true on success, false on fail

    bool TreeAPI::tree_promote_right (  AnnotationId    anno ) 
     

    Make the given node a right sibling of parent node.

    Parameters:
    anno  Id of the annotation (node) to be moved. The node must be the rightmost child, and it can't be an only child. Otherwise the operation fails.
    Returns:
    true on success, false on fail

    AnnotationId TreeAPI::tree_right (  AnnotationId    x ) 
     

    Find a right sibling.

    Parameters:
    x  Id of an annotation (node) whose right sibling will be searched.
    Returns:
    Id of the right sibling.

    AnnotationId TreeAPI::tree_root (  AnnotationId    x,
    int    depth = 1
    ) 
     

    Find the root node.

    Parameters:
    x  Id of an annotation (node). The root of the tree with x will be searched.
    depth  A positive integer. Suppose a path from the root to x. Then the (depth+1)th node in the path will be returned. This is useful when the root of a sentence and the root of the tree are different.
    Returns:
    Id of the root annotation (node).