This release contains some important changes in the main API. In particular, the first two changes described below will require modifications to applications which are based on earlier versions of AGLIB (version 1.*). These changes are the result of input from developers, and we feel that such changes are necessary. The two essential changes are 1) the list return types, and 2) the optional type arguments.
In addition, this release contains some new additions to the features of AGLIB, which we hope developers find useful.
New functions:
Obsolete functions:
The Store2 function has been added. In contrast to the Store function which accepts only one AG or AGSet id, Store2 accepts a list of AG or AGSet ids to be stored, giving more options to the implementation of file I/O modules.
The GetAnnotationSet function has been added and the GetAnnotationSetByType function has been incorporated into it, by virtue of the optional type argument of the GetAnnotationSet function.
Because of the optional type arguments of the GetIncomingAnnotationSet and GetOutgoingAnnotationSet, the GetIncomingAnnotationSetByType and GetOutgoingAnnotationSetByType were no longer needed and have been dropped.
The load and store functions were aliases to Load and Store. They are no longer supported.
The first of the important API level changes is the list return types: functions that used to return a space-separated string of items now return a true list. This means that the applications written for previous releases of AGLIB will need to be modified slightly in order to use AGLIB version 2.0 and later.
Here is the list of functions that are affected:
The following functions have been modified to accept a list of SignalIds.
Additionally, the following functions are modified to accept and return a hash table of feature-value pairs.
An optional argument for annotation type is added to some functions. This optional type argument is used to restrict the operation to the annotations of a specified type. This makes it easy for an application to ignore the existence of annotations it doesn't care about (e.g. annotations created by some other application). Affected functions are:
The naming scheme for the AG object IDs that are automatically generated by AGLIB has changed in version 2. AGLIB can still read old AG (AIF-Level0) xml files and use the IDs stored in those files; also, applications can use their own ID assignment schemes.
The prefixes AG, Annotation, Anchor, Timeline and Signal have been replaced with simpler strings or empty strings. For example, Timeline becomes T, and Annotation becomes E. The rest are replaced with empty strings. The numbering scheme is also changed to use base-60 numbers. The digits come from [0-9A-DF-SU-Za-z]. Note that E and T are reserved for Annotation and Timeline IDs. Here are some examples:
TIMIT:AG6:Annotation115 ---> TIMIT:6:E1v
TIMIT:AG23:Anchor87 ---> TIMIT:N:1R
TIMIT:Timeline1:Signal2 ---> TIMIT:T1:2
It is still possible for users to specify custom IDs when creating the objects, e.g. CreateAG("TIMIT:Timeline1"), CreateAnchor("TIMIT:Timeline1:Signal1"), etc.
These changes will reduce the size of the AG (AIF-Level0) format files, and memory usage of the kernel. The changes don't imply modifications of applications, since applications are not supposed to manipulate IDs directly.
A file I/O plugin architecture has been introduced in AGLIB 2.0. The basic idea is to make a seperate module (or plugin) for each file format that can be dynamically loaded at runtime. The plugins are kept in the file system, and loaded into the memory only when they are needed. The new lightweight libag, without the file I/O modules that were previously built into it, can save loading time and memory.
Another important benefit of the architecture is that it decentralizes the file I/O development and reduces engineering efforts required to add a new format support. The old development model was something like this: develop a file I/O module; adding the module by editing several other AGLIB modules, Makefiles and possibly configuration scripts; make a patch and report this to the central development site (http://agtk.sf.net); an AGTK developer reviews the patch and incorporates it into a new release of AGLIB. With the new architecture, you just follow the file I/O plugin framework to develop your plugin. It doesn't involve any modification of AGLIB sources at all. You can post your plugin on your web site so that people can download and use it. We hope this encourages wider participation in the development of AGLIB I/O modules.
The ATLAS (AIF level 1) format has been added the supported file format list. Since the ATLAS data model is a superset of the annotation graph model, there are some restrictions on data which the ATLAS format plugin can deal with. As long as the data is for a linear signal and the annotations are fielded records, everything should work fine.
The CAG (Compact Annotation Graph) format has been added to the supported file format list. CAG is a compact table representation of the annotation graph data model. It's a significant space saver for a project that has to deal with a large quantity of data.
A Java AG wrapper has been added. (This is in addition to the Java support already provided with the Java port of AGLIB.) The Java AG wrapper is a Java version of AGAPI, which is a collection of C++ functions that wrap the C++ core of AGLIB. The AGLIB Java port rewrites the C++ core in Java. The difference is the programming interface: Java AG wrapper exports the flat AGAPI, while the AGLIB Java port takes an object oriented approach.