.\" Copyright (c) 1987 Entropic Speech, Inc.; All rights reserved.\" @(#)fea.5t	1.2 7/15/87 ESI.TH FEA 5\-ESPS 7/15/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 NAMEESPS Feature File \- (.fea).SH SYNOPSIS.B #include <sps/sps.h>.br.B #include <sps/fea.h>.SH DESCRIPTION.PPAn ESPS Feature File consists of a header followed by a sequence offeature records.  Each record consists of a number of named ``fields''that may hold numeric or ``coded'' data or arrays of such data.  A fieldis characterized by its name, data type, size (number of items), andarray dimensions.  The header contains a list of field names andassociated information.  Each feature record contains, for each field,storage sufficient to hold the given number of items of the given datatype.  .PPA ``coded'' data type is like a C enum type; the header contains a listof possible values, which are strings, and in a record a string isrepresented by the short integer that gives its position in the list.  Atypical use for a coded type is to represent class identifiers.  Forexample the header could associate the field name "voicing" and the setof values {"voiced", "unvoiced", "silent"} with a record item; the sizewould be 1 for a single item.  Then in each record a value 0, 1, or 2for that item would indicate a value of "voiced", "unvoiced", or"silent", respectively, for the voicing class of the record.  .PPFor many applications, each feature record refers to a frame of speechin some sampled-data file or, more generally, to a contiguous segment ofrecords in some ESPS file.  There is provision for flagging a featurefile as ``segment_labeled'', which implies that, in addition to whatever other information is stored,each record identifiesan ESPS file and a starting record and number of records in that file.A support function.RI ( set_seg_lab (3\-ESPSu))is provided for setting up fields to hold this information.  .PPThe header has the following layout as defined by .I <sps/header.h>.The data items common to all ESPS data files are described in.IR ESPS (5\-ESPS).The type-specific header structure for .fea files is shown below..PP.nf/* Feature File specific header */.spstruct fea_header {.TSl1 l1 l1 l.    short	fea_type;	/\(** indicates special feature-file types \(**/    short	segment_labeled;	/\(** If YES, records contain file name,		\h'10n' start & length of segment \(**/    unsigned short	field_count;	/\(** number of fields  \(**/    char	**names;	/\(** name of each field \(**/    long	*sizes;	/\(** total number of items in field \(**/    short	*ranks;	/\(** number of dimensions in field \(**/    long	**dimens;	/\(** array dimensions for field \(**/    short	*types;	/\(** type (DOUBLE, FLOAT, etc.) of field \(**/    char	***enums;	/\(** arrays of values for coded types \(**/    long	*starts;	/\(** starting point for this field \(**/    short	*derived;	/\(**indicates whether field was derived \(**/    char	***srcfields;	/\(**for derived fields, 		\h'10n' arrays of source field names \(**/    short	spares[FEA_SPARES];	/\(** spares \(**/.TE};.fi.sp.PPThe following items are all in the feature-file-specific header structure..IP fea_typeThis item may be used to indicate that the feature file is of a specialtype.  It might imply specific uses of some of the spares, for instance,or that certain conditions apply to the set of fields that may ormust be defined.  FEA_GEN indicates a completely general feature file typewith no special conditions except those implied by.I segment_labeled..IP segment_labeledIf the value of this flag is YES, three fields are guaranteed to bedefined:  a coded field of size 1 named "source_file" and twolong-integer fields of size 1 named "segment_start" and "segment_length".For each record these give the name of an ESPS file and the beginningrecord number and number of records of a segment in that file to whichthe feature record refers.  If the flag value is NO, these fields neednot be defined and in fact should not be defined; the three field namesshould be treated as reserved.  The flag is set by the function .IR set_seg_lab (3\-ESPSu),and the programmer should not set it directly.  A value of YES for.I segment_labeledis incompatible with a value of YES for.I tagin the common part of the header..IP field_countThis is the number of distinct fields defined in the header.The items.I names,.I sizes,.I ranks,.I dimens,.I types,.I starts,and.I enumseach point to the first element of an array of length.I field_countor (in the case of.I names).I field_count+ 1.  Each element of each of these arrays refers to the field named bythe corresponding element of .I names..IP namesThis points to the beginning of an array of strings that contains thefield names and a terminating null string.  The array is suitable as anargument of .IR lin_search2 (3\-ESPSu).  (Note that the difference between .IR lin_searchand.IR lin_search2 is that .IR lin_search does a case insensitive compare.).IP sizesThis points to the beginning of an array of long integers.Each integer gives the number of items in the corresponding field..IP ranksThis points to the beginning of an array of short integers.Each integer gives the number of dimensions of the corresponding field(0 for a scalar, 1 for a vector, 2 for a matrix, etc.).  This item and.I dimensmay be NULL if there are no fields of 2 or more dimensions, and if thereis no need to distinguish a scalar from a vector of length 1..IP dimensThis item points to the beginning of an array of pointers.  Each ofthese pointers points to the beginning of an long integer array that givesthe dimensions of the corresponding field.  The length of that integerarray is the number of dimensions given in the array that .I rankspoints to.  The product of the dimensions must equal the field sizegiven in the array that .I sizespoints to.  This item may be NULL if .I ranksis NULL or contains no entries greater than 1..IP typesThis points to the beginning of an array of short integers.Each integer gives the type of each item in the corresponding field.The types are indicated by the constants DOUBLE, FLOAT, LONG, SHORT,CHAR, and CODED, which are defined in.I <sps/sps.h>..IP enumsThis item points to the beginning of an array of pointers.Each of these pointers is NULL unless the corresponding typeis CODED, and then it indicates the possible values for each item of thecorresponding field.More specifically, the pointer, if not NULL, points to the beginning of a null-terminated arrayof strings suitable as an argument of .IR lin_search2 (3\-ESPSu);these strings are the possible values.Functions are available to find the code corresponding to a given stringand vice versa; see.IR fea_encode (3\-ESPSu),.IR fea_decode (3\-ESPSu)..IP startsThis points to the beginning of an array of longs.  Each element givesthe starting point of the data for the corresponding field relative tothe pointer of the correct type in the data record.(Type CODED is treated as a SHORT)..IP derivedThis points to the beginning of an array of shorts, one for each field.  A non-zero value means that the corresponding field was "derived" from another FEA file.  That is, each element in the field corresponds to some particular element in other FEA files with different field structures(see \fIsrcfields\fP)..IP srcfieldsThis item points to the beginning of an array of character pointers.  Each of these pointers is NULL unless the corresponding field is derived (see \fIderived\fP), in which case it points the beginning of anull-terminated array of strings.  Each string has the form.nf    <fieldname> [ <element_range> ].fiwhere <fieldname> is a field name (usually not a field in the current FEA file), and where <element_range> is a list of elements in a form suitable for \fIgrange_switch\fP (3\-ESPS).  The total number of elements described in this way must equal the size of the corresponding field.  For example, suppose that a FEA file contains a derived field named .I svectorof size 5.  The contents of the corresponding array of strings in .I srcfields might be as follows: "raw_power[0]", "spec_param[1,3:5]".  This is interpreted to mean that the five elements of .I svectorwere derived from elements in the .I raw_powerand.I spec_paramfields of some other FEA file \- in particular, the 5 elements of .I svectorcorrespond to \fIraw_power\fP[0], \fIspec_param\fP[1],\fIspec_param\fP[3], \fIspec_param\fP[4], and \fIspec_param\fP[5](see .I set_fea_deriv(3\-ESPSu)).  .IP sparesThere are FEA_SPARES spare shorts..PPThe data follows the header.   The data structure in the file is shown below in C syntax.  The variables.I ndouble, nfloat, nlong, num_short, num_coded,and.I ncharare not actually used in the declaration, but are used by the headerroutines to allocate the correct amount of memory..PPThis data structure is defined in.I <sps/fea.h>.A function is available to allocate memory for this data structure,based on a particular header.  See .IR allo_fea_rec (3\-ESPSu)..PP.nfstruct fea_data {.TSl1 l1 l1 l.    long	tag;	/\(** position tag \(**/     double	d_data[ndouble]; 	/\(** double record items \(**/    float	f_data[nfloat]; 	/\(** float record items \(**/    long	l_data[nlong]; 	/\(** long record items \(**/    short	s_data[num_short]; 	/\(** short and coded record items \(**/    char	b_data[nchar]; 	/\(** char record items \(**/.TE};.fi.PPA feature file may have a position tag in each record.  This tag refers to records in the file named in the header field\fIcommon.refer\fR.In addition thereis space for .I ndoubledoubles, .I nfloatfloats, .I nlonglongs, .I nshortshorts, and.I ncharbytes, where.I ndouble, nfloat, nlong, nshort,and.I ncharare values from the common part of the ESPS file header.The value of.I ndoubleis the sum of the sizes of the fields of type DOUBLE;.I nfloat, nlong,and.I ncharare defined similarly.The header value.I nshortis of the form.I num_short + num_coded,where.I num_shortis the sum of the sizes of the fields of type SHORT and.I num_codedis the sum of the sizes of the fields of type CODED.Space in.I d_datafor fields of type DOUBLE is allocated in the order of occurrence of thefields' names in.I names.Space in the other five data arrays in a record is allocated similarly.However, programs generally need not and should not depend on thisinformation about record format.  Functions are available to get apointer to the beginning of the storage in a given record for the fieldwith a given name; see.IR get_fea_ptr (3\-ESPSu)..SH EXAMPLES.PPAssume declarations.PP.nf.TSl1 l1 l.    struct header	*hd;    struct fea_data	*rec;    int	siz, rnk, *dim;    double	*pd;    short	*pe;.TE.fi.PPSuppose.I hdand.I rechave properly initialized, for example by.IR new_header (3\-ESPSu)or.IR read_header (3\-ESPSu)and by.IR allo_fea_rec (3\-ESPSu).Then the statement.IPpd = (double *)get_fea_ptr(rec, "energy", hd);.PPwill assign to.I pda pointer to the first double in the storage in.I recfor the field named "energy", provided that the field exists.Now a statement like.IP*pd = 3.7.PPwill store a value into the field in.I rec.If the field has several elements, a subscripted variable like.I pd[3]can be used instead of.I *pd.If.I recalready contains data, for example as a result of calling.IR get_fea_rec (3\-ESPSu),the data can be accessed by using.I *pdor a subscripted.I pdin an expression.  The statement.IPpe = (short *)get_fea_ptr(rec, "voicing", hd);.PPwill assign to.I pea pointer to a short integer in the storage in.I recthat holds a code for a value in the field named "voicing".A statement like.IP*pe = fea_encode("voiced", "voicing", hd);.PPwill assign the code for the string "voiced" to the short integer,and the expression.IPfea_decode(*pe, "voicing", hd);.PPwill get the string value corresponding to the code that is there..SH SEE ALSOallo_fea_rec(3\-ESPSu), get_fea_rec(3\-ESPSu), put_fea_rec(3\-ESPSu),add_fea_fld(3\-ESPSu), set_fea_deriv(3\-ESPSu), get_fea_deriv(3\-ESPSu),set_seg_lab(3\-ESPSu),get_fea_ptr(3\-ESPSu),fea_encode(3\-ESPSu), fea_decode(3\-ESPSu),new_header(3\-ESPSu) read_header(3\-ESPSu), write_header(3\-ESPSu),lin_search(3\-ESPSu), ESPS(5\-ESPS).SH FUTURE CHANGESDefine additional values for the.I typefield in the header..SH AUTHORRodney Johnson.  Incorporates suggestions by Joe Buck, Alan Parker, andJohn Shore.  .PPImplementation by Alan Parker