ghmmwrapper.i

来自「General Hidden Markov Model Library 一个通用」· I 代码 · 共 1,725 行 · 第 1/4 页

  /** Number of states */
  int N;
  /** Number of outputs */   
  int M;   
  /** Vector of the states */
  state *s; 
  /** The a priori probability for the model.
      A value of -1 indicates that no prior is defined. 
      Note: this is not to be confused with priors on emission
      distributions*/
  double prior;

  /* contains a arbitrary name for the model */
  char* name;
  
   /** Contains bit flags for varios 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; /*AS*/

  /** 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

      Note: tied_to != NULL iff (model_type & kTiedEmissions) == 1  */
  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 state.order.

      Note: state.order != NULL iff (model_type & kHigherOrderEmissions) == 1  */
  
  /** background_distributions is a pointer to a
      background_distributions 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) == 1  */
  int *background_id;
  background_distributions* bp;

  /** (WR) added these variables for topological ordering of silent states 
      Condition: topo_order != NULL iff (model_type & kSilentStates) == 1
   */
  int* topo_order; 
  int  topo_order_length;


};
typedef struct model model;

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

/**
   Reads in ASCII data to initialize an array of models. Memory allocation for
   the models is done here.
   @return array of pointers to the models
   @param filename:   the ASCII input file
   @param mo_number:  filled with number of models read */
extern model** model_read(char *filename, int *mo_number);

/**
   Writes a model in matrix format.
   @param file: output file
   @param mo:   model
*/
void model_print(FILE *file, model *mo); 


/**
   Produces simple left-right models given sequences. 
   The function "model_generate_from_sequence" is called for each 
   model that should be made. The sequences are read in from the
   ASCII file and thrown away again when leaving the function.
   @return vector of models
   @param s:          scanner
   @param new_models: number of models to produce */
extern model **model_from_sequence_ascii(scanner_t *s, long *mo_number);

/** 
    Produces simple left-right models given sequences. The sequences
    are not read in from file, but exists already as a structur.
    @return vector of models
    @param s:          scanner
    @param new_models: number of models to produce */
extern model **model_from_sequence(sequence_t *sq, long *mo_number);

/**
   Copies a given model. Allocates the necessary memory.
   @return copy of the model
   @param mo:  model to copy */
extern model*  model_copy(const model *mo);

/**
   Tests if all standardization requirements of model are fulfilled. 
   (That is, if the sum of the probabilities is 1).
   @return 0 for succes; -1 for error
   @param mo:  model to test */
extern int     model_check(const model* mo);

/**
   Tests if number of states and number of outputs in the models match.
   @return 0 for succes; -1 for error
   @param mo:           vector of models
   @param model_number: numbr of models */
extern int     model_check_compatibility(model **mo, int model_number);

/**
   Produces a model, which generates the given sequence with probability 1.
   The model is a strict left-right model with one state for each element 
   in the sequence and the output in state i is the i-th value in the sequence 
   with probability 1. The model also has a final state, a state with no output.
   @return         pointer to the produced model 
   @param seq:      sequence
   @param seq_len:  length of the sequence
   @param anz_symb: number of symbols in the sequence
*/
extern model*  model_generate_from_sequence(const int *seq, int seq_len, 
				     int anz_symb);

/** 
    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
*/
extern sequence_t *model_generate_sequences(model* mo, int seed, int global_len,
				     long seq_number, int Tmax);

/**
   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       
*/
extern double model_likelihood(model *mo, sequence_t *sq);


/** 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 model_prob_distance(model *m0, model *m, int maxT, int symmetric, int verbose);


/******** Reestimate Baum-Welch (reestimate.c) *******/
extern int reestimate_baum_welch(model *mo, sequence_t *sq);
extern int reestimate_baum_welch_nstep(model *mo, sequence_t *sq, int max_step, double likelihood_delta);

extern void reestimate_update_tie_groups(model *mo);

/**
  Baum Welch training for StateLabelHMMs
*/
extern int reestimate_baum_welch_label(model *mo, sequence_t *sq);

/**
  Just like reestimate_baum_welch_label, but you can limit
  the maximum number of steps
  */
extern int reestimate_baum_welch_nstep_label(model *mo, sequence_t *sq, int max_step, double likelihood_delta);



/********  Gradient Descent (gradescent.c) ********/
/**
   Trains the model with a set of annotated sequences until the training
   converges using gradient descent.
   Model must not have silent states. (checked in Python wrapper)
   @return            0/-1 success/error
   @param mo:         reference to a model pointer
   @param sq:         struct of annotated sequences
   @param eta:
 */
extern int gradient_descent(model** mo, sequence_t *sq);

/********  K-Best decoding (kbest.c) ********/
/**
   Calculates the most probable labeling for the given sequence in the given
   model using k-best decoding.
   @return array of labels (internal representation)
   @param mo:         pointer to a model
   @param o_seq:      output sequence (array of internal representation chars)
   @param seq_len:    length of output sequence
   */
extern int* kbest(model* mo, int* o_seq, int seq_len, int k, double* log_p);

