SEGRec Version 1.0: SEGLib/segModel.c File Reference

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <math.h>
#include <float.h>
#include "segCommon.h"
#include "segStdLib.h"
#include "segModel.h"


Functions
static double *	readVector (double vec, FILE fp, int dim)
	Read a vector from a given file stream.
static int	writeVector (double vec, FILE fp, int dim)
	Write a vector to a given file stream.
static double **	readMatrix (double *mat, FILE fp, int nrow, int ncol)
	Read a matrix from a file stream given.
static int	writeMatrix (double *mat, FILE fp, int nrow, int ncol)
	Write a matrix to a file stream given.
static double *	readParameter (FILE *fp, int dim)
	Allocate memory space, read a matrix from a file stream given, and store the matrix in the allocated space.
static double **	readMapping (FILE *fp, int domainDim, int rangeDim)
	Read a map matrix.
static int	readParamAccum (double param, double accum, FILE *fp, int dim)
	Load a parameter vector from a model file.
static SEG_TRJ *	readVariance (SEG_TRJ trajModel, FILE fp, int dim)
	Read and store a variance vector.
static SEG_TRPROB *	readTransProbs (FILE *fp)
	Read and store a transition probability matrix.
static SEG_DUR *	readDurModel (FILE *fp, int maxDur)
	Read and store a durational distribution.
static char *	readLabel (char *line)
	Read a label from a given char array.
static SEG_TRJ *	readTrjModel (FILE *fp)
	Read a trajectory model.
static SEG_MAP *	readMappings (FILE *fp)
	Read a set of forward and inverse map matrices.
static SEG_STATE *	readStateInfo (SEG_STATE state, FILE fp, int numDur)
	Read model parameters of an emitting state.
static int	readHeader (int numStream, int streamSize, int vecSize, int targetVecSize, FILE *fp)
	Read the header of model definition.
static SEG_MODEL_SET *	readModelSet (char *modelList, int maxDur)
	Read a set of multi-level segmental-HMMs in the file of model name list.
static SEG_MDPARAM *	readModel (FILE *fp, int maxDur)
	Read a single model.
static int	tieModelParameters (SEG_MODEL_SET *modelset)
	Tie model parameters.
static int	countModels (SEG_MODEL_SET modelset, int nLines, FILE fp_list)
	Count all the different levels of models.
static int	buildLogicalModels (SEG_MODEL_SET modelset, char tiedList)
	Read tied list file and build the logical layer of the models.
static int	writeStateInfo (FILE fp, SEG_STATE state)
	Write model parameters for an emitting state.
int	segMakeStrictLRTopology (SEG_MODEL_SET *modelset)
	Force models to maintain strict left-to-right topology.
int	segCheckModelSet (SEG_MODEL_SET *modelset)
	Check the consistency of model parameter set.
SEG_MODEL_SET *	segReadModelSet (char modelList, char tiedList, int maxDur)
	Read a set of multi-level segmental-HMMs in the file of model name list.
int	segWriteModelSet (SEG_MODEL_SET modelset, FILE fp)
	Write a set of models to a file.
int	segWriteDump (SEG_MODEL_SET modelset, char fName)
	Write dump file contents.

Detailed Description

Function Documentation

static int buildLogicalModels	(	SEG_MODEL_SET *	modelset,
		char *	tiedList
	)			`[static]`

Read tied list file and build the logical layer of the models.

Parameters:

`[in,out]`	modelset	Model set
`[in]`	tiedList	Name of file containing tied phone list

Return values:

	ERROR_ALLOC	Memory allocation error
	ERROR_FOPEN	File open error
	ERROR_FREAD	File read error
	RTN_ERROR	Inconsistency found in the list
	NO_ERROR	Successfully executed

Note:: Function countLines() is called internally.

See also:: countLines()

static int countModels	(	SEG_MODEL_SET *	modelset,
		int	nLines,
		FILE *	fp_list
	)			`[static]`

Count all the different levels of models.

This function counts how many physical models, transition probability matrices, states, trajectory models, duration models and articulatory-acoustic map matrices are in the model set.

Parameters:

`[in,out]`	modelset	Model set
`[in]`	nLines	Number of lines in the model file
`[in]`	fp_list	File pointer

Return values:

	RTN_ERROR	File open error
	NO_ERROR	Successful execution

static SEG_DUR * readDurModel	(	FILE *	fp,
		int	maxDur
	)			`[static]`

Read and store a durational distribution.

Parameters:

`[in]`	fp	File pointer from which the distribution is loaded
`[in]`	maxDur	Maximum segment-duration

Return values:

	NULL	Memory allocation error / File read error
	otherwise	Pointer to the structure (durModel) variable where the distribution is stored

