classify.cc

KNN algorithm, and related

/*--------------------------------------------------------------------------
@COPYRIGHT  :
              Copyright 1997, Vasken Kollokian, 
              McConnell Brain Imaging Centre,
              Montreal Neurological Institute, McGill University.
              Permission to use, copy, modify, and distribute this
              software and its documentation for any purpose and without
              fee is hereby granted, provided that the above copyright
              notice appear in all copies.  The author and McGill University
              make no representations about the suitability of this
              software for any purpose.  It is provided "as is" without
              express or implied warranty.
---------------------------------------------------------------------------- 
$RCSfile: classify.cc,v $
$Revision: 1.3 $
$Author: bert $
$Date: 2005/02/11 20:16:15 $
$State: Exp $
--------------------------------------------------------------------------*/
/* ----------------------------- MNI Header -----------------------------------
@NAME       : classify
@INPUT      : argc, argv -command line arguments
@OUTPUT     : 
@RETURNS    : error status
@DESCRIPTION: calls a classifier routine, feeds input data, stores result
@METHOD     : 
@GLOBALS    : 
@CALLS      : 
@CREATED    : May 8, 1995 (Vasco KOLLOKIAN)
@MODIFIED   : $Log: classify.cc,v $
@MODIFIED   : Revision 1.3  2005/02/11 20:16:15  bert
@MODIFIED   : Minor changes, primarily for compilation issues
@MODIFIED   :
@MODIFIED   : Revision 1.2  2002/03/20 22:25:06  jason
@MODIFIED   : added a sadly forgotten configure.ac and took out one debugging line
@MODIFIED   :
@MODIFIED   : Revision 1.1.1.1  2002/03/20 22:16:34  jason
@MODIFIED   : first autoconfiscated version that compiles under linux gcc 3
@MODIFIED   :
@MODIFIED   : Revision 1.9  1999/01/14 19:32:50  alex
@MODIFIED   : Added a few printf statements
@MODIFIED   :
@MODIFIED   : Revision 1.8  1998/02/26 19:52:12  alex
@MODIFIED   : C++-ified things
@MODIFIED   :
@MODIFIED   : Revision 1.7  1997/12/16 18:33:27  alex
@MODIFIED   : Added -output_range option
@MODIFIED   :
@MODIFIED   : Revision 1.6  1997/12/14 16:02:15  alex
@MODIFIED   : Fixed small bug in '-fuzzy all' option
@MODIFIED   :
@MODIFIED   : Revision 1.5  1997/12/13 20:26:04  alex
@MODIFIED   : Added '-fuzzy all' option
@MODIFIED   :
@MODIFIED   : Revision 1.4  1997/09/11 14:26:05  alex
@MODIFIED   : Various changes directed at g++ compatibility
@MODIFIED   :
@MODIFIED   : Revision 1.3  1997/02/14 21:07:22  alex
@MODIFIED   : Modified ann training, added -clobber switch
@MODIFIED   :
@MODIFIED   : Revision 1.2  1997/02/11 05:48:31  alex
@MODIFIED   : Changed history from overwriting to appending to the history of the first input file
@MODIFIED   :
@MODIFIED   : Revision 1.1.1.1  1997/02/11 00:06:41  alex
@MODIFIED   : Sources for classify, copied from Vasken Kollokian
@MODIFIED   :
 * Revision 1.26  1996/08/25  05:20:49  vasco
 * Added support for Bayes classification.
 * Added support for apriori probabilities to be fed to any classifier
 * Fixed bug, so that fuzzy volume clobbering is checked before classifications starts
 * Made cache the default behavior by adding -nocache switch
 *
 * Revision 1.25  1996/03/14  06:30:02  vasco
 * eliminated some unused variables.
 *
 * Revision 1.24  1996/03/14  05:45:50  vasco
 * fixed a bug in cleanup_memory, and re-commented it out.
 *
 * Revision 1.23  1996/03/06  00:25:41  vasco
 * The is another major revamp. I added Fuzzy C Means, and I modularized fcm min and hcm
 *
 * Revision 1.22  1996/01/25  06:10:03  vasco
 * fixed max_class_index bug in -load_tr option. and commented out
 * cleanup_memory()
 *
 * Revision 1.21  1995/12/07  15:48:19  vasco
 * Added Hard C Means classification, by supplying load_tag_volume
 * function, also added supervised flag to distinguish between the two
 * type of classifiers, supervised and unsupervised.
 * Replaced volume and image min and max by max_class_label.
 *
 * Revision 1.20  1995/11/17  07:50:54  vasco
 * fixed a bug in -dump, and added -fpath, a fuzzy pathname for fuzzvols.
 *
 * Revision 1.19  1995/11/06  06:39:41  vasco
 * Added memory cleanup routines, and chaged some volio calls.
 *
 * Revision 1.18  1995/10/27  05:34:39  vasco
 * added volume caching options, and set class_names to NULL
 *
 * Revision 1.17  1995/10/26  06:28:36  vasco
 * added -fuzzy "01001" string to select which class is expected
 * to write a fuzzy classification.  This gives a finer control
 * over what class results oin fuzzy classification.  This is
 * quite useful in MS since they require the fuzziness of only
 * one 'lesion' class.
 *
 * Revision 1.16  1995/10/23  02:03:46  vasco
 * Prints "*" while classifying each slice.
 *
 * Revision 1.15  1995/10/09  00:45:11  vasco
 * added an option to user specified voxel_min and voxel_man, image_min, image_max
 * fuzzy_voxel_min, fuzzy_voxel_max, fuzzy_image_min, fuzzy_image_max.
 * fixed the -help crashing. added some newlines for more readability, and added punctuations.
 *
 * Revision 1.14  1995/10/03  03:03:05  vasco
 * added -dump_features flag, and changed some stderr to stdout.
 *
 * Revision 1.13  1995/09/24  17:31:26  vasco
 * Fixed a bug in counting the correct number of remaining tags. Once
 * the tags that fell outside the volume were ignored. Also fixed a bug
 * (rather volio modification) of accessing volume size by volume->size.
 *
 * Revision 1.12  1995/09/20  06:07:11  vasco
 * I added class_names array that houses the class names, in the order they
 * appear in the tag file.
 *
 * Revision 1.11  1995/09/15  20:46:51  vasco
 * Added -mask -user_mask_class -user_mask_value, so that masks could be supported
 *
 * Revision 1.10  1995/09/15  08:16:34  vasco
 * added -fuzzy option with all of its intricacies and dependencies.
 * these include, writing of different data types in the fuzzy volumes
 * availability of fuzziness of implemented classifiers
 * creation, initialization and writing of fuzzy volumes.
 * Also, isolated in set_classifier_functions(), all function initializations
 * moved data allocation just before load_training to avoid duplication of code.
 *
 * Revision 1.9  1995/09/14  03:24:37  vasco
 * removed test_classifier option, and converted include files to <> form.
 *
 * Revision 1.8  1995/08/28  05:11:48  vasco
 * first version of including c4.5
 *
 * Revision 1.7  1995/08/28  03:25:51  vasco
 * converted to g++, and added class_names
 *
 * Revision 1.6  1995/07/12  05:12:23  vasco
 * added -parameter switch to load custom classifier parameters
 *
 * Revision 1.5  1995/07/12  03:49:36  vasco
 * added command history saving feature.
 *
 * Revision 1.4  1995/07/12  03:21:32  vasco
 * added training tag inside volume checks
 *
 * Revision 1.3  1995/06/10  17:59:50  vasco
 * Radical changes
 *
 * Revision 1.2  1995/05/31  01:29:22  vasco
 * added some comments and potential location of initialization routine.
 *
 * Revision 1.1  1995/05/31  00:58:46  vasco
 * Initial revision
 *
---------------------------------------------------------------------------- */
#include "config.h"

