Main Page   Class Hierarchy   Compound List   Compound Members  

AGAPI Interface Reference

AGAPI 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

AGSet functions
AGSetId CreateAGSet (AGSetId agSetId)
 Create a new AGSet.

bool ExistsAGSet (AGSetId agSetId)
 Test if an AGSet exists.

void DeleteAGSet (AGSetId agSetId)
 Delete an AGSet.

sequence< AGId > GetAGIds (AGSetId agsetId)
 Get all the Ids of AGs which belong to the specified AGSet.

Timeline functions
TimelineId CreateTimeline (Id id)
 Create a new timeline and add it to the AGSet.

bool ExistsTimeline (TimelineId timelineId)
 Test if a timeline exists.

void DeleteTimeline (TimelineId timelineId)
 Delete a timeline.

sequence< SignalId > GetSignals (TimelineId timelineId)
 Get a list of all the Ids of sigals which belong to the specified timeline.

Signal functions
SignalId CreateSignal (Id id, URI uri, MimeClass mimeClass, MimeType mimeType, Encoding encoding, Unit unit, Track track)
 Create a new signal and add it to the timeline.

bool ExistsSignal (SignalId signalId)
 Test if a signal exists.

void DeleteSignal (SignalId signalId)
 Delete a signal.

MimeClass GetSignalMimeClass (SignalId signalId)
 Get the MimeClass of the specified signal.

MimeType GetSignalMimeType (SignalId signalId)
 Get the MimeType of the specified signal.

Encoding GetSignalEncoding (SignalId signalId)
 Get the encoding of the specified signal.

string GetSignalXlinkType (SignalId signalId)
 Get the XlinkType of the specified signal.

string GetSignalXlinkHref (SignalId signalId)
 Get the XlinkHref of the specified signal.

string GetSignalUnit (SignalId signalId)
 Get the unit of the specified signal.

Track GetSignalTrack (SignalId signalId)
 Get the track of the specified signal.

AG functions
AGId CreateAG (Id id)
 Create a new AG and add it to the AGSet.

AGId CreateAG (Id id, TimelineId timelineId)
 Create a new AG and add it to the AGSet.

bool ExistsAG (AGId agId)
 Test if an AG exists.

void DeleteAG (AGId agId)
 Delete an AG.

sequence< AnchorId > GetAnchorSet (AGId agId)
 Get all the anchors in an AG.

sequence< AnchorId > GetAnchorSetByOffset (AGId agId, Offset offset)
 Get all anchors which are anchored at the given offset.

sequence< AnchorId > GetAnchorSetByOffset (AGId agId, Offset offset, float epsilon)
 Get all anchors which are anchored within specified distance of the given offset.

sequence< AnchorId > GetAnchorSetNearestOffset (AGId agId, Offset offset)
 Get a list of all anchors which are anchored at the closest offset to the given offset.

sequence< AnnotationId > GetAnnotationSet (AGId agId, AnnotationType type="")
 Get a list of all annotation ids in the given annotation graph.

sequence< AnnotationId > GetAnnotationSetByFeature (AGId agId, FeatureName featureName, FeatureValue featureValue, AnnotationType type="")
 Get a list of all annotations whose specified feature equals to the specified value.

sequence< AnnotationId > GetAnnotationSetByOffset (AGId agId, Offset offset, AnnotationType type="")
 Get a list of all annotations which hangs over a given offset.

sequence< AnnotationId > GetAnnotationSeqByOffset (AGId agId, Offset begin=0.0, Offset end=0.0, AnnotationType type="")
 Get an ordered list of AnnotationIds within the given interval.

AnnotationId GetAnnotationByOffset (AGId agId, Offset offset, AnnotationType type="")
 Get one of the annotations which overlap a particular time offset.

Annotation functions
AnnotationId CreateAnnotation (Id id, AnchorId start, AnchorId end, AnnotationType annotationType)
 Create a new annotation.

bool ExistsAnnotation (AnnotationId annotationId)
 Test if an annotation exists.

void DeleteAnnotation (AnnotationId annotationId)
 Delete an annotation.

AnnotationId CopyAnnotation (AnnotationId annotationId)
 Clone an annotation.

sequence< AnnotationId > SplitAnnotation (AnnotationId annotationId)
 Split an annotation in two.

sequence< AnnotationId > NSplitAnnotation (AnnotationId annotationId, short N)
 Split an annotation to n annotations.

AnnotationType GetAnnotationType (AnnoationId annotationId)
 Get the type of the annotation.

AnchorId GetStartAnchor (AnnotationId annotationId)
 Get the start anchor.

AnchorId GetEndAnchor (AnnotationId annotationId)
 Get the end anchor.

string GetAnnotationInfo (AnnoationId annotationId)
 Get all the information of the specified annotation.

void SetStartAnchor (AnnotationId annotationId, AnchorId anchorId)
 Set the start of an annotation to the specified anchor.

