hmmer-3.3/src/modelstats.c
/* Function:  p7_hmm_CompositionKLD()
 * Synopsis:  A statistic of model's composition bias.
 * Incept:    SRE, Mon Jul  2 08:40:12 2007 [Janelia]
 *
 * Purpose:   Calculates the KL divergence (relative entropy) between
 *            the average match state residue composition in model
 *            <hmm> and the background frequency distribution in <bg>;
 *            return it in <ret_KL>, in bits.
 *            
 *            Optionally return the average match state residue
 *            composition in <opt_avp>. This vector, of length
 *            <hmm->abc->K> is allocated here and becomes the caller's
 *            responsibility if <opt_avp> is non-<NULL>. 
 *            
 *            The average match composition is an occupancy-weighted
 *            average (see <p7_hmm_CalculateOccupancy()>.
 *
 *            For average match state residue composition <p> and
 *            background residue frequencies <q>, the KL divergence
 *            is:
 *
 *            \begin{eqnarray*}
 *                 \sum_a p_a \log_2 \frac{p_a}{q_a}
 *            \end{eqnarray*}
 *            
 * Returns:   <eslOK> on success.
 *
 * Throws:    <eslEMEM> on allocation error.
 */
p7_hmm_CompositionKLD()
Synopsis:  A statistic of model's composition bias.

Calculates the KL divergence (relative entropy) between
the average match state residue composition in model
 and the background frequency distribution in ;
return it in , in bits.

Optionally return the average match state residue
composition in . This vector, of length
abc->K> is allocated here and becomes the caller's
responsibility if  is non-.

The average match composition is an occupancy-weighted
average >.

For average match state residue composition  and
background residue frequencies , the KL divergence
is.



 on success.

 on allocation error.
p7_hmm_CompositionKLD () Synopsis : A statistic of model ' s composition bias . Calculates the KL divergence ( relative entropy ) between the average match state residue composition in model and the background frequency distribution in ; return it in in bits . Optionally return the average match state residue composition in . This vector of length abc - > K > is allocated here and becomes the caller ' s responsibility if is non - . The average match composition is an occupancy - weighted average > . For average match state residue composition and background residue frequencies the KL divergence is . on success . on allocation error .
int
p7_hmm_CompositionKLD(const P7_HMM *hmm, const P7_BG *bg, float *ret_KL, float **opt_avp)
{
  int    K   = hmm->abc->K;
  float *occ = NULL;
  float *p   = NULL;
  int    status;
  int    k;
  ESL_ALLOC(occ, sizeof(float) * (hmm->M+1));
  ESL_ALLOC(p,   sizeof(float) * K);
  p7_hmm_CalculateOccupancy(hmm, occ, NULL);         
  esl_vec_FSet(p, K, 0.);                            
  for (k = 1; k <= hmm->M; k++)
    esl_vec_FAddScaled(p, hmm->mat[k], occ[k], K);
  esl_vec_FNorm(p, K);
  *ret_KL = esl_vec_FRelEntropy(p, bg->f, K);       
  if (opt_avp != NULL) *opt_avp = p;  else free(p); 
  free(occ);
  return eslOK;
 ERROR:
  free(occ);
  free(p);
  if (opt_avp) *opt_avp = NULL;
  *ret_KL = 0.0;
  return status;
}
int p7_hmm_CompositionKLD ( const P7_HMM * hmm , const P7_BG * bg , float * ret_KL , float * * opt_avp ) { int K = hmm -> abc -> K ; float * occ = NULL ; float * p = NULL ; int status ; int k ; ESL_ALLOC ( occ , sizeof ( float ) * ( hmm -> M + 1 ) ) ; ESL_ALLOC ( p , sizeof ( float ) * K ) ; p7_hmm_CalculateOccupancy ( hmm , occ , NULL ) ; esl_vec_FSet ( p , K , 0. ) ; for ( k = 1 ; k <= hmm -> M ; k ++ ) esl_vec_FAddScaled ( p , hmm -> mat [ k ] , occ [ k ] , K ) ; esl_vec_FNorm ( p , K ) ; * ret_KL = esl_vec_FRelEntropy ( p , bg -> f , K ) ; if ( opt_avp != NULL ) * opt_avp = p ; else free ( p ) ; free ( occ ) ; return eslOK ; ERROR : free ( occ ) ; free ( p ) ; if ( opt_avp ) * opt_avp = NULL ; * ret_KL = 0.0 ; return status ; }
Function:  p7_hmm_CompositionKLD()
 Synopsis:  A statistic of model's composition bias.
Function : p7_hmm_CompositionKLD () Synopsis : A statistic of model ' s composition bias .
// match state occupancy probabilities  // average composition over match states // easel returns this value in bits