#include <iostream>		// (bert) added to force -lCio?
using namespace std;		// (bert) added
extern "C" {
#include <volume_io.h>
#include "time_stamp.h"
#include <ParseArgv.h>		// (bert) moved inside extern "C"
}
#include <unistd.h>
#include "class_protos.h"	// (bert) use quotes
#include "classify.h"		// (bert) use quotes
#include "mindist/mindist.h"	// (bert) use quotes
#include "knn/knn.h"		// (bert) use quotes
#include "ann/ann.h"		// (bert) use quotes

//extern "C" {
//#include <c4_5.h>
//}
#include "hcm/hcm.h"		// (bert) use quotes
#include "fcm/fcm.h"		// (bert) use quotes
#include "bayes/bayes.h"	// (bert) use quotes

/* MAIN */
int main(int argc, char *argv[])
{

  parse_arguments(argc, argv);
  
  allocate_memory(); 

  /* set the generic classifier functions */
  set_classifier_functions( classifier );


  /* the three following verification are to be called after
     set_classifier_functions() that is why they do not reside in
     parse_argv */

  if ( apriori && !use_apriori ) {

    (void) fprintf(stderr,"Chosen classifier doesn't support -apriori.\n");
    exit(EXIT_FAILURE);

  }

  if ( supervised && trainvol_filename && !apriori) {

    (void) fprintf(stderr,"Supervised classifiers don't accept tag volumes without -apriori switch.\n");
    exit(EXIT_FAILURE);

  }

  if ( !supervised && tagfile_filename ) {

    (void) fprintf(stderr,"Unsupervised classifiers don't accept tag files.\n");
    exit(EXIT_FAILURE);

  }



  /* check for fuzziness, ie if a classifier supports a fuzzy option */
  if ( fuzzy && !fuzzy_available) {

    fprintf(stderr, "The specified classifier does not support a fuzzy option\n");
    exit(EXIT_FAILURE);
  }


  /* set specific caching options */
  if ( cache_set && supervised && !apriori ) { 

    /* enable volume caching by setting threshold to 0 */ 
    set_n_bytes_cache_threshold(0);

    /* set max cache size, originally 0 to include only 1 block*/
    set_default_max_bytes_in_cache(max_cache_size);

    /* randomize caching to access for 1 voxel at a time which is good
       for reading tag files throughout the volumes - no user choice */
    block_sizes[0] = 1;
    block_sizes[1] = 1;
    block_sizes[2] = 1;
    set_default_cache_block_sizes(block_sizes);

  }
  else if ( cache_set && ( apriori || !supervised)) {

    /* if unsupervised classifier used, or apriori , enable slice caching */

    /* enable volume caching by setting threshold to 0 */ 
    set_n_bytes_cache_threshold(0);

    /* set max cache size, originally 0 to include only 1 block*/
    set_default_max_bytes_in_cache(max_cache_size);

    block_sizes[0] = user_block_sizes[0]; 
    block_sizes[1] = user_block_sizes[1];
    block_sizes[2] = user_block_sizes[2];
  
    /* And set slice caching for volumes to be created */
    set_default_cache_block_sizes(block_sizes);

  }

  else {

    /* disable caching all together*/
    set_n_bytes_cache_threshold(-1);
  }


  load_input_volumes();


  /* train supervised classifiers here */
  if ( supervised && tagfile_filename) {

    load_tag_file( tagfile_filename );
    create_feature_matrix_from_tagfile();
    init_training(param_filename);

    /* load the apriori volumes (with the training volume mechanism) 
       since it is exactly as loading FCM training volumes */
    if ( apriori ) {

      load_train_volumes(trainvol_filename);

      /* make sure number of classes is the same number of apriori volumes */
      if ( num_classes != num_train_vols ) {
	
	fprintf( stderr, "Number of classes <> # of apriori volumes\n");
	exit(EXIT_FAILURE);
      }

      /* allocate some memory for apriori vector - for apriori classifier */
      ALLOC(apriori_vector, num_classes);  

    }

    if ( classifier != KNN )
      /* knn has to train in each sample, so it is placed on it own */
      train();

  }

  /* train unsupervised classifiers here */
  if ( !supervised && trainvol_filename) {

    load_train_volumes(trainvol_filename);
    init_training(param_filename);
    train();
  }

  /* load previously trained classifier here - if proper switch is supplied */
  if ( load_train_filename) {

    init_training(param_filename);
    load_training(load_train_filename);
    max_class_index = num_classes;
  }

  /* save trained classifier here - if proper switch is supplied */
  if ( save_train_filename )
    save_training(save_train_filename);


  /* if not training, create, initialize, load mask, classify and write */
  if ( !train_only ) {

    if ( cache_set )     /* set slice caching options */
      convert_features_to_slice_caching();

    if ( fuzzy ) {

      decide_fuzzy_volumes();

    }

    create_empty_classified_volume();

    if ( mask_filename ) 
      load_mask_volume( mask_filename);

    classify_volume();

    write_classified_volume();

  }

  if ( fuzzy || classifier == FCM)
    write_fuzzy_volumes();

  /* this is for testing memory leaks, and may not be necessary to call 
  cleanup_memory(); */

  return(EXIT_SUCCESS);

} /* main */ 



