KKMLL::ClassificationBiasMatrix Class Reference

Assists in adjusting a Classifiers output for bias of a classifier. More...

#include <ClassificationBiasMatrix.h>

Public Types
typedef ClassificationBiasMatrix *	ClassificationBiasMatrixPtr
typedef KKB::DateTime	DateTime
typedef KKB::KKStr	KKStr
typedef KKB::Matrix	Matrix
typedef KKB::MatrixPtr	MatrixPtr
typedef KKB::RunLog	RunLog

Public Member Functions
	ClassificationBiasMatrix (RunLog &_runLog)
	Will construct an instance as defined in the Paper. More...
	ClassificationBiasMatrix (const ClassificationBiasMatrix &cbm)
	ClassificationBiasMatrix (MLClassList &classes, RunLog &_runLog)
	ClassificationBiasMatrix (const KKStr &_configFileName, MLClassList &_classes, RunLog &_runLog)
	Construct a ClassificationBiasMatrix instance from the parameter file for '_configFileName'. More...
	ClassificationBiasMatrix (const ConfusionMatrix2 &cm, RunLog &_runLog)
	Construct a ClassificationBiasMatrix instance from a ConfusionMatrix object. More...
	~ClassificationBiasMatrix ()
DateTime	DateTimeFileWritten () const
void	PerformAdjustmnts (const VectorDouble &classifiedCounts, VectorDouble &adjCounts, VectorDouble &stdErrors)
void	PrintAdjustedResults (ostream &sw, const VectorDouble &classifiedCounts)
void	PrintBiasMatrix (ostream &sw)
void	TestPaperResults (ostream &sw)
void	WriteXML (ostream &o)

Static Public Member Functions
static ClassificationBiasMatrixPtr	BuildFromIstreamXML (istream &f, MLClassList &classes, RunLog &log)
	Will construct a ClassificationBiasMatrix instance from a input stream. More...

Detailed Description

Assists in adjusting a Classifiers output for bias of a classifier.

See the paper:

"Estimating the Taxonomic composition of a sample when individuals are classified with error"
by Andrew Solow, Cabll Davis, Qiao Hu
Woods Hole Ocanographic Institution, Woods Hole Massachusetts
Marine Ecology Progresss Series
published 2006-july-06;  vol 216:309-311

This class uses the results of a previous 10 fold cross validation confusion matrix to adjust the results of a classification run. The application CrossValidation will create a parameter file in the directory "${xxxxxHomeDir}\\Classifier\\TrainingModels\\Save" that contains the confusion matrix. The option "-BiasMatrix" tells the CrossValidation program to generate this parameter file. It will have the same name as the Configuration file with the extension ".BiasMatrix.txt" appended to the end. There is a managed version of this class in PicesInterface called PicesInterface::ClassificationBiasMatrix

Definition at line 44 of file ClassificationBiasMatrix.h.

Member Typedef Documentation

typedef ClassificationBiasMatrix* KKMLL::ClassificationBiasMatrix::ClassificationBiasMatrixPtr

Definition at line 47 of file ClassificationBiasMatrix.h.

typedef KKB::DateTime KKMLL::ClassificationBiasMatrix::DateTime

Definition at line 51 of file ClassificationBiasMatrix.h.

typedef KKB::KKStr KKMLL::ClassificationBiasMatrix::KKStr

Definition at line 50 of file ClassificationBiasMatrix.h.

typedef KKB::Matrix KKMLL::ClassificationBiasMatrix::Matrix

Definition at line 52 of file ClassificationBiasMatrix.h.

typedef KKB::MatrixPtr KKMLL::ClassificationBiasMatrix::MatrixPtr

Definition at line 53 of file ClassificationBiasMatrix.h.

typedef KKB::RunLog KKMLL::ClassificationBiasMatrix::RunLog

Definition at line 49 of file ClassificationBiasMatrix.h.

Constructor & Destructor Documentation

ClassificationBiasMatrix::ClassificationBiasMatrix

(

RunLog &

_runLog

)

Will construct an instance as defined in the Paper.

Definition at line 159 of file ClassificationBiasMatrix.cpp.

