param.vtme

来自「speech signal process tools」· VTME 代码 · 共 924 行 · 第 1/3 页

.lo
.de SM          \"macro to shrink left margin
.br
.nr $i \\n($i+\\$1i
..
.de RM          \"macro to restore original left margin
.br
.nr $i 0
..
.SJ "Parameter and Common Files in ESPS"
.AU "Joe Buck"
.RB "John Shore"
.TM ETM-S-86-12:jtb 3.5 1/22/93
.*R
Entropic Signal Processing System (ESPS), Programmers Reference Manual
.*R
ETM-S-86-13:rap, Data Files in the Entropic Signal Processing System (ESPS)
.*R
ETM-S-86-25, Guidelines for Implementing ESPS Feature File Subtypes
.*R
J. Shore and R.  Parker, Introduction to the Entropic Signal Processing System (ESPS)
.*R
ETM-S-86-14, Entropic Signal Processing System Programming Guidelines
.sh 1 Introduction
.lp
This document describes the Entropic Signal Processing System (\s-1ESPS\s+1)
parameter and common files, and presents information required to write
programs using them.  
.(f
\(co Copyright 1987-1993 Entropic Research Laboratory, Inc.; All rights reserved.  
.)f
.lp
Unix command-line options provide a convenient means for passing parameters, 
but this mechanism quickly becomes clumsy in the case of signal processing
programs that have a large number of input parameters.  A suitable 
mechanism should achieve the following goals:
.ip "\ \ \(bu"
It should be easy to prepare parameter sets.
.ip "\ \ \(bu"
It should be easy to review existing parameter sets, change some 
values and re-run the program.  
.ip "\ \ \(bu"
The preparation of parameter sets in advance should not be an absolute
requirement.  Programs should have a mode in which the user is prompted for
parameter values.  
.ip "\ \ \(bu"
Parameter files should optionally contain hints that could be used
when prompting users or processing inputs; such hints include a list
of acceptable values or a range of acceptable values, and descriptive
strings for use when prompting the user.
.ip "\ \ \(bu"
There should be system-wide defaults for parameter sets, with these
defaults being changeable easily by the system administrator.  
.lp
The ESPS parameter mechanism was designed with these goals in mind. 
.lp
Readers of this document should also read the \s-1ESPS\s+1 manual pages in
reference [1].  These manual pages are in the standard \s-1UNIX\s+1 format;
section 1 describes user commands, section 3 describes library routines,
and section 5 describes the format of \s-1ESPS\s+1 files (see also [2] and
[3]).  For a general introduction to ESPS, see [4].  
.sh 1 "Relevant Programs and Library Functions"
.lp
.sh 1 "User Level Programs"
.lp
Most ESPS programs process ESPS parameter files, and all that do
support a command line option (\fB-P\fP) to specify a particular
parameter file (the default name is "params").  A few programs are
intended specifically to aid in the preparation or application of
parameter files, or to provide relevant information, namely:
.sp .5
.nf
.ta 1.25i
  \fIeparam\fP \-	run an ESPS program with parameter prompts

  \fIxeparam\fP \-	run an ESPS program with X Window parameter prompts

  \fIexprompt\fP \-	interactive ESPS parameter entry in a pop-up window

  \fIexpromptrun\fP \-	interactive ESPS parameter entry and program run

  \fIgetparam\fP \-	prints value of ESPS parameter from parameter file or ESPS Common

  \fIespsenv\fP \-	display relevant UNIX environment variables
.sp .5
.fi
.sh 2 "Library Functions"
.lp
The following utility library functions relate to parameter
processing:
.sp .5
.nf
.ta 1.25i
  \fIread_params\fP \-	create symbol table from ESPS Parameter or Common file
  \fIsymlist\fP \-	get list of parameter names and return number of parameters
  \fIsymtype\fP \-	return the type of a parameter 
  \fIsymsize\fP \-	return the size of a parameter 
  \fIsymdefinite\fP \-	indicates whether or not a run-time parameter prompt will occur
  \fIsymchoices\fP \-	get list of discrete choices for a parameter's value
  \fIsymrange\fP \-	 get the value range for a parameter 
  \fIsymprompt\fP \-	returns the prompt string for a parameter
  \fIgetsym_X\fP \-	get parameter value of type X from the symbol table
  \fIgetsymdef_X\fP \-	get default parameter value of type X from the symbol table
  \fIputsym_X\fP \-	put a parameter value of type X into the ESPS Common file
  \fIfputsym_X\fP \-	put a parameter value of type X into an arbitrary file
.sp .5
.fi
.sh 1 "Introductory Example"
.lp
You can can provide parameter values to most programs by means of an ASCII
file containing the data types, names, and values of relevant parameters.
Here, for example, is a parameter file suitable for the vector quantizer
design program \fIvqdes\fP (1\-\s-1ESPS\s+1):
.nf

.ft CW
    #parameter file for for vqdes
    int    fea_dim     = 10;
    float  conv_ratio  = .1;
    int    vq_size     = 16;
    string dist_type   = "MSE";
    string cbk_struct  = "FULL_SEARCH";
    string cbk_type    = "MISC";
    string init_file   = "test.cbk";
    int    init_rec    = 3;
    string init_behav  = "INIT_CLUSTER";
    string fea_field   = "spec_param";
.ft LR

.fi
.lp
By default, ESPS programs look for a parameter file named "params" in the
current directory; you can override this default by providing an
explicit parameter file name by means of the \fB\-P\fP option, which is
supported by all programs that process parameter files.  
.lp
If you want to enter certain parameters interactively, changing a "="
in the parameter file to a "?=" causes the program to prompt for that
parameter after the program starts up.  Such parameters are termed
"indefinite parameters". The value in the parameter file is then given
as a default \- i.e., if you type a return in response to the prompt,
the default is used.  The standard prompt is just the name of the
required parameter; however, you can also provide your own prompt
string in the parameter file.  Here, for example, is a modified
version of the VQ parameter file; it specifies that the program prompt
for
.ft CW
conv_ratio
.ft LR
and
.ft CW
vq_size,
.ft LR
and it gives an explicit prompt string for 
.ft CW
vq_size:
.nf

    #parameter file for vqdes
    int    fea_dim     = 10;
    float  conv_ratio ?= .1;
    int    vq_size    ?= 16 : "Enter size of VQ codebook to be designed";
    string dist_type   = "MSE";
    string cbk_struct  = "FULL_SEARCH";
    string cbk_type    = "MISC";
    string init_file   = "test.cbk";
    int    init_rec    = 3;
    string init_behav  = "INIT_CLUSTER";
    string fea_field   = "spec_param";
.ft LR

.fi
.lp
Here is what happens when \fIvqdes\fP is run with the foregoing parameter
file:
.nf
.ft CW

    %vqdes -Pvqparams rc.fana rc.cbk
    Enter size of VQ codebook to be designed [16]: 32
    conv_ratio [0.100000]: 0.25
    %
.fi
.ft LR
.lp
The ESPS distribution contains a "default" parameter file for 
every ESPS program that processes a parameter file.  Easy access
to these parameter files is provided by \fIeparam\fP (1\-\s-1ESPS\s+1), 
which invokes any given ESPS program with its default parameter file.  
The default parameter files are written to prompt for all values so 
you can override each default.  Here is an example of running
\fIvqdes\fP by means of \fIeparam\fP:
.nf
.ft CW

    %eparam vqdes rc.fana rc.cbk
    max_iter [100]: 
    fea_dim [10]: 
    vq_size [32]: 16
    fea_field [spec_param]: 
    cbk_type [MISC]: 
    cbk_struct [FULL_SEARCH]: 
    conv_ratio [0.050000]: .01
    dist_type [MSE]: 
    %

.ft LR
.fi
.lp
In this example, the defaults were taken for all parameters but 
.ft CW
vq_size
.ft LR
and
.ft CW
conv_ratio.
.ft LR
Notice the user was not prompted for the parameters 
.ft CW
init_file
.ft LR
and
.ft CW
init_rec.
.ft LR
This is because these parameters are relevant only if the \fB\-i\fP option
for \fIvqdes\fP is used.  ESPS programs take values from the parameter file
(or prompt for them) only when they are actually called for by the program
at run time.
.lp
Besides the optional prompt string, parameter files can contain other hints
that can be exploited when prompting the user for indefinite
parameters.  In particular, if a parameter should be restricted to a
discrete set of values (e.g., the parameter 
.ft CW
cbk_struct
.ft LR
in the example above), one can include the list of possible choices in
the parameter file.  This list is available within C programs 
by means of an ESPS library function.  Similarly, if a parameter
should be restricted to lie within some continuous range, the
parameter file can include the limits of that range.  
.sh 1 "ESPS Parameter Files, the Common File, and Command Lines"
.lp
The parameter file is only one mechanism by which ESPS programs get their
parameters.  In general, parameters come from three sources:
.SM .5i
.ip \(bu 3
the ESPS parameter file
.ip \(bu 3
the ESPS common file
.ip \(bu 3
command line options
.RM
.lp
The ESPS Common file is an ASCII file with the same general format 
as the parameter file.  The main difference between the two is that
people prepare parameter files whereas programs write values into the
Common file.  The purpose of this is to provide a mechanism by which
one ESPS program can communicate parameter values to one that is 
run subsequently.  (Of course, there's no reason why a program can't
prepare a parameter file also; indeed, that's what \fIxprompt\fP does.)

.sh 2 "Parameter Precedence Rules"
.lp
In general, if a command-line option is available to set a parameter 
value, its use overrides possible values in a parameter file or the 
Common file.  For parameters that are not specified on the command line (either
because no option is available or because an available option is not
used), the parameters usually are obtained from an ESPS parameter file
.lp
Sometimes, a value in the parameter file is superseded by a value in the
ESPS common file \- this is determined by the following rules.  For 
some programs, the parameter file value is superseded if rules 
(1)-(3) are satisfied; for other programs the parameter file value 
is superseded if rules (1)-(4) apply.  
.SM .5i
.ip (1)
Common file processing has not been disabled.  (Users can disable Common
file processing by means of the Unix environment variable USE_ESPS_COMMON
(see below).  Individual programs can also disable Common processing; if
they do, this is noted in the manual page for the program.)  
.ip (2)
The common file exists and is younger than the parameter file. 
.ip (3)
The common file contains a value for the parameter in question.  
.ip (4)
A file name stored in the common file matches the name of an input 
file.  (Whether or not this rule applies is stated in the program's 
manual page.)  
.RM
.lp
The purpose of the ESPS common file is to allow one ESPS program to
communicate parameter values to another ESPS program that is run 
subsequently.  For example, suppose that
.i plotsd
(1-ESPS) is used to plot the first three seconds of a sampled-data file:
.nf
 
.ft CW
	%plotsd -s3 file.sd
.ft LR
 
.fi
After this plot is made, the user can run \fIrange\fP (1-ESPS) to select a
portion of the displayed data.  When \fIrange\fP exits, it writes the
selected range and the filename "file.sd" into the ESPS common file.  If
the user then runs