/******* Viterbi (viterbi.c)*******/
/**
  Viterbi algorithm. Calculates the Viterbi path (the optimal path trough
  the model) and the Viterbi probability to a given model and a given 
  sequence.
  @return Viterbi path
  @param mo:    model
  @param o:     sequence
  @param len:   length of the sequence
  @param log_p: probability of the sequence in the Viterbi path
  */

// XXX use swig OUTPUT typemap
extern int *viterbi(model *mo, int *o, int len, double *log_p);

/**
  Calculates the logarithmic probability to a given path through the 
  states (does not have to be the Viterbi path), given sequence and
  a model.
  @param mo:        model
  @param o:         sequence
  @param len:       length of the sequence
  @param state_seq: path through the states
  @return log P
  */
extern double viterbi_logp(model *mo, int *o, int len, int *state_seq);


/********  Discriminative Training (discrime.c) ********/
/**
   Trains two or more models to opimise the discrimination between the
   classes in the trainingset.
   The models must have the same topology. (checked)
   @return                 0/-1 success/error
   @param mo:              array of pointers to some models
   @param sqs:             array of annotated sequence sets
   @param noC:             number of classes
 */
extern int discriminative(model** mo, sequence_t** sqs, int noC, int gradient);

/**
   Returns the value of the in this discriminative training algorithm optimised
   function for a tupel of HMMs and sequencesets.
   @return                 value of funcion
   @param mo:              array of pointers to some models
   @param sqs:             array of annotated sequence sets
   @param noC:             number of classes
*/
extern double discrime_compute_performance(model** mo, sequence_t** sqs, int noC);

extern model** discrime_modelarray_alloc(int size);
extern void discrime_modelarray_dealloc(model** mos);
extern void discrime_modelarray_setptr(model** mos, model* mo, int pos);
extern model* discrime_modelarray_getptr(model** mos, int pos);

extern sequence_t** discrime_seqarray_alloc(int size);
extern void discrime_seqarray_dealloc(sequence_t** seqs);

extern void discrime_seqarray_setptr(sequence_t** seqs, sequence_t* seq, int pos);
extern sequence_t* discrime_seqarray_getptr(sequence_t** seqs, int pos);


/******* Forward , backward (foba.c) ******/

/** 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 smo      model
  @param O        sequence
  @param length: length of sequence
  @param alpha:  alpha[t][i]
  @param scale:  scale factors
  @param log\_p:  log likelihood log( P(O|lambda) )
  @return 0 for success, -1 for error
  */
extern int foba_forward(model *mo, const int *O, int length, double **alpha, 
		 double *scale, double *log_p);

/** 
  Backward-Algorithm. 
  Calculates beta[t][i] given an integer sequence and a model. Scale factors 
  given as parameter (come from foba\_forward).
  @param  mo      model
  @param O          sequence
  @param length   length of sequence
  @param beta     beta[t][i]
  @param scale    scale factors
  @return 0 for success, -1 for error
  */
extern int foba_backward(model *mo, const int *O, int length, double **beta, 
		 const double *scale);

/**
  Calculation of  log( P(O|lambda) ). 
  Done by calling foba\_forward. Use this function if only the
  log likelihood and not alpha[t][i] is needed.
  @param  mo      model
  @param O        sequence
  @param len       length of sequence
  @param log\_p    log likelihood log( P(O|lambda) )
  @return 0 for success, -1 for error
  */
extern int foba_logp(model *mo, const int *O, int len, double *log_p);

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

/** Forward-Algorithm (lean version).
  Calculates log( P(O|lambda) ) for a given double sequence and a given model.
  @param smo      model
  @param O        sequence
  @param length: length of sequence
  @param log\_p:  log likelihood log( P(O|lambda) )
  @return 0 for success, -1 for error
  */
int foba_forward_lean(model *mo, const int *O, int len, double *log_p); 


/* Labeled HMMs */
extern int foba_label_forward(model *mo, const int *O, const int *label, int len, double **alpha, double *scale, double *log_p);
extern int foba_label_logp(model *mo, const int *O, const int *label, int len, double *log_p);
extern int foba_label_backward(model *mo, const int *O, const int *label, int len, double **alpha, double *scale, double *log_p);


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

extern background_distributions *model_copy_background_distributions(background_distributions *bg);
extern int model_free_background_distributions(background_distributions *bg);

/** 
	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   j:  state id 
	@param obs:  integer observation to be updated with
    @param   t:  position of obs in sequence (time)
*/ 
extern int get_emission_index (model* mo, int j , int obs, int t );


/**
	Updates emission history of model mo, discarding the oldest and 'adding' the
	new observation by using modulo and multiplication	
    @param  mo:  model to be updated
	@param obs:  integer observation to be updated with
*/
extern void update_emission_history(model* mo, int obs);


/**
	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 )
	@param  mo:  model to be updated
	@param obs:  integer observation to be updated with
*/
extern void update_emission_history_front(model* mo, int obs);


/**
    Uses vector_normalize in vector.h
    Normalizes the transition and output probs for each state
    in the given model
    @author Heval Benav
    @return 0 if normalization went through
	@param mo: model to be normalized

*/
extern int model_normalize(model* 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,