man.diff

speech signal process tools

.fi

Here, <field_name> is a FEA record field name, <index> is an integer
value indicating an offset from the beginning of the field (used if
the field is not a scaler), 
<value> is a numerical value, 
<character_string> is a character string in quotes ("),
<function> is the name of a built in function (see FUNCTIONS),
<rel_op> is a relational operator, and <arith_op> is a
arithmetic operator (defined below).
<external_function> is the name of an external program that is called to
implement some function on each record.  This is described in detail
below.
The "{}" brackets indicate
that the inclusion of field index is optional. 
If <field_name> is not a scaler field, <field_name> is equivalent to
<field_name>[0] when used in an expression.   
An <external_function> is always preceded by a dollar sign ($).
.PP
If a <field_name> is used in an expression which is not defined in the
current input file, then a warning is printed (once for each file) and
zero is used as its value.   This is not a fatal error, because
there might be several input files open that do not have all of the same
fields.
.PP
The permitted relational are:
.sp
.TS
center,box,tab(;);
c s
l l.
<rel_op>
=
==;equals
\&=;equals
!=;not equals
>;greater than
>=;greater than or equal to
<;less than
<=;less than or equal to
&&;and
&;and
||;or	    
|;or
.TE
.PP
The && has precedence over the || ; & and | are
treated as synonyms for && and ||.   There are no bitwise logical
operations.
.PP
The permitted arithmetic operators are:
.sp
.TS
center,box,tab(;);
c s
l l.
<arith_op>
=
+;addition
\-;subtraction
*;multiplication
/;division
^;exponentiation
.TE
.PP
The ^ operator has the highest precedence and is right associative.  The
/ and * operators have the next highest precedence and are left
associative.  The + and \- operators have the lowest precedence and are
also left associative.
.PP
If <value> is a numerical value (appropriate if the type of the field
is a numerical type), it should be given in a corresponding format
for C constants.  If the field type is coded, then <value> should be
a quoted string (upper or lower case) that is one of the legal values.
.PP
In the case of coded field types, the default behavior is for the comparison
to be case insensitive.  Comparisons can be made case sensitive by using
the \fB-c\fR option on the command line.
.SH FUNCTIONS
.PP
There are three types of functions supported by \fIselect\fR.
One type of function takes as its domain a numerical value, which can be
given as any expression that \fIselect\fR can process.   Another type of
function operates on a <field_name>.  The third type of function is the
<external_function>.  This form of function results in an external
program being called to perform some function on each record.
This provides a very general capability, but since the external program
will be called for each record processed it is much slower than built in
functions.
.PP
The available built in function are:
.sp
.TS
center,box,tab(;);
c s
l l.
Functions on Expressions
=
abs;absolute value
atan;arc tangent
cos;cosine
exp;exponent
int;integer
log;natural log
log10;log base 10
sin;sine
sqrt;square root
tan;tangent
.TE
.sp
.TS
center,box, tab(;);
c s
l l.
Functions on Fields
=
max;maximum of elements in field
mean;mean of elements in field
min;minimum of elements in field
prod;product of elements in field
size;number of elements in field
sum;sum elements in field
.TE
.PP
The only legal argument for functions on fields is a single
<field_name> without an index.  In this case, the <field_name> refers to
the entire field.
.PP
If <external_function> is found in an expression
.I select
searches the users current PATH for a program with the specified
name.  This program is assumed to accept a single-record ESPS FEA file
as its only argument and to output a value (ASCII) on standard output.  
.I Select
creates a single-record ESPS file from each record in the input files 
and calls <external_function> with this file; the
output of <external_function> is then used within the query.  
An example of the source code for an external function can be found
in the \fIselect\fR source directory, or in /usr/sps/lib on a non-source
system.
.PP
There are several built in field names that have special meaning.  The
are:
.sp
.TS
center,box, tab(;);
c s
l l.
Built in Field Names
=
tag;built in tag field of the record
REC;record number (from 1)
FILE;file name of the input file within the set of input files
.TE
The field name "tag" always refers to the built in tag field of the
record.  (See the discussion of tags and segment labelling under
DESCRIPTION.)
The name "REC" refers to the record number (from 1) of the
record in the set of input files and
the name "FILE" refers to the filename of the input file in the
set of input files.
.SH "EXPRESSION ERRORS"
.PP
There are three types of expression errors.  
.PP
The first type are syntax
errors caught by the parser.   These result result in a "syntax error"
message followed by the offending character.   In the current release,
the query is usually executed anyway.   If the selected records are not
wanted, they can be removed from the buffer with the \fBUNDO\fR command.
If the select is long (because the input file is large) then the select
can be interrupted and then undone.   This will be improved in a future
release.
.PP
The other type of expression errors relate to the execution of the
expression itself.  These include use of undefined fields, undefined
functions, field indexes out of bounds, arithmetic overflow and
underflow, and divide by zero.   Errors that cannot change from one
record or one input file to the next are considered fatal and terminate
the \fBSELECT\fR (or \fBEVAL\fR or \fBSHOW SELECT\fR).  This type of
error is caused by trying to call an undefined built in function or
trouble running an external function.
.PP
The other errors described above cause the termination of the
expression for the current record.  In most cases the expression
evaluates to zero.  In the case of undefined field and index out of
bounds, zero is returned and the expression continues.   In the case of
arithmetic problems, the expression is terminated and zero is returned
for the expression.  The reason that these errors are not fatal is that
several input files might be open and they do not have to all have the
same fields.   A field might not be defined for one file of the input
set, but might be defined for others.  Therefore, the query should be
allowed to process.   A message is printed, once for each file, in the
case of these errors.   The query can be interrupted if the desired
results will not be achieved.
.PP
In all cases a message is printed stating what action is being taken
when errors are found.
.SH "ESPS PARAMETERS"
.PP
The ESPS parameter file is not read by 
.I select.  
.SH "ESPS COMMON"
.PP
ESPS Common file is not read or written by 
.I select.
.SH ESPS HEADERS
.PP
.I Select
reads the 
.I common.type
field from the header of 
.I input
(to make sure that it is of type FEA), and it reads the
field-defining information as well.  
If output files do not exist, their headers are created with 
.I copy_header
(3\-ESPS).  
Unless the \fB\-n\fP option is used, the headers of output files are expanded
to include the the input files as sources and the selection queries as 
comments in the \fIvariable.comment\fP field.  
.SH ENVIRONMENT
.PP
The
.B PAGER
environment variable determines what paging program is used to break up
large displays of text. By default, the
.I more
program is used (however, this may be changed by the installer).
To use a different pager (or if your system doesn't have
.IR more ),
set this environment variable to some other value.  A full pathname is not
required.  If you don't like paging, try setting
.B PAGER
to
.IR cat .
.SH EXAMPLES
.PP
.nf
\fIThis command gathers all voiced from the input files into allvoiced.fea\fR
select -q 'frame_type == "VOICED"' -o allvoiced.fea *.fana

\fIThis command applies a command file of queries on file1 with output to file2\fR
select -o file2 file1 < commands

Examples of queries:
	
select pulse_len = 90 & frame_type = "VOICED"
  \fIframe_type is a CODED type\fR
	
select (a = 3 & FILE = "f1") | (b = 4 & FILE = "f2")
  \fIthis means to select records with a = 3 from input file
  f1 and b = 4 from input file f2; assuming that there
  are at least two input files\fR

select sqrt(gamma)/4 > alpha[3]
  \fIIf gamma is a field of size one, then its value is used by the sqrt
  function.   If gamma is a field of greater than size one, then the
  element is used (same as saying gamma[0]).\fR

select sum(gamma) > mean(beta)
  \fIThese functions operate on entire fields, so the fieldname here 
  without the index does not refer to only the first element; it refers
  to the entire field.\fR

select sum(gamma) > mean(beta) && ($func1 > 45.6)
  \fIsum and mean are functions of fields.  $func1 is a user supplied
  external program which is called for each record.
.fi
.SH "SEE ALSO"
.PP
ESPS(5-ESPS), FEA(5\-ESPS)
.SH "FUTURE CHANGES"
.PP
Provide a method to link in user-defined functions to provide higher
performance than external functions.
.SH "WARNINGS"
.PP
A number of warning and error message are printed in the event of
various expression errors.  Some errors terminate the query.
.SH "BUGS"
.PP
The following paragraph describes the way \fIselect\fR will handle
existing output files and input files with tags:
.PP
If the output file exists and is segment labelled, and if there
is one or more tagged input file, all tagged records written to the output
file are converted to segment labelled.  If the output file exists and is
tagged, and if there is one or more tagged input file, the output file is
converted from tagged to segment labelled, and all tagged records written
to the output file are converted to segment labelled.  
.PP
This is not done in this version.   The pre-existing output file is not
changed, and the tag values copied into it may be meaningless (because
the \fIrefer\fR file might be different.
.PP
A syntax error in a query will terminate the parse of the query and
it will then run.   After it runs you will get a syntax error message.
If the select, selected records that you don't want, use the "undo"
command to undo the effect of the most recent select operation.  Undo
can only be used once after each select.  You can't undo an undo
(except to select again).
.PP
If referenced fieldname is a complex feature field, then the real part
of that is used in the expression.   Better support for complex types
will be added in the next version.
.SH "AUTHOR"
.PP
Manual page by John Shore and Alan Parker
.br
Program by Alan Parker