// lat/confidence.h
  
  // Copyright 2013  Johns Hopkins University (Author: Daniel Povey)
  
  // See ../../COPYING for clarification regarding multiple authors
  //
  // Licensed under the Apache License, Version 2.0 (the "License");
  // you may not use this file except in compliance with the License.
  // You may obtain a copy of the License at
  //
  //  http://www.apache.org/licenses/LICENSE-2.0
  //
  // THIS CODE IS PROVIDED *AS IS* BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  // KIND, EITHER EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION ANY IMPLIED
  // WARRANTIES OR CONDITIONS OF TITLE, FITNESS FOR A PARTICULAR PURPOSE,
  // MERCHANTABLITY OR NON-INFRINGEMENT.
  // See the Apache 2 License for the specific language governing permissions and
  // limitations under the License.
  
  
  #ifndef KALDI_LAT_CONFIDENCE_H_
  #define KALDI_LAT_CONFIDENCE_H_
  
  #include <vector>
  #include <map>
  
  #include "base/kaldi-common.h"
  #include "util/common-utils.h"
  #include "fstext/fstext-lib.h"
  #include "lat/kaldi-lattice.h"
  
  namespace kaldi {
  
  /// Caution: this function is not the only way to get confidences in Kaldi.
  /// This only gives you sentence-level (utterance-level) confidence.  You can
  /// get word-by-word confidence within a sentence, along with Minimum Bayes Risk
  /// decoding, by looking at sausages.h.
  /// Caution: confidences estimated using this type of method are not very
  /// accurate.
  /// This function will return the difference between the best path in clat and
  /// the second-best path in clat (a positive number), or zero if clat was
  /// equivalent to the empty FST (no successful paths), or infinity if there
  /// was only one path in "clat".  It will output to "num_paths" (if non-NULL)
  /// a number n = 0, 1 or 2 saying how many n-best paths (up to two) were found.
  /// If n >= 1 it outputs to "best_sentence" (if non-NULL) the best word-sequence;
  /// if n == 2 it outputs to "second_best_sentence" (if non-NULL) the second best
  /// word-sequence (this may be useful for testing whether the two best word
  /// sequences are somehow equivalent for the task at hand).  If you need more
  /// information than this or want to look deeper inside the n-best list, then
  /// look at the implementation of this function.
  /// This function requires that distinct paths in "lat" have distinct word
  /// sequences; this will automatically be the case if you generated "clat"
  /// in any normal way, such as from a decoder, because a deterministic FST
  /// has this property.
  /// This function assumes that any acoustic scaling you want to apply,
  /// has already been applied.
  BaseFloat SentenceLevelConfidence(const CompactLattice &clat,
                                    int32 *num_paths,
                                    std::vector<int32> *best_sentence,
                                    std::vector<int32> *second_best_sentence);
  
  
  /// This version of SentenceLevelConfidence takes as input a state-level lattice.
  /// It needs to determinize it first, but it does so in a "smart" way that only generates
  /// about as many output paths as it needs.
  BaseFloat SentenceLevelConfidence(const Lattice &lat,
                                    int32 *num_paths,
                                    std::vector<int32> *best_sentence,
                                    std::vector<int32> *second_best_sentence);
  
  
  
  
  
  }  // namespace kaldi
  
  #endif  // KALDI_LAT_CONFIDENCE_H_