/ghmm-0.7.0/ghmm/sdmodel.h

  1/*******************************************************************************
  2*
  3*       This file is part of the General Hidden Markov Model Library,
  4*       GHMM version __VERSION__, see http://ghmm.org
  5*
  6*       Filename: ghmm/ghmm/sdmodel.h
  7*       Authors:  Wasinee Rungsarityotin, Benjamin Georgi
  8*
  9*       Copyright (C) 1998-2004 Alexander Schliep 
 10*       Copyright (C) 1998-2001 ZAIK/ZPR, Universitaet zu Koeln
 11*	Copyright (C) 2002-2004 Max-Planck-Institut fuer Molekulare Genetik, 
 12*                               Berlin
 13*                                   
 14*       Contact: schliep@ghmm.org             
 15*
 16*       This library is free software; you can redistribute it and/or
 17*       modify it under the terms of the GNU Library General Public
 18*       License as published by the Free Software Foundation; either
 19*       version 2 of the License, or (at your option) any later version.
 20*
 21*       This library is distributed in the hope that it will be useful,
 22*       but WITHOUT ANY WARRANTY; without even the implied warranty of
 23*       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 24*       Library General Public License for more details.
 25*
 26*       You should have received a copy of the GNU Library General Public
 27*       License along with this library; if not, write to the Free
 28*       Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
 29*
 30*
 31*       This file is version $Revision: 1191 $ 
 32*                       from $Date: 2005-06-21 11:56:12 +0200 (Tue, 21 Jun 2005) $
 33*             last change by $Author: cic99 $.
 34*
 35*******************************************************************************/
 36#ifndef SDMODEL_H
 37#define SDMODEL_H
 38
 39#ifdef __cplusplus
 40extern "C" {
 41#endif
 42
 43/**@name HMM-Modell */
 44/*@{ (Doc++-Group: model) */
 45
 46/** @name state
 47    The basic structure, keeps all parameters that belong to a state. 
 48*/
 49  struct sdstate {
 50  /** Initial probability */
 51    double pi;
 52  /** Output probability */
 53    double *b;
 54  /** ID of the following state */
 55    int *out_id;
 56  /** ID of the previous state */
 57    int *in_id;
 58
 59  /** transition probs to successor states. It is a
 60   matrix in case of mult. transition matrices (COS > 1)*/
 61    double **out_a;
 62  /** transition probs from predecessor states. It is a
 63   matrix in case of mult. transition matrices (COS > 1) */
 64    double **in_a;
 65
 66  /** Transition probability to a successor 
 67      double *out_a; */
 68  /** Transition probablity to a precursor 
 69      double *in_a;*/
 70
 71  /** Number of successor states */
 72    int out_states;
 73  /** Number of precursor states */
 74    int in_states;
 75  /** if fix == 1 --> b stays fix during the training */
 76    int fix;
 77    char *label;
 78    /* XXX Specific variable for ProfileHMM to count the number of
 79       match states. Not elegant solution.
 80       WS: if 1 then counts me, 0 don't count me */
 81    int countme;
 82  };
 83  typedef struct sdstate sdstate;
 84
 85/** @name model
 86    The complete HMM. Contains all parameters, that define a HMM.
 87*/
 88  struct sdmodel {
 89  /** Number of states */
 90    int N;
 91  /** Number of outputs */
 92    int M;
 93 /** smodel includes continuous model with one transition matrix 
 94      (cos  is set to 1) and an extension for models with several matrices
 95      (cos is set to a positive integer value > 1).*/
 96    int cos;
 97  /** Vector of the states */
 98    sdstate *s;
 99  /** Prior for the a priori probability for the model.
100      A value of -1 indicates that no prior is defined. */
101    double prior;
102
103  /** Contains bit flags for various model extensions such as
104      kSilentStates, kTiedEmissions (see ghmm.h for a complete list)
105  */
106
107  /** pointer to class function   */
108    int (*get_class) (int *, int);
109
110    /*int (*get_class)(const double*,int,double*); */
111
112  /** Contains bit flags for various model extensions such as
113      kSilentStates, kTiedEmissions (see ghmm.h for a complete list)
114  */
115    int model_type;
116
117  /** Flag variables for each state indicating whether it is emitting
118      or not. 
119      Note: silent != NULL iff (model_type & kSilentStates) == 1  */
120    int *silent;
121      /*AS*/ int topo_order_length;
122      /*WR*/ int *topo_order;
123    /*WR*/};
124  typedef struct sdmodel sdmodel;
125
126
127#ifdef __cplusplus
128}
129#endif
130/*
131  Important: The inclusion of sequence.h ist not done before this point in
132  order to avoid error by compiling.
133*/
134#include <ghmm/sequence.h>
135#include <ghmm/scanner.h>
136#ifdef __cplusplus
137extern "C" {
138#endif
139
140
141  /** Frees the memory of a model.
142      @return 0 for succes; -1 for error
143      @param mo:  pointer to a model */
144  int sdmodel_free (sdmodel ** mo);
145
146  int sdmodel_initSilentStates (sdmodel * mo);
147
148  /** 
149      Produces sequences to a given model. All memory that is needed for the 
150      sequences is allocated inside the function. It is possible to define
151      the length of the sequences global (global_len > 0) or it can be set 
152      inside the function, when a final state in the model is reach (a state
153      with no output). If the model has no final state, the sequences will
154      have length MAX_SEQ_LEN.
155      @return             pointer to an array of sequences
156      @param mo:          model
157      @param seed:        initial parameter for the random value generator
158      (an integer). If seed == 0, then the random value
159      generator is not initialized.
160      @param global_len:  length of sequences (=0: automatically via final states)
161      @param seq_number:  number of sequences
162	  @param T_max:  maximal number of consecutive silent states in model (used to
163	  identify silent circles).
164  */
165  sequence_t *sdmodel_generate_sequences (sdmodel * mo, int seed,
166                                          int global_len, long seq_number,
167                                          int Tmax);
168
169
170  /**
171     Copies a given model. Allocates the necessary memory.
172     @return copy of the model
173     @param mo:  model to copy */
174  sdmodel *sdmodel_copy (const sdmodel * mo);
175
176  /** Utility for converting between single discrete model and switching model */
177  model *sdmodel_to_model (const sdmodel * mo, int kclass);
178
179  /** */
180  void model_to_sdmodel (const model * mo, sdmodel * smo, int klass);
181
182  /**
183     Writes a model in matrix format.
184     @param file: output file
185     @param mo:   model
186  */
187  void sdmodel_print (FILE * file, sdmodel * mo);
188
189
190  /**
191     Writes transition matrix of a model.
192     @param file: output file
193     @param mo:   model
194     @param tab:  format: leading tabs
195     @param separator: format: seperator for columns
196     @param ending:    format: end of a row  
197  */
198  void sdmodel_Ak_print (FILE * file, sdmodel * mo, int k, char *tab,
199                         char *separator, char *ending);
200  /**
201     Writes output matrix of a model.
202     @param file: output file
203     @param mo:   model
204     @param tab:  format: leading tabs
205     @param separator: format: seperator for columns
206     @param ending:    format: end of a row  
207  */
208  void sdmodel_B_print (FILE * file, sdmodel * mo, char *tab, char *separator,
209                        char *ending);
210
211  /**
212     Writes initial allocation vector of a matrix.
213     @param file: output file
214     @param mo:   model
215     @param tab:  format: leading Tabs
216     @param separator: format: seperator for columns
217     @param ending:    format: end of a row  
218  */
219  void sdmodel_Pi_print (FILE * file, sdmodel * mo, char *tab,
220                         char *separator, char *ending);
221
222  /*============================================================================*/
223  /** sdviterbi is working for switching discrete model
224   *  sdmodel_topo_ordering -- need to be implemented with DFS (as in model_util.c)
225   *============================================================================
226   **/
227
228  void sdmodel_topo_ordering (sdmodel * mo);
229
230  int *sdviterbi (sdmodel * mo, int *o, int len, double *log_p);
231
232  /** Forward-Algorithm.
233      Calculates alpha[t][i], scaling factors scale[t] and log( P(O|lambda) ) for
234      a given double sequence and a given model.
235      @param smo      model
236      @param O        sequence
237      @param length: length of sequence
238      @param alpha:  alpha[t][i]
239      @param scale:   a reference for double type, scale factors
240      @param log\_p:  a reference for double type, log likelihood log( P(O|lambda) )
241      @return 0 for success, -1 for error
242  */
243  int sdfoba_forward (sdmodel * mo, const int *O, int len, double **alpha,
244                      double *scale, double *log_p);
245
246
247  /** Descale
248      descales the alpha matrix from the forward algorithm
249      @param alpha: alpha matrix from forward
250      @param scale: scale vector from forward
251      @param t:     number of timesteps
252      @param n:     number of states
253      @param newalpha: unscaled alpha matrix
254      @return 0 for success, -1 for error
255  */
256  int sdfoba_descale (double **alpha, double *scale, int t, int n,
257                      double **newalpha);
258
259
260/**
261   Calculates the sum log( P( O | lambda ) ).
262   Sequences, that can not be generated from the given model, are neglected.
263   @return    log(P)
264   @param mo model
265   @param sq sequences       
266*/
267  double sdmodel_likelihood (sdmodel * mo, sequence_t * sq);
268
269
270/** 
271    Writes the parameters of a model sorted by states. 
272    Is not very concise.   
273    @param file: output file
274    @param mo:   model
275*/
276  void sdmodel_states_print (FILE * file, sdmodel * mo);
277
278
279#ifdef __cplusplus
280}
281#endif
282#endif
283/*@} (Doc++-Group: model) */