fea_stat.5t

speech signal process tools

.\" Copyright (c) 1987, 1988 Entropic Speech, Inc. All rights reserved.
.\" @(#)fea_stat.5t	1.6 24 Sep 1997 ESI
.TH FEA_STAT 5\-ESPS 24 Sep 1997
.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
ESPS Statistics Feature File Subtype \- (.stat)
.SH SYNOPSIS
.nf
.ft B
#include <esps/esps.h>
#include <esps/fea.h>
#include <esps/fstat.h>
.fi
.SH DESCRIPTION
.PP
The FEA_STAT file is a subtype of the FEA file.  If \fIhd\fR is a 
pointer to the header of such a file, then \fIhd\->hd.fea\->fea_type\fR
== FEA_STAT.  FEA_STAT files are used to store statistical parameters
useful for classification.  FEA_STAT files are created by calling 
.I init_feastat_hd
(3\-ESPSu) after 
.I new_header
(3\-ESPSu).  
.PP
The header for a FEA_STAT
file contains the following generic header items:
.PP
.TS
center, box, tab(;);
c | c | c | c
l | l | l | l.
Name;Size;Type;Enums
=
statfield;(varies);character;NULL
statsize;1;long;NULL;
.TE
.PP
The generic header items have the following meanings:
.IP statfield
The name of the field on which statistics were computed.  A pointer
to the header of the file on which statistics were computed is 
stored in the 
.I variable.refhd
header item in the FEA_STAT file header.  
For example, 
if a FEA_STAT file is generated by 
.I fea_stats
(1\-ESPS), 
.I statfield 
would be the name of one of the fields in the input 
file to 
.I fea_stats,
and 
.I variable.refhd
in the FEA_STAT header would be a pointer to the header of the 
input file to 
.I fea_stats.
Note that the information available through
.I variable.refhd
allows programs that process FEA_STAT files to assemble compatible 
classification vectors from input FEA files.  
.IP statsize
The size of the field on which statistics were computed.
.PP
.ne 10
The header of a FEA_STAT file also contains definitions for one or 
more of the record fields given by the following table:
.PP
.TS
center, box, tab(;);
c | c | c | c | c | c 
l | l | l | l | l | l.
Name;Size;Rank;Dimen;Type;Enums
=
class;1;0;NULL;coded;(varies)
nsamp;1;0;NULL;long;NULL
mean;\fIstatsize\fP;1;NULL;float;NULL
covar;\fIstatsize * statsize\fP;2;{\fIstatsize, statsize\fP};float;NULL
invcovar;\fIstatsize * statsize\fP;2;{\fIstatsize, statsize\fP};float;NULL
eigenval;\fIstatsize\fP;1;NULL;float;NULL
eigenvec;\fIstatsize * statsize\fP;2;{\fIstatsize, statsize\fP};float;NULL
.TE
.PP
The three fields class, nsamp, and mean, are always present in a FEA_STAT file.
The other fields, covar, invcovar, eigenval, and eigenvec are option
fields that can be created by calling \fIinit_feastat_hd\fP(3\-ESPSu).
Either
.I eigenval
and
.I eigenvec
are both present, or both are absent.  See \fIfea\fR(5\-ESPS) 
for additional information on the meaning of the table columns.
.PP
In most cases, programs that deal with FEA_STAT files will use the support
routines provided in the ESPS library and will not have to make direct
use of the information in the above tables.   The library routine
.I init_feastat_hd
(3\-ESPSu) creates the record fields and the generic header items.
.PP
Programs that deal with FEA_STAT files do so in terms of structures of
type (struct fstat) \- pointers to structures of this type are returned by 
.I allo_feastat_rec
(3\-ESPSu), and the FEA_STAT read and write routines (\fIget_fstat_rec\fR
and \fIput_fstat_rec\fP) have parameters of type (struct fstat).  Here is 
the definition of the fstat struct (given in \fI<esps/fstat.h>\fR):
.nf
.ta .5i 1i 1.75i

    struct fstat  {
	short		*class;
	long		*nsamp;
	float		*mean;
	float		**covar;
	float		**invcovar;
	float		*eigenval;
	float		**eigenvec;
        struct fea_data    *fea_rec;
    };
.fi
.PP
The record fields have the following meanings:
.IP class
This field contains a list of all the possible types of classes available.
For example, in making voicing decisions a valid class might be given by
{"voiced", "unvoiced", "silent"}.
.IP nsamp
This is the number of sample vectors that were averaged in computing
the mean and covariance, \fIi. e.,\fP the number of records that were
processed.
.IP mean
This is a vector which consists of the average of \fIstatfield\fP
in a FEA file across all records.
.IP covar
This is the sample covariance matrix corresponding to \fIstatfield\fP in
a FEA file.
.IP invcovar
This field contains the sample inverse covariance matrix.
.IP eigenval
This is a vector which contains the eigenvalues of the covariance matrix.
.IP eigenvec
This is a matrix which contains the eigenvectors of the covariance matrix.
.IP fea_rec
This is a pointer to the FEA file record in which all the FEA_STAT 
information is stored.  Programs should not use this value directly.
.SH SEE ALSO
.PP
.IR set_fea_deriv (3\-ESPSu),
.IR get_fea_deriv (3\-ESPSu), 
.br
.IR init_feastat_hd (3\-ESPSu),
.IR allo_feastat_rec (3\-ESPSu),
.br
.IR get_feastat_rec (3\-ESPSu),
.IR put_feastat_rec (3\-ESPSu),
.br
.IR get_genhd (3\-ESPSu),
.IR FEA (5\-ESPS),
.IR ESPS (5\-ESPS)
.SH RECORD ELEMENT FILE STRUCTURE
.PP
In order to use this (or any other) FEA file type with a generic ESPS
program (one that operates on any file type) it is necessary to know how
record elements are positioned in the file.   For a FEA file
that information is obtained by running the program
\fIfea_element\fR(1\-ESPS) on the file in question.
.SH FILES
.PP
.nf
/usr/include/esps/fea.h
/usr/include/esps/feastat.h
.SH AUTHOR
Manual page by John Shore