References KKB::DateTime::DateTime(), KKB::KKStr::KKStr(), KKMLL::MLClassList::MLClassList(), and KKB::VectorKKStr::VectorKKStr().

                                                                   :
   biasFileName        (),
   classes             (new MLClassList ()),
   configFileName      (),
   configFileNameFromMatrixBiasFile (),
   configDateTime      (),
   counts              (NULL),
   dateTimeFileWritten (),
   errMsgs             (),
   numClasses          (0),
   probabilities       (NULL),
   runLog              (_runLog),
   valid               (true)
{
  BuildTestMatrix ();

  //ofstream  sw ("c:\\Temp\\ClassificationBiasMatrix_Test.txt");
  //TestPaperResults (sw);
  //sw.close ();
}

ClassificationBiasMatrix::ClassificationBiasMatrix

(

const ClassificationBiasMatrix &

cbm

)

Definition at line 84 of file ClassificationBiasMatrix.cpp.

References KKB::DateTime::DateTime(), KKB::KKStr::KKStr(), KKB::Matrix::Matrix(), KKMLL::MLClassList::MLClassList(), and KKB::VectorKKStr::VectorKKStr().

                                                                                        :
   biasFileName        (cbm.biasFileName),
   classes             (NULL),
   configFileName      (cbm.configFileName),
   configFileNameFromMatrixBiasFile (cbm.configFileNameFromMatrixBiasFile),
   configDateTime      (cbm.configDateTime),
   counts              (NULL),
   dateTimeFileWritten (cbm.dateTimeFileWritten),
   errMsgs             (),
   numClasses          (cbm.numClasses),
   probabilities       (NULL),
   runLog              (cbm.runLog),
   valid               (true)

{
  if  (cbm.counts)
    counts = new Matrix (*cbm.counts);

  if  (cbm.classes)
    classes = new MLClassList (*cbm.classes);

  if  (cbm.probabilities)
    probabilities = new Matrix (*cbm.probabilities);
}

ClassificationBiasMatrix::ClassificationBiasMatrix	(	MLClassList &	classes,
		RunLog &	_runLog
	)

Definition at line 136 of file ClassificationBiasMatrix.cpp.

References KKB::DateTime::DateTime(), KKB::KKStr::KKStr(), KKMLL::MLClassList::MLClassList(), and KKB::VectorKKStr::VectorKKStr().

Referenced by BuildFromIstreamXML().

                                                    :
   biasFileName        (),
   classes             (new MLClassList (_classes)),
   configFileName      (),
   configFileNameFromMatrixBiasFile (),
   configDateTime      (),
   counts              (NULL),
   dateTimeFileWritten (),
   errMsgs             (),
   numClasses          (0),
   probabilities       (NULL),
   runLog              (_runLog),
   valid               (true)

{
  numClasses = classes->QueueSize ();
  DeclareMatrix ();
}

ClassificationBiasMatrix::ClassificationBiasMatrix	(	const KKStr &	_configFileName,
		MLClassList &	_classes,
		RunLog &	_runLog
	)

Construct a ClassificationBiasMatrix instance from the parameter file for '_configFileName'.

Parameters

[in]	_configFileName	The name of the BiasMatrix file will be derived from the configuration file name. the term '_BiasMatrix.txt' will be appended onto the end.
[in]	_classes	List of classes that you are expecting to be in the 'BiasMatrix' file.
[in,out]	_runLog	Logging file to use.

Definition at line 34 of file ClassificationBiasMatrix.cpp.

References KKB::DateTime::DateTime(), KKB::KKStr::KKStr(), KKMLL::MLClassList::MLClassList(), KKB::KKStr::operator+(), KKB::KKStr::operator=(), KKB::osRemoveExtension(), and KKB::VectorKKStr::VectorKKStr().

                                                    :
   biasFileName        (),
   classes             (new MLClassList (_classes)),
   configFileName      (_configFileName),
   configFileNameFromMatrixBiasFile (),
   configDateTime      (),
   counts              (NULL),
   dateTimeFileWritten (),
   errMsgs             (),
   numClasses          (0),
   probabilities       (NULL),
   runLog              (_runLog),
   valid               (true)
{
  biasFileName = osRemoveExtension (configFileName) + ".BiasMatrix.txt";

  ifstream  sr (biasFileName.Str ());

  if  (!sr.is_open ())
  {
    valid = false;
    KKStr  errorMsg = "Error opening ConfigFileName[" + configFileName + "]";
    errMsgs.push_back (errorMsg);
    return;
  }

  DeclareMatrix ();

  try
  {
    ReadXML (sr);
  }
  catch  (const exception& e)
  {
    valid = false;
    errMsgs.push_back (e.what ());
  }
  catch (...)
  {
    valid = false;
    errMsgs.push_back ("ClassificationBiasMatrix    Exception occurred reading XML File");
  }
  sr.close ();
}