Note:: If a negative value is set to maxDur, the function uses the maximum duration specified in the model file.

: The function calls readVector() and logProb() internally.

See also:: readVector() and logProb()

static int readHeader	(	int *	numStream,
		int *	streamSize,
		int *	vecSize,
		int *	targetVecSize,
		FILE *	fp
	)			`[static]`

Read the header of model definition.

The function reads and returns the size of the stream and the dimensions of intermediate and acoustic vectors.

Parameters:

`[in]`	numStream	Number of the stream
`[in]`	streamSize	Size of the stream
`[in]`	vecSize	Dimension of an intermediate feature
`[in]`	targetVecSize	Dimension of an acoustic feature
`[in]`	fp	File pointer from which the header is read

Return values:

	RTN_ERROR	File read error
	NO_ERROR	Successful execution

static char * readLabel ( char * line ) [static]

Read a label from a given char array.

Parameters:

[in] line Array of characters

Return values:

	NULL	Memory allocation error
	otherwise	Pointer to an allocated array for the label

static double ** readMapping	(	FILE *	fp,
		int	domainDim,
		int	rangeDim
	)			`[static]`

Read a map matrix.

Parameters:

`[in]`	fp	File pointer to the model file
`[in]`	domainDim	Number of columns of the matrix
`[in]`	rangeDim	Number of rows of the matrix

Return values:

	NULL	Memory allocation error / File read error
	otherwise	Pointer to the matrix

Note:: This function allocates memory space for a matrix used to map between acoustic and articulatory features. Then it reads the coefficients of linear mapping in the file, and stores them in the allocated space.

: The following functions are called internally: allocDblMatrix(), readMatrix() and freeDblMatrix().

See also:: allocDblMatrix(), readMatrix() and freeDblMatrix()

static SEG_MAP * readMappings ( FILE * fp ) [static]

Read a set of forward and inverse map matrices.

Parameters:

[in] fp File pointer to the model file

Return values:

	NULL	Memory allocation error / File read error
	otherwise	Pointer to a mapping information variable of structure segMap (SEG_MAP)

Note:: This function allocates memory space of matrices for forward and inverse articulatory-acoustic linear mapping. Then it reads the coefficients of the matrices in the file, and stores them in the allocated space.

: The following functions are called internally: readMapping() and freeDblMatrix().

See also:: readMapping() and freeDblMatrix()

static double ** readMatrix	(	double **	mat,
		FILE *	fp,
		int	nrow,
		int	ncol
	)			`[static]`

Read a matrix from a file stream given.

Parameters:

`[in,out]`	mat	Matrix (2-D)
`[in]`	fp	File pointer
`[in]`	nrow	Number of rows of the matrix
`[in]`	ncol	Number of columns of the matrix

Return values:

	NULL	File read error
	otherwise	Pointer to the matrix

Note:: This function calls readVector() internally.

See also:: readVector()

static SEG_MDPARAM * readModel	(	FILE *	fp,
		int	maxDur
	)			`[static]`

Read a single model.

Parameters:

`[in]`	fp	File pointer from which model parameters are read
`[in]`	maxDur	Maximal segment-duration

Return values:

	NULL	Memory allocation/File read error
	otherwise	Pointer to a variable of structure modelDef (SEG_MDPARAM) containing the read model parameters

Note:: Users can set new maximal segment-duration (maxDur) different from ones specified per state in the model file. If a negative value is set to maxDur, the maximal segment-durations for each state in the model are applied.

: This function internally calls probeWord(), readLabel(), readStateInfo(), readTransProbs(), and readMappings().

See also:: probeWord(), readLabel(), readStateInfo(), readTransProbs() and readMappings()

static SEG_MODEL_SET * readModelSet	(	char *	modelList,
		int	maxDur
	)			`[static]`

Read a set of multi-level segmental-HMMs in the file of model name list.

Parameters:

`[in]`	modelList	Name of file containing model-name list
`[in]`	maxDur	Maximal segment-duration

Return values:

	NULL	Memory allocation / File read error
	otherwise	Pointer to a read model set

Note:: Users can set new maximal segment-duration (maxDur) different from ones specified per state in the model file(s). If a negative value is set to maxDur, the maximal segment-durations for each state in the model are applied.

: The following functions are internally called: countModels(), readHeader(), readLabel(), readModel(), readTransProbs(), readStateInfo(), readTrjModel(), readDurModel() and readMappings().

See also:: countModels(), readHeader(), readLabel(), readModel(), readTransProbs(), readStateInfo(), readTrjModel(), readDurModel() and readMappings().

static int readParamAccum	(	double **	param,
		double **	accum,
		FILE *	fp,
		int	dim
	)			`[static]`

Load a parameter vector from a model file.

