vqdesasc.1

speech signal process tools

.\" @(#)vqdesasc.1	3.6 4/7/97 ESI
.\" Copyright (c) 1987 Entropic Speech, Inc.; All rights reserved
.TH VQDESASC 1\-ESPS 4/7/97
.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"
vqdesasc - design a vector quantization codebook from an ASCII training sequence
.SH "SYNOPSIS"
.B vqdesasc
[
.BI \-x " debug_level"
] [
.BI \-P " param_file"
] [
.BI \-h " histfile"
] [
.BI \-k " checkfile"
] [
.BI \-l " max_line_len"
] [
.BI \-i 
] [
.BI \-c " comment"
] [
.BI \-C " comment_file"
]
.I "input output.fea"
.SH "DESCRIPTION"
.PP
.I Vqdesasc
takes as input an ASCII file
.I input 
containing a training sequence of feature vectors.  The components
of each vector are separated by white space, and the vectors are
separated by new-lines.   
.I Vqdesasc
designs a vector quantization codebook from the input training sequence
with codebook characteristics determined from information in the ESPS
parameter file (see ESPS PARAMETERS).  The dimension of the codewords in 
the codebook is set to the dimension of the first vector in the 
input file
.I input,
and all input vectors are assumed to be this length.  
.PP
If the \fB\-i\fR option is given, an initial codebook is read 
from a file determined by information in the ESPS parameter file.  
.PP
The codebook and all converged codebooks of intermediate sizes 
are output as records in an ESPS FEA_VQ file 
.I output.fea.  
If "\-" is supplied in place of 
.I output.fea, 
then standard output is used.  
.PP
After every pass through the training sequence, the centroid-adjusted
codebook is output to a checkpoint file.  Only a single record is kept
in the checkpoint file (it is over-written each time).  
.PP
For record-keeping purposes,
.I vqdesasc
stores an ASCII comment in the header of 
.I output.fea.  
If a comment is not supplied by means of the
\fB\-c\fR or \fB\-C\fR options, the user is prompted for one.  The
comment should describe the origin of the training sequence.  
.PP
For a detailed description of the VQ design algorithm, 
see
.I vqdesign
(3\-ESPS).  
.PP
If the total memory required to store the contents of 
.I input 
is less than an internal limit of 
.I vqdesasc,
the codebook design algorithm will run in memory.  Otherwise, 
.I vqdesasc
will obtain pieces from 
.I input
as necessary.  
.SH OPTIONS
.PP
The following options are supported:
.TP
.BI \-x " debug_level \fR[2]\fP"
If 
.I debug_level
is positive,
.I vqdesasc
outputs debugging messages and other information about the codebook
design to a history file.  The messages proliferate as 
.I debug_level 
increases.  Levels up to 6 are supported currently.  For
For
information about what output results from each value of 
.I debug_level,
see the discussion of the parameter 
.I hdetail
in
.I vqdesign
(3\-ESPS).  
.IP
For the default level (2), a summary of the various design parameters is
output to the history file at the beginning of the run.  Then, the
following are written each time the codebook has converged at a given size
or after an empty cell has been filled:  current date and time, current
codebook size, size of training sequence for current codebook, total number
of clustering iterations so far, average distortion of the current
codebook, total number of empty cells found so far, and codebook entropy.
Also, the average distortion with respect to the current codebook is output
each time the full training sequence is encoded.
.TP
.BI \-h " histfile \fR[vqdesaschist]\fP"
Specifies the file to use for history and debugging output.  
.TP
.BI \-k " checkfile \fR[vqdesasc.chk]\fP"
Specifies the name of the checkpoint file written by 
.I vqdesasc.  
.TP
.BI \-l " max_line_len \fR[500]\fP"
Specifies the maximum length of input lines.  
.TP
.B \-i
Specifies that an initial codebook is to be used (otherwise a root
codebook is designed from the training sequence).  The filename 
and record number for the initial codebook are given respectively
by the parameters 
.I init_file
and
.I init_rec
in the ESPS parameter file.  The file must be of type FEA_VQ.  
Whether or not the initial codebook is clustered before splitting 
is determined by the parameter
.I init_behav
in the ESPS parameter file.  
.IP
The parameters
.I conv_ratio
and
.I dist_type
apply whether or not the \fB\-i\fP option is used.  
.TP
.BI \-c " comment"
Specifies that the ASCII string 
.I comment
be added as a comment in the header of 
.I output.fea.
.TP
.BI \-C " comment_file"
Specifies that the contents of the file
.I comment_file
be added as a comment in the header of 
.I output.fea.  
.SH "ESPS PARAMETERS"
.PP
The following parameters are read from the parameter or common 
file (see also the description of the \fB\-i\fP option):
.sp
.I "double conv_ratio"
.PP
Each clustering iteration of the codebook design algorithm is 
repeated until the fractional decrease in the overall average 
distortion between successive iterations falls below
.I conv_ratio.  
A reasonable initial value is .05
.sp
.I "int vq_size"
.PP
Specifies the size of the desired VQ codebook.
.sp
.I "string dist_type"
.PP
Specifies the type of distortion measure to use.  Currently supported
values are "MSE" (mean-square-error) and "MSE_LAR" (mean-square-error on log
area ratios, which assumes that the input vectors are reflection
coefficients).  
.sp
.I "string cbk_struct"
.PP
Specifies the search-structure of the desired codebook.  "FULL_SEARCH"
is the only value supported at this time.  
.sp
.I "string init_file"
.PP
Specifies the name of the file containing the initial codebook (see
\fB\-i\fP).  
.sp
.I "int init_rec"
.PP
Specifies the record number of the initial codebook in 
.I init_file
(see \fB\-i\fP).  
.sp
.I "string init_behav"
.PP
If this parameter is "INIT_NOCLUSTER", the initial codebook is 
split right away.  If it is "INIT_CLUSTER", the training sequence 
is used to recluster the initial codebook (until convergence) before
splitting.  (See \fB\-i\fP).  
.sp 
.I "int max_iter"
Specifies the maximum number of iterations per level.  If this
parameter is not present, a default value of 500 is used.  
.PP
The values of parameters obtained from the parameter file are printed
if the environment variable ESPS_VERBOSE is 3 or greater.  The default
value is 3.
.SH ESPS COMMON
.PP
ESPS Common is read if
.I filename
in Common matches 
.I input. 
No values are written to ESPS Common. 
.PP
ESPS Common processing may be disabled by setting the environment variable
USE_ESPS_COMMON to "off".  The default ESPS Common file is .espscom 
in the user's home directory.  This may be overidden by setting
the environment variable ESPSCOM to the desired path.  User feedback of
Common processing is determined by the environment variable ESPS_VERBOSE,
with 0 causing no feedback and increasing levels causing increasingly
detailed feedback.  If ESPS_VERBOSE is not defined, a default value of 3 is
assumed.
.SH ESPS HEADERS
.PP
.I Vqdesasc
sets 
.I hd.fea\->type
to FEA_VQ, and it fills in the other header fields so 
as to define FEA records of that type.  
The command line is added as a comment.  It there is an initial 
codebook specified, its header is added as a source.  
.I Vqdesasc
also writes the following generic header items:
.sp
.I "design_size"
.PP
This is the number of codewords in the codebook.  
.sp
.I "codeword_dimen"
.PP
This is the dimension of each codeword.  
.PP
Note that both of these generic header items are redundant since 
the same values are stored in the FEA record itself.  However, 
they are also written in the header as they do determine the size
of the FEA file records.  
.SH "FUTURE CHANGES"
.PP
Additional values for the parameters
.I dist_type,
and
.I cbk_struct 
will be supported.  
.I Vqdesasc
will be modified so that standard input can be used in 
place of 
.I input.
.SH "SEE ALSO"
.PP
vqasc(1\-ESPS), vq(1\-ESPS), vqdes(1\-ESPS),
vqdesign(3\-ESPS), FEA_VQ(5\-ESPS), ESPS(5-ESPS), FEA(5-ESPS)
.SH "WARNINGS AND DIAGNOSTICS"
.PP
.I Vqdesasc
will exit with appropriate messages if any of the following hold:
.IP
An initial codebook is used and its file name is the same as that of
the checkpoint file (this is for safety).
.IP
There is no data in the input file.
.IP
The feature vectors in 
.I input
do not all have the same dimension or their dimension is less than 2. 
.IP
Sufficient memory could not be allocated.
.IP
It can't read the ESPS header of the initial codebook file, or the file
is not of type FEA_VQ, or there are insufficient records in the
file.  
.IP
The dimension of the initial codebook doesn't match that of the 
training sequence.  
.IP
An invalid distortion type is specified.  
.PP
.I Vqdesasc
performs various consistency checks on the initial codebook.  
.SH "BUGS"
.PP
None known.  
.SH "REFERENCES"
.nf
\fIvqdesign\fP(3\-\s-1ESPS\s+1), \fIvqasc\fP(1\-\s-1ESPS\s+1), \fIvqdes\fP(1\-\s-1ESPS\s+1), 
\fIvq\fP(1\-\s-1ESPS\s+1), \fIpplain\fP(1\-\s-1ESPS\s+1), \fIaddfea\fP(1\-\s-1ESPS\s+1).  
.fi
.SH "AUTHOR"
.PP
Manual page by John Shore; program by John Shore.