void SetEndAnchor (AnnotationId annotationId, AnchorId anchorId)
 Set the end of an annotation to the specified anchor.

Offset GetStartOffset (AnnotationId annotationId)
 Get the offset of the start anchor of an annotatino.

Offset GetEndOffset (AnnotationId annotationId)
 Get the offset of the end anchor of an annotation.

void SetStartOffset (AnnotationId annotationId, Offset offset)
 Set the offset of the start anchor of an annotation.

void SetEndOffset (AnnotationId annotationId, Offset offset)
 Set the offset of the end anchor of an annotation.

bool SPrecedes (AnnotationId annotationId1, AnnotationId annotationId2)
 Test structural precedence of one annotation over the other.

Anchor functions
AnchorId CreateAnchor (Id id, Offset offset, Unit unit, sequence< SignalId > signalIds)
 Create an anchor with specified offset, unit and signals.

AnchorId CreateAnchor (Id id, sequence< SignalId > signalIds)
 Create an anchor with specified signals.

AnchorId CreateAnchor (Id id)
 Create an anchor.

bool ExistsAnchor (AnchorId anchorId)
 Test if an anchor exists.

void DeleteAnchor (AnchorId anchorId)
 Delete an anchor.

void SetAnchorOffset (AnchorId anchorId, Offset offset)
 Set the offset of an anchor.

void UnsetAnchorOffset (AnchorId anchorId)
 Unset the offset of an anchor.

Offset GetAnchorOffset (AnchorId anchorId)
 Get the offset of an anchor.

bool GetAnchored (AnchorId anchorId)
 Test if an anchor is anchored (has offset).

void SetOffsetUnit (AnchorId anchorId, Unit unit)
 Set the unit of the offset of an anchor.

Unit GetOffsetUnit (AnchorId anchorId)
 Get the unit of the offset of an anchor.

void SetAnchorSignalIds (AnchorId anchorId, sequence< SignalId > signalIds)
 Set the SignalIds associated with the given anchor.

sequence< SignalId > GetAnchorSignalIds (AnchorId anchorId)
 Get a list of the signal Ids associated with the given anchor.

AnchorId SplitAnchor (AnchorId anchorId)
 Split an anchor in two.

sequence< AnnotationId > GetIncomingAnnotationSet (AnchorId anchorId, AnnotationType type="")
 Get the incoming annotations of an anchor.

sequence< AnnotationId > GetOutgoingAnnotationSet (AnchorId anchorId, AnnotationType type="")
 Get the outgoing annotations of an anchor.

General functions for various objects
AGSetId GetAGSetId (Id id)
 Get the AGSetId of the given id.

AGId GetAGId (Id id)
 Get the AGId of the given id.

TimelineId GetTimelineId (Id id)
 Get the TimelineId of the given id.

sequence< AnnotationType > GetAnnotationTypes (Id id)
 Get a list of types of all annotations in an AGSet, AG, or Annotation.

sequence< FeatureName > GetAnnotationFeatureNames (Id id, AnnotationType type="")
 Get a list of feature names of all annotations in an AGSet, AG, or Annotation.

void SetFeature (Id id, FeatureName featureName, FeatureValue featureValue)
 Set the value of a feature.

bool ExistsFeature (Id id, FeatureName featureName)
 Test if a feature exists.

void DeleteFeature (Id id, FeatureName featureName)
 Delete a feature.

string GetFeature (Id id, FeatureName featureName)
 Get the value of a feature.

void UnsetFeature (Id id, FeatureName featureName)
 Unset a feature.

sequence< FeatureName > GetFeatureNames (Id id)
 Get all feature names in a list.

void SetFeatures (Id id, hash< FeatureName, FeatureValue > features)
 Set multiple features in a hash table.

hash< FeatureName, FeatureValue > GetFeatures (Id id)
 Get all features and values in a hash table.

void UnsetFeatures (Id id)
 Unset all features Set all features to empty. This is for both the features of an annotation, and for the metadata associated with AGSets, AGs, Timelines and Signals.

I/O functions
string toXML (AGSetId id)
 Dump the specified AGSet in ATLAS Level 0 format.

string toXML (AGId agId)
 Dump the specified AG in ATLAS Level 0 forma.

sequence< AGId > Load (string format, string filename, Id id="", hash< string, string > signalInfo=NULL, hsah< string, string > options=NULL)
 Load an annotation file.

void Store (string format, string filename, Id id, hash< string, string > options=NULL)
 Store an annotation graph in a given format.

void Store2 (string format, string filename, sequence< Id > ids, hash< string, string > options=NULL)
 Store annotation graphs in a given format.

bool LoadFromDB (string connStr, AGSetId agsetId)
 LoadFromDB loads the specified AGSet from the database server.

bool StoreToDB (string connStr AGSetId agsetId)
 StoreToDB stores the specified AGSet to the database server.

