FunctionQuery usage

FunctionQuery is a utility for outputting tab-delimited data. It takes all elements resulting from the result of a query, as long as they are timed, and puts them in order of start time. Then it outputs, one line per element, the values of a the named attributes or aggregates with a tab character between each attribute. The attributes can be qualified with a variable specifier (e.g. $v@attribute). If the variable specifier is omitted, the attribute belonging to the first variable in the query (the "primary variable") is returned.

FunctionQuery is designed to answer queries of the form: For each result give me this list of values. A list of examples can be found on the NXT Sample Queries page.

To call the utility, which is in the gdf2nxt subdirectory of the JCT software distribution, first ensure that the classpath has been set:

export NXT="/group/ltg/projects/NITE/nxt"
export CLASSPATH=".:$NXT:$NXT/lib:$NXT/lib/nxt.jar:$NXT/lib/jdom.jar:$NXT/lib/JMF/lib/jmf.jar"
export CLASSPATH=$CLASSPATH":$NXT/lib/pnuts.jar:$NXT/lib/resolver.jar:$NXT/lib/xalan.jar"
export CLASSPATH=$CLASSPATH":$NXT/lib/xercesImpl.jar:$NXT/lib/xml-apis.jar:$NXT/lib/jmanual.jar"
export CLASSPATH=$CLASSPATH":$NXT/lib/jh.jar:$NXT/lib/helpset.jar:$NXT/lib/poi.jar" 

replacing the directories in the commands above as appropriate. Then call FunctionQuery as follows:

java FunctionQuery -c metadata_file_name -ob observation_name -q query -atts [attname+]

-corpus is required; it is the path to the metadata file.

-observation is optional: it's the name of the observation. If not present the program cycles through all observations.

-query is required; the first matched variable from every result forms the basis of the output.

-atts is required; input is expected as a space separated list of attributes or aggregates. Note that if the attribute does not exist for some matched elements, a blank tab-stop will be the output. Attributes are generally of the form: $v@attribute. If $v is omitted, the attribute is taken from the primary variable. If the attribute is omitted, the textual content of $v and its children are returned.

N.B. The FunctionQuery program must be able to find the codings xml files in the location specified in the codings section of the metadata file. If the locations are specified as relative paths, then FunctionQuery should be run from a directory such that the relative paths are correct.

Aggregate functions are identified by a leading '@' character. There are currently 4 aggregate functions included in FunctionQuery, described below. The first argument to a function is always a subquery to be evaluated in the context of the current result.

Aggregate Functions:

For the following functions, optional arguments are denoted by an equals sign followed by the default value of that argument. The context query that is the first argument of each of these functions should be of the form:

($v var):$v test $q && other tests

So that the results of this query are filtered with respect to the main query (represented here by the $q variable). For example $v # $q will return all results that overlap the main query result, whilst $q ^ $v will return all descendants of the current query result.

 

@count(conquery)

returns the number of results from evaluating conquery in the context of the current result of query.

@sum(conquery, attr)

returns the sum of the values of attr for all results of conquery evaluated in the context of query. attr should be a numerical attribute.

@extract(conquery, attr, n=0, last=n+1)

returns the attr attribute of the nth result of conquery evaluated in the context of query. If n is less than 0, extract returns the attr attribute of the nth last result. If last is provided, the attr value of all results whose index is at least n and less than last is returned. If last is less than 0, it will count back from the final result. If last equals zero, all items between n and the end of the result list will be returned.

@overlapduration(conquery)

returns the length of time that the results of conquery overlap with the results of the main query. For some conquery results, this number may exceed the duration of the main query result. For example, the duration of speech for all participants over a period of time may exceed the duration of the time segment where there a multiple simultaneous speakers. This can be avoided, for example, by restricting the conquery to a specific agent.

Example:

  java FunctionQuery -c METADATA -ob OBS -q '($m move)' -atts type nite:start nite:end '@count(($w w):$w#$m)' '$m'

will output a sorted list of moves for the observation consisting of type attribute, start and end times, the count of w (words) that overlap each move, and any text included in the move, or any children.

FunctionQuery is designed to be backwards-compatible with SortedOutput.

(note: can use complex query in FunctionQuery to test output but only simple -atts extracting data from the primary clause will work.)