Allocate memory for a parameter vector and an accumulator vector, read the parameter vector from a model file, and store the parameter vector in the allocated memory

Parameters:

`[in,out]`	param	Pointer to a pointer to an array to be used to store read parameters
`[in,out]`	accum	Pointer to a pointer to an array to be used for accumulators
`[in]`	fp	File pointer to the model file
`[in]`	dim	Dimension of vector of the parameter and accumulator

Return values:

	NO_ERROR	Successful execution
	RTN_ERROR	Memory allocation error/File read error

Note:: This function calls readParameter() internally.

See also:: readParameter()

static double * readParameter	(	FILE *	fp,
		int	dim
	)			`[static]`

Allocate memory space, read a matrix from a file stream given, and store the matrix in the allocated space.

Parameters:

`[in]`	fp	File pointer
`[in]`	dim	Dimension of vector

Return values:

	NULL	Memory allocation error / File read error
	otherwise	Pointer to the allocated space (i.e. the vector)

Note:: This function calls readVector() internally.

See also:: readVector()

static SEG_STATE * readStateInfo	(	SEG_STATE *	state,
		FILE *	fp,
		int	numDur
	)			`[static]`

Read model parameters of an emitting state.

Parameters:

`[in,out]`	state	Model parameters for the state
`[in]`	fp	File pointer of the model file
`[in]`	numDur	Maximum segment-duration

Return values:

	NULL	Memory allocation error / File read error
	otherwise	Pointer to the model parameter

Note:: This function reads mean, slope, variance and duration information for an single emitting state, and stores it in a variable of structure stateInfo (SEG_STATE). Memory space for accumulators used in training is also allocated.

: The following functions are called internally: probeWord(), readParamAccum(), readVariance(), readDurModel(), readMappings() and readLabel().

See also:: probeWord(), readParamAccum(), readVariance(), readDurModel(), readMappings() and readLabel()

static SEG_TRPROB * readTransProbs ( FILE * fp ) [static]

Read and store a transition probability matrix.

Parameters:

[in] fp File pointer to the model file

Return values:

	NULL	Memory allocation error / File read error
	otherwise	Pointer to a variable of structure transProb (SEG_TRPROB)

Note:: This function first allocates meomory for a transition probability data structure (transProb/SEG_TRPROB). Then it reads and stores transition probabilities for a model. Memory space for accumulator (rTrProb) used in training is also allocated.

: The following functions are called internally: allocDblMatrix(), allocDblMatrix(), allocLngMatrix(), readMatrix(), logProb(), freeLngMatrix(), freeDblMatrix() and freeDblMatrix().

See also:: allocDblMatrix(), allocDblMatrix(), allocLngMatrix(), readMatrix(), logProb(), freeLngMatrix(), freeDblMatrix() and freeDblMatrix()

static SEG_TRJ * readTrjModel ( FILE * fp ) [static]

Read a trajectory model.

Parameters:

[in] fp File pointer from which the the model is loaded

Return values:

	NULL	Memory allocation error / File read error
	otherwise	Pointer to a structure (trjModel) variable where the model is stored

Note:: This function reads the mean, slope and variance of a trajectory model from a given file stream, and stores them in a structure (trjModel) variable, allocating necessary memory space. Memory space for accumulator (trajModel->rMean, rSlope and rVar) used in training is also allocated.

: The following functions are called internally: readParamAccum() and readVariance().

See also:: readParamAccum() and readVariance()

static SEG_TRJ * readVariance	(	SEG_TRJ *	trajModel,
		FILE *	fp,
		int	dim
	)			`[static]`

Read and store a variance vector.

Parameters:

`[in,out]`	trajModel	Structure variable for the segment trajectory
`[in]`	fp	File pointer
`[in]`	dim	Dimension of the variance vector

Return values:

	NULL	Memory allocation error / File read error
	otherwise	Pointer to the structure variable (SEG_TRJ) where the vector is stored

Note:: This function first allocates meomory for the variance vector and then loads the vector. Memory space for accumulator (trajModel->rVar) used in training is also allocated. In addition, the logarithm and reciprocal of variance, and the sum of the log variance are calculated and stored in the structure variable, which reduce the computation of output probability in the following decoding process.

: This function calls readParameter() internally.

See also:: readParameter()

static double * readVector	(	double *	vec,
		FILE *	fp,
		int	dim
	)			`[static]`

Read a vector from a given file stream.

Parameters:

`[in,out]`	vec	Vector
`[in]`	fp	File pointer
`[in]`	dim	Dimension of the vector

Return values:

	NULL	File read error
	otherwise	Pointer to the vector

int segCheckModelSet ( SEG_MODEL_SET * modelset )

Check the consistency of model parameter set.