/* ----------------------------- MNI Header -----------------------------------
@NAME       : parse_arguments
@INPUT      : argc, argv - command line arguments
@OUTPUT     : 
@RETURNS    : 
@DESCRIPTION: parses command line arguments
@METHOD     : 
@GLOBALS    :   pname          - program name
                verbose        - show progress
                clobber        - overwrite file
                debug          - show debug info
                sub_command    - subclassifer arguments
                type           - type to read
                signtype       - sign to read
                num_features    - number of input volumes
                output_filename- the name of the classified volume 
@CALLS      : 
@CREATED    : February 6, 1995 (Vasco KOLLOKIAN)
@MODIFIED   : 
---------------------------------------------------------------------------- */
void parse_arguments(int argc, char *argv[])
{

  int   i, dst_idx = 0, src_idx = 0, buff_idx = 0;

  /* buffer to hold fuzzy_training volume names, limit 10, kludge! */
  char  fuzzy_train_buffer[10][256]; 

  pname = argv[0];

  /* form the history string - before parseargv is called */
  history = time_stamp(argc, argv);


  /* Call ParseArgv */
  if ( !ParseArgv(&argc, argv, argTable, 0) ) {   /* switches supplied are OK */ 

    if ( ( train_only || dump_features ) && (argc < 2) ) { 
      /* at least one volume has to be specified : output volume is optional
	 if the -train_only, or -dump_features switches are specified */

      (void) fprintf(stderr, "-train, -dump: specify at least one input volume.\n");
      (void) fprintf(stderr, "       %s [-help]\n\n", pname);
      exit(EXIT_FAILURE);

    } 

    if ( !(train_only || dump_features) && (argc < 3) ) {
      /* at least two volumes have to be specified - source and destination  */
      
      (void) fprintf(stderr, 
	     "\nUsage: %s <options> <infile1> [infile2] ... <outfile>\n", pname);
      (void) fprintf(stderr, "       %s [-help]\n\n", pname);
      
      exit(EXIT_FAILURE);
    }
  
  } /* ParseArgv */


  /* determine the number of volumes - ie features given to classify */
  if ( !( train_only || dump_features) ) 
    num_features = argc - 2;  /* count out progname and outvol */
  else
    num_features = argc - 1;  /* -train, -dump: count out only progname - no output*/

  /* Set clobber flags */
  if (clobber_all)
    clobber = clobber_training = clobber_fuzzy = TRUE;

  /* this is a kludge, to prevent -help from core dumping I guess it
     is a shortcoming of parseargv or my ignorance, rather impatient
     to deal with this problem. I guess the way ParseArgv is structured */
  
  if ( num_features == 0 ) 
    exit(EXIT_SUCCESS);


  /* reserve array for input volume filenames */
  ALLOC(input_filename, num_features); 


  /* make sure that the typed filenames exist */
  for_less(i, 0, num_features ) {

    if (!file_exists(argv[i+1])) {
      (void) fprintf(stderr, "filename `%s' not found. \n", argv[i+1]);
      exit(EXIT_FAILURE);
    }

    /* get the filename of the volume */
    input_filename[i] = argv[i+1];
    if ( debug >= 1)
      (void) fprintf(stdout, "input_filename[%d] = `%s'\n", i, input_filename[i]);

  } /* for_less */
  
  if ( !(train_only || dump_features) ) 
    output_filename = argv[num_features + 1];


  if ( debug >= 1 )
    (void) fprintf(stdout, "output_filename = `%s' \n", output_filename);
  

  if (!clobber && !train_only && !dump_features && file_exists(output_filename)) {

    (void) fprintf(stderr,"File `%s' exists ! \n", output_filename);
    (void) fprintf(stderr,"Use -clob_out to overwrite output classified volume.\n");