ClassificationBiasMatrix::ClassificationBiasMatrix	(	const ConfusionMatrix2 &	cm,
		RunLog &	_runLog
	)

Construct a ClassificationBiasMatrix instance from a ConfusionMatrix object.

Parameters

[in]	cm	Confusion Matrix to get parameters from.
[in,out]	_runLog	Logging file to use.

Definition at line 112 of file ClassificationBiasMatrix.cpp.

References KKB::DateTime::DateTime(), KKB::KKStr::KKStr(), KKMLL::ConfusionMatrix2::MLClasses(), KKMLL::MLClassList::MLClassList(), and KKB::VectorKKStr::VectorKKStr().

                                                     :
   biasFileName        (),
   classes             (NULL),
   configFileName      (),
   configFileNameFromMatrixBiasFile (),
   configDateTime      (),
   counts              (NULL),
   dateTimeFileWritten (),
   errMsgs             (),
   numClasses          (0),
   probabilities       (NULL),
   runLog              (_runLog),
   valid               (true)
{
  classes = new MLClassList (cm.MLClasses ());
  numClasses = classes->QueueSize ();
  DeclareMatrix ();
  BuildFromConfusionMatrix (cm);
}

ClassificationBiasMatrix::~ClassificationBiasMatrix

(

)

Definition at line 183 of file ClassificationBiasMatrix.cpp.

{
  delete  probabilities;
  probabilities = NULL;
  delete  counts;
  counts = NULL;
  delete  classes;
  classes = NULL;
}

Member Function Documentation

ClassificationBiasMatrixPtr ClassificationBiasMatrix::BuildFromIstreamXML ( istream &  f, MLClassList &  classes, RunLog &  log  )

static

Will construct a ClassificationBiasMatrix instance from a input stream.

Parameters

[in]	f	Input Stream.
[in]	classes	List of classes we expect to find in the input stream f.
[in,out]	log	Logging File.

Definition at line 195 of file ClassificationBiasMatrix.cpp.

References ClassificationBiasMatrix().

{
  ClassificationBiasMatrixPtr cbm = new ClassificationBiasMatrix (classes, log);
  cbm->ReadXML (f);
  return  cbm;
}  /* BuildFromIstreamXML */

DateTime KKMLL::ClassificationBiasMatrix::DateTimeFileWritten ( ) const

inline

Definition at line 105 of file ClassificationBiasMatrix.h.

{return  dateTimeFileWritten;}

void ClassificationBiasMatrix::PerformAdjustmnts	(	const VectorDouble &	classifiedCounts,
		VectorDouble &	adjCounts,
		VectorDouble &	stdErrors
	)

Definition at line 565 of file ClassificationBiasMatrix.cpp.

References KKB::Matrix::Inverse(), KKB::Matrix::Matrix(), KKB::Matrix::operator*(), KKB::Matrix::operator[](), KKB::Row::operator[](), and KKB::Matrix::Transpose().

Referenced by PrintAdjustedResults().

