model.h

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

    @param i  state index (source)
    @param j  state index (target)
*/
  double ghmm_dmodel_get_transition(ghmm_dmodel* mo, int i, int j);

/**
    Set transition from state 'i' to state 'j' to value 'prob'.
    NOTE: No internal checks - model might get broken if used without care.
    @param mo model
    @param i  state index (source)
    @param j  state index (target)
    @param prob probabilitys
    
*/
  void ghmm_dmodel_set_transition (ghmm_dmodel * mo, int i, int j, double prob);

/**
   Writes a model in matrix format.
   @param file: output file
   @param mo:   model
*/
  void ghmm_dmodel_print (FILE * file, ghmm_dmodel * 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_dmodel_A_print (FILE * file, ghmm_dmodel * mo, 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_dmodel_B_print (FILE * file, ghmm_dmodel * 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_dmodel_Pi_print (FILE * file, ghmm_dmodel * mo, char *tab, char *separator,
                       char *ending);
/**
   Writes fix 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_dmodel_fix_print (FILE * file, ghmm_dmodel * mo, char *tab, char *separator,
                        char *ending);
/**
   Writes transposed 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_dmodel_A_print_transp (FILE * file, ghmm_dmodel * mo, char *tab,
                             char *separator, char *ending);
/**
   Writes transposed 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_dmodel_B_print_transp (FILE * file, ghmm_dmodel * mo, char *tab,
                             char *separator, char *ending);

/**
   Writes transposed 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_dmodel_Pi_print_transp (FILE * file, ghmm_dmodel * mo, char *tab,
                              char *ending);

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

/** Computes probabilistic distance of two models
    @return the distance
    @param m0  model used for generating random output
    @param m  model to compare with
    @param maxT  maximum output length (for HMMs with absorbing states multiple
                 sequences with a toal langth of at least maxT will be 
                 generated)
    @param symmetric  flag, whether to symmetrize distance (not implemented yet)
    @param verbose  flag, whether to monitor distance in 40 steps.
                    Prints to stdout (yuk!)
*/
  double ghmm_dmodel_prob_distance (ghmm_dmodel * m0, ghmm_dmodel * m, int maxT, int symmetric,
                              int verbose);

/** 
    Frees all memory from a ghmm_dstate, sets the pointers to NULL and 
    variables to zero.
    @author Peter Pipenbacher
    @param my_state  state to clean (\Ref{struct ghmm_dstate})
*/
  void ghmm_dstate_clean (ghmm_dstate * my_state);


  ghmm_dseq *ghmm_dmodel_label_generate_sequences (ghmm_dmodel * mo, int seed,
                                              int global_len, long seq_number,
                                              int Tmax);

/** 
    Calculates the right index for emission array b of state j in model mo
    given an observation obs and taking the state order into account,
    returns -1 if state order exceeds number of so far emitted characters
    @param MO:  model
    @param  S:  state id 
    @param  O:  integer observation to be updated with
    @param  T:  position of obs in sequence (time)
*/
#define get_emission_index(MO, S, O, T)   (((MO)->model_type & GHMM_kHigherOrderEmissions) ?    \
                                            ((MO)->order[S] > (T)) ? -1 :                       \
                                              (((MO)->emission_history*(MO)->M) %               \
                                              ghmm_ipow((MO), (MO)->M, (MO)->order[S]+1)+(O)) \
                                            : (O))

/**
   Updates emission history of model mo, discarding the oldest and 'adding' the
   new observation by using modulo and multiplication
   left-shift the history, truncate to history length and
   add the last observation
   @param MO:  model to be updated
   @param  O:  integer observation to be updated with
*/
#define update_emission_history(MO, O)   if ((MO)->model_type & GHMM_kHigherOrderEmissions)               \
                                              (MO)->emission_history = ((MO)->emission_history*(MO)->M) % \
                                                ghmm_ipow((MO), (MO)->M, (MO)->maxorder) + (O)


/**
   Updates emission history of model mo for backward algorithm by 'adding'
   observation obs to the left,
   (example: obs = 3
   2 0 0 1 --> 3 2 0 0 )
   removes the most significant position (right-shift) and add the last seen
   observation (left-shifted with the length of history)
   @param MO:  model to be updated
   @param  O:  integer observation to be updated with
*/
#define update_emission_history_front(MO, O)   if ((MO)->model_type & GHMM_kHigherOrderEmissions)       \
                                                 (MO)->emission_history =                               \
                                                   ghmm_ipow((MO), (MO)->M, (MO)->maxorder-1) * (O) + \
                                                   (MO)->emission_history / (MO)->M


/**
    Uses ighmm_cvector_normalize in vector.h
    Normalizes the transition and output probs for each state
    in the given model
    @return 0 if normalization went through
    @param mo: model to be normalized
*/
  int ghmm_dmodel_normalize (ghmm_dmodel * mo);

/**
   Add a specific level of noise to the model parameters
   @return     :        -1 on error, 0 else
   @param mo   :        a pointer to the model
   @param level:        amount of noise to use,
                        a noise level of 0.0 doesn't change the model
   @param seed :        seed for ramdom number generator
*/
  int ghmm_dmodel_add_noise (ghmm_dmodel * mo, double level, int seed);


/** 
   Allocates a new ghmm_dbackground struct and assigs the arguments to
   the respective fields. Note: The arguments need allocation outside of this
   function.
   
   @return     :               0 on success, -1 on error
   @param mo   :               one model
   @param cur  :               a id of a state
   @param times:               number of times the state cur is at least evaluated
*/
  int ghmm_dmodel_duration_apply (ghmm_dmodel * mo, int cur, int times);


/**
   Apply the background distributions to the emission probabilities of states of
   the model which have one specified (background_id[state_id] != kNoBackgroundDistribution).

   @return    :                -1 on error, 0 else
   @param mo  :                a pointer to the ghmm_dmodel
   @param background_weight:   a parameter controlling the weight given to the
                               background. Note, should be between 0 and 1.
*/
  int ghmm_dmodel_background_apply (ghmm_dmodel * mo, double *background_weight);


/** 
   Allocates a new ghmm_dbackground struct and assigs the arguments to
   the respective fields. Note: The arguments need allocation outside of this
   function.
   
   @return    :               new pointer to a ghmm_dbackground struct
   @param n   :               number of distributions
   @param order:              orders of the distribtions
   @param B:                  matrix of distribution parameters
*/
  ghmm_dbackground *ghmm_dbackground_alloc (int n, int m,
							    int *orders,
							    double **B);

  ghmm_dbackground *ghmm_dbackground_copy (ghmm_dbackground * bg);

  int ghmm_dbackground_free (ghmm_dbackground * bg);

/**
   Calculates the background distribution for a ghmm_dseq
   the calculated distribution is uniform, every ghmm_dstate with the same order
   has the same background distribution.
   Set more sophisticated background distribution from python.
   Caution: overwrites the pointer to previous defined background distributions!
   @return    : -1 on error, 0 else
   @param mo  :	a pointer to the ghmm_dmodel
   @param sq  : a pointer to a ghmm_dseq struct
   
*/
  int ghmm_dmodel_get_uniform_background (ghmm_dmodel * mo, ghmm_dseq * sq);

/**
   Calculates the squared distance between two compatible models.
   The distance is normalized by the number of parameters of the models.
   @return:      normalized squared distance
   @param mo:    first model
   @param m2:    second model
*/
  double ghmm_dmodel_distance(const ghmm_dmodel * mo, const ghmm_dmodel * m2);

/**
   Calculates a topological ordering of the silent states
   and saves it in the model. Detects cycles of silent states.
   @param mo:      model
*/
  void ghmm_dmodel_order_topological (ghmm_dmodel * mo);

/**
   Update the emissions according to the tie groups by computing the mean
   values within all groups.
   @param mo:      model
*/
  void ghmm_dmodel_update_tie_groups (ghmm_dmodel * mo);

/**
   Reads a xml file and returns an array of dmodel pointer
   @return           :array of dmodels, NULL on error
   @param file       :filename of the xml file
   @param mo_number  :address of an int to store the length of the returned array
*/
  ghmm_dmodel** ghmm_dmodel_xml_read(const char *filename, int* mo_number);

/**
   Writes an array of dmodel pointer in a xml-file
   @return           :-1 on error, 0 else
   @param file       :filename of the xml file
   @param mo         :an array of pointers to ghmm_dmodel
   @param mo_number  :length of the array
*/
  int ghmm_dmodel_xml_write(ghmm_dmodel** mo, const char *file, int mo_number);

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