smodel.h

General Hidden Markov Model Library 一个通用的隐马尔科夫模型的C代码库

/*******************************************************************************
*
*       This file is part of the General Hidden Markov Model Library,
*       GHMM version 0.8_beta1, see http://ghmm.org
*
*       Filename: ghmm/ghmm/smodel.h
*       Authors:  Bernhard Knab, Benjamin Georgi
*
*       Copyright (C) 1998-2004 Alexander Schliep 
*       Copyright (C) 1998-2001 ZAIK/ZPR, Universitaet zu Koeln
*	Copyright (C) 2002-2004 Max-Planck-Institut fuer Molekulare Genetik, 
*                               Berlin
*                                   
*       Contact: [e-mail]             
*
*       This library is free software; you can redistribute it and/or
*       modify it under the terms of the GNU Library General Public
*       License as published by the Free Software Foundation; either
*       version 2 of the License, or (at your option) any later version.
*
*       This library is distributed in the hope that it will be useful,
*       but WITHOUT ANY WARRANTY; without even the implied warranty of
*       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
*       Library General Public License for more details.
*
*       You should have received a copy of the GNU Library General Public
*       License along with this library; if not, write to the Free
*       Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*
*
*       This file is version $Revision: 1831 $ 
*                       from $Date: 2007-05-23 14:18:45 +0200 (Wed, 23 May 2007) $
*             last change by $Author: grunau $.
*
*******************************************************************************/
#ifndef GHMM_SMODEL_H
#define GHMM_SMODEL_H