{
  // For description of calc's see the paper: 
  //    "Estimating the Taxonomic composition of a sample when individuals are classified with error"
  //     by Andrew Solow, Cabll Davis, Qiao Hu
  //     Woods Hole Oceanographic Institution, Woods Hole Massachusetts
  //     Marine Ecology Progress Series
  //     published 2006-july-06;  vol 216:309-311

  if  (classifiedCounts.size () != (kkuint32)numClasses)
  {
    KKStr errMsg = "ClassificationBiasMatrix::PerformAdjustmnts  ***ERROR***   Disagreement in length of classifiedCounts[" + 
                   StrFormatInt ((kkint32)classifiedCounts.size (), "ZZZ0") + 
                   "]  and Prev Defined ClassList[" + StrFormatInt (numClasses, "ZZZ0") + "].";
    runLog.Level (-1) << errMsg << endl;
    valid = false;
    throw KKException (errMsg);
  }

  kkint32 x = 0;
  kkint32  i, j, k;


  // We need to deal with the special case when one entry in the probability diagonal is zero.
  {
    for (x = 0;  x < numClasses;  x++)
    {
      if  ((*probabilities)[x][x] == 0.0)
      {
        // This will cause the inversion of the diagonal matrix to fail.  To deal
        // with this situation; I will steal some probability from other buckets on 
        // same row.

        double  totalAmtStolen = 0.0;
        double  percentToSteal = 0.01;
        for (i = 0;  i < numClasses;  i++)
        {
          if  ((*probabilities)[x][i] != 0.0)
          {
            double amtToSteal = (*probabilities)[x][i] * percentToSteal;
            (*probabilities)[x][i] = (*probabilities)[x][i] - amtToSteal;
            totalAmtStolen += amtToSteal;
          }
        }

        (*probabilities)[x][x] = totalAmtStolen;
      }
    }
  }

  Matrix  m (numClasses, 1);
  for  (x = 0;  x < numClasses;  x++)
    m[x][0] = classifiedCounts[x];

  Matrix  transposed = probabilities->Transpose ();
  Matrix  Q = transposed.Inverse ();
  Matrix  n = Q * m;

  Matrix  varM (numClasses, numClasses);
  for  (j = 0;  j < numClasses;  j++)
  {
    double  varM_j = 0.0;
    for  (i = 0;  i < numClasses;  i++)
    {
      double  p = (*probabilities)[i][j];
      varM_j += n[i][0] * p * (1.0 - p);
    }
    varM[j][j] = varM_j;
  }

  for (j = 0;  j < numClasses;  j++)
  {
    for  (k = 0;  k < numClasses;  k++)
    {
      if  (j != k)
      {
        double  covM_jk = 0.0;
        for  (i = 0;  i < numClasses;  i++)
          covM_jk -= n[i][0] * (*probabilities)[i][j] * (*probabilities)[j][k];
        varM[j][k] = covM_jk;
      }
    }
  }

  Matrix  varN = Q * varM * Q.Transpose ();

  adjCounts.clear ();
  stdErrors.clear ();
    
  for  (x = 0;  x < numClasses;  x++)
  {
    adjCounts.push_back (n[x][0]);
    stdErrors.push_back (sqrt (varN[x][x]));
  }

  return;
}  /* PerformAdjustmnts */

void ClassificationBiasMatrix::PrintAdjustedResults	(	ostream &	sw,
		const VectorDouble &	classifiedCounts
	)

Definition at line 741 of file ClassificationBiasMatrix.cpp.

References KKMLL::MLClassList::ExtractThreeTitleLines(), KKB::KKException::KKException(), and PerformAdjustmnts().

{
  if  (classifiedCounts.size () != (kkuint32)numClasses)
  {
    KKStr  errMsg = "ClassificationBiasMatrix::PrintAdjustedResults  ***ERROR***    Number of entries in 'classifiedCounts' not equal the number of classes";
    cerr << "ClassificationBiasMatrix::PrintAdjustedResults  ***ERROR***  " << errMsg << endl;
    valid = false;
    throw KKException (errMsg);
  }

  try
  {
    VectorDouble   adjustedReults;
    VectorDouble   stdErrors;
    
    PerformAdjustmnts (classifiedCounts, adjustedReults, stdErrors);

    KKStr  tl1, tl2, tl3;
    classes->ExtractThreeTitleLines (tl1, tl2, tl3);
    sw << ""             << "\t" << "\t" << tl1 << endl;
    sw << ""             << "\t" << "\t" << tl2 << endl;
    sw << "Description"  << "\t" << "\t" << tl3 << endl;
   
    kkint32  col = 0;

    sw << "Classified Results" << "\t";
    for  (col = 0;  col < numClasses;  col++)
      sw << "\t" << StrFormatDouble (classifiedCounts[col], "Z,ZZZ,ZZ0.0");
    sw << endl;

    sw << "Adjusted Results" << "\t";
    for  (col = 0;  col < numClasses;  col++)
      sw << "\t" << StrFormatDouble (adjustedReults[col], "Z,ZZZ,ZZ0.0");
    sw << endl;

    sw << "Standard Errors" << "\t";
    for  (col = 0;  col < numClasses;  col++)
      sw << "\t" << StrFormatDouble (stdErrors[col], "Z,ZZZ,ZZ0.0");
    sw << endl;
  }
  catch  (KKException&  e)
  {
    KKStr  errMsg = "ClassificationBiasMatrix::PrintAdjustedResults   ***ERROR***  KKException";
    runLog.Level (-1) << errMsg << endl << e.ToString () << endl;
    throw KKException (errMsg, e);
  }
  catch  (std::exception& e2)
  {
    KKStr  errMsg = "ClassificationBiasMatrix::PrintAdjustedResults   ***ERROR***  std::exception";
    runLog.Level (-1) << errMsg << endl << e2.what() << endl;
    throw KKException (errMsg, e2);
  }
  catch  (...)
  {
    KKStr  errMsg = "ClassificationBiasMatrix::PrintAdjustedResults   ***ERROR***  Exception(...)";
    runLog.Level (-1) << endl << errMsg << endl;
    throw KKException (errMsg);
  }
}  /* PrintAdjustedResults */

