sdmodel.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/sdmodel.h
*       Authors:  Wasinee Rungsarityotin, 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: 1790 $ 
*                       from $Date: 2006-11-15 11:43:16 +0100 (Wed, 15 Nov 2006) $
*             last change by $Author: grunau $.
*
*******************************************************************************/
#ifndef GHMM_SDMODEL_H
#define GHMM_SDMODEL_H

#include "ghmm.h"

#ifdef __cplusplus
extern "C" {
#endif

/**@name HMM-Modell */
/*@{ (Doc++-Group: model) */

/** @name ghmm_dsstate
    The basic structure, keeps all parameters that belong to a state. 
*/
  struct ghmm_dsstate {
  /** Initial probability */
    double pi;
  /** Output probability */
    double *b;
  /** ID of the following state */
    int *out_id;
  /** ID of the previous state */
    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 precursor states */
    int in_states;
  /** if fix == 1 --> b stays fix during the training */
    int fix;

  /* XXX Specific variable for ProfileHMM to count the number of
     match states. Not elegant solution.
     WS: if 1 then counts me, 0 don't count me */
    int countme;

  /** contains a description of the state (null terminated utf-8)*/
    unsigned char * desc;
  /** Position for graphical editing */
    int xPosition;
    int yPosition;
  };

  typedef struct ghmm_dsstate ghmm_dsstate;

/** @name ghmm_dmodel
    The complete HMM. Contains all parameters, that define a HMM.
*/
  struct ghmm_dsmodel {
  /** Number of states */
    int N;
  /** Number of outputs */
    int M;
  /** ghmm_dsmodel 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;
  /** Vector of the states */
    ghmm_dsstate *s;
  /** Prior for the a priori probability for the model.
      A value of -1 indicates that no prior is defined. */
    double prior;

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

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

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

  /** Flag variables for each state indicating whether it is emitting
      or not. 
      Note: silent != NULL iff (model_type & kSilentStates) == 1  */
    int *silent;

    /** Int variable for the maximum level of higher order emissions */
    int maxorder;
    /** saves the history of emissions as int, 
        the nth-last emission is (emission_history * |alphabet|^n+1) % |alphabet|
        see ...*/
    int emission_history;

    /** Flag variables for each state indicating whether the states emissions
        are tied to another state. Groups of tied states are represented
        by their tie group leader (the lowest numbered member of the group).

        tied_to[s] == kUntied  : s is not a tied state

        tied_to[s] == s        : s is a tie group leader

        tied_to[t] == s        : t is tied to state s (t>s)

        Note: tied_to != NULL iff (model_type & kTiedEmissions) != 0  */
    int *tied_to;

    /** Note: State store order information of the emissions.
        Classic HMMS have emission order 0, that is the emission probability
        is conditioned only on the state emitting the symbol.

        For higher order emissions, the emission are conditioned on the state s
        as well as the previous emission_order[s] observed symbols.

        The emissions are stored in the state's usual double* b. The order is
        set order.

        Note: order != NULL iff (model_type & kHigherOrderEmissions) != 0  */
    int * order;

    /** ghmm_dbackground is a pointer to a
        ghmm_dbackground structure, which holds (essentially) an
        array of background distributions (which are just vectors of floating
        point numbers like state.b).

        For each state the array background_id indicates which of the background
        distributions to use in parameter estimation. A value of kNoBackgroundDistribution
        indicates that none should be used.

        Note: background_id != NULL iff (model_type & kHasBackgroundDistributions) != 0  */
    int *background_id;
    ghmm_dbackground *bp;
    
    /** (WR) added these variables for topological ordering of silent states 
        Condition: topo_order != NULL iff (model_type & kSilentStates) != 0  */
    int *topo_order;
    int topo_order_length;
    
    /** pow_lookup is a array of precomputed powers
        It contains in the i-th entry M (alphabet size) to the power of i
        The last entry is maxorder+1 */
    int *pow_lookup;

  /** Store for each state a class label. Limits the possibly state sequence

      Note: label != NULL iff (model_type & kLabeledStates) != 0  */
    int* label;
    ghmm_alphabet* label_alphabet;

    ghmm_alphabet* alphabet;
  };

  typedef struct ghmm_dsmodel ghmm_dsmodel;


#ifdef __cplusplus
}
#endif
/*
  Important: The inclusion of sequence.h ist not done before this point in
  order to avoid error by compiling.
*/
#include "sequence.h"
#include "scanner.h"
#ifdef __cplusplus
extern "C" {
#endif


  /** Frees the memory of a model.
      @return 0 for succes; -1 for error
      @param mo:  pointer to a ghmm_dsmodel */
  int ghmm_dsmodel_free (ghmm_dsmodel ** mo);

  /** Allocates space for an empty dsmodel.
      @return   pointer to the created model on succes; 0 on error
      @param M:         number of emissions
      @param N:         number of states
      @param modeltype: bit field for model type
      @param cos:       number of transition classes
      @param inDegVec:  array of incomming degree for every state
      @param outDegVec: array of outgoing degree for every state
  */
  ghmm_dsmodel * ghmm_dsmodel_calloc(int M, int N, int modeltype, int cos,
				     int * inDegVec, int * outDegVec);


  int ghmm_dsmodel_init_silent_states (ghmm_dsmodel * mo);

  /** 
      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 
      inside the function, when a final state in the model is reach (a state
      with no output). If the model has no final state, the sequences will
      have length MAX_SEQ_LEN.
      @return             pointer to an array of sequences
      @param mo:          model
      @param seed:        initial parameter for the random value generator
      (an integer). If seed == 0, then the random value
      generator is not initialized.
      @param global_len:  length of sequences (=0: automatically via final states)
      @param seq_number:  number of sequences
      @param T_max:  maximal number of consecutive silent states in model (used to
	  identify silent circles).
  */
  ghmm_dseq * ghmm_dsmodel_generate_sequences(ghmm_dsmodel * mo, int seed,
					 int global_len, long seq_number,
					 int Tmax);

  /**
     Copies a given model. Allocates the necessary memory.
     @returns a copy of the model
     @param mo:  dmodel to copy */
  ghmm_dsmodel * ghmm_dsmodel_copy(const ghmm_dsmodel * mo);

  /** Utility for converting between single discrete model and switching model */
  ghmm_dmodel * ghmm_dsmodel_to_dmodel(const ghmm_dsmodel * mo, int kclass);

  /** */
  void ghmm_dsmodel_from_dmodel (ghmm_dsmodel * smo, const ghmm_dmodel * mo, int klass);

#ifdef GHMM_OBSOLETE 
  /**
     Writes a model in matrix format.
     @param file: output file
     @param mo:   model
  */
  void sdmodel_print (FILE * file, ghmm_dsmodel * mo);


  /**
     Writes transition matrix of a model.
     @param file: output file
     @param mo:   model
     @param tab:  format: leading tabs
     @param separator: format: seperator for columns
     @param ending:    format: end of a row  
  */
  void ghmm_dsmodel_Ak_print (FILE * file, ghmm_dsmodel * mo, int k, char *tab,
                         char *separator, char *ending);
  /**
     Writes output matrix of a model.
     @param file: output file
     @param mo:   model
     @param tab:  format: leading tabs
     @param separator: format: seperator for columns
     @param ending:    format: end of a row  
  */
  void ghmm_dsmodel_B_print (FILE * file, ghmm_dsmodel * mo, char *tab, char *separator,
                        char *ending);

  /**
     Writes initial allocation vector of a matrix.
     @param file: output file
     @param mo:   model
     @param tab:  format: leading Tabs
     @param separator: format: seperator for columns
     @param ending:    format: end of a row  
  */
  void ghmm_dsmodel_Pi_print (FILE * file, ghmm_dsmodel * mo, char *tab,
                         char *separator, char *ending);
#endif

  /*============================================================================*/
  /** ghmm_dsmodel_viterbi is working for switching discrete model
   *  ghmm_dsmodel_topo_order -- need to be implemented with DFS (as in model_util.c)
   *============================================================================
   **/

  void ghmm_dsmodel_topo_order (ghmm_dsmodel * mo);

  int *ghmm_dsmodel_viterbi (ghmm_dsmodel * mo, int *o, int len, double *log_p);

  /** Forward-Algorithm.
      Calculates alpha[t][i], scaling factors scale[t] and log( P(O|lambda) ) for
      a given double sequence and a given model.
      @param mo:      model
      @param O        sequence
      @param length: length of sequence
      @param alpha:  alpha[t][i]
      @param scale:   a reference for double type, scale factors
      @param log\_p:  a reference for double type, log likelihood log( P(O|lambda) )
      @return 0 for success, -1 for error
  */
  int ghmm_dsmodel_forward (ghmm_dsmodel * mo, const int *O, int len, double **alpha,
                      double *scale, double *log_p);


  /** Descale
      descales the alpha matrix from the forward algorithm
      @param alpha: alpha matrix from forward
      @param scale: scale vector from forward
      @param t:     number of timesteps
      @param n:     number of states
      @param newalpha: unscaled alpha matrix
      @return 0 for success, -1 for error
  */
  int ghmm_dsmodel_forward_descale (double **alpha, double *scale, int t, int n,
                      double **newalpha);


/**
   Calculates the sum log( P( O | lambda ) ).
   Sequences, that can not be generated from the given model, are neglected.
   @return    log(P)
   @param mo model
   @param sq sequences       
*/
  double ghmm_dsmodel_likelihood (ghmm_dsmodel * mo, ghmm_dseq * sq);


/** 
    Writes the parameters of a model sorted by states. 
    Is not very concise.   
    @param file: output file
    @param mo:   model
*/
  void ghmm_dsmodel_states_print (FILE * file, ghmm_dsmodel * mo);


#ifdef __cplusplus
}
#endif
#endif
/*@} (Doc++-Group: model) */