#ifdef __cplusplus
extern "C" {
#endif

#include "ghmm.h"
#include "scanner.h"


/**@name SHMM-Modell */
/*@{ (Doc++-Group: smodel) */

/** Continuous HMM. Structures and function. 
    ghmm_cmodel includes continuous ghmm_dmodel with one transition matrix 
    (COS  is set to 1) and an extension for
    models with several matrices
    (COS is set to a value greater than 1). In the latter case
    a suitable (depending on the spezific application) function 
    sequence\_get\_class has to be defined */

/**
   typedef density\_t fuer ghmm_cmodel.
*/
  typedef enum {
    normal,
    normal_right,
    normal_approx,
    normal_left,
    uniform,
    density_number
  } ghmm_density_t;


/** @name ghmm_cstate
    Structure for one state.
*/
  typedef struct ghmm_cstate {
  /** Number of output densities per state */
    int M;
  /** initial prob. */
    double pi;
  /** IDs of successor states */
    int *out_id;
  /** IDs of predecessor states */
    int *in_id;
  /** transition probs to successor states. It is a
   matrix in case of mult. transition matrices (COS > 1)*/
    double **out_a;
  /** transition probs from predecessor states. It is a
   matrix in case of mult. transition matrices (COS > 1) */
    double **in_a;
  /** number of  successor states */
    int out_states;
  /** number of  predecessor states */
    int in_states;
  /** weight vector for output function components */
    double *c;
  /** mean vector for output functions (normal density and truncated normal
      density) or max value for uniform distribution */
    double *mue;
  /** variance vector for output functions or min value for uniform distribution */
    double *u;
  /** value where the normal is truncated (only for truncated distributions) */
    double *a;
  /** flag for fixation of parameter. If fix = 1 do not change parameters of
      output functions, if fix = 0 do normal training. Default is 0. */
    int fix;
  /** Flag for density function for each component of the mixture
      0: normal density, 1: truncated normal (right side) 
      density, 2: approximated normal density, 3: truncated normal (left side)
      4: uniform distribution */
    ghmm_density_t *density;
  /**  array of flags for fixing mixture components in the reestimation
        mixture_fix[i] = 1 means mu and sigma of component i are fixed.  **/
    int *mixture_fix;
  /** contains a description of the state (null terminated utf-8)*/
  unsigned char * desc;
  /** x coordinate position for graph representation plotting **/
  int xPosition;
  /** y coordinate position for graph representation plotting **/
  int yPosition;
  } ghmm_cstate;

  struct ghmm_cmodel;

  typedef struct ghmm_cmodel_class_change_context {

    /* Names of class change module/function (for python callback) */
    char *python_module;
    char *python_function;

    /* index of current sequence */
    int k;

    /** pointer to class function */
    int (*get_class) (struct ghmm_cmodel *, double *, int, int);


    /* space for any data necessary for class switch, USER is RESPONSIBLE */
    void *user_data;

  } ghmm_cmodel_class_change_context;

/** @name ghmm_cmodel
    continous HMM    
*/
  typedef struct ghmm_cmodel {
  /** Number of states */
    int N;
  /** Maximun number of components in the states */
    int M;
  /** ghmm_cmodel includes continuous model with one transition matrix 
      (cos  is set to 1) and an extension for models with several matrices
      (cos is set to a positive integer value > 1).*/
    int cos;
  /** prior for a priori prob. of the model. -1 means no prior specified (all
      models have equal prob. a priori. */
    double prior;

  /* contains a arbitrary name for the model (null terminated utf-8) */
  unsigned char * name;

  /** Contains bit flags for varios model extensions such as
      kSilentStates (see ghmm.h for a complete list)
  */
  int model_type;

  /** All states of the model. Transition probs are part of the states. */
    ghmm_cstate *s;

    /* pointer to a ghmm_cmodel_class_change_context struct necessary for multiple transition
       classes */
    ghmm_cmodel_class_change_context *class_change;

  } ghmm_cmodel;



/* don't include this earlier: in sequence.h ghmm_cmodel has to be known */
#include "sequence.h"

  int ghmm_cmodel_class_change_alloc (ghmm_cmodel * smo);

/** Allocates a cstate 
    @return 0: success, -1: error
    @param s           pointer to the allocated states
    @param M           maximal number of densities of the state
    @param in_states   number of incoming transitions
    @param out_states  number of outgoing transitions
    @param cos         number of transition classes
*/
  int ghmm_cstate_alloc (ghmm_cstate * s, int M,
			  int in_states, int out_states, int cos);

/** Alloc model
    @return allocated cmodel, -1: error
    @param N number of states in the model 
    @param modeltype type of the model
*/
  ghmm_cmodel * ghmm_cmodel_calloc( int N, int modeltype);

/** Free memory ghmm_cmodel 
    @return 0: success, -1: error
    @param smo  pointer pointer of ghmm_cmodel */
  int ghmm_cmodel_free (ghmm_cmodel ** smo);

/**
   Copies one smodel. Memory alloc is here.
   @return pointer to ghmm_cmodel copy
   @param smo   ghmm_cmodel to be copied  */
  ghmm_cmodel *ghmm_cmodel_copy (const ghmm_cmodel * smo);

/**
   Checks if ghmm_cmodel is well definded. E.g. sum pi = 1, only positive values 
   etc.
   @return 0 if ghmm_cmodel is ok, -1 for error
   @param smo   ghmm_cmodel for  checking
*/
  int ghmm_cmodel_check (const ghmm_cmodel * smo);

/**
   For a vector of smodels: check that the number of states and the number
   of output function components are the same in each smodel.
   @return 0 if smodels are  ok, -1 for error
   @param smo:            vector of smodels for checking
   @param smodel_number:  number of smodels
 */
  int ghmm_cmodel_check_compatibility (ghmm_cmodel ** smo, int smodel_number);

/**
   Generates random symbol.
   Generates one random number for a specified state and specified
   output component of the given smodel.
   @return           random number
   @param smo:       ghmm_cmodel
   @param state:     state
   @param m:         index of output component
*/
  double ghmm_cmodel_get_random_var (ghmm_cmodel * smo, int state, int m);


/** 
    Produces sequences to a given model. All memory that is needed for the 
    sequences is allocated inside the function. It is possible to define
    the length of the sequences global (global_len > 0) or it can be set