void ClassificationBiasMatrix::PrintBiasMatrix

(

ostream &

sw

)

Definition at line 668 of file ClassificationBiasMatrix.cpp.

References KKMLL::MLClassList::ExtractThreeTitleLines(), KKB::KKException::KKException(), KKB::Matrix::operator[](), and KKB::Row::operator[]().

Referenced by TestPaperResults().

{
  if  (classes == NULL)
  {
    KKStr  errMsg = "ClassificationBiasMatrix::PrintBiasMatrix  ***ERROR***   'Classes' not defined;  this indicates that this object was not properly initialized.";
    runLog.Level (-1) << errMsg << endl;
    valid = false;
    throw KKException (errMsg);
  }

  sw << "BiasMatrix File Name            [" << biasFileName                     << "]" << endl
     << "Date Bias Matrix was Created    [" << dateTimeFileWritten              << "]" << endl
     << "Configuration File Name         [" << configFileName                   << "]" << endl
     << "ConfigFile Used for Bias Matrix [" << configFileNameFromMatrixBiasFile << "]" << endl
     << endl
     << endl;

  KKStr  tl1, tl2, tl3;

  classes->ExtractThreeTitleLines (tl1, tl2, tl3);
  {
    sw << ""      << "\t" << ""      << "\t" << tl1 << endl;
    sw << "Class" << "\t" << ""      << "\t" << tl2 << endl;
    sw << "Name"  << "\t" << "Count" << "\t" << tl3 << endl;
  }

  kkint32  row = 0;
  kkint32  col = 0;
  
  double  total = 0.0;

  VectorDouble  colTotals (numClasses, 0.0);
  VectorDouble  rowTotals (numClasses, 0.0);

  for  (row = 0;  row < numClasses;  row++)
  {
    double  rowTotal = 0;
    for  (col = 0;  col < numClasses;  col++)
    {
      rowTotal += (*counts)[row][col];
      colTotals[col] += (*counts)[row][col];
    }
    rowTotals[row] = rowTotal;

    sw << (*classes)[row].Name () << "\t" << StrFormatDouble (rowTotal, "zzz,zz0.00");
    for  (col = 0;  col < numClasses;  col++)
      sw << "\t" << StrFormatDouble ((*counts)[row][col], "###,##0.00");
    sw << endl;
    total += rowTotal;
  }
  sw << "Total" << "\t" << StrFormatDouble (total, "###,##0.00");
  for  (col = 0;  col < numClasses;  col++)
     sw << "\t" << StrFormatDouble (colTotals[col], "ZZZ,ZZ0.00");
  sw << endl;
 
  sw << endl;
 
  for  (row = 0; row < numClasses;  row++)
  {
    sw << (*classes)[row].Name ();
    double  rowPercent = 100.0 * rowTotals[row] / total;
    sw << "\t" << StrFormatDouble (rowPercent, "ZZ0.0000") + "%";

    for  (col = 0;  col < numClasses;  col++)
      sw << "\t" << StrFormatDouble (100.0 * (*probabilities)[row][col], "ZZZ,ZZ0.00") << "%";
    sw << endl;
  }
  sw << endl;
}  /* PrintBiasMatrix */

