intro.doc

speech signal process tools

       INTRODUCTION TO ESPS                                            page 7


       Similarly, if only the FEA_SPEC file is wanted, the first two commands
       could be replaced by:

               %refcof data.sd - | me_spec - data.spec


       An important consideration in using pipes with ESPS programs  is  that
       record  keeping  is  not  compromised.   Thus,  the  file  header  for
       data.spec in the command above will include the  header  of  the  file
       produced by refcof (i.e., the header of data.fana in the first version
       of this sequence of operations, above). For a more  detailed  example,
       see. [7]

       5 .  PARAMETERS FOR ESPS PROGRAMS

       Signal processing programs often are affected by a large set of  input
       parameters.  Rather than requiring that all parameters be specified on
       the  command  line,  which  is  not  only  error-prone  but  leads  to
       ridiculously-long command lines, ESPS provides a mechanism that uses a
       distinguished ASCII file called the parameter  file.   Parameters  are
       specified  in  this  file  using  a C-like syntax that allows the user
       either to provide specific values for the parameters within the param-
       eter  file  or to have the program prompt the user for their values at
       run time.  The default convention  for  the  parameter  file  name  is
       "params"  in  the  current directory, but for all programs this can be
       changed using the -P command-line option.

       For example, refcof  (1-ESPS)  computes  reflection  coefficients  for
       fixed-length  segments  of sampled-data.  To do so it requires parame-
       ters that specify the starting point, the number of points to analyze,
       the frame length, and the order of the analysis.  The call

           %refcof -P params.3 john.sd john.fana

       indicates that reflection coefficients are to be computed for data  in
       the  file  john.sd  using  parameter  values in the file params.3 (the
       nuser may be prompted for some of the values), and  that  the  results
       are to be written to the file john.fana.

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


       Version 3.6                      ERL                           1/22/93







       INTRODUCTION TO ESPS                                            page 8


           cbk_struct [FULL_SEARCH]:
           conv_ratio [0.050000]: .01
           dist_type [MSE]:
           %


       Here, the defaults were taken  for  all  parameters  but  vq_size  and
       conv_ratio.

       The ESPS parameter file provides a convenient means for users to  com-
       municate parameter values to signal processing programs.  In many sig-
       nal processing applications, however, there is also  a  need  for  one
       program to communicate parameter values to another program that is run
       subsequently.  In ESPS, this need is met by the ESPS common  file.  If
       the  common file exists and was written more recently than the parame-
       ter file, then parameter values in the common file may supersede those
       in  the  parameter  file (for a detailed discussion of the conditions,
       see.  ESPS parameters Thus, a program can write a value into the  com-
       mon  file  and  have  that value be used by a subsequent program.  For
       example, suppose that plotsd (1-ESPS) is used to plot the first 10,000
       points of an SD file in a graphics window:

               %plotsd -p1:10000 file.sd

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

               %plotsd

       (i.e., without any command line options), the selected  range  of  the
       same file will be displayed.  Similarly, if the user runs

               %play

       (again, without options), the selected range of the same file will  be
       played out over the system D/A converter.

       The default ESPS common file is ".espscom " in the user's home  direc-
       tory, but this default can be changed by using the UNIX shell environ-
       ment variable ESPSCOM.  Thus, for csh users,

               %setenv ESPSCOM /u/shore/common.3

       resets the common file to /u/shore/common.3.  This facility for chang-
       ing  the  common  file  is  needed  so  that users can prepare and run
       several shell scripts without having them interfere with  each  other.
       Common  processing can also be turned off entirely by setting the UNIX
       environment variable USE_ESPS_COMMON to "off".  By default, ESPS  pro-
       vides detailed user-feedback about the parameter values taken from the
       parameter and common files.  The verbosity of the  resulting  messages
       is  controlled  by  the  UNIX  environment variable ESPS_VERBOSE.  The


       Version 3.6                      ERL                           1/22/93







       INTRODUCTION TO ESPS                                            page 9


       default value is 3; a value of 0 inhibits all messages.

       To summarize, ESPS programs get their parameters from three sources:

            +  the ESPS parameter file

            +  the ESPS common file

            +  command line options

       In general, if a command-line option is available to set  a  parameter
       value, its use overrides any of the other mechanisms by which programs
       get parameter values.  For details about  ESPS  parameter  and  common
       file processing see. [3]

       6 .  CONVERSIONS TO OR FROM ESPS FILES

       Most ESPS users have occasion to import non-ESPS data into ESPS files,
       and  also to export data from ESPS files for use by non-ESPS programs.
       Here is a list of the ESPS programs that are the  main  utilities  for
       converting  back  and forth between ESPS files and ASCII or headerless
       binary data:

         addfea -  adds a new FEA file field based  on ASCII data

         addfeahd -adds an ESPS feature file header to non-ESPS binary or ASCII data

         addgen -  adds a generic header item to an existing  nor new ESPS file header

         bhd -     behead an ESPS file

         btosps -  convert binary sampled data file to an ESPS FEA_SD file

         comment - displays or appends to comment field in ESPS file headers

         demux -   (demultiplex) extract real or complex channels from a FEA_SD file

         eman -    displays or prints ESPS manual pages

         eparam -  run an ESPS program with parameter prompts

         esps2mu - convert an ESPS sampled data file to a headerless mu-encoded file

         fea2mat - converts FEA to MATLAB .mat

         fea_edit -feature file editor

         fea_element -prints binary format table for ESPS FEA files

         fea_print - print data from FEA records with user-controlled formatting

         feafunc - apply function, gain factor, additive constant, and type change to FEA fields



       Version 3.6                      ERL                           1/22/93







       INTRODUCTION TO ESPS                                           page 10


         fea_deriv -derive a new FEA file containing elements from an existing one

         hditem -  print an item from an ESPS header

         ils_esps -convert an ILS sampled data file to an ESPS file

         mat2fea - converts from MATLAB .mat to FEA

         mergefea -merge two FEA files so that output records contain fields from both

         mux -     multiplex sampled-data files into a single multichannel or complex file

         mu2esps - converts mu-encoded data to ESPS FEA_SD file

         pplain -  print values from ESPS file in "plain format"

         epsps -   print headers and data from ESPS file in "pretty format"

         select -  applies arbitrary queries to select records from FEA files

         testsd -  make test signal (sine wave, square wave, noise, pulses, ASCII input, etc.)

         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

       ESPS also includes facilities for  dealing  directly  with  headerless
       files as well as with files that have foreign (non-ESPS) headers.  One
       type of foreign header - NIST (Sphere) sampled data headers - are read
       directly  by  ESPS  programs.  For a detailed discussion discussion of
       file conversion and foreign data, see the ESPS applications note "Con-
       verting Data to and from ESPS FEA Files".

       7 .  PROGRAMMING WITH ESPS FILES

       This section contains a brief introduction to the  C  structures  used
       for  ESPS  headers and records, as well as to some of the ESPS library
       routines that  facilitate  ESPS  file  processing.   If  you  are  not
       interested  in  ESPS programming, skip to Section 7.  For an introduc-
       tion to ESPS file headers see. [7]

       7 .1 .  ESPS File Headers

       The standard ESPS file header  consists  of  two  primary  parts,  the
       universal  section  and  the  type-specific section.  All header items
       (including generics) are referred to by name in programs.  This  makes
       it  easier  to write, read, and maintain programs.  Also, when headers
       are output in ASCII  form  using  psps  (1-ESPS),  all  of  the  items
       (including generics) are identified by name.




       Version 3.6                      ERL                           1/22/93







       INTRODUCTION TO ESPS                                           page 11


       7 .1 .1 .  The Universal Section of the Header

       As the name implies, the universal section of the ESPS header has  the
       same  definition  for all ESPS file types.  This section of the header
       is divided into a fixed-length portion called the common section,  and
       a variable-length portion called the variable section.

       The universal section of an ESPS header contains information about the
       type  of data in the file, the program that created the file, the user
       who created the file, the creation date, version  information,  house-
       keeping  information  required  by the header access routines, history
       data, etc.  When user programs need to refer directly to these  items,
       they do so by name.  For example, consider the items "tag" in the com-
       mon portion and "refer" in the  variable  portion.   "Tag"  determines
       whether  or not the records in the file each contain a tag pointing to
       a particular record in some pre-existing source file; if they do, then
       "refer"  is  the name of the source file to which they refer.  Here is
       an example of how these header items are referred to in source code:

           #include <esps/sps.h>
           struct header *h;
           . . .
           if (h->common.tag) printf("source file for tags is %s0, h->variable.refer);

       In most cases, ESPS programs do not refer directly  to  items  in  the
       universal  section  of  the  header because these items are maintained
       directly or indirectly by utility routines in the ESPS  library.   For
       example,  the  universal  section  of  the header contains a variable-
       length comment field that is used to record arbitrary ASCII  comments.
       Programs  add comments to an existing header though use of add_comment
       (3-ESPS), as in

           add_comment(h, "This file contains clipped values.0);

       The user-level program comment (1-ESPS), mentioned in Section 3 above,
       is implemented by means of calls to add_comment.

       7 .1 .2 .  The Type-Specific Section of the Header

       As the name implies, this section of the  header  is  used  to  record
       information relevant to the specific file type.  The items defined for
       a particular file type are described in the manual page for that  file
       type  in  Section  5 of the ESPS Manual.  For example, see SD (5-ESPS)
       for the type-specific header definition for sampled data  files.   For
       FEA files, the type-specfic section contains the field definitions.

       7 .1 .3 .  Generic Header Items

       The pre-defined items in the universal and type-specific  header  sec-
       tions  are  intended to be useful in a broad range of typical applica-
       tions.  However, they cannot anticipate every application.  For  exam-
       ple,  the SD file type does not make provision for storing in the file
       header the average rate of zero crossings, but applications arise when


       Version 3.6                      ERL                           1/22/93







       INTRODUCTION TO ESPS                                           page 12


       it  is convenient to do so.  To address such needs, ESPS provides gen-
       eric header items.

       Generic header items provide programmers with the  ability  to  create
       arbitrary  named fields in the header of any ESPS file.  Utility func-
       tions in the ESPS library facilitate the creation and manipulation  of
       generics.   For example, the function add_genhd_f (3-ESPS) can be used
       to create a generic header comprising one or more floats.  Here's  one
       example   of   its   use   to   create   and   fill   an  item  called
       "zero_cross_rate":

           struct header *hd;
           float time;
           long nzeros;
           . . .
           *add_genhd_f("zero_cross_rate", NULL, 1L, hd) = nzeros / time;


       Similarly, get_genhd (3-ESPS) returns a pointer to an existing generic
       and might be used as follows:

           struct header *hd;
           long estim_zeros;
           float time;
           . . .
           /*compute estimated number of zeros*/
           estim_zeros = time * (*(float *) get_genhd("zero_cross_rate", hd));


       Generic header items can store any type of C variable values,  includ-
       ing  characters (and strings).  Also provided are generic header items
       to store enumerated types (also called  coded  types).   These  header
       items  store  an  integer value but allow those values to be expressed
       symbolically via a set of pre-defined strings.For example,  this  code
       creates and fills a generic header item called "filter_type":

           /*defined constants for filter_type*/
           #define MISC0
           #define LOW_PASS1
           #define HIGH_PASS2
           #define BAND_PASS3

           /*string array of filter_type values*/
           char * f_types[] = {"MISC", "LOW_PASS", "HIGH_PASS", "BAND_PASS", NULL};

           /*create generic header item and fill it*/
           *add_genhd_e("filt_type", NULL, 1L, f_types, hd) = MISC;
           . . .
           /*change filt_type item in header*/
           *(short *) get_genhd("filt_type", hd) = BAND_PASS;





       Version 3.6                      ERL                           1/22/93