This function checks if a given model parameter set is consistent in terms of the dimensionality of vectors and matrices.

Parameters:

[in] modelset Pointer to the model-set structure variable

Return values:

	NO_ERROR	Successful execution
	RTN_ERROR	Inconsistency found in the set

Author:: Yoshinori Shiga @ CVSSP, University of Surrey

int segMakeStrictLRTopology ( SEG_MODEL_SET * modelset )

Force models to maintain strict left-to-right topology.

Parameters:

[in,out] modelset Pointer to the model-set structure variable

Return values:

NO_ERROR

Successful execution

Author:: Yoshinori Shiga @ CVSSP, University of Surrey

Note:: This function scans all the transition probability matrices in the model set for any self loops. If present, it replaces their probabilities with zero.

SEG_MODEL_SET* segReadModelSet	(	char *	modelList,
		char *	tiedList,
		int	maxDur
	)

Read a set of multi-level segmental-HMMs in the file of model name list.

Parameters:

`[in]`	modelList	Name of file containing model file name list
`[in]`	tiedList	Name of file containing tied-phone list
`[in]`	maxDur	Maximal segment-duration

Return values:

	NULL	Memory allocation/File read error
	otherwise	Pointer to a read model set

Author:: Yoshinori Shiga @ CVSSP, University of Surrey

Note:: If the pointer "tiedList" is NULL, logical models are so built as to be identical to physical models.

: Users can set new maximal segment-duration (maxDur) different from ones specified per state in the model file. If a negative value is set to maxDur, the maximal segment-durations for each state in the model are applied.

: This function internally calls readModelSet(), tieModelParameters(), buildLogicalModels() and segCheckModelSet().

See also:: readModelSet(), tieModelParameters(), buildLogicalModels() and segCheckModelSet().

int segWriteDump	(	SEG_MODEL_SET *	modelset,
		char *	fName
	)

Write dump file contents.

This function creates a dump file, which includes the label name, maximum segment-duration, the number of states, and duration count and skip count results, for debugging purpose.

Parameters:

`[in]`	modelset	Pointer to the model-set structure variable
`[in]`	fName	Name of dump file

Return values:

	RTN_ERROR	File open error
	NO_ERROR	Successful execution

Author:: Yoshinori Shiga @ CVSSP, University of Surrey

int segWriteModelSet	(	SEG_MODEL_SET *	modelset,
		FILE *	fp
	)

Write a set of models to a file.

Parameters:

`[in]`	modelset	Pointer to the model-set structure variable
`[in]`	fp	File pointer

Return values:

	RTN_ERROR	Memory allocation error / File write error
	NO_ERROR	Successful execution

Author:: Yoshinori Shiga @ CVSSP, University of Surrey

Note:: This function outputs the current model set to the user-specified directory.

: The following functions are called internally: writeMatrix(), writeVector() and writeStateInfo().

See also:: writeMatrix(), writeVector() and writeStateInfo()

static int tieModelParameters ( SEG_MODEL_SET * modelset ) [static]

Tie model parameters.

The function makes pointer-links between model parameters to be tied.

Parameters:

[in] modelset Model set

Return values:

	RTN_ERROR	Illegal definitions found in the set
	NO_ERROR	Successful execution

static int writeMatrix	(	double **	mat,
		FILE *	fp,
		int	nrow,
		int	ncol
	)			`[static]`

Write a matrix to a file stream given.

Parameters:

`[in]`	mat	Matrix (2-D)
`[in]`	fp	File pointer
`[in]`	nrow	Number of rows of the matrix
`[in]`	ncol	Number of columns of the matrix

Return values:

	RTN_ERROR	File write error
	NO_ERROR	Successful execution

Note:: This function calls writeVector() internally.

See also:: writeVector()

static int writeStateInfo	(	FILE *	fp,
		SEG_STATE *	state
	)			`[static]`

Write model parameters for an emitting state.

Parameters:

`[in]`	fp	File pointer to which the parameters are written
`[in]`	state	Model parameters for the state

Return values:

	RTN_ERROR	File write error
	NO_ERROR	Pointer to the model parameter

Note:: This function writes mean, slope, variance and duration information in a variable of structure stateInfo (SEG_STATE) for an single emitting state, to stream fp.

: The following functions are called internally: writeVector() and writeMatrix().

See also:: writeVector() and writeMatrix().

static int writeVector	(	double *	vec,
		FILE *	fp,
		int	dim
	)			`[static]`

Write a vector to a given file stream.

Parameters:

`[in]`	vec	Vector
`[in]`	fp	File pointer
`[in]`	dim	Dimension of the vector

Return values:

	RTN_ERROR	File write error
	NO_ERROR	Successful execution

segModel.c File Reference

Functions

Detailed Description

Function Documentation