void ClassificationBiasMatrix::TestPaperResults

(

ostream &

sw

)

Definition at line 264 of file ClassificationBiasMatrix.cpp.

References PrintBiasMatrix().

{
  VectorDouble classCounts (7, 0.0);
  classCounts[0] = 2891;
  classCounts[1] = 1965;
  classCounts[2] = 495;
  classCounts[3] = 1399;
  classCounts[4] = 676; 
  classCounts[5] = 1191;
  classCounts[6] = 1752;

  VectorDouble   adjCounts; 
  VectorDouble   stdErrors;

  PerformAdjustmnts (classCounts, adjCounts, stdErrors);

  kkint32  x = 0;

  sw << endl << endl;

  PrintBiasMatrix (sw);

  sw << endl << endl;

  sw << "Desc";
  for  (x = 0;  x < 7;  x++)
    sw << "\t" << StrFormatInt (x, "ZZ0");
  sw << endl;

  sw << "ClassifiedCounts";
  for  (x = 0;  x < 7;  x++)
    sw << "\t" << StrFormatDouble (classCounts[x], "ZZ,ZZ0.0");
  sw << endl;

  sw << "adjCounts";
  for  (x = 0;  x < 7;  x++)
    sw  << "\t" << StrFormatDouble (adjCounts[x], "ZZZ,ZZ0.0");
  sw << endl;

  sw << "stdErrors";
  for  (x = 0;  x < 7;  x++)
    sw << "\t" << StrFormatDouble (stdErrors[x], "ZZ,ZZ0.0");

  sw << endl << endl;
}  /* TestPaperResults*/

void ClassificationBiasMatrix::WriteXML

(

ostream &

o

)

Definition at line 487 of file ClassificationBiasMatrix.cpp.

{
  o << "<ClassificationBiasMatrix>" << std::endl;

  o << "BiasFileName" << "\t" << biasFileName << std::endl;

  if  ((!classes)  ||  (!counts)  ||  (!probabilities))
  {
    runLog.Level (-1) << "ClassificationBiasMatrix::WriteXML    ***ERROR***   Not all data is defined." << endl;
    return;
  }

  if  ((numClasses != classes->QueueSize ())  ||  
       (numClasses != counts->NumOfRows  ())  ||  
       (numClasses != probabilities->NumOfRows ())
      )
  {
    runLog.Level (-1) << "ClassificationBiasMatrix::WriteXML    ***ERROR***   Disagreement in variable dimensions." << endl;
    return;
  }

  o << "NumClasses"          << "\t" << numClasses                      << std::endl;
  o << "Classes"             << "\t" << classes->ToCommaDelimitedStr () << std::endl;
  o << "ConfigFileName"      << "\t" << configFileName                  << std::endl;
  o << "ConfigDateTime"      << "\t" << configDateTime                  << std::endl;
  o << "DateTimeFileWritten" << "\t" << dateTimeFileWritten             << std::endl;

  o << "<SimpleConfusionMatrix>" << std::endl;
  for  (kkint32 rowIdx = 0;  rowIdx < numClasses;  rowIdx++)
  {
    o << "DataRow"                  << "\t" 
      << (*classes)[rowIdx].Name () << "\t";

    for  (kkint32 colIdx = 0;  colIdx < numClasses;  colIdx++)
    {
      if  (colIdx > 0)
        o << ",";
      o << ((*counts)[rowIdx][colIdx]) << ":" << StrFormatDouble ((*probabilities)[rowIdx][colIdx], "ZZ0.0000");
    }
    o << std::endl;
  }

  o << "</SimpleConfusionMatrix>" << std::endl;

  o << "</ClassificationBiasMatrix>"  << std::endl;

}  /* WriteXML */

---

The documentation for this class was generated from the following files:

• C:/Users/Kurt/GitHub/KSquareLibraries/KKMachineLearning/ClassificationBiasMatrix.h
• C:/Users/Kurt/GitHub/KSquareLibraries/KKMachineLearning/ClassificationBiasMatrix.cpp