classify.1

speech signal process tools

.\" @(#)classify.1	1.1 (EPI) 6/5/87
.TH CLASSIFY 1\-ESPS 6/5/87
.ds ]W "\fI\s+4\ze\h'0.05'e\s-4\v'-0.4m'\fP\(*p\v'0.4m'\ Entropic Speech, Inc.
.SH NAME
classify \- maximum-likelihood classification of feature records
.SH SYNOPSIS
.B classify
[
.BI \-x " debug_level"
] [
.BI \-f " field"
] [
.BI \-e " elements"
] [
.BI \-d
] [
.BI \-C " field"
] [
.BI \-L " field"
]
.br
[
.BI \-h " file.his"
]
.I " input.stat"
.I " input.fea"
.I " output.fea"
.SH DESCRIPTION
.PP
.I Classify
takes as inputs an ESPS feature file of any subtype
and an ESPS statistics (FEA_STAT(5\-ESPS)) file
containing mean vectors and inverse covariance matrices.
It writes an output feature file of the same subtype as the input
feature file.
If ``\-'' is given for
.I input.fea,
the standard input is used.
If ``\-'' is given for
.I input.stat,
the standard input is used,
but the input files must not both be the standard input.
If ``\-'' is given for
.I output.fea,
the standard output is used.
.PP
.I Classify
classifies each record of the input feature file into one of several
classes on the basis of information in the statistics file.
The possible classes are those named in the
.I class
field in the records in the statistics file.
Since that is a coded field, the class names actually refer to
strings in the
.I enums
array for the field
.I class
in the statistics-file header,
but there need not be a statistics record for every such string.
There must not be more than one record for any one class.
.PP
Classification is by maximum likelihood.
To classify a record, the program computes a likelihood for each
class by a method to be described.
The record is assigned to the class for which the likelihood is greatest.
.PP
The output file is a copy of the input feature file
with two additional fields in each record.
One is a coded field
that identifies the class to which the record is assigned.
The other is a vector field that contains the likelihoods.
These occur in the same order as the corresponding class names in the
.I enums
array for the new coded field.
The likelihoods are normalized so that their sum is 1 for each record;
they may thus be viewed as posterior class probabilities for a prior
distribution that (at present) is implicitly taken to be uniform.
.PP
To compute the likelihood,
given a feature record and a statistics record,
.I classify
first assembles a vector consisting of values of certain elements of
fields in the feature record.
The length of this ``feature vector'' must match the generic header item
.I statsize
in the statistics-file header.
The inverse covariance matrix and the mean vector in the statistics record
define a multivariate Gaussian probability density;
the desired likelihood is the value of the density
at the point given by the feature vector.
.PP
In the simplest case, the elements of the feature vector
are simply all the elements of the field named by the generic header item
.I statfield
in the statistics-file header;
however, the field name may be overridden by the
.B \-f
option, and a subset of the elements may be selected by the
.B \-e
option.
.PP
If
.I statfield
does not name a field in the input feature file,
and neither
.B \-f
nor
.B \-e
is selected,
then the elements of the feature vector are chosen
with the help of the derived-field mechanism explained in FEA(5\-ESPS).
In that case
.I statfield
must name a field that is flagged as
.I derived
in the reference header of the statistics-file header,
and the field elements specified in the corresponding
.I srcfields
entry must exist in the input feature file;
those field elements then become the elements of the feature vector.
The
.B \-d
option forces use of the derived-field mechanism even when the
contents of
.I statfield
coincide with the name of a field in the input statistics file.
.SH "ESPS PARAMETERS"
.PP
This program does not read the parameter file or the common file.
.SH "ESPS HEADERS"
.PP
The output header is an altered copy of the input feature-file header
made with
.IR copy_header (3\-ESPS).
New values are filled in for
.I common.prog,
.I common.vers,
and
.I common.date.
The command line is added to the comment field.
The two input files are made the source files of the output.
Two new fields are added with
.IR add_fea_field (3-\ESPS).
The following items in the statistics-file header are accessed:
.I common.type,
.I common.tag,
.I hd.fea\->fea_type,
the generic header items
.I statsize
and
.I statfield,
all items consulted by
.IR allo_feastat_rec (3\-EPSP)
and
.IR get_feastat_rec (3\-ESPS),
and, in case the derived-field mechanism is used,
.I variable.refhd.
In that case the following fields of the reference header are accessed:
.I hd.fea\->names,
.I hd.fea\->derived,
and
.I hd.fea\->srcfields.
.SH OPTIONS
.PP
The following options are supported:
.TP
.BI \-x " debug_level"
If
.I debug_level
is positive,
.I classify
prints debugging messages and other information on the standard error
output.  The messages proliferate as the 
.I debug_level
increases.  If
.I debug_level
is 0, no messages are printed.  The default is 0.  
.TP
.BI \-f " field"
The specified field must exits in
.I input.fea.
The elements of the feature vector for each input record are drawn
from this field instead of the field named in the generic header item
.I statfield
in
.I input.stat.
This option may not be used if
.B \-d
is used.
.TP
.BI \-e " elements"
The argument is in the form expected by
.I grange_switch(3\-ESPS)
and specifies the set of field elements that are to comprise the feature
vector for each input record.
The field from which the elements are selected is that specified with the
.B \-f
option, if any; if
.B \-f
is not used, then the field is that named in the generic header item
.I statfield
in
.I input.stat.
This option may not be used if
.B \-d
is used.
.TP
.B \-d
Forces the use of the derived-field mechanism of feature files even when
.I statfield
in the statistics-file header is the name of a field in the input feature
file.  (See the Description section for more detail.)  This option may not
be used if
.B \-e
or
.B \-f
is used.
.TP
.BI \-C " field"
Specifies the name of the field in the output feature file that is to
contain the classification result for each record.  Default is
.I class.
The program exits with an error message if the field
is already present in the input feature file.
.TP
.BI \-L " field"
Specifies the name of the field in the output feature file that is to
contain the vector of normalized likelihood values.  Default is
.I posteriors.
The program exits with an error message if the field
is already present in the input feature file.
.TP
.BI \-h " file.his"
Place various intermediate results in the ASCII history file
.I file.his.
At the end place summary statistics such as the total number of
records classified, number of records in each class, and fraction of
records in each class.
.SH "FUTURE CHANGES"
.PP
Option to input prior probabilities for the classes and perform
maximum-posterior-probability classification.
.PP
Fix the problem mentioned under Bugs.
.SH EXAMPLE
Suppose you want to classify speech analysis frames
as ``voiced'', ``unvoiced'', or ``silent''
on the basis of raw power
and (for some reason) reflection coefficients number 2, 4, 5, and 6.
Obtain 3 fea_ana(5\-ESPS) files, say
.I voi.fana,
.I unv.fana,
and
.I sil.fana,
containing training sequences of voiced, unvoiced, and silent frames.
Also prepare an Ascii file,
.I fields,
containing the lines
.nf
.IP
field = svector
raw_power[0]
spec_param[1,3:5]
.fi
.PP
or substitute a name of your choice for
.I svector.
.PP
Execute the command
.IP
feaderiv fields voi.fana voi.fea
.PP
This will create a feature file
.I voi.fea
having a single vector field
.I svector
of length 5.
In each record of
.I voi.fea
the contents of
.I svector
will consist of the contents of
.I raw_power,
.IR spec_param [1],
.IR spec_param [3],
.IR spec_param [4],
and
.IR spec_param [5]
in the corresponding record of
.I voi.fana.
In the header of
.I voi.fea,
the element of
.IR hd.fea \-> derived
corresponding to "svector" in
.IR hd.fea \-> names
will have the value YES,
and the corresponding element of
.IR hd.fea \-> srcfields
will contain the strings "raw_power" and "spec_param[1,3:5]".
Likewise execute
.nf
.IP
feaderiv fields unv.fana unv.fea
feaderiv fields sil.fana sil.fea
.fi
.PP
to create files
.I unv.fea
and
.I sil.fea.
.PP
Execute
.nf
.IP
fea_stats -I -f svector -n VOICED voi.fea clas.stat
fea_stats -I -f svector -n UNVOICED unv.fea clas.stat
fea_stats -I -f svector -n SILENCE sil.fea clas.stat
.fi
.PP
to create a fea_stat(5\-ESPS) file
.I clas.stat
and append 3 records, each containing a mean vector, an inverse
covariance matrix, and a value for the coded field
.I class.
The
.I class
values in the 3 fields will be "VOICED", "UNVOICED", and "SILENCE".
The generic header items
.I statfield
and
.I statsize
will contain "svector" and 5.
.PP
Now, given a fea_ana file
.I test.fana
of records to be classified, use
.IP
classify clas.stat test.fana result.fana
.PP
to create a fea_ana file
.I result.fana
of classification results.
This will be a copy of
.I test.fana
with a coded field
.I class
indicating "VOICED", "UNVOICED", or "SILENCE" for each frame,
and a 3-element vector field
.I posteriors
giving the normalized likelihoods for the 3 voicing classes for each record.
.PP
The order of the likelihoods may or may not be
``voiced'', ``unvoiced'', ``silence''.
To find out, use
.IP
psps -x -v result.fana
.PP
to determine the order of the strings "VOICED", "UNVOICED", and "SILENCE"
in the field definition for
.I class.
.SH "SEE ALSO"
.PP
fea_deriv(1\-ESPS), fea_stats(1\-ESPS), classify(3\-ESPS),
get_deriv_vec(3\-ESPS), FEA(5\-ESPS), FEA_STAT(5\-ESPS)
.SH DIAGNOSTICS
.PP
.nf
classify: unknown option \-\fIletter\fP
Usage: classify .\ .\ .\ .
classify: can't open \fIfilename\fP: \fIreason\fP
classify: \fIfilename\fP is not an ESPS file
classify: \fIfilename\fP is not an ESPS feature file
classify: \fIfilename\fP is not an ESPS fea_stat file
classify: \-f and \-e are incompatible with \-d
classify: \fIfield\fP is not a derived field
classify: feature-vector length inconsistent with statsize in stat file
.fi
.SH BUGS
.PP
The correspondence between class names and elements of the vectors of
likelihoods can be scrambled by programs like
.IR fea_edit (1\-ESPS)
and
.IR select (1\-ESPS),
which can alter headers or copy records from one file into another
with a different header.
.SH REFERENCES
.PP
.SH AUTHOR
Rodney W. Johnson