sequence< string > StoreSQLs (AGSetId agsetId)
 Return SQL queries needed to store the kernel to the database server.

Validation functions
bool CheckAnchorOffsetTotal (Id agId, AnnotationType type)
 Check that all anchors of annotations of a given type have an offset.

bool CheckAnchorOffsetBounded (Id agId, AnnotationType type)
 Check that all anchors of annotations of a given type are bounded by anchors that have an offset, following paths of this type.

bool CheckFeatureExists (Id agId, AnnotationType type, FeatureName featureName)
 Check that all annotations of a given type have the specified feature.

bool CheckFeatureIsAnnotationId (Id agId, AnnotationType type, FeatureName featureName)
 Check that all annotations of a given type have the specified feature and that its value is a valid AnnotationId.

bool CheckLinear (Id agId, AnnotationType type)
 Check that all annotations of a given type form a connected linear sequence.

bool CheckConnected (Id agId, AnnotationType type)
 Check that all annotations of a given type form a connected subgraph.

bool CheckCoextensive (Id agId, AnnotationType type1, AnnotationType type2)
 Check that all annotations of type type1 are coextensive with an annotation of type type2, and vice versa (an existence not uniqueness test).

bool CheckSpan (Id agId, AnnotationType spanType, AnnotationType spannedType)
 Check that all annotations of type spanType span annotations of type spannedType and that all annotations of type spannedType are spanned by annotations of type spanType.

Detailed Description

AGAPI interface.

