param.doc

speech signal process tools

                         ENTROPIC RESEARCH LABORATORY, INC.


       TECHNICAL MEMORANDUM

       SUBJECT: Parameter and Common Files in ESPS

       ID: ETM-S-86-12:jtb

       VERSION: 3.5

       DATE: 1/22/93

       AUTHOR: Joe Buck

       LAST REVISED BY: John Shore

       REFERENCES:

        [1] Entropic Signal Processing System (ESPS),  Programmers  Reference
            Manual

        [2] ETM-S-86-13:rap, Data Files in  the  Entropic  Signal  Processing
            System (ESPS)

        [3] ETM-S-86-25, Guidelines for Implementing ESPS Feature  File  Sub-
            types

        [4] J. Shore and R.  Parker, Introduction to the Entropic Signal Pro-
            cessing System (ESPS)

        [5] ETM-S-86-14, Entropic Signal Processing System Programming Guide-
            lines

       1 .  Introduction

       This document describes the Entropic Signal Processing  System  (ESPS)
       parameter and common files, and presents information required to write
       programs using them.

       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  parame-
       ters.  A suitable mechanism should achieve the following goals:

         +  It should be easy to prepare parameter sets.


       ____________________
          c
            Copyright  1987-1993  Entropic  Research  Laboratory,  Inc.;  All
       rights reserved.











       ETM-S-86-12:jtb                                                 page 3


         +  It should be easy to review existing parameter sets, change  some
            values and re-run the program.

         +  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.

         +  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.

         +  There should be system-wide defaults  for  parameter  sets,  with
            these  defaults being changeable easily by the system administra-
            tor.

       The ESPS parameter mechanism was designed with these goals in mind.

       Readers of this document should also read the  ESPS  manual  pages  in
       reference  [1].   These  manual pages are in the standard UNIX format;
       section 1 describes user commands, section 3  describes  library  rou-
       tines,  and section 5 describes the format of ESPS files (see also [2]
       and [3]).  For a general introduction to ESPS, see [4].

       2 .  Relevant Programs and Library Functions

       3 .  User Level Programs

       Most ESPS programs process ESPS parameter files, and all that do  sup-
       port a command line option (-P) to specify a particular parameter file
       (the default name is "params").  A few programs are intended  specifi-
       cally  to aid in the preparation or application of parameter files, or
       to provide relevant information, namely:

         eparam -  run an ESPS program with parameter prompts

         xeparam - run an ESPS program with X Window parameter prompts

         exprompt -interactive ESPS parameter entry in a pop-up window

         expromptrun -interactive ESPS parameter entry and program run

         getparam -prints value of ESPS parameter from parameter file or ESPS Common

         espsenv - display relevant UNIX environment variables

       3 .1 .  Library Functions

       The following utility library functions relate to  parameter  process-
       ing:

         read_params -create symbol table from ESPS Parameter or Common file
         symlist - get list of parameter names and return number of parameters


       Version 3.5                      ERL                           1/22/93







       ETM-S-86-12:jtb                                                 page 4


         symtype - return the type of a parameter
         symsize - return the size of a parameter
         symdefinite -indicates whether or not a run-time parameter prompt will occur
         symchoices -get list of discrete choices for a parameter's value
         symrange - get the value range for a parameter
         symprompt -returns the prompt string for a parameter
         getsym_X -get parameter value of type X from the symbol table
         getsymdef_X -get default parameter value of type X from the symbol table
         putsym_X -put a parameter value of type X into the ESPS Common file
         fputsym_X -put a parameter value of type X into an arbitrary file


       4 .  Introductory Example

       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 vqdes (1-ESPS):

           #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";


       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 -P option, which is  sup-
       ported by all programs that process parameter files.

       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 ver-
       sion of the VQ parameter file; it specifies that  the  program  prompt
       for conv_ratio and vq_size, and it gives an explicit prompt string for
       vq_size:

           #parameter file for vqdes
           int    fea_dim     = 10;
           float  conv_ratio ?= .1;
           int    vq_size    ?= 16 : "Enter size of VQ codebook to be designed";


       Version 3.5                      ERL                           1/22/93







       ETM-S-86-12:jtb                                                 page 5


           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";


       Here is what happens when vqdes is run with  the  foregoing  parameter
       file:

           %vqdes -Pvqparams rc.fana rc.cbk
           Enter size of VQ codebook to be designed [16]: 32
           conv_ratio [0.100000]: 0.25
           %

       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  eparam  (1-ESPS),  which  invokes  any
       given ESPS program with its default parameter file. The default param-
       eter files are written to prompt for all values so  you  can  override
       each default.  Here is an example of running vqdes by means of eparam:

           %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]:
           %


       In this example, the  defaults  were  taken  for  all  parameters  but
       vq_size  and  conv_ratio.   Notice  the  user was not prompted for the
       parameters init_file and init_rec.  This is because  these  parameters
       are  relevant  only if the -i option for vqdes 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.

       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 cbk_struct 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.



       Version 3.5                      ERL                           1/22/93







       ETM-S-86-12:jtb                                                 page 6


       5 .  ESPS Parameter Files, the Common File, and Command Lines

       The parameter file is only one mechanism by which  ESPS  programs  get
       their parameters.  In general, parameters come from three sources:

            +  the ESPS parameter file

            +  the ESPS common file

            +  command line options

       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 peo-
       ple 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 xprompt does.)


       5 .1 .  Parameter Precedence Rules

       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

       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 super-
       seded if rules (1)-(4) apply.

            (1)  Common file processing has not been  disabled.   (Users  can
                 disable Common file processing by means of the Unix environ-
                 ment variable USE_ESPS_COMMON (see below).  Individual  pro-
                 grams  can  also disable Common processing; if they do, this
                 is noted in the manual page for the program.)

            (2)  The common file exists and is  younger  than  the  parameter
                 file.

            (3)  The common file contains a value for the parameter in  ques-
                 tion.

            (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.)

       The purpose of the ESPS common file is to allow one  ESPS  program  to
       communicate  parameter  values  to  another  ESPS  program that is run


       Version 3.5                      ERL                           1/22/93







       ETM-S-86-12:jtb                                                 page 7


       subsequently.  For example, suppose that plotsd (1-ESPS)  is  used  to
       plot the first three seconds of a sampled-data file:

                   %plotsd -s3 file.sd

       After this plot is made, the user can run range (1-ESPS) to  select  a
       portion  of  the  displayed  data.   When  range  exits, it writes the
       selected range and the filename "file.sd" into the ESPS  common  file.
       If the user then runs

                   %plotsd
                   %play

       (i.e., without any command line options), the selected  range  of  the
       same  file  will be displayed and then played.  Note that waves+ has a
       mode (global parameter write_common non-zero) in which the ESPS Common
       is written whenever the mouse is used to mark a segment of a displayed
       ESPS file.

       For most ESPS programs,  common  file  processing  is  enabled  (i.e.,