This is a description of AGAPI. 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 AGAPI.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> AGAPI::<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: 

     sequence<AnnotationId>
 AGAPI::GetIncomingAnnotationSet(
         AnchorId anchorId,
         AnnotationType type=""
 )

    Function GetIncomingAnnotationSet returns a sequence(list) of AnnotationIds. It takes an AnchorId as an argument. AnnotationType can be given optionally. If it is not given, default value for type is an empty string, which mean no type is given.

    Author:
    Steven Bird, Xiaoyi Ma, Haejoong Lee (LDC)
    Version:
    2.0 @updated 2003-02-01

    Member Function Documentation

    bool AGAPI::CheckAnchorOffsetBounded (  Id    agId,
    AnnotationType    type
    ) 
     

    Check that all anchors of annotations of a given type are bounded by anchors that have an offset, following paths of this type.

    Parameters:
    ag, an  annotation graph
    type, an  annotation type
    Returns:
    boolean indicating whether all anchors are bounded

    bool AGAPI::CheckAnchorOffsetTotal (  Id    agId,
    AnnotationType    type
    ) 
     

    Check that all anchors of annotations of a given type have an offset.

    Parameters:
    ag, an  annotation graph
    type, an  annotation type
    Returns:
    boolean indicating whether all anchors have an offset

    bool AGAPI::CheckCoextensive (  Id    agId,
    AnnotationType    type1,
    AnnotationType    type2
    ) 
     

    Check that all annotations of type type1 are coextensive with an annotation of type type2, and vice versa (an existence not uniqueness test).

    Parameters:
    ag, an  annotation graph
    type1, an  annotation type
    type2, an  annotation type
    Returns:
    boolean indicating whether the types are coextensive

    bool AGAPI::CheckConnected (  Id    agId,
    AnnotationType    type
    ) 
     

    Check that all annotations of a given type form a connected subgraph.

    Parameters:
    ag, an  annotation graph
    type, an  annotation type
    Returns:
    boolean indicating whether the set of annotations is connected

    bool AGAPI::CheckFeatureExists (  Id    agId,
    AnnotationType    type,
    FeatureName    featureName
    ) 
     

    Check that all annotations of a given type have the specified feature.

    Parameters:
    ag, an  annotation graph
    type, an  annotation type
    featureName, the  name of the feature
    Returns:
    boolean indicating whether all annotations have the feature

    bool AGAPI::CheckFeatureIsAnnotationId (  Id    agId,
    AnnotationType    type,
    FeatureName    featureName
    ) 
     

    Check that all annotations of a given type have the specified feature and that its value is a valid AnnotationId.

    Parameters:
    ag, an  annotation graph
    type, an  annotation type
    featureName, the  name of the feature
    Returns:
    boolean indicating whether all instances of the feature are AnnotationIds

    bool AGAPI::CheckLinear (  Id    agId,
    AnnotationType    type
    ) 
     

    Check that all annotations of a given type form a connected linear sequence.

    Parameters:
    ag, an  annotation graph
    type, an  annotation type
    Returns:
    boolean indicating whether the set of annotations is linear

    bool AGAPI::CheckSpan (  Id    agId,
    AnnotationType    spanType,
    AnnotationType    spannedType
    ) 
     

    Check that all annotations of type spanType span annotations of type spannedType and that all annotations of type spannedType are spanned by annotations of type spanType.

    Parameters:
    ag, an  annotation graph
    spanType, the  spanning type
    spanedType, the  spanned type
    Returns:
    boolean indicating whether the spanning relationship holds

    AnnotationId AGAPI::CopyAnnotation (  AnnotationId    annotationId ) 
     

    Clone an annotation.

    Make a copy of the specified annotation, assign the new annotation a new AnnotationId.

    Parameters:
    annotationId  the original annotation
    Returns:
    the AnnotationId of the clone

    AGId AGAPI::CreateAG (  Id    id,
    TimelineId    timelineId
    ) 
     

    Create a new AG and add it to the AGSet.

    Parameters:
    id  might be AGSetId or AGId. If id is an AGSetId, an AGId will be assigned to the new AG. If id is an AGId, it will try the given id first, if it's taken, assign a new AGId.
    timelineId  the id of the timeline with which the new AG will be associated.
    Returns:
    the AGId of the new AG.
    Exceptions:
    AGException  IF (the id given is invalid OR the timeline doesn't exist)

    AGId AGAPI::CreateAG (  Id    id ) 
     

    Create a new AG and add it to the AGSet.

    Parameters:
    id  might be AGSetId or AGId. If id is an AGSetId, an AGId will be assigned to the new AG. If id is an AGId, it will try the given id first, if it's taken, assign a new AGId.
    Returns:
    the AGId of the new AG.
    Exceptions:
    AGException  IF (the id given is invalid)

    AGSetId AGAPI::CreateAGSet (  AGSetId    agSetId ) 
     

    Create a new AGSet.

    Parameters:
    agSetId  the id of the new AGSet
    Returns:
    the AGSetId of the new AGSet.
    Exceptions:
    AGException  IF (the an AGSet with the same id already exists)

    AnchorId AGAPI::CreateAnchor (  Id    id ) 
     

    Create an anchor.

    Parameters:
    id  It might be AGId or AnchorId. If id is a AGId, an AnchorId will be assigned the new anchor. If id is a AnchorId, it will try the given id first, if it's taken, assign a new AnchorId.
    Returns:
    AnchorId of the new anchor.
    Exceptions:
    AGException  IF (the id given is invalid)

    AnchorId AGAPI::CreateAnchor (  Id    id,
    sequence< SignalId >    signalIds
    ) 
     

    Create an anchor with specified signals.

    Parameters:
    id  It might be AGId or AnchorId. If id is a AGId, an AnchorId will be assigned the new anchor. If id is a AnchorId, it will try the given id first, if it's taken, assign a new AnchorId.
    signalIds  A list of SignalIds.
    Returns:
    AnchorId of the new anchor.
    Exceptions:
    AGException  IF (the id given is invalid)

    AnchorId AGAPI::CreateAnchor (  Id    id,
    Offset    offset,
    Unit    unit,
    sequence< SignalId >    signalIds
    ) 
     

    Create an anchor with specified offset, unit and signals.

    Parameters:
    id  It might be AGId or AnchorId. If id is a AGId, an AnchorId will be assigned the new anchor. If id is a AnchorId, it will try the given id first, if it's taken, assign a new AnchorId.
    offset 
    unit 
    signalIds  A list of SignalIds.
    Returns:
    AnchorId of the new anchor.
    Exceptions:
    AGException  IF (the id given is invalid)

    AnnotationId AGAPI::CreateAnnotation (  Id    id,
    AnchorId    start,
    AnchorId    end,
    AnnotationType    annotationType
    ) 
     

    Create a new annotation.

    Parameters:
    id  might be AGId or AnnotationId. If id is an AGId, an AnnotationId will be assigned to the new annotation. If id is an AnnotationId, it will try the given id first, if it's taken, assign a new AnnotationId.
    Returns:
    the AnnotationId of the new annotation.
    Exceptions:
    AGException  IF (the id given is invalid)

    SignalId AGAPI::CreateSignal (  Id    id,
    URI    uri,
    MimeClass    mimeClass,
    MimeType    mimeType,
    Encoding    encoding,
    Unit    unit,
    Track    track
    ) 
     

    Create a new signal and add it to the timeline.

    Parameters:
    id  might be TimelineId or SignalId. If id is a TimelineId, an SignalId will be assigned to new Signal. If id is a SignalId, it will try the given id first, if it's taken, assign a new SignalId.
    Returns:
    SignalId of the new signal.
    Exceptions:
    AGException  IF (the id given is invalid)

    TimelineId AGAPI::CreateTimeline (  Id    id ) 
     

    Create a new timeline and add it to the AGSet.

    Parameters:
    id  might be AGSetId or TimelineId. If id is an AGSetId, a TimelineId will be assigned to the new timeline. If id is a TimelineId, it will try the given id first, if it's taken, assign a new TimelineId.
    Returns:
    TimelineId of the new timeline.
    Exceptions:
    AGException  IF (the id given is invalid)

    void AGAPI::DeleteAGSet (  AGSetId    agSetId ) 
     

    Delete an AGSet.

    Parameters:
    agSetId  the AGSet to be deleted
    Exceptions:
    AGException  IF (the AGSet does not exist)

    void AGAPI::DeleteFeature (  Id    id,
    FeatureName    featureName
    ) 
     

    Delete a feature.

    This is for both the features of an annotation, and for the metadata associated with AGSets, AGs, Timelines and Signals.

    Parameters:
    id  the Id of the entity whose feature will be deleted
    featureName  the name of the feature
    Note:
    id can be AGSetId, AGId, TimelineId, SignalId or AnnotationID. If the id is AGSetId, AGId, TimelineId or SignalId, delete the feature in its Metadata. If the id is an AnnotationId, delete the feature in the annotation.

    bool AGAPI::ExistsFeature (  Id    id,
    FeatureName    featureName
    ) 
     

    Test if a feature exists.

    This is for both the features of an annotation, and for the metadata associated with AGSets, AGs, Timelines and Signals.

    Parameters:
    id  the Id of the entity whose feature's existence will be tested
    featureName  the name of the feature
    Note:
    id can be AGSetId, AGId, TimelineId, SignalId or AnnotationID. If the id is AGSetId, AGId, TimelineId or SignalId, test the feature in its Metadata. If the id is an AnnotationId, test the feature in the annotation.

    AGId AGAPI::GetAGId (  Id    id ) 
     

    Get the AGId of the given id.

    Note:
    id may be AnnotationId or AnchorId.

    sequence<AGId> AGAPI::GetAGIds (  AGSetId    agsetId ) 
     

    Get all the Ids of AGs which belong to the specified AGSet.

    Parameters:
    agsetId  The AGSet.
    Returns:
    List of AGIds.

    AGSetId AGAPI::GetAGSetId (  Id    id ) 
     

    Get the AGSetId of the given id.

    Note:
    id may be AGId, AnnotationId, AnchorId, TimelineId, or SignalId.

    sequence<AnchorId> AGAPI::GetAnchorSet (  AGId    agId ) 
     

    Get all the anchors in an AG.

    Parameters:
    agId  The AG.
    Returns:
    List of AnchorIds.

    sequence<AnchorId> AGAPI::GetAnchorSetByOffset (  AGId    agId,
    Offset    offset,
    float    epsilon
    ) 
     

    Get all anchors which are anchored within specified distance of the given offset.

    Parameters:
    agId  The id of the AG within which to search qualified anchors.
    offset  The offset.
    epsilon  The distance.
    Returns:
    A list of all anchors which are in the specified AG and are anchored at the given offset.
    Note:
    An anchor a is returned if a belongs the AG AND a is anchored AND the offset of a >= offset-epsilon AND the offset of a <= offset+epsilon

    sequence<AnchorId> AGAPI::GetAnchorSetByOffset (  AGId    agId,
    Offset    offset
    ) 
     

    Get all anchors which are anchored at the given offset.

    Parameters:
    agId  The id of the AG within which to search qualified anchors.
    offset  The offset.
    Returns:
    A list of all anchors which are in the specified AG and are anchored at the given offset.
    Note:
    An anchor a is returned if a belongs the AG AND a is anchored AND the offset of a equals to offset.

    sequence<AnchorId> AGAPI::GetAnchorSetNearestOffset (  AGId    agId,
    Offset    offset
    ) 
     

    Get a list of all anchors which are anchored at the closest offset to the given offset.

    This function first finds the existing offset o which is nearest to the given offset, then returns all the anchors that anchor at offset o.

    AnnotationId AGAPI::GetAnnotationByOffset (  AGId    agId,
    Offset    offset,
    AnnotationType    type = ""
    ) 
     

    Get one of the annotations which overlap a particular time offset.

    Should be favored over GetAnnotationSetByOffset whenever possible. If type is given, only the annotations of the given type is considered in the computation.

    See also:
    GetAnnotationSetByOffset

    sequence<FeatureName> AGAPI::GetAnnotationFeatureNames (  Id    id,
    AnnotationType    type = ""
    ) 
     

    Get a list of feature names of all annotations in an AGSet, AG, or Annotation.

    If type is given, annotations of other types than the given type are filtered out in the return value.

    string AGAPI::GetAnnotationInfo (  AnnoationId    annotationId ) 
     

    Get all the information of the specified annotation.

    Returns:
    a string containing annotation type, start anchor offset, end anchor offset, start anchor id, end anchor id and all features in DCSV format.
    Note:
    see http://dublincore.org/documents/2000/07/28/dcmi-dcsv/ for details about DCSV format.

    sequence<AnnotationId> AGAPI::GetAnnotationSeqByOffset (  AGId    agId,
    Offset    begin = 0.0,
    Offset    end = 0.0,
    AnnotationType    type = ""
    ) 
     

    Get an ordered list of AnnotationIds within the given interval.

    If none of begin and end are given (if begin=end=0.0), get a list of all annotations of the given type.

    If only begin is given (if begin!=0.0 and end=0.0), get a list of all the annotations with start offset are greater than or equal to specified offset, sort by using start anchor offset as first sorting key and end anchor offset as the second.

    If both begin and end are given (if begin!=0.0 and end!=0.0), get a list of all the annotations with start anchor offset in between the specified offsets, sort by using start anchor offset as first sorting key and end anchor offset as the second.

    If type is given, only the annotations of the given type are included in the computation.

    sequence<AnnotationId> AGAPI::GetAnnotationSet (  AGId    agId,
    AnnotationType    type = ""
    ) 
     

    Get a list of all annotation ids in the given annotation graph.

    If the annotation type is given, only the ids of annotations of the type will be returned.

    Note:
    Nothing should be assumed about the order of the returned ids. To retrieve all the annotations in the order of there start offsets, use GetAnnotationSeqByOffset.

    sequence<AnnotationId> AGAPI::GetAnnotationSetByFeature (  AGId    agId,
    FeatureName    featureName,
    FeatureValue    featureValue,
    AnnotationType    type = ""
    ) 
     

    Get a list of all annotations whose specified feature equals to the specified value.

    If type is given, only the annotations of the given type are considered in the computation.

    sequence<AnnotationId> AGAPI::GetAnnotationSetByOffset (  AGId    agId,
    Offset    offset,
    AnnotationType    type = ""
    ) 
     

    Get a list of all annotations which hangs over a given offset.

    Return all annotations whose start offset is smaller than or equal to the given offset AND whose end offset is greater than or equal to the given offset.

    If type is given, only the annotaions of the given type are concidered in the computation.

    string AGAPI::GetFeature (  Id    id,
    FeatureName    featureName
    ) 
     

    Get the value of a feature.

    This is for both the features of an annotation, and for the metadata associated with AGSets, AGs, Timelines and Signals.

    Parameters:
    id  the Id of the entity whose feature value will be returned
    featureName  the name of the feature
    Note:
    id can be AGSetId, AGId, TimelineId, SignalId or AnnotationID. If the id is AGSetId, AGId, TimelineId or SignalId, get the value of the feature in its Metadata. If the id is an AnnotationId, get the value the feature in the annotation.

    sequence<FeatureName> AGAPI::GetFeatureNames (  Id    id ) 
     

    Get all feature names in a list.

    This is for both the features of an annotation, and for the metadata associated with AGSets, AGs, Timelines and Signals.

    Parameters:
    id  The Id of the entity whose feature names will be returned.
    featureName  The name of the feature.
    Returns:
    A list of FeatureNames.
    Note:
    id can be AGSetId, AGId, TimelineId, SignalId or AnnotationID. If the id is AGSetId, AGId, TimelineId or SignalId, return the feature names in its Metadata. If the id is an AnnotationId, return the feature names in the annotation.

    hash<FeatureName,FeatureValue> AGAPI::GetFeatures (  Id    id ) 
     

    Get all features and values in a hash table.

    Parameters:
    id  The Id of the entity whose feature names will be returned.
    Returns:
    A hash table of feature-value pairs.
    Note:
    id can be AGSetId, AGId, TimelineId, SignalId or AnnotationID. If the id is AGSetId, AGId, TimelineId or SignalId, return the feature names and values in its Metadata. If the id is an AnnotationId, return the feature names and values in the annotation.

    sequence<AnnotationId> AGAPI::GetIncomingAnnotationSet (  AnchorId    anchorId,
    AnnotationType    type = ""
    ) 
     

    Get the incoming annotations of an anchor.

    If type is given, annotations of other types than the given type are filtered out in the return value.

    sequence<AnnotationId> AGAPI::GetOutgoingAnnotationSet (  AnchorId    anchorId,
    AnnotationType    type = ""
    ) 
     

    Get the outgoing annotations of an anchor.

    If type is given, annotations of other types than the given type are filtered out in the return value.

    sequence<SignalId> AGAPI::GetSignals (  TimelineId    timelineId ) 
     

    Get a list of all the Ids of sigals which belong to the specified timeline.

    Parameters:
    timelineId  The id of the timeline.
    Returns:
    A list of SignalIds.

    TimelineId AGAPI::GetTimelineId (  Id    id ) 
     

    Get the TimelineId of the given id.

    Note:
    id may be AGId or SignalId.

    sequence<AGId> AGAPI::Load (  string    format,
    string    filename,
    Id    id = "",
    hash< string, string >    signalInfo = NULL,
    hsah< string, string >    options = NULL
    ) 
     

    Load an annotation file.

    Parameters:
    format  Annotation file format. Possible formats are: AG, TIMIT, BU, TreeBank, SwitchBoard, BAS, TF, LCF, XLabel, ATLAS and CAG.
    filename  The name of the annotation file to load.
    id  The id of the ag/agset where the file will be loaded.
    signalInfo  A feature-value pair list for the signal information. Features that should be used are:
    • uri
    • mimeClass
    • mimeType
    • encoding
    • unit
    • track (optional)
    The values shouldn't be empty.
    options  A hash table of option-value pairs for format specific options.
    Returns:
    A list of AGIds loaded.

    bool AGAPI::LoadFromDB (  string    connStr,
    AGSetId    agsetId
    ) 
     

    LoadFromDB loads the specified AGSet from the database server.

    Parameters:
    connStr  the connect string, which specifies the connection string that ODBC uses to connect to the server. It contains information such as hostname, database name, user name, password etc.
    The following table shows some of the parameters used in a connect string. For a complete list, see http://www.mysql.com/doc/M/y/MyODBC_connect_parameters.html

    ODBC connect string argumentsWhat the argument specifies
    DSNRegistered ODBC Data Source Name.
    SERVERThe hostname of the database server.
    UIDUser name as established on the server.
    PWDPassword that corresponds with the logon name.
    DATABASEDatabase to connect to. If not given, DSN is used.

    DSN is the registered ODBC Data Source Name, it should be defined in the .odbc.ini file in your home directory. All other arguments can be either defined in the .odbc.ini file, or defined in the connect string itself.

    To gain access to most ODBC data sources, you must provide a valid user ID and corresponding password. These values are initially registered by the database administrator.

    Probably the easiest way is to define every argument in the .odbc.ini file in your home directory. The following is a sample driver section for DSN 'talkbank' in the configuration file for iODBC. To make the explanation easier, line numbers are included. Please notice that UID and PWD become USER and PASSWORD, respectively, in iODBC's configuration file. 

     1  [talkbank]
 2  Driver   = /pkg/ldc/lib/libmyodbc.so
 3  DSN      = talkbank
 4  SERVER   = talkbank.ldc.upenn.edu
 5  USER     = myuserid
 6  PASSWORD = mypasswd
 7  DATABASE = talkbank

    Line 1 is the name of the driver section, which is 'talkbank'. You can have multiple driver sections in one configuration file. Line 2 specifies the ODBC driver to use. Line 3 gives the name of the DSN, which is 'talkbank'. Line 4 specifies the hostname of the machine on which the database server is running. Line 5 is the user name to use to connect to the server. Line 6 is the password associated with the user name. Line 7 is the database to connect to.

    If you have all required arguments specified in your .odbc.ini file like the one above, the connect string can simply be:

    DSN=talkbank;

    If you have not specified some of the arguments, say USER and PASSWORD, in the configuration file, you can still specify them in your connect string:

    DSN=talkbank;UID=myuserid;PWD=mypasswd;

    sequence<AnnotationId> AGAPI::NSplitAnnotation (  AnnotationId    annotationId,
    short    N
    ) 
     

    Split an annotation to n annotations.

    A version of split which does the split operation n-1 times, i.e. split the original annotation into n annotations.

    Parameters:
    annotationId  The annotation to be split.
    N  An integer specifying the number of annotations to split into.
    Returns:
    The set of new annotations, including the original one.
    See also:
    SplitAnnotation

    void AGAPI::SetFeature (  Id    id,
    FeatureName    featureName,
    FeatureValue    featureValue
    ) 
     

    Set the value of a feature.

    This is for both the features of an annotation, and for the metadata associated with AGSets, AGs, Timelines and Signals.

    Parameters:
    id  the Id of the entity whose feature will be set
    featureName  the name of the feature
    featureValue  the value of the feature
    Note:
    id can be AGSetId, AGId, TimelineId, SignalId or AnnotationID. If the id is AGSetId, AGId, TimelineId or SignalId, the feature in its Metadata will be set. If the id is an AnnotationId, the feature in the annotation will be set.

    void AGAPI::SetFeatures (  Id    id,
    hash< FeatureName, FeatureValue >    features
    ) 
     

    Set multiple features in a hash table.

    Parameters:
    id  The Id of the entity whose feature names will be returned.
    features  A hash table of feature-value pairs.
    Note:
    id can be AGSetId, AGId, TimelineId, SignalId or AnnotationID. If the id is AGSetId, AGId, TimelineId or SignalId, set the feature values names in its Metadata. If the id is an AnnotationId, return the feature values names in the annotation.

    AnchorId AGAPI::SplitAnchor (  AnchorId    anchorId ) 
     

    Split an anchor in two.

    Split an anchor a in two, creating a new anchor a' having the same offset as the original one. Anchor a has all the incoming annotations, while anchor a' has all the outgoing annotations.

    Returns:
    the id of the new anchor a'.

    sequence<AnnotationId> AGAPI::SplitAnnotation (  AnnotationId    annotationId ) 
     

    Split an annotation in two.

    Split an annotation a in two, creating a new annotation a' having the same label data as the original one. The two annotations a, a' connect head-to-tail at a new anchor. The new annotation and anchor have identifiers assign from the specified identifier spaces. The new anchor is unanchored, i.e. has no offset.

    Parameters:
    annotationId  The annotation to be split.
    Returns:
    A list of the AnnotationIds of the a and a'.

    void AGAPI::Store (  string    format,
    string    filename,
    Id    id,
    hash< string, string >    options = NULL
    ) 
     

    Store an annotation graph in a given format.

    Parameters:
    format  Annotation file format. Possible formats are: AG, TreeBank, SwitchBoard, TF, LCF, CAG and ATLAS.
    filename  The name of the file to be stored.
    id  The id of ag/agset to be stored.
    options  A hash table of option-value pairs for format specific options.

    void AGAPI::Store2 (  string    format,
    string    filename,
    sequence< Id >    ids,
    hash< string, string >    options = NULL
    ) 
     

    Store annotation graphs in a given format.

    Parameters:
    format  Annotation file format. Possible formats are: AG, TreeBank, SwitchBoard, TF, LCF, CAG and ATLAS.
    filename  The name of the file to be stored.
    ids  A list of ids of ag/agset to be stored.
    options  A hash table of feature-value pairs for format specific options.

    bool AGAPI::StoreToDB (  string connStr AGSetId    agsetId ) 
     

    StoreToDB stores the specified AGSet to the database server.

    Parameters:
    connStr  the connect string, which specifies the connection string that ODBC uses to connect to the server. It contains information such as hostname, database name, user name, password etc.
    The following table shows some of the parameters used in a connect string. For a complete list, see http://www.mysql.com/doc/M/y/MyODBC_connect_parameters.html

    ODBC connect string argumentsWhat the argument specifies
    DSNRegistered ODBC Data Source Name.
    SERVERThe hostname of the database server.
    UIDUser name as established on the server.
    PWDPassword that corresponds with the logon name.
    DATABASEDatabase to connect to. If not given, DSN is used.

    DSN is the registered ODBC Data Source Name, it should be defined in the .odbc.ini file in your home directory. All other arguments can be either defined in the .odbc.ini file, or defined in the connect string itself.

    To gain access to most ODBC data sources, you must provide a valid user ID and corresponding password. These values are initially registered by the database administrator.

    Probably the easiest way is to define every argument in the .odbc.ini file in your home directory. The following is a sample driver section for DSN 'talkbank' in the configuration file for iODBC. To make the explanation easier, line numbers are included. Please notice that UID and PWD become USER and PASSWORD, respectively, in iODBC's configuration file. 

     1  [talkbank]
 2  Driver   = /pkg/ldc/lib/libmyodbc.so
 3  DSN      = talkbank
 4  SERVER   = talkbank.ldc.upenn.edu
 5  USER     = myuserid
 6  PASSWORD = mypasswd
 7  DATABASE = talkbank

    Line 1 is the name of the driver section, which is 'talkbank'. You can have multiple driver sections in one configuration file. Line 2 specifies the ODBC driver to use. Line 3 gives the name of the DSN, which is 'talkbank'. Line 4 specifies the hostname of the machine on which the database server is running. Line 5 is the user name to use to connect to the server. Line 6 is the password associated with the user name. Line 7 is the database to connect to.

    If you have all required arguments specified in your .odbc.ini file like the one above, the connect string can simply be:

    DSN=talkbank;

    If you have not specified some of the arguments, say USER and PASSWORD, in the configuration file, you can still specify them in your connect string:

    DSN=talkbank;UID=myuserid;PWD=mypasswd;

    void AGAPI::UnsetAnchorOffset (  AnchorId    anchorId ) 
     

    Unset the offset of an anchor.

    The anchor becomes unanchored after being unset.

    void AGAPI::UnsetFeature (  Id    id,
    FeatureName    featureName
    ) 
     

    Unset a feature.

    Set the feature to empty. This is for both the features of an annotation, and for the metadata associated with AGSets, AGs, Timelines and Signals.

    Parameters:
    id  the Id of the entity whose feature will be unset
    featureName  the name of the feature
    Note:
    id can be AGSetId, AGId, TimelineId, SignalId or AnnotationID. If the id is AGSetId, AGId, TimelineId or SignalId, unset the feature in its Metadata. If the id is an AnnotationId, unset the feature in the annotation.

    void AGAPI::UnsetFeatures (  Id    id ) 
     

    Unset all features Set all features to empty. This is for both the features of an annotation, and for the metadata associated with AGSets, AGs, Timelines and Signals.

    Parameters:
    id  the Id of the entity whose feature will be unset
    featureName  the name of the feature
    Note:
    id can be AGSetId, AGId, TimelineId, SignalId or AnnotationID. If the id is AGSetId, AGId, TimelineId or SignalId, unset all features in its Metadata. If the id is an AnnotationId, unset all features in the annotation.