---

neuralregionmap.c

Go to the documentation of this file.

#include <utility>

#include "neuralregionmap.h"
#include "matriximage.h"
#include "matrixadapter.h"
#include "imagegrid.h"
#include "ppm_draw.h"      /* Temporary; allows ppm_post_write_hook to be shared. */
#include "globals.h"
#include "worldviews.h"    /* Could probably be eliminated with some juggling */
#include "loopspec.h"
#include "stimulusparametermap.h"
#include "pathspecification.h"


#ifdef EXPLICIT_INSTANTIATION_FOR_STATICS
template class Histo::OneDBinList<int,double>;
template class Plot::HSVPixel<Plot::Pixel::FComponent,Plot::Pixel::HueComponent>;
template class ExpressionParser<PointerLookup<Typeless> >;
#endif 


/* Workaround for apparent bug in at least egcs-1.1.2, possibly GCC 2.95 as well.
   Even with the workaround, .ppm file generation will not work on those
   compilers on Windows or DOS machines, because they will put extra linefeed or
   newline characters in the output stream
*/
#if (__GNUC__ <= 2)
#define BINARY_FILE_FLAGS
#else
#define BINARY_FILE_FLAGS ,std::ios::binary
#endif    



int NeuralRegionMap::ppm_post_write_hook(const char* filename ) const
{
  const Tristate spawn       = blackboard.get_with_default("spawn_viewer",True);
  const bool     interactive = blackboard.get_with_default("interactive",True);
  
  if (spawn==True || (spawn==Uninitialized && interactive) ) {
    static int spawned_already=False;
    const bool     independent   = blackboard.get_with_default("ppm_spawn_independent_viewers",False);
    const string   remote_viewer = blackboard.get_with_default("ppm_remote_viewer",string(""));
    const string   image_viewer  = blackboard.get_with_default("ppm_image_viewer",string(""));
    const bool     remote        = blackboard.get_with_default("running_remotely",False);
    
    if (!spawned_already || independent) {
      const string command =
        (remote? remote_viewer : image_viewer) + " " +
        filename + " " + (remote? "" : "&");

      system(command.c_str());
      spawned_already=True;
    }
  }
  
  return 0;
}


void ppm_write_to_file(const string& filebase,const Plot::AARImage<>& img)
{
  /* Create combined image and save as a PPM file */
  const string filename = filebase + ".ppm";
  {
    std::ofstream os(filename.c_str() BINARY_FILE_FLAGS);
    img.ppm_write(os,filename,(unsigned char)(255));
  }
}


/* Static variables */
string NeuralRegionMap::current_region;
int    NeuralRegionMap::current_width=-1;
int    NeuralRegionMap::current_height=-1;
int    NeuralRegionMap::current_ui=-1;
int    NeuralRegionMap::current_uj=-1;
string NeuralRegionMap::current_plot;
int    NeuralRegionMap::plot_pe=PARENTPE;


template <class OutputRectangle, class InputRectangle>
inline OutputRectangle weightbounds_to_subregion(const InputRectangle& r)
{
  const typename InputRectangle::Points p=r.corners();
  return OutputRectangle(-p.yl,-p.xl,-p.yh-1,-p.xh-1);
}



const string NeuralRegionMap::pe_extension () const {
  if (plot_pe==Uninitialized)
    return string(".pe")+String::stringrep(MyPE,String::StreamFormat(2,'0'));
  return string();
}

        

const string NeuralRegionMap::filenamebase(const string& plotgroup, const string& suppliedformat) const
{
  const string defaultformat  = blackboard.lookup_map("::PlotGroup::" + plotgroup).
    get_with_default("filename_format",string(""));
  const string filenameformat = (suppliedformat != string("") ? suppliedformat : defaultformat);
  const string basename       = Parse(*(params.valueptr()),filenameformat.c_str()).cmds() + pe_extension();
  return basename;
}



NeuralRegionMap::RegionManagerList
NeuralRegionMap::retrieve_matching_regions(const string& names_string,
                                           Tristate plastic,
                                           Tristate internal) const
{
  StringParser sp;
  StringParser::arglist names;
  sp.parse(names_string,names);
  const bool all = names.empty();

  /* Dummy one-item list; will iterate over all items as-is instead */
  if (all) sp.parse(string("Dummy"),names);
  
  RegionManagerList result;
  for (StringParser::arglist::const_iterator a=names.begin(); a!=names.end(); a++)
    for (const_iterator i=begin(); i!=end(); i++) {
      RegionManager* item = (*i).second;
      if ( (all || String::non_numeric_basename_matches(*a,item->region()->name())) &&
           ((internal!=True  ||   item->region()->is_internal() ) &&
            (internal!=False || !(item->region()->is_internal())) &&
            (plastic!=True   ||   item->region()->is_plastic())   &&
            (plastic!=False  || !(item->region()->is_plastic()))))
        result.push_back(item);
    }

  return result;
}



NeuralRegionMap::RegionManagerList
NeuralRegionMap::retrieve_matching_regions(const ParamMap& params,
                                           const string& name_of_regionlist_param,
                                           const bool uselimits) const
{
  const string regionlist     = params.get_with_default(name_of_regionlist_param.c_str(),string(""));
  const Tristate plastic      = (uselimits? params.get_with_default("plastic",Uninitialized)  : Uninitialized);
  const Tristate internal     = (uselimits? params.get_with_default("internal",Uninitialized) : Uninitialized);
  return retrieve_matching_regions(regionlist, plastic, internal);
}


  
const bool NeuralRegionMap::gnuplot_image(const ParamMap& argparams,
                                          NeuralRegionManager::PlotSpec& plotspec,
                                          const string& filebase,
                                          const NeuralRegionManager::PlotSpec::MatrixTable* tempmaps,
                                          const SpecRegion& subregion) const
{
  const Tristate spawn       = argparams.get_with_default("spawn_viewer",True);
  const bool     interactive = argparams.get_with_default("interactive",True);

  /* Do a full separate plot if showing interactively (clunky, but
  helps encapsulation for now) */
  if (spawn==True || (spawn==Uninitialized && interactive) )
    plotspec.gnuplot_image("",tempmaps,&subregion);
    
  /* Plot to get file on disk */
  return plotspec.gnuplot_image(filebase,tempmaps,&subregion);
}


const NeuralRegionMap::PlotSpecList
NeuralRegionMap::retrieve_matching_plots
(const PlotSpecList::const_iterator& plotsbegin,
 const PlotSpecList::const_iterator& plotsend,
 const string& names_string) const
{
  StringParser sp;
  StringParser::arglist names;
  sp.parse(names_string,names);
  const bool all = names.empty();

  /* Dummy one-item list; will iterate over all items as-is instead */
  if (all) sp.parse(string("Dummy"),names);
  
  NeuralRegionManager::PlotSpecList result;
  for (StringParser::arglist::const_iterator a=names.begin(); a!=names.end(); a++)
    for (NeuralRegionManager::PlotSpecList::const_iterator i=plotsbegin; i!=plotsend; i++) {
      NeuralRegionManager::PlotSpec* item = *i;
      if (all || String::non_numeric_basename_matches(*a,item->name()))
        result.push_back(item);
    }
  
  return result;
}




/* This routine should be re-written to be generally valid for any bag
   of parameter sets, looking up the value of a list of Tristate
   parameters (plastic and internal, for this application) for every
   parameter set in the bag, and returning all sets in the bag that
   match.
*/
cmdstat NeuralRegionMap::cmd_child_set( CMD_ARGS )
{
  CMD_ARG_PARAMS(child_set);

  const string   parent    = arglist.next(argparams.get_with_default("parent",string("")));
  const string   children  = arglist.next(argparams.get_with_default("children",string("")));
  const Tristate plastic   = argparams.get_with_default("plastic",Uninitialized);
  const Tristate internal  = argparams.get_with_default("internal",Uninitialized);

  if (parent != "Region") {
    message(Msg::Error, "Only a parent of 'Region' is supported at this time");
    return CMD_PARAMETER_ERROR;
  }

  RegionManagerList regions = retrieve_matching_regions(children, plastic, internal);
  for (RegionManagerList::iterator r=regions.begin(); r!=regions.end(); r++) {
    StringArgs args(arglist);
    cmdparams_set(blackboard.lookup_map("::Region::"+(*r)->region()->name()),
                  args,true,true);
  }
    
  return CMD_NO_ERROR;
}

 

void  NeuralRegionMap::register_params_and_commands( void )
{
  ppm_init_hook();
  
  PARAM_A(blackboard,"internal",Uninitialized,.add_lower_bound(Uninitialized),
          "True if a region accepts input from other regions, or False if it does not.\n"
          "Often used as a guard (filter) for operations on a list of regions, where if\n"
          "specified as True only internal regions are included, if specified False only\n"
          "non-internal regions are included, and if unspecified (i.e. Uninitialized) all\n"
          "regions are included.");
  
  PARAM_A(blackboard,"plastic",Uninitialized,.add_lower_bound(Uninitialized),
          "True if a region has modifiable weights, or False if it does not.\n"
          "Often used as a guard (filter) for operations on a list of regions, where if\n"
          "specified as True only plastic regions are included, if specified False only\n"
          "non-plastic regions are included, and if unspecified (i.e. Uninitialized) all\n"
          "regions are included.");

  CMDOBJ_DOC(plot,"init_network",this,0,"%s [<named_arguments>]* [<plotgroup>]",
          "Supported <named_arguments> include:\n"
          "<plotgroup>,"
          "<filename_format>,"
          "<save_matrices>,"
          "<gnuplot_plots>,"
          "<ppm_plots>,\n"
          "<ppm_separate_plots>,"
          "<ppm_combined_plots>,"
          "<ppm_interior_border>,\n"
          "<ppm_histograms>,"
          "<ppm_mainplot>.\n\n"

          "Generate a plot of the specified <plotgroup> of items, evaluating the\n"
          "<filename_format> to construct the filename (not including the extension,\n"
          "e.g. .ppm or .ps).  The only natively-supported <plotgroup> is:\n\n"

          "   Activity\n\n"
             
          "     Shows activation levels of all the units in each area (including input\n"
          "     areas) at the current iteration.  The areas are shown from left to right\n"
          "     in the activation_order (which see).   Some areas may define more than\n"
          "     one activity plot, e.g. at different timesteps of a recurrent algorithm;\n"
          "     if so those timesteps are shown in alphabetical order by name except\n"
          "     that Activity is at the end.  Each of the areas may have an associated\n"
          "     histogram relating the activity values to another map plot; these appear\n"
          "     beneath the associated area plot.\n\n"

          "The command measure_stimulus_map may be used to create other such plots,\n"
          "e.g. for OrientationPreference, OrientationSelectivity, OcularPreference,\n"
          "etc.\n\n"

          "From zero to several output files will be generated, depending on the values\n"
          "of <ppm_plots>, <gnuplot_plots>, and <save_matrices>.\n"
             
          "If <ppm_plots> is true, the plots are generated as PPM images and saved\n"
          "to files.  Many parameters may be set to control the graphing format for\n"
          "these files; unfortunately those have not yet been enumerated in a single\n"
          "listing.\n\n"

          "If <gnuplot_plots> is true, the plots are generated as PostScript 3D plots\n"
          "using gnuplot.  At present only limited functionality is supported with\n"
          "gnuplot.  In particular, only the primary dimension will be shown, e.g.\n"
          "activity level, without e.g. any color coding for a subplot like\n"
          "OrientationPreference.  Each plot is also at present a separate gnuplot\n"
          "image; eventually they may be combined into a single plot like the PPM\n"
          "plots to facilitate comparison between simultaneous activations.\n\n"

          "If <save_matrices> is true, the plots are generated as ASCII data files\n"
          "for each Strength matrix (or Color if no Strength) in a format intended\n"
          "to be compatible with GNU Octave, but which should be easily convertible\n"
          "to any other program accepting an ASCII matrix.  Read the output files\n"
          "(*.matrix) in an editor to see the format (and the data).  To view the\n"
          "image in Octave (or, probably, Matlab), you can use the Octave\n"
          "commands `load <filename>.matrix ; imagesc(Activity);' (where the\n"
          "name Activity will differ depending on the name of the matrix plotted).");
  blackboard.lookup_map("::cmd::plot").set_local("plotgroup",string("Activity")); /* Default */

  PARAM_A(blackboard.lookup_map("::cmd"),"ppm_separate_plots",False,.add_lower_bound(False),
          "When ppm_plots is true, whether to generate individual image plots for each\n"
          "region or set of weights.  At present the individual plots do not spawn\n"
          "viewers, regardless of the value of spawn_viewer, because of the quantity\n"
          "of windows that would be spawned.  Also see ppm_combined_plots.");

  PARAM_A(blackboard.lookup_map("::cmd"),"ppm_combined_plots",True,.add_lower_bound(False),
          "When ppm_plots is true, whether to generate a combined image from all the \n"
          "plots for each region or set of weights.  Also see ppm_separate_plots.");

  
  CMDOBJ_DOC(plot_unit,"init_network",this,0,"%s [<named_arguments>]* [<ui> <uj>]*",
          "Supported <named_arguments> include:\n"
          "<colorspec>,"
          "<filename_format>,"
          "<gnuplot_plots>,"
          "<plotgroup>,\n"
          "<ppm_border>,"
          "<ppm_histograms>,"
          "<ppm_interior_border>,\n"
          "<ppm_interior_outline>,"
          "<ppm_line_*>,"
          "<ppm_mainplot>,\n"
          "<ppm_master_scale>,"
          "<ppm_outline_weights>,"
          "<ppm_outline_width>,\n"
          "<ppm_page_*>,"
          "<ppm_plots>,"
          "<ppm_separate_plots>,"
          "<ppm_combined_plots>,\n"
          "<region>,"
          "<verbose>,"
          "<weight_bare>,"
          "<weight_fill_background>,\n"
          "<weight_situate>.\n"
          "(Plus others, in all likelihood.)\n\n"
             
          "Same as plot, but plots single-unit data, e.g. weights, rather than data\n"
          "from all regions.  The only <plotgroup> currently supported is Weights.  The\n"
          "origin is at the upper left, with <ui> counting downwards and <uj> counting\n"
          "to the right.\n\n"
             
          "The values of each weight are scaled using the globals ppm_weight_scale_type\n"
          "and ppm_weight_fixed_multiplier before plotting, even with gnuplot.  Use a\n"
          "type of Fixed and a multiplier of 1.0 to see the true values in gnuplot.\n"
          "(Or leave those parameters as they are to see how the magnitudes are being\n"
          "auto-scaled for the bitmap display).");
  blackboard.lookup_map("::cmd::plot_unit")
    .set_local("plotgroup",string("Weights"))
    .set_local("weight_situate",True)
    .set_local("weight_bare",False);
  
  CMDOBJ_DOC(plot_unit_range,"init_network",this,0,"%s [<named_arguments>]* [<start_r> [<start_c>  [<end_r>  [<end_c> [<ppm_neuron_skip_aff>]]]]]",
          "Supported <named_arguments> include:\n"
          "<colorspec>,"
          "<filename_format>,"
          "<gnuplot_plots>,"
          "<name>,"
          "<plotgroup>,\n"
          "<ppm_border>,"
          "<ppm_histograms>,"
          "<ppm_interior_border>,\n"
          "<ppm_interior_outline>,"
          "<ppm_line_*>,"
          "<ppm_mainplot>,\n"
          "<ppm_master_scale>,"
          "<ppm_outline_weights>,"
          "<ppm_outline_width>,\n"
          "<ppm_page_*>,"
          "<ppm_plots>,"
          "<ppm_separate_plots>,"
          "<ppm_combined_plots>,\n"
          "<region>,"
          "<verbose>,"
          "<weight_bare>,"
          "<weight_fill_background>,\n"
          "<weight_situate>.\n"
          "(Plus others, in all likelihood.)\n\n"
             
          "Same as plot_unit, but plots data (e.g. weights) from a rectangular range of\n"
          "units in a region rather than just one.\n\n"
             
          "The only <plotgroup> currently supported is Weights.  The <name> should\n"
          "specify which set of data of the given <plotgroup> to use, e.g. Afferent0.\n"
          "A glob pattern (e.g. * or Afferent*) may also be used, to plot multiple\n"
          "items side by side, but support for this may change to e.g. a regular\n"
          "expression in the future, so do not rely on it.");
  blackboard.lookup_map("::cmd::plot_unit_range")
    .set_local("plotgroup",string("Weights"))
    .set_local("name",string("Afferent0"))
    .set_local("ppm_interior_border",1.0)
    .set_local("weight_situate",False)
    .set_local("weight_bare",True)
    .set_local("ppm_master_scale",double(Uninitialized))
    .set_local("ppm_histograms",False);
  blackboard.lookup_map("::cmd::plot_unit_range")
    .lookup("ppm_interior_border").add_default_expr("");

  PARAM_A(blackboard.lookup_map("::cmd"),"verbose",False,.add_lower_bound(False),
          "If True, increases the verbosity of the output of a command.");

  CMDOBJ_DOC(save_snapshot,"init_network",this,0,"%s [<named_arguments>]* [<filename>]",
          "Supported <named_arguments> include:\n"
          "<filename>,<regions>,<plastic>,<internal>,<verbose>.\n\n"
             
          "Save the current state of the network weights of the specified region(s).\n"
          "The binary files are intended to be portable between any machines that use\n"
          "the IEEE floating-point format.  When the file is reloaded, load_snapshot\n"
          "will assume that it was saved *after* the current iteration had completed,\n"
          "which is true when save_snapshot is used directly on the command line or in\n"
          "a command file.  If saving indirectly via a hook, you should use the hooklist\n"
          "after_learning to be consistent with this assumption.");
  blackboard.lookup_map("::cmd::save_snapshot") /* Default arguments, overriding globals */
    .set_local("plastic",True);

  PARAM_A(blackboard.lookup_map("::cmd"),"reset",False,.add_lower_bound(False),
          "Command argument specifying that internal state maintained across command\n"
          "invocations should be reset to its initial value.");

  PARAM_A(blackboard.lookup_map("::cmd"),"horizontal",True,.add_lower_bound(False),
          "When printing items from a list, whether to print each on a new line (False)\n"
          "or on the same line (True).");

  PARAM_A(blackboard.lookup_map("::cmd"),"label",string(),,
          "Command argument: label for printed information.");

  CMDOBJ_DOC(map_statistics,"init_network",this,0, "%s [<named_arguments>]* [<name>]",
          "Supported <named_arguments> include:\n"
          "<regions>,<plastic>,<internal>,<verbose>,<reset>,<cumulative>,<min_max>,<kurtosis>,<horizontal>,<label>,<name>.\n\n"
          
          "Computes and displays some statistics about the named map for the given\n"
          "region.  The headings can be suppressed (e.g. for multiple calls in a row)\n"
          "by setting verbose=False.  If <reset> is true then all internal state\n"
          "is reset, e.g. to make an average or cumulative sum be zero again; no\n"
          "statistics are printed in that case.  Note that at present cumulative\n"
          "values are cumulative over all regions and all maps measured since\n"
          "the previous reset, and thus in most cases only a single map should\n"
          "be measured when cumulative is true.");
  blackboard.lookup_map("::cmd::map_statistics") /* Default arguments, overriding globals */
    .set_local("name",string("Activity"))
    .set_local("plastic",True);

  PARAM_A(blackboard.lookup_map("::cmd::map_statistics"),"cumulative",False,.add_lower_bound(False),
          "Command argument: whether to print cumulative sums or averages.");

  PARAM_A(blackboard.lookup_map("::cmd::map_statistics"),"kurtosis",False,.add_lower_bound(False),
          "Command argument: whether to print kurtosis.");

  PARAM_A(blackboard.lookup_map("::cmd::map_statistics"),"min_max",False,.add_lower_bound(False),
          "Command argument: whether to print min and max values.");


  CMDOBJ_DOC(backproject,"init_network",this,0,"%s [<named_arguments>]* [<name>]",
          "Supported <named_arguments> include: <verbose>.\n\n"

          "Backproject current activity back to upstream regions through the\n"
          "incoming connection weights.\n");
  blackboard.lookup_map("::cmd::backproject") /* Default arguments, overriding globals */
    .set_local("name",string("Activity"));

#ifdef OBJ_LISSOM
  CMDOBJ_DOC(resp_to_residual,"init_network",this,0,"%s [<name>]",
        "Computes the input response to the residual of upstream activity.\n"
        "(use with OBJ-LISSOM)");

  CMDOBJ_DOC(train_obj_weights,"init_network",this,0,"%s [<name>]",
        "Modifies weights in OBJ-LISSOM.  Should call backproject and resp_to_residual\n"
        "just before calling this command.");

  CMDOBJ_DOC(randomize_lat_wts,"init_network",this,0,"%s [<name>]",
        "Replace all of the lateral weights with random values, as a test of\n"
        "OBJ-LISSOM.\n\n");
#endif /* OBJ_LISSOM */

  CMDOBJ_DOC(kill_connections,"init_network",this,0, "%s [<named_arguments>]*",
          "Supported <named_arguments> include:\n"
          "<regions>,<plastic>,<internal>,<verbose>.\n\n"
          
          "Prunes connections in each specified region (defaulting to all plastic\n"
          "regions) if they are at or below the values of their corresponding\n"
          "inh_death, exc_death, etc.");
  blackboard.lookup_map("::cmd::kill_connections") /* Default arguments, overriding globals */
    .set_local("plastic",True);
  
  CMDOBJ_DEFINE_CATCHUP(this,0,child_set,
          "%s [<constraints>]* <parent> <children> [<path>=<value>]*",
                        
          "This command is the same as the general set command, except that it\n"
          "can be limited to a subset of paths representing the children of a given\n"
          "set of parameters.  It can do so without specifying the actual names of\n"
          "those children, which may not be known ahead of time or easily enumerable.\n"
          "It is also a handy way to apply a set of a parameters to an enumerated\n"
          "subset of children.\n\n"
             
          "At present the only <parent> supported is 'Region', and thus the <children>\n"
          "are also <regions>.  For Region the supported <constraints> include:\n"
          "<plastic>,<internal>.\n\n"
          
          "The given list of names of <children> of the parameter set <parent>\n"
          "(which may be '' to specify all children) is first subjected to the\n"
          "given constraints, if any, to determine a list of regions.  (See the\n"
          "<plastic> and <internal> parameters for more information.)  The given\n"
          "parameters are then set to the given values in every child in that\n"
          "list.  The <path>s are relative to each child; a parameter name\n"
          "usually suffices.  Example:\n\n"
          
          "  child_set plastic=True Region '' colorspec=Grayscale");
  blackboard.lookup_map("::cmd::child_set") /* Default arguments, overriding globals */
    .set_local("verbose",True);
          
  PARAM_A(blackboard.lookup_map("::cmd"),"children",string(""),,
          "Command argument for a list of the names of children, e.g. of a set of\n"
          "parameters.  Specified names may omit trailing digits, which will select\n"
          "all items matching up to the digits, in the order of their creation.  \n"
          "(E.g. 'Eye' will match 'Eye0', 'Eye1', etc.)");
  
  CMDOBJ_DOC(define_plot,"init_network",this,0,"%s [<named_arguments>]* [<strength_map> [<color_map> [<confidence_map>]]]",
          "Supported <named_arguments> include:\n"
          "<plotgroup>,<name>,<regions>,<filename_format>,<plastic>,<internal>.\n\n"
          
          "Define a new plot for use with the plot command.\n\n"
          
          "The <name> of this plot defaults to the name of the first non-empty map\n"
          "name specified; this default value can be overridden with an explicit\n"
          "<name> if desired.  The <plotgroup> in turn defaults to the <name>, and\n"
          "it too can be overridden (e.g. to combine multiple plots into a single\n"
          "<plotgroup>).  If the <plotgroup> (whether specified or deduced) does not\n"
          "already exist, it is created, in which case you might also want to specify\n"
          "a <filename_format> to override the default format (which is constructed\n"
          "from the filebase, iteration number, presentation number, and <plotgroup>).\n\n"
          
          "The <*_map> parameters specify the name of a registered map, e.g. Activity,\n"
          "or '' if none is desired for that quantity.  The <strength_map> is usually\n"
          "the primary dimension, and is colored according to the <color_map> (if\n"
          "present).  (Note that <color_map> is not a computer-graphics-style\n"
          "colormap, i.e. a mapping from a value into a color; rather it is a matrix\n"
          "of values to use for the Hue component of the image.)  The strength of the\n"
          "colors will be determined by the <confidence_map>.  The specific colors\n"
          "used can be determined by setting appropriate parameters in\n"
          "PlotGroup::<plotgroup>::*; see the plot command for more details.\n\n"
          
          "The plot is defined for all regions by default, but an explicit list of\n"
          "regions may be supplied as the <regions> parameter.  This list (or the\n"
          "default of all regions) is further limited to plastic or non-plastic\n"
          "regions if <plastic> is True or False, and/or to internal or external\n"
          "regions only (regions which can or cannot accept input from other\n"
          "regions) if <internal>is True or False.\n\n"
          
          "Once the plot has been defined, you may obtain a plot via\n"
          "'plot <plotgroup>'.");
  PARAM_A(blackboard.lookup_map("::cmd"),"regions",string(""),,
          "Command argument for a list of the names of neural regions, in order.  If\n"
          "empty, all regions will be used, in the order they were defined.  Specified\n"
          "names may omit trailing digits, which will select all regions matching up to\n"
          "the digits, in the order of their creation.  (E.g. 'Eye' will match 'Eye0',\n"
          "'Eye1', etc.)");
  
  CMDOBJ_DOC(measure_stimulus_map,"init_network",this,0,
          "%s [<named_arguments>]* <presentation-command> [<dimension_spec>]*",
          "Supported <named_arguments> include:\n"
          "<regions>, <plastic>, and <internal> (as well as any of the\n"
          "<named_arguments> from the <dimension_spec>, below, which if specified\n"
          "here apply as defaults for all dimensions.)\n\n"

          "Computes maps of preferences for specified input patterns.  To measure the\n"
          "data required, this command calls the <presentation-command> multiple times,\n"
          "systematically varying the specified parameters (and thus the input patterns)\n"
          "and recording the responses of each unit in each region.  The\n"
          "<presentation-command> is typically input_present_object or a variant, but\n"
          "may be any valid command.\n\n"
             
          "A <dimension_spec> has the form:\n"
          "\"[<named_arguments>]* [<name> [<divisions>]]\",\n"
          "where any of the following <named_arguments> may be used:\n"
          "<cyclic>, <discrete_inputs>, <divisions>, <measure_distribution>,\n"
          "<name>, <num_bins>, <register>, <valuegenerator>,\n"
          "<varname>, and <weighted_average>.\n\n"

          "Each <dimension_spec> specifies one dimension of input variance, e.g.\n"
          "orientation or spatial frequency, of which an arbitrary number can be\n"
          "supplied.  All possible combinations of all values of each dimension\n"
          "will be tested, and the set of parameter values which generated the\n"
          "maximum response will be stored. From these stored peak values the maps\n"
          "will be constructed, using one of a variety of methods determined by the\n"
          "<named_arguments> for the dimension (which see).\n\n"

          "For each dimension, a global Param_Float parameter ranging from 0.0 to\n"
          "1.0 must be defined before this call, using the same <name> as this\n"
          "dimension (although if desired a different name for this parameter may\n"
          "be specified as <varname>).  By default, the full range of possible\n"
          "values for this parameter from 0.0 to 1.0 will be divided into\n"
          "<divisions> equally-spaced portions, and inputs will be presented\n"
          "with parameter values set to the boundaries of these divisions.\n\n"

          "The <presentation-command> will generally compute the actual input\n"
          "parameter values as a function of the normalized value of each dimension.\n"
          "E.g., an orientation might be computed from the dimension named Orientation\n"
          "as theta=2*PI*Orientation.  This uniformly normalized approach was taken to\n"
          "ensure that the underlying map computation is independent of the scale\n"
          "and type of transformation, which makes it possible to use the same\n"
          "algorithm for both linear and non-linear or discontinuous transformations.\n\n"
             
          "Responses are computed and stored for each region specified in <regions>,\n"
          "which is all regions by default.  By default, the list of regions (whether\n"
          "default or specified) is limited to those with modifiable connections (to\n"
          "avoid wasting computation time); this default may be overridden by supplying\n"
          "Uninitialized for <plastic>.  The list of regions may also be limited to\n"
          "internal regions only by supplying True for <internal>.\n\n"

          "When this command completes, maps for each specified region\n"
          "and for each dimension for which <register> is true are computed and\n"
          "registered under the names \"<name>Preference\" and (if\n"
          "<measure_distribution> is true) \"<name>Selectivity\".  For instance,\n"
          "if <name> is 'Orientation', maps will be created with the names\n"
          "'OrientationPreference' and (possibly) 'OrientationSelectivity' for\n"
          "each specified region.  The Selectivity maps range from 0 to 1.0, i.e.\n"
          "no selectivity (response was the same to all parameter values) to\n"
          "complete selectivity (neuron responded to only one parameter value).\n"
          "The method used to calculate the selectivity depends on whether the\n"
          "dimension is <cyclic>; see <weighted_average> for more details.\n\n"

          "Once the maps are registered, they may then be plotted by calling\n"
          "define_plot using these names, and then plot.  For instance, the maps\n"
          "created for the dimension named 'Orientation' can be plotted using:\n"

          "define_plot plastic=True plotgroup=OrMap '' OrientationPreference\n"
          "define_plot plastic=True plotgroup=OrMap    OrientationSelectivity\n"
          "plot OrMap");
  PARAM_A(blackboard.lookup_map("::cmd::measure_stimulus_map"),"discrete_inputs",True,.add_lower_bound(False),
          "Truncate the value for this parameter to be one of the discrete values 0 to\n"
          "<num_bins>.  This can be useful when generating random or continuous values, to\n"
          "ensure that the value of stimulus parameter corresponds precisely to the bin in\n"
          "which its response will later be placed for measurement purposes.  Usually set\n"
          "to True, but there may be some circumstance in which this is undesirable.");
  PARAM_A(blackboard.lookup_map("::cmd"),"divisions",1,.add_lower_bound(0),
          "The number of divisions to use for a dimension, e.g. for measure_stimulus_map.\n"
          "If the dimension is cyclic, this value is the same as the number of actual\n"
          "stimulus presentations that will be used; otherwise the number of presentations\n"
          "is one more than the number of divisions because of the boundary condition at\n"
          "1.0. The higher the number of divisions, the better the sampling, but the more\n"
          "presentations (and therefore time) will be required.");
  PARAM_A(blackboard.lookup_map("::cmd::measure_stimulus_map"),"measure_distribution",True,.add_lower_bound(False),
          "When measuring a preference map, whether to store a distribution of the\n"
          "maximal responses for the different values for this dimension, or just the\n"
          "single set of parameters that caused the peak response for this unit.\n"
          "Computing and storing the full distribution does not generally take much\n"
          "computation time, but it does take memory. The distribution is required\n"
          "for calculating selectivity and for <weighted_average> map computation\n"
          "types.");
  PARAM_A(blackboard.lookup_map("::cmd"),"num_bins",0,.add_lower_bound(-1),
          "When measure_distribution is true in measure_stimulus_map, how many\n"
          "distinct values of the parameter to keep track of, i.e. the number of\n"
          "bins to use in the histogram.  Higher values give more precision, but\n"
          "take more memory and slightly more time.  The default is the total number\n"
          "of presentations, which for the default equally-spaced parameter values\n"
          "provides exactly enough precision to represent all of the information\n"
          "that can be obtained.  For non-evenly-spaced parameter values (e.g. using\n"
          "a Random <valuegenerator>), increasing num_bins from this default may be\n"
          "appropriate.  In such cases, unless num_bins is quite large, you will\n"
          "probably want to enable discrete_inputs.");
  PARAM_A(blackboard.lookup_map("::cmd::measure_stimulus_map"),"register",True,.add_lower_bound(False),
          "For a dimension specified when measuring a preference map, whether to compute\n"
          "and register a map showing the preferences for that dimension.  (Often\n"
          "dimensions will be included just to ensure good coverage of possible stimuli,\n"
          "without each one necessarily being useful to graph.)");
  PARAM_A(blackboard.lookup_map("::cmd::measure_stimulus_map"),"selectivity_scale",1.0,,
          "Multiplier applied to the selectivity before it is returned as a map.  This\n"
          "defaults to 1.0, but can be set to other values to simplify the use of\n"
          "selectivity as part of combined plots; the scaling should leave the typical\n"
          "or useful values for selectivity in the range 0 to 1.0.");
  PARAM_A(blackboard.lookup_map("::cmd::measure_stimulus_map"),"weighted_average",False,.add_lower_bound(False),
          "If maximum response distribution information is available\n"
          "(measure_distribution is True), compute preference map from a weighted\n"
          "average of the values of each bin in the distribution, rather than simply\n"
          "using the actual value of the parameter for which response was maximal (the\n"
          "default, discrete method).  Such a computation will generally produce much\n"
          "more precise maps using fewer test stimuli than the discrete method.\n"
          "However, weighted_average methods generally require uniform sampling, as\n"
          "described below, which is not always desirable.\n\n"

          "Because of differences in how the averaging needs to be done near the\n"
          "borders of the parameter range, different methods are used depending on\n"
          "whether the parameter (dimension) is cyclic or not.  If this dimension is\n"
          "non-cyclic (cyclic=False), the weighted_average is computed as the center\n"
          "of gravity of the distribution, i.e. the arithmetic mean of the product of\n"
          "each bin's value and its bin number, over the total value of the bins.  The\n"
          "selectivity is then computed from the value of the bin with the largest\n"
          "value, divided by the total value of all of the bins; it is then scaled to\n"
          "range from 0.0 (no differences between bins) to 1.0 (only a single bin is\n"
          "nonzero).\n\n"

          "If this dimension is cyclic, the preference is computed as the direction of\n"
          "a vector sum.  The vectors in the sum have as their length the maximum\n"
          "response at each of the num_bins possible values, with their direction\n"
          "determined by the bin number (on a scale 0..1.0 transformed into 0..2*PI).\n"
          "The selectivity is then the length of the vector sum; it is zero if all bins\n"
          "have equal values, and 1.0 if only one bin has a nonzero value.\n\n"

          "For measurements at evenly-spaced intervals over the full range of possible\n"
          "parameter values, weighted_averages are a good measure of the underlying\n"
          "continuous-valued parameter preference, assuming that neurons are tuned\n"
          "broadly enough (and/or sampled finely enough) that they respond to at least\n"
          "two of the tested parameter values.  This method will not usually give good\n"
          "results when those criteria are not met, i.e. if the sampling is too sparse,\n"
          "not at evenly-spaced intervals, or does not cover the full range of possible\n"
          "values.  Thus a weighted_average measurement should not ordinarily use a\n"
          "random <valuegenerator>, and will probably not be useful with other\n"
          "ValueGenerator types either.  If using a ValueGenerator with a\n"
          "weighted_average; be sure to check that all of the possible num_bins values\n"
          "are equally represented in the set of testing stimuli, e.g. by setting\n"
          "display=True in the <presentation_command>.");
  PARAM_A(blackboard.lookup_map("::cmd::measure_stimulus_map"),"valuegenerator",string(""),,
          "Usually each stimulus dimension will just increase uniformly and monotonically\n"
          "from 0 to 1.0, in which case this parameter is not needed.  However, if you\n"
          "prefer random values to avoid sampling biases, or perhaps want some other\n"
          "distribution, you can specify any ValueGenerator (see input_define_generator)\n"
          "here instead.  For instance, to use a random value each time, use\n"
          "'Random 0.5 0.5'.  See also num_bins; for random distributions you will\n"
          "probably want more than the default num_bins in the plot.");
  PARAM_A(blackboard.lookup_map("::cmd::measure_stimulus_map"),"varname",string(""),,
          "Usually a variable with the same name as this dimension will be set to the\n"
          "value of the dimension's parameter at each iteration.  If you have defined\n"
          "a different variable name and want to use it instead, specify its name here.\n"
          "Note that the variable must still be a Param_Float ranging from 0 to 1.0\n"
          "as for the default case.\n\n"

          /* Might want to relax this limitation, or otherwise clean up how the parameter
             value is communicated to the <presentation_command>. */
          "Note that at present the parameter (whether default or specified explicitly\n"
          "here) must be in the global namespace, because the variable values are\n"
          "updated by setting the parameter in that namespace to make it available\n"
          "to the <presentation_command>.");
  blackboard.lookup_map("::cmd::measure_stimulus_map") /* Default arguments, overriding globals */
    .set_local("plastic",True);

  /* Set up default filename formats */
  PARAM_A(blackboard,"filename_format",string(""),,
          "String expression for a filename to use for a generated file.  It will\n"
          "be evaluated before each use, and may thus contain references to other\n"
          "parameters.  Ordinarily, the global value be \"\", which means that\n"
          "the value set for the appropriate PlotGroup (<plotgroup>) will be\n"
          "used.  Alternatively, you can force all plots to have the same filename_format\n"
          "(presumably one using multiple string substitutions) by defining this\n"
          "parameter at the root level.");

  PARAM_A(blackboard,"default_filename_format",
          string("${filebase}.${06iteration}p${03presentation}.${current_region}${?current_region,_}${current_plot}"),,
          "The filename_format used for new PlotGroups (see define_plot and\n"
          "define_plotgroup).  Also useful to override one defined for a particular\n"
          "type of plot, by supplying filename_format=$${default_filename_format} when\n"
          "calling a command.");
  

  /* Declare a ParamMap for each plot group so that we can set the
     default filenames.  New plotgroups can be defined dynamically, but
     for now we pre-set these default filenames here for
     compatibility.  Eventually specific ones like
     OrientationPreference and OcularPreference should move to a
     command file that collects that data. */
  blackboard.new_child("PlotGroup", true); /* Create branch in tree for PlotGroups */
  define_plotgroup("Activity"             ,"${filebase}.${06iteration}.${03current_object_angle}p${01presentation}");
  define_plotgroup("Weights"              ,"${filebase}.${06iteration}.wts.${03current_ui}_${03current_uj}");
  define_plotgroup("OrientationPreference","${filebase}.${06iteration}.or");
  define_plotgroup("OcularPreference"     ,"${filebase}.${06iteration}.od");
  define_plotgroup("WeightsMap"           ,"${filebase}.${06iteration}.aff_map${input_current_eye}");
  define_plotgroup("Backprojection"       ,"${filebase}.${06iteration}.bp.p${01presentation}");

  /* Not usually true PlotGroups, but useful places to store parameters nonetheless*/
  define_plotgroup("Histogram"); 
  define_plotgroup("SavedState"           ,"${filebase}.${06iteration}.wts");

  
  /* Declare parameters specific to Regions */
  ParameterMap<>& regionparams = *dynamic_cast< ParameterMap<>* >(params.valueptr());
  
  PARAM_A(regionparams,"activation_order",string("Eye Ganglia LGN Primary Secondary Association Frontal"),,
          "List of each neural region in the order in which they should be activated\n"
          "when new input is computed.  Also determines activity plot order.  If empty,\n"
          "all regions will be activated or plotted, in the order they were defined.");

  PARAM_A(regionparams,"connection_order",string("Afferent AfferentExcitatory AfferentInhibitory Lateral LateralExcitatory LateralInhibitory Efferent EfferentExcitatory EfferentInhibitory Feedback FeedbackExcitatory FeedbackInhibitory"),,
          "List of each type of connection in the order in which they should be plotted\n"
          "by plot_unit.  If empty, all connections will be plotted, in the order they\n"
          "were defined.");

  PARAM_A(regionparams,"ppm_weight_fixed_multiplier",500.0,.add_lower_bound(0.0),
          "Amount by which to multiply weight values to get luminance value for\n"
          "plots, when ppm_weight_scale_type=PPM_WtScale_Fixed.");

  PARAM_A(regionparams,"ppm_weight_fixed_offset",0.0,,
          "Amount which to add to weight values to get luminance value for\n"
          "plots, when ppm_weight_scale_type=PPM_WtScale_Fixed.");

  PARAM_A(regionparams,"colorspec",string("RYW"),,
          "Specification for a color lookup function to use for a plot of a single\n"
          "dimension.  The function returns a color when given a single quantity in\n"
          "the range 0.0 to 1.0, here called a level.\n\n"

          "The <colorspec> can be one of the named colormaps below, or it can specify\n"
          "a list of characters corresponding to colors between which to interpolate.\n"
          "(Interpolation is performed linearly in RGB space.)  Available colors include:\n\n"
        
          "  R Red\n"
          "  Y Yellow\n"
          "  G Green\n"
          "  C Cyan\n"
          "  B Blue\n"
          "  M Magenta\n"
          "  K Black\n"
          "  W White\n\n"

          "Use a lowercase letter to indicate that a color should use half intensity.\n"
          "For instance, a <colorspec> of 'KgYW' would map the level range 0.0->1.0\n"
          "to the color range black->dark green->yellow->white, with smooth\n"
          "interpolation between the specified colors.\n\n"

          
          "Predefined named <colorspec>s include:\n\n"
          
          "Cold\n"
          "  Bright cool colors based on blue and cyan.  Same as KBCW, or WBC for\n"
          "  ppm_paper_based_colors.\n\n"
          
          "Cool\n"
          "  Cool colors based on blue and cyan.  Same as KBC, or WbBC for\n"
          "  ppm_paper_based_colors.\n\n"

          "Warm\n"
          "  Warm colors based on red and yellow.  Same as KRY, or WrRY for\n"
          "  ppm_paper_based_colors.\n\n"
            
          "Hot\n"
          "  Bright warm colors based on red and yellow.  Useful for emphasizing\n" 
          "  peak values, particularly on video terminals.  Same as KRYW, or WRY for\n"
          "  ppm_paper_based_colors.  \n\n\n" 

          
          "CoolWarm\n"
          "  Uses a Cool <colorspec> for negative excursions from the middle of the\n"
          "  range, and a Warm <colorspec> for positive excursions.  Useful for\n"
          "  highlighting changes in either direction relative to a prevailing\n"
          "  background level of 0.5.  For paper_based_colors, blob outlines are\n"
          "  somewhat jagged because of the sharp transition from the colors to white.\n"
          "  Same as CBKRY, or CBbWrRY for ppm_paper_based_colors.\n\n"
            
          "ColdHot\n"
          "  Uses a Cold <colorspec> for negative excursions from the middle of the\n"
          "  range, and a Hot <colorspec> for positive excursions.  Useful for\n"
          "  highlighting changes in either direction relative to a prevailing\n"
          "  background level of 0.5.  For ppm_paper_based_colors==False, the extremes\n"
          "  are both white, which can be confusing unless the underlying\n"
          "  parameter is cyclic.  Same as WCBKRYW, or CBWRY for ppm_paper_based_colors.\n\n"

          "BlueRed\n"
          "  Uses blue colors for negative excursions from the middle of the\n"   
          "  range, and red colors for positive excursions.  Useful for\n"
          "  highlighting changes in either direction relative to a prevailing\n"
          "  background level.  Same as BKR, or BWR for ppm_paper_based_colors.\n\n\n"


          "In addition to the above named abbreviations for interpolated colormaps,\n"
          "several other specific types based on the hue, saturation, and value are\n"
          "available:\n\n"
          
          "Hue [saturation [value]]\n"
          "  Useful for plotting cyclic quantities, such as orientation.\n"
          "  The hue is computed from the level, and is combined with the given fixed\n"
          "  saturation and value (default '1.0 1.0') to determine the color.  The hue\n"
          "  wraps around at each end of the range (e.g. red->yellow->green->blue->magenta\n"
          "  ->red), and thus is usually appropriate only when the quantity plotted has\n"
          "  that same property.  For the defaults, nearly identical to RYGCBMR.\n\n"

          "Saturation [hue [value]]\n"
          "  Usually SpecifiedHue is used instead of specifying this type directly.\n"
          "  The saturation is computed from the level, and is combined with the given\n"
          "  fixed hue and value (default '0.0 1.0') to determine the color.\n\n"

          "Value [hue [saturation]]\n"
          "  Usually Grayscale is used instead of specifying this type directly.\n"
          "  The value is computed from the level, and is combined with the given fixed\n"
          "  hue and saturation (default '0.0 0.0') to determine the color.  The defaults\n"
          "  result in a range of grayscale values from black to white; the optional\n"
          "  arguments allow other colors to be used instead of gray.\n"
          "  For the defaults, nearly identical to KW.\n\n"

          "Grayscale [hue [saturation]]\n"
          "  Useful for monochrome displays or printers, or to show photographs.\n"
          "  Same as Value but the scale is flipped when ppm_paper_based_colors=True.\n"
          "  This makes the most-active areas show up with the intensity that is most\n"
          "  visible for the given medium (video or paper).  For the defaults, nearly\n"
          "  identical to KW, or WK for ppm_paper_based_colors.\n\n"

          "SpecifiedHue [hue [confidence]]\n"
          "  Useful for color-coding a plot with a specific hue visible on the default\n"
          "  background. For paper_based_colors=False, same as ValueColorLookup;\n"
          "  the confidence is used as the saturation.  Such a plot works well for\n"
          "  showing color on a black background.  For paper_based_colors==True,\n"
          "  returns the specified hue masked by the specified confidence, such\n"
          "  that low values produce white, and high values produce black for low\n"
          "  confidences and the specified hue for high confidences.  Such a plot\n"
          "  is good for showing colors on light backgrounds.\n\n"

          "MapSpecifiesHue [nameofhuemap [nameofconfidencemap]]\n"
          "  Neural-region-specific variant of SpecifiedHue where these colorspec\n"
          "  arguments specify not the actual hue and confidence, but the names of\n"
          "  registered maps (as in define_plot) in which to look up the hue and\n"
          "  confidence when plotting.  This colorspec can be used by plot_unit or\n"
          "  plot_unit_range to colorize a plot based on some property of a unit;\n"
          "  it is not supported in other contexts.  Examples:\n"
          "  Region::Eye0::Afferent0::colorspec='MapSpecifiesHue OrientationPreference OrientationSelectivity'\n"
          "  Region::Ganglia*::Afferent*::colorspec='MapSpecifiesHue OrientationPreference OrientationSelectivity\n\n"
          
          "SpecifiedColor [hue [saturation [value]]]\n"
          "  Used to turn off color ranges, e.g. for a plot whose shape is more\n"
          "  important than the intensity of each pixel, such as a histogram.  Ignores\n"
          "  the level, and always returns the single given fixed color.  The default\n"
          "  color is a medium gray: '0.0 0.0 0.5'.  For the defaults, nearly identical\n"
          "  to 'w'.");

#define PARAM_ARO(bboard,name_str,initial_value,options,doc)\
PARAM_A(bboard,name_str,initial_value,options,doc);\
bboard.lookup(name_str).add_setfn(new setfnobj2_read_only_param_setfn2())

  PARAM_ARO(regionparams,"type",string(),,
          "Reports the type of this region.");

  PARAM_A(regionparams,"height",0,.add_lower_bound(0),
          "Reports the number of units in each column of a region.");
  
  PARAM_A(regionparams,"width",0,.add_lower_bound(0),
          "Reports the number of units in each row of a region.");

  PARAM_A(regionparams,"xoffset",0.5,,
          "Reports the horizontal position of the origin of this region.");

  PARAM_A(regionparams,"yoffset",0.5,,
          "Reports the vertical position of the origin of this region.");


  PARAM_A(regionparams,"histo_name",string("OrientationPreference"),,
          "When computing a histogram, the name of the map to use when determining the\n"
          "bin to which a given unit belongs.  At present, the Strength::name for the\n"
          "plot which a given histogram accompanies is used for the bin value.");

  PARAM_A(regionparams,"histo_colorspec",string("Hue"),,
          "Same as colorspec but specific to histogram plots.  If this parameter is\n"
          "not an empty string, its value is used instead of the value of colorspec\n"
          "for a histogram.  (Without it, it would be difficult to set the colorspec\n"
          "default for all histograms.)");

  PARAM_A(regionparams,"num_bins",36,.add_lower_bound(0),
          "Number of bins to use in histogram plots.");

  PARAM_A(blackboard,"cyclic",True,.add_lower_bound(False).add_upper_bound(True),
          "Whether this range or quantity is cyclic, i.e. has upper and lower bounds\n"
          "that are identical (like orientation or hue).  Being (or not being) cyclic\n"
          "is usually most important when we must obtain a number within a specified\n"
          "range, when given one that may fall outside of it.  If the range is cyclic,\n"
          "the values will wrap around to get a result in range; otherwise they will be\n"
          "cropped at the ends of the range.  It can also affect whether bounds are\n"
          "considered exclusive (appropriate for cyclic ranges) or inclusive\n"
          "(appropriate for non-cyclic ranges).");

  PARAM_A(regionparams,"range_end",0.25,.add_lower_bound(0),
          "Upper bound of a 1-dimensional range, e.g. for histogram values.");

  PARAM_A(regionparams,"reference",string(),,
          "In general, the name of an object to use as a reference.  For a map plot,\n"
          "the name of a map (in the form region::mapname) to subtract from the current\n"
          "Strength map before plotting.");

  PARAM_A(regionparams,"vertical",False,.add_lower_bound(False).add_upper_bound(True),
          "Determines the orientation of some types of plots, e.g. histograms.  If true,\n"
          "the image is oriented with the long direction vertically.");

  PARAM_A(regionparams,"aspect_ratio",0.25,.add_lower_bound(0),
          "Determines the aspect ratio for some types of plots, e.g. histograms.  For a\n"
          "histogram, the aspect ratio is the ratio between the number of bins and the\n"
          "length of the representation to use for the bin fullnesses.");


  PARAM_A(blackboard,"name",string(""),,
          "A name, as a string.  This parameter is used as an argument for commands\n"
          "and for e.g. specifying a name for some part of a Region.");

  PARAM_A(blackboard,"value_offset",0.0,,
          "Offset for a strength or value, e.g. an activity level, as opposed to a\n"
          "size_scale.  See also value_scale.");

  PARAM_A(blackboard,"value_scale",1.0,,
          "Scale for a strength or value, e.g. an activity level, as opposed to a\n"
          "size_scale.  See also value_offset.");

  PARAM_A(blackboard,"size_scale",1.0,.add_lower_bound(0.0),
          "Scale intended to specify distance or size across the surface of a map,\n"
          "as opposed to a value_scale.  Most uses of this parameter are overridden\n"
          "by ppm_master_scale, which see.\n");

  PARAM_A(blackboard,"start_c",-1,.add_lower_bound(-1),
          "Number of the column in which to start analysis or plotting.\n"
          "See also start_r,end_c,end_r; negative values on any of these\n"
          "mean to include all available units.");
  
  PARAM_A(blackboard,"start_r",-1,.add_lower_bound(-1),
          "Number of the row in which to start analysis or plotting.\n"
          "See also start_c,end_c,end_r; negative values on any of these\n"
          "mean to include all available units.");

  PARAM_A(blackboard,"end_c",-1,.add_lower_bound(-1),
          "Number of the first column not to include in analysis or plotting.\n"
          "See also start_c,start_r,end_r; negative values on any of these\n"
          "mean to include all available units.");
  
  PARAM_A(blackboard,"end_r",-1,.add_lower_bound(-1),
          "Number of the first row not to include in analysis or plotting.\n"
          "See also start_c,start_r,end_c; negative values on any of these\n"
          "mean to include all available units.");

  PARAM_II(PARAM_INT,reversed_color_order,&Plot::HSVPixel<>::reversed_color_order,False,True,
          "The hue in HSV-based colors normally goes red->yellow->green->purple->red\n"
          "as the numeric hue goes from 0 to 1.0.  Some code and publications use the\n"
          "reverse order (red->purple->green->yellow->red), and if you want to match\n"
          "them, set this parameter to True.");
  
  // Should clean up these two parameters a bit -- e.g. define them only in 
  // the parameter list for cmd_plot?
  blackboard.define_param(DECLARE_PARAM(PARAM_INT,"current_ui",true,&current_ui));
  params_define_doc("current_ui",
          "Read-only parameter which reports the unit currently being examined;\n"
          "see current_region for more details.");
  SETFN_DEFINE2(current_ui,read_only_param_setfn2);
 
  blackboard.define_param(DECLARE_PARAM(PARAM_INT,"current_uj",true,&current_uj));
  params_define_doc("current_uj",
          "Read-only parameter which reports the unit currently being examined;\n"
          "see current_region for more details.");
  SETFN_DEFINE2(current_uj,read_only_param_setfn2);

  blackboard.define_param(DECLARE_PARAM(PARAM_INT,"current_height",true,&current_height));
  params_define_doc("current_height",
          "Read-only parameter which reports the height of the region currently being\n"
          "examined; see current_region for more details.");
  SETFN_DEFINE2(current_height,read_only_param_setfn2);

  blackboard.define_param(DECLARE_PARAM(PARAM_INT,"current_width",true,&current_width));
  params_define_doc("current_width",
          "Read-only parameter which reports the width of the region currently being\n"
          "examined; see current_region for more details.");
  SETFN_DEFINE2(current_width,read_only_param_setfn2);

  blackboard.define_param(DECLARE_PARAM(PARAM_USTRING,"current_region",true,&current_region));
  params_define_doc("current_region",
          "Read-only parameter which reports the region currently being examined, e.g.\n"
          "in weight plots or weight analysis.  The current_* parameters can be useful\n"
          "for e.g. constructing filenames.  At present, their value is only guaranteed\n"
          "to be defined during a call to the plot_unit, save_snapshot, and load_snapshot\n"
          "commands, and only the relevant ones for each command are updated.  When\n"
          "not defined, they have clearly undefined values, usually -1 or ''.");
  SETFN_DEFINE2(current_region,read_only_param_setfn2);

  blackboard.define_param(DECLARE_PARAM(PARAM_USTRING,"current_plot",true,&current_plot));
  params_define_doc("current_plot",
          "Read-only parameter which reports the name of the plot currently being\n"
          "constructed, if any; see current_region for more details.  The name is\n"
          "the name of the current PlotGroup except while constructing a specific\n"
          "plot, in which case it is the name of that particular plot.");
  SETFN_DEFINE2(current_plot,read_only_param_setfn2);


  /* Legacy multiprocessor support */
  PARAM_I(PARAM_INT,   plot_pe,Uninitialized,NPES-1,
          "PE which plots data, e.g. for the plot command.  By default only a single\n"
          "PE plots the data, but when debugging on multiple-PE machines, sometimes\n"
          "it is helpful to get plots from every PE (if plot_pe == Uninitialized)\n"
          "or just a different PE than usual.  This can help e.g. verify that\n"
          "each PE has identical copies of global arrays.");
}



/* Might be better using a cmd::activate::regions parameter instead of
   Regions::activation_order.  */
void NeuralRegionMap::activate(bool learn, bool settle, bool activatefn, bool verbose) const
{
  /* Might want to cache the result of this call, though the time taken is probably minimal. 
     (Caching would just need a setfn for the activation_order parameter to update this value.) */
  RegionManagerList regions = retrieve_matching_regions(*params,"activation_order",false);

  /* Activate each region in order specified */
  for (RegionManagerList::iterator r=regions.begin(); r!=regions.end(); r++) {
    message((verbose? Msg::Notify : Msg::Verbose), "Activating " + (*r)->region()->name());
    (*r)->region()->activate(learn,settle,activatefn);
  }
}



cmdstat NeuralRegionMap::cmd_plot_unit( CMD_ARGS )
{
  CMD_ARG_PARAMS(plot_unit);

  const string plotgroup        = argparams.get_with_default("plotgroup",string("Weights"));
  const string default_region   = argparams.get_with_default("default_region",string(""));
  const string specified_region = argparams.get_with_default("region",string(""));
  const string regionname       = (specified_region!=""? specified_region : default_region);
  
  const NeuralRegionManager* rm = lookup_internal_region(regionname);
  if (!rm) return CMD_PARAMETER_ERROR;

  if (plotgroup!="Weights")
    message(Msg::Warning, "The plot_unit command only supports a <plotgroup> of Weights.");
  
  /* Create one image per unit */
  int beenthrough=false;
  bool statusok=true;
  for (; (!arglist.empty()||!beenthrough); ) {
    define_globals(rm,Uninitialized,Uninitialized,plotgroup);
    const bool numargsisodd=arglist.oneremaining();
    const int  ui=arglist.next(rm->default_ui());
    const int  uj=arglist.next(rm->default_uj());
    
    /* Construct and save image */
    if (numargsisodd) {
      message(Msg::Error, "Wrong number of arguments to plot_unit");
      return CMD_PARAMETER_ERROR;
    }
    define_globals(rm,ui,uj,plotgroup);
    
    // Multiprocessor note:
    /*
      Assumes that all weights will be available to all units, which
      requires NeuralRegion::get_weights to fetch them from the
      appropriate PE if need be.
    */
    if (plot_pe==Uninitialized || MyPE==plot_pe) {
      message(Msg::Notify, "Plotting weights for " +
              rm->region()->name() + " unit (" +
              String::stringrep(ui) + "," +
              String::stringrep(uj) + ")");

      const bool newstatus = plot_write_unit(argparams, rm, ui, uj);
      if (!newstatus) statusok=false;
    }
    
    beenthrough=true;
  }
  define_globals();
  
  CMD_ARG_ASSERT_EMPTY;
  return (statusok ? CMD_NO_ERROR : CMD_PARAMETER_ERROR);
}




const NeuralRegionManager* NeuralRegionMap::lookup_region(const string& name) const
{
  const NeuralRegionManager* rm = getptr(name);

  if (!rm) {
    message(Msg::Error, "Region '" + name + "' not found");
    return 0;
  }
  return rm;
}



const NeuralRegionManager* NeuralRegionMap::lookup_internal_region(const string& name) const
{
  const NeuralRegionManager* rm = lookup_region(name);

  if (rm && !rm->internalregion()) {
    message(Msg::Error, "Region '" + name + "' has no weights");
    return 0;
  }
  return rm;
}



cmdstat NeuralRegionMap::cmd_plot_unit_range( CMD_ARGS )
{
  CMD_ARG_PARAMS(plot_unit_range);

  const string plotitem       = argparams.get_with_default("name",string(""));
  const string default_region = argparams.get_with_default("default_region",string(""));
  const string specified_region=argparams.get_with_default("region",string(""));
  const string regionname     = (specified_region!=""? specified_region : default_region);
  const bool   verbose        = argparams.get_with_default("verbose",True);
  int          ui_start       = arglist.next(argparams.get_with_default("start_r", -1));
  int          uj_start       = arglist.next(argparams.get_with_default("start_c", -1));
  int          ui_end         = arglist.next(argparams.get_with_default("end_r",   -1));
  int          uj_end         = arglist.next(argparams.get_with_default("end_c",   -1));
  int          step           = arglist.next(argparams.get_with_default("ppm_neuron_skip_aff",1));
  
  const NeuralRegionManager* rm = lookup_internal_region(regionname);
  if (!rm) return false;

  const int nrows = rm->region()->nrows();
  const int ncols = rm->region()->ncols();

  if (ui_start<0) ui_start=0;  if (ui_end<0) ui_end = nrows;
  if (uj_start<0) uj_start=0;  if (uj_end<0) uj_end = ncols;
  if (step<1)     step=1;

  ui_start = Generic::crop(0,nrows,ui_start);
  ui_end   = Generic::crop(0,nrows,ui_end);
  uj_start = Generic::crop(0,nrows,uj_start);
  uj_end   = Generic::crop(0,nrows,uj_end);

  /* Update global that might be used in filenames; should probably be eliminated */
  WorldViews::set_current_eye(String::numeric_extension<int>(plotitem));

  message((verbose? Msg::Notify : Msg::Verbose), "Plotting " + rm->region()->name() + "::" + plotitem);

  const bool status = plot_write_unit_range(argparams,rm,plotitem,ui_start,uj_start,ui_end,uj_end,step);
  define_globals();
  
  CMD_ARG_ASSERT_EMPTY;
  return (status ? CMD_NO_ERROR : CMD_PARAMETER_ERROR);
}



cmdstat NeuralRegionMap::cmd_plot( CMD_ARGS )
{
  CMD_ARG_PARAMS(plot);

  if (plot_pe!=Uninitialized && MyPE!=plot_pe)
    return true;
  
  /* Construct each subimage, zero or more for each NeuralRegion */
  ImagePListList imagelists;

  const string   plotgroup_     = arglist.next(argparams.get_with_default("plotgroup",string("")));
  const string   plotgroup      = (plotgroup_!=""? plotgroup_ : argparams.get_with_default("plotgroup",string("Activity")));
  const string   suppliedformat = argparams.get_with_default("filename_format",string(""));
  const bool     verbose        = argparams.get_with_default("verbose",True);
  const bool     save_matrices  = argparams.get_with_default("save_matrices",False);
  const bool     gnuplot_plots  = argparams.get_with_default("gnuplot_plots",False);
  const bool     ppm_plots      = argparams.get_with_default("ppm_plots",True);
  const bool     separate_plots = argparams.get_with_default("ppm_separate_plots",True);
  const bool     combined_plots = argparams.get_with_default("ppm_combined_plots",True);
  const bool     histograms     = argparams.get_with_default("ppm_histograms",True);
  const bool     mainplot       = argparams.get_with_default("ppm_mainplot",True);
  const double   master_scale   = argparams.get_with_default("ppm_master_scale", double(Uninitialized));

  const double   interior_b     = argparams.get_with_default("ppm_interior_border",1.0);
  const int      interior_border= (interior_b>=0? int(interior_b) : std::max(2,int(-interior_b*min_of_max_dimensions())));
  const Color    pagecolor      = lookup_param(argparams,    "ppm_page", Color());
  bool status=true;

  SpecRegion maxregion          = max_subregion();

  RegionManagerList regions     = retrieve_matching_regions(*params,"activation_order",false);
  

  /* Plot each region in the activation_order */
  for (RegionManagerList::iterator r=regions.begin(); r!=regions.end(); r++) {
    NeuralRegionManager* rm = (*r);
    
    for (NeuralRegionManager::PlotSpecList::const_iterator pi=rm->plotspeclist_begin(plotgroup);
         pi!=rm->plotspeclist_end(plotgroup); pi++) {

      define_globals(rm,Uninitialized,Uninitialized,(*pi)->name());
        
      /* Register the specified reference map, if any.  Only accepts a
         restricted format at present: "region::mapname", and creates
         a map named __StrengthReference for PlotSpecification to use. */
      const string   ref_path_name  = (*pi)->lookup_param("Strength::reference",string());
      NeuralRegionManager::PlotSpec::MatrixTable tempmaps;

      message((verbose? Msg::Notify : Msg::Verbose), "Plotting " + (*pi)->objectname() + "::" + (*pi)->name() +
              (ref_path_name=="" ? string() : " relative to " + ref_path_name));

      if (ref_path_name!="") {
        const PathSpecification referencepath(ref_path_name);
        const NeuralRegionManager* ref_rm  = getptr(referencepath.first());
        const NeuralRegion::MapBaseType* ref_map =
          (!ref_rm? 0 : ref_rm->region()->table().getptr(referencepath.last()));
        if (referencepath.all().size()!=2 || !ref_map)
          message(Msg::Error, "Invalid reference path: " + ref_path_name);
        else {
          typedef mat::MatrixInterfaceAdapter<NeuralRegion::MapBaseType> MatAdapter;
          tempmaps.set("__StrengthReference",new MatAdapter(*ref_map));
        }
      }
      
      if (gnuplot_plots) {
        if (!gnuplot_image(argparams,**pi,filenamebase(plotgroup,suppliedformat),&tempmaps,
                           lookup_subregion((**pi).param_map(),SpecRegion())))
          status=false;
      }
      
      if (save_matrices) {
        const SpecRegion& region = lookup_subregion((**pi).param_map(),SpecRegion());
        if (!((*pi)->save_matrix(filenamebase(plotgroup,suppliedformat),&tempmaps,
                                 &region)))
          status=false;
      }
      
      /*
        Compute and save an image as a ppm file.  The first PE computes and saves 
        the entire image; this could be improved by making each PE responsible for
        part of the image or for an activity or input panel, etc., but the speedup
        is probably minimal since I imagine the process is IO-bound.
      */
      if (ppm_plots) {
        /* Holder for a set of related images (main plot, histogram, etc.) */
        ImagePList* li = new ImagePList;

        /* Add main plot */
        if (mainplot) {
          Plot::AARImage<>* img = (*pi)->bitmap_image(master_scale,&maxregion,&tempmaps);
          if (img) {
            if (combined_plots) li->push_back(img);
            if (separate_plots) ppm_write_to_file(filenamebase(plotgroup,suppliedformat),*img);
          }
        }
        
        /* Add histogram(s) */
        if (histograms) {
          Plot::AARImage<>* histoimg =
            (*pi)->bitmap_histogram(master_scale,blackboard.lookup_map("::PlotGroup::Histogram"),&maxregion,&tempmaps);
          if (histoimg) {
            if (combined_plots) li->push_back(histoimg);
            if (separate_plots) ppm_write_to_file(filenamebase(plotgroup,suppliedformat)+"_Histogram",*histoimg);
          }
        }

        /* If anything was plotted, add it to the image grid */
        if (li->empty())
          delete li;
        else
          imagelists.push_back(li);
      }
    }
  }

  define_globals(0,Uninitialized,Uninitialized,plotgroup);
  if (ppm_plots && combined_plots)
    status = ppmgrid_write(filenamebase(plotgroup,suppliedformat),
                           imagelists,interior_border,pagecolor);
  Generic::nested_delete_contents(imagelists);
  define_globals();
  
  CMD_ARG_ASSERT_EMPTY;  
  return (status ? CMD_NO_ERROR : CMD_PARAMETER_ERROR);
}



const bool NeuralRegionMap::add_maps_for_unit(NeuralRegionManager::PlotSpec::MatrixTable& tempmaps,
                                              const NeuralRegionManager& rm,
                                              const NeuralRegionManager::PlotSpec& plotspec,
                                              const int ui, const int uj) const
{
  const string   ref_path_name  = plotspec.lookup_param("Strength::reference",string());
  if (!rm.add_maps_for_unit(tempmaps,plotspec,ui,uj))
    return false;
  
  /* Register the specified reference map, if any.  Only accepts a
     restricted format at present: "region::mapname", and creates
     a map named __StrengthReference for PlotSpecification to use. */
  if (ref_path_name!="") {
    const PathSpecification referencepath(ref_path_name);
    const NeuralRegionManager* ref_rm = getptr(referencepath.first());
    if (referencepath.all().size()!=2 || !ref_rm) {
      message(Msg::Error, "Invalid reference path: " + ref_path_name);
      return false;
    }
    else
      return ref_rm->add_maps_for_unit(tempmaps,referencepath.last(),
                                       "__StrengthReference",plotspec,ui,uj);
  }
  
  return true;
}


const string NeuralRegionMap::overriding_colorspec
(const NeuralRegionManager* rm, int ui, int uj, const string colorspec) const
{
  typedef const NeuralRegion::MapBaseType* mapptr;
  StringParser sp;
  StringArgs   specargs(sp, colorspec);
  const bool   override_colorspec = (specargs.next(string(""))=="MapSpecifiesHue");
  const mapptr colorizingmap      = !override_colorspec? 0 : rm->region()->table().getptr(specargs.next(string("")));
  const mapptr confidencizingmap  = !override_colorspec? 0 : rm->region()->table().getptr(specargs.next(string("")));
  return
    (!override_colorspec? "" :
     ("SpecifiedHue" +
      (!colorizingmap?     "" : " " + String::stringrep(mat::elem(*colorizingmap,ui,uj))) +
      (!confidencizingmap? "" : " " + String::stringrep(mat::elem(*confidencizingmap,ui,uj)))));
}



const bool NeuralRegionMap::plot_write_unit
(const ParamMap& argparams, const NeuralRegionManager* rm, 
 const int ui, const int uj) const
{
  /* Construct each subimage, zero or more for each NeuralRegion */
  ImagePListList imagelists;
  
  const string   plotgroup      = argparams.get_with_default("plotgroup",string(""));
  const string   suppliedformat = argparams.get_with_default("filename_format",string(""));
  const bool     verbose        = argparams.get_with_default("verbose",True);
  const bool     situate        = argparams.get_with_default("weight_situate",True);
  const bool     gnuplot_plots  = argparams.get_with_default("gnuplot_plots",False);
  const bool     ppm_plots      = argparams.get_with_default("ppm_plots",True);
  const bool     separate_plots = argparams.get_with_default("ppm_separate_plots",True);
  const bool     combined_plots = argparams.get_with_default("ppm_combined_plots",True);
  const bool     histograms     = argparams.get_with_default("ppm_histograms",True);
  const bool     mainplot       = argparams.get_with_default("ppm_mainplot",True);
  const double   master_scale   = argparams.get_with_default("ppm_master_scale", double(Uninitialized));

  const double   interior_b     = argparams.get_with_default("ppm_interior_border",1.0);
  const int      interior_border= (interior_b>=0? int(interior_b) : std::max(2,int(-interior_b*min_of_max_dimensions())));
  const Color    pagecolor      = lookup_param(argparams, "ppm_page", Color());
  bool status=true;
  
  PlotSpecList plots = retrieve_matching_plots
    (rm->plotspeclist_begin(plotgroup), rm->plotspeclist_end(plotgroup),
     params->get_with_default("connection_order",string("")));

  for (PlotSpecList::const_iterator pi=plots.begin(); pi!=plots.end(); pi++) {
    define_globals(rm,ui,uj,(*pi)->name()); /* Ensure current_* are available for e.g. filename_format */
    
    /* Parameters specific to this type of plot, or that we otherwise must handle */
    const bool     draw_outline   = (*pi)->lookup_param("ppm_outline_weights", False);
    const int      outline_width  = (*pi)->lookup_param("ppm_outline_width", 1);
    const string   ref_path_name  = (*pi)->lookup_param("Strength::reference",string());
    const string   colorspec      = (*pi)->lookup_param("colorspec",string());
    
    /* Get maps to plot, or abort if this is an invalid unit */
    NeuralRegionManager::PlotSpec::MatrixTable tempmaps;
    if (!add_maps_for_unit(tempmaps,*rm,**pi,ui,uj)) {
      define_globals();
      return false;
    }

    message((verbose? Msg::Notify : Msg::Verbose), "Plotting " + rm->internalregion()->name() + "::" + (*pi)->name() +
            (ref_path_name=="" ? string() : " relative to " + ref_path_name));


    if (gnuplot_plots) {
      if (unit_gnuplot(argparams,**pi,filenamebase(plotgroup,suppliedformat),&tempmaps,
                       rm->internalregion()->weights((*pi)->name(),ui,uj).bounds(),situate))
        status=false;
    }
    
    if (ppm_plots) {
      ImagePList* li = new ImagePList;
      unit_bitmap(master_scale,*li,**pi,&tempmaps,
                  rm->internalregion()->weights((*pi)->name(),ui,uj).bounds(),
                  pagecolor,draw_outline,outline_width,situate,mainplot,
                  separate_plots,combined_plots,
                  filenamebase(plotgroup,suppliedformat),histograms,
                  -1,false,overriding_colorspec(rm,ui,uj,colorspec));

      /* If anything was plotted, add it to the image grid */
      if (li->empty())
        delete li;
      else
        imagelists.push_back(li);
    }
  }

  define_globals(rm,ui,uj,plotgroup);
  if (ppm_plots && combined_plots)
    status = ppmgrid_write(filenamebase(plotgroup,suppliedformat),
                           imagelists,interior_border,pagecolor);
  Generic::nested_delete_contents(imagelists);

  define_globals();
  return status;
}



const bool NeuralRegionMap::plot_write_unit_range
(const ParamMap& argparams, const NeuralRegionManager* rm, 
 const string& plotitem, int ui_start, int uj_start, int ui_end, int uj_end, int step) const
{

#if (NPES>1)
  if (NPEs>1) {
    message(Msg::Error, "plot_write_unit_range is not supported on multi-PE systems");
    return false;
  }
#endif
  
  /* Construct each subimage, zero or more for each NeuralRegion */
  ImagePListList imagelists;

  const string   plotgroup      = argparams.get_with_default("plotgroup",string(""));
  const bool     ppm_plots      = argparams.get_with_default("ppm_plots",True);
  const bool     separate_plots = argparams.get_with_default("ppm_separate_plots",True);
  const bool     combined_plots = argparams.get_with_default("ppm_combined_plots",True);
  const bool     situate        = argparams.get_with_default("weight_situate", False);
  const bool     bare           = argparams.get_with_default("weight_bare", True);
  const bool     fill_bg        = argparams.get_with_default("weight_fill_background", False);
  const bool     showinterior   = argparams.get_with_default("ppm_interior_outline", False);
  const Color    pagecolor      = lookup_param(argparams, (!showinterior && !fill_bg? "ppm_line" : "ppm_page"), Color());
  const bool     histograms     = argparams.get_with_default("ppm_histograms",True);
  const bool     mainplot       = argparams.get_with_default("ppm_mainplot",True);
  const double   master_scale   = argparams.get_with_default("ppm_master_scale", double(Uninitialized));
  const string   suppliedformat = argparams.get_with_default("filename_format",string(""));
  const double   interior_b     = argparams.get_with_default("ppm_interior_border",1.0);
  const int      interior_border= (interior_b>=0? int(interior_b) : std::max(2,int(-interior_b*min_of_max_dimensions())));

  /* Plot each unit */
  for   (int ui=ui_start; ui<ui_end; ui+=step) {
    ImagePList* li = new ImagePList;
    for (int uj=uj_start; uj<uj_end; uj+=step) {
      for (NeuralRegionManager::PlotSpecList::const_iterator pi=rm->plotspeclist_begin(plotgroup);
           pi!=rm->plotspeclist_end(plotgroup); pi++)
        if (String::glob_match(plotitem,(*pi)->name())) {
          define_globals(rm,ui,uj,(*pi)->name());

          /* Get maps to plot, or abort if this is an invalid unit */
          NeuralRegionManager::PlotSpec::MatrixTable tempmaps;
          if (!add_maps_for_unit(tempmaps,*rm,**pi,ui,uj))
            return false;

          /* Parameters specific to this type of plot, or that we otherwise must handle */
          const bool     draw_outline   = (bare? False : (*pi)->lookup_param("ppm_outline_weights", False));
          const int      outline_width  = (bare? 0     : (*pi)->lookup_param("ppm_outline_width", 1));
          const int      border_width   = (bare? 0     : (*pi)->lookup_param("ppm_border", 1));
          const string   colorspec      = (*pi)->lookup_param("colorspec",string());

          /* Plot the unit */
          if (ppm_plots)
            unit_bitmap(master_scale,*li,**pi,&tempmaps,
                        rm->internalregion()->weights((*pi)->name(),ui,uj).bounds(),
                        pagecolor,draw_outline,outline_width,situate,
                        mainplot,separate_plots,combined_plots,
                        filenamebase(plotgroup,suppliedformat),
                        histograms,border_width,fill_bg,
                        overriding_colorspec(rm,ui,uj,colorspec));
        }
    }

    /* If anything was plotted, add it to the image grid */
    if (li->empty())
      delete li;
    else
      imagelists.push_back(li);
  }

  define_globals(rm,Uninitialized,Uninitialized,plotgroup);
  bool status=true;
  if (ppm_plots && combined_plots)
    status = ppmgrid_write(filenamebase(plotgroup+"Map",suppliedformat),
                           imagelists,interior_border,pagecolor,false);
  Generic::nested_delete_contents(imagelists);

  return status;
}



bool NeuralRegionMap::unit_gnuplot(const ParamMap& argparams,
                                   NeuralRegionManager::PlotSpec& plotspec,
                                   const string& filebase,                         
                                   const NeuralRegionManager::PlotSpec::MatrixTable* tempmaps,
                                   const InternalNeuralRegion::WeightBounds& bounds,
                                   bool situate) const
{
  SpecRegion region = (situate? lookup_subregion(plotspec.param_map(),SpecRegion()) : 
                       weightbounds_to_subregion<SpecRegion>(bounds.aarectangle()));
  return gnuplot_image(argparams,plotspec,filebase,tempmaps,region);
}




bool NeuralRegionMap::unit_bitmap(const double master_scale, ImagePList& imagelist,
                                  const NeuralRegionManager::PlotSpec& plotspec,
                                  const NeuralRegionManager::PlotSpec::MatrixTable* tempmaps,
                                  const InternalNeuralRegion::WeightBounds& bounds,
                                  const Color& pagecolor,
                                  bool draw_outline, int  outline_width,
                                  bool situate, bool mainplot, bool separate_plots,
                                  bool combined_plots, const string& filebase,
                                  bool histograms, int  border_width, bool fill_bg,
                                  const string& overriding_colorspec) const
{
  SpecRegion maxregion = max_subregion();
  SpecRegion region = (situate? lookup_subregion(plotspec.param_map(),SpecRegion()) : 
                       weightbounds_to_subregion<SpecRegion>(bounds.aarectangle()));

  /* Add main plot */
  if (mainplot) {
    Plot::MatrixImage<>* img = plotspec.bitmap_image(master_scale,&maxregion,tempmaps,&region,border_width,overriding_colorspec);
    if (!img) return false;
    
    /* Outline the weights, if needed */
    if (draw_outline || fill_bg) {
      InternalNeuralRegion::WeightBounds* wtbounds = bounds.clone();
      if (!region.isinfinite())
        wtbounds->translate(int(region.corners().yl),int(region.corners().xl));
      if (fill_bg)
        img->outline_boundary(*wtbounds,outline_width,pagecolor,fill_bg);
      else
        img->outline_boundary(*wtbounds,outline_width);
      delete wtbounds;
    }
    
    /* Add this image to the grid */
    if (combined_plots) imagelist.push_back(img);
    if (separate_plots) ppm_write_to_file(filebase,*img);
  }
  
  /* Add histogram(s) */
  if (histograms) {
    Plot::AARImage<>* histoimg =
      plotspec.bitmap_histogram(master_scale,blackboard.lookup_map("::PlotGroup::Histogram"),&maxregion,tempmaps);
    if (histoimg) {
      if (combined_plots) imagelist.push_back(histoimg);
      if (separate_plots) ppm_write_to_file(filebase+"_Histogram",*histoimg);
    }
  }
  
  return true;
}



const bool NeuralRegionMap::ppmgrid_write(const string& filebase,
                                          const ImagePListList& imagelists, int interior_border,
                                          const Color& pagecolor, bool column_major) const
{
  /* Skip empty plot */
  if (imagelists.empty()) {
    message(Msg::Warning, "Skipping empty image");
    return false;
  }
  
  /* Create combined image and save as a PPM file */
  typedef MatrixType<Plot::AARImage<>* >::rectangular MatrixOfImagePointers;
  const MatrixOfImagePointers moi =
    mat::matrix_from_nested_containers
    <MatrixOfImagePointers,ImagePList>(imagelists,column_major);

  const string filename = filebase + ".ppm";
  {
    Plot::ImagePointerGrid<> img(moi,interior_border,interior_border,pagecolor);
    std::ofstream os(filename.c_str() BINARY_FILE_FLAGS);
    img.ppm_write(os,filename,(unsigned char)(255));
  }
  ppm_post_write_hook( filename.c_str() );
  
  return true;
}



bool NeuralRegionMap::define_plotgroup(const string plotgroup, const string filename_format)
{
  const string    format         = (filename_format!=""? filename_format :
                                    blackboard.get_with_default("default_filename_format",string("file")));
  BlackboardType& plotgroups     = blackboard.lookup_map("::PlotGroup");
  BlackboardType& plotgroupparams= plotgroups.lookup_map(plotgroup,false);
  const bool      alreadyexists  = (&plotgroupparams != &plotgroups);;
  BlackboardType* paramsptr      = (alreadyexists ? &plotgroupparams :
                                    plotgroups.new_child(plotgroup,true));

  if (filename_format!="" || !alreadyexists)
    paramsptr->set_local("filename_format",format);

  return !alreadyexists;
}


cmdstat NeuralRegionMap::cmd_define_plot( CMD_ARGS )
{
  CMD_ARG_PARAMS(define_plot);
  bool status=true;
  const string strength       = arglist.next(string(""));
  const string color          = arglist.next(string(""));
  const string confidence     = arglist.next(string(""));
  
  const string specified_name = argparams.get_with_default("name",string(""));
  const string name           = (specified_name!=""? specified_name :
                                 (strength!=""?       strength :
                                  (color!=""?          color : confidence)));

  const string specified_type = argparams.get_with_default("plotgroup",string(""));
  const string plotgroup      = (specified_type!="" ? specified_type : name);
  const string format         = argparams.get_with_default("filename_format",string(""));

  /* The name is required */
  if (name=="") {
    message(Msg::Error, "Skipping plot definition; no name was specified");
    return CMD_PARAMETER_ERROR;
  }
  
  /* Create a set of parameters for the <plotgroup> if none exists */
  define_plotgroup(plotgroup,format);
  
  /* Define plot for each region in order specified */
  RegionManagerList regions = retrieve_matching_regions(argparams);
  for (RegionManagerList::iterator r=regions.begin(); r!=regions.end(); r++)
    (*r)->define_plot(plotgroup,name,strength,color,confidence);

  CMD_ARG_ASSERT_EMPTY;
  return (status ? CMD_NO_ERROR : CMD_PARAMETER_ERROR);
}



cmdstat NeuralRegionMap::cmd_measure_stimulus_map( CMD_ARGS )
{
  CMD_ARG_PARAMS(measure_stimulus_map);
  const bool status = measure_stimulus_map(arglist,argparams);
  CMD_ARG_ASSERT_EMPTY;
  return (status ? CMD_NO_ERROR : CMD_PARAMETER_ERROR);  
}



template<class LoopContainer, class UpdatableObjectContainer>
class NeuralRegionMap::measure_stimulus_map_iteration {
public:

  measure_stimulus_map_iteration(const string& input_command_,
                                 const LoopContainer& loops_,
                                 const UpdatableObjectContainer& spmrs_)
    : input_command(input_command_), loops(loops_), spmrs(spmrs_)  {  };
  
  void operator() () {
    /* Make variable values public.  Uses the global parameter map. */
    string variables;
    for (typename LoopContainer::const_iterator i=loops.begin(); i!=loops.end(); i++) {
      variables += " " + String::stringrep(**i);
      blackboard.lookup((*i)->name()).datavalue().set(Polymorph<double>((*i)->value()));
    }
    message(Msg::Notify, "Setting variables:" + variables);

    /* Present input */
    cmddefs_exec_str(input_command.c_str());
    
    /* Tell each of the SPMRs to update to the current activation levels */
    for (typename UpdatableObjectContainer::const_iterator si=spmrs.begin(); si!=spmrs.end(); si++)
      (*si)->update();
  }
  
private:
  const string& input_command;
  const LoopContainer& loops;
  const UpdatableObjectContainer& spmrs;
};


template<class T1, class T2>
T1 accum_num_calls(const T1& accum, const T2* p)
{  return accum*p->num();  }




const bool NeuralRegionMap::measure_stimulus_map(StringArgs& arglist, ParameterMap<>& argparams)
{
  typedef double                        VType;
  typedef ValueGenerator<VType>         VGenerator;
  typedef LoopSpec<VType>               Loop;
  typedef std::vector<Loop*>            Loops;
  typedef StimulusParameterMapsForRegion<const NeuralRegion::ActivityMatrix, NeuralRegion::MapBaseType, Loop>   SPMR;  
  typedef std::vector<SPMR*>            SPMRs;
  typedef SPMR::ScaleType               Scale;
  
  const string  input_command  = arglist.next(string(""));
  RegionManagerList regions    = retrieve_matching_regions(argparams);  
  
  SPMRs spmrs;

  for (RegionManagerList::iterator r=regions.begin(); r!=regions.end(); r++)
    spmrs.push_back(new SPMR(*r));
  

  Loops loops;
  DistributedValueGeneratorFactory<VType> vgf;
  while (!arglist.empty()) {
    StringArgs dimensionargs=arglist.recursiveparser();

    /* Set named parameters */
    ParameterMap<> subargparams(&argparams);
    cmdparams_set(subargparams,dimensionargs,true,false,false);

    /* Get parameter values */
    const string name                 = dimensionargs.next(subargparams.get_with_default("name",string("")));
    const int    divisions            = dimensionargs.next(subargparams.get_with_default("divisions",1));
    
    const bool   registermap          = subargparams.get_with_default("register",False);
    const bool   weighted_average     = subargparams.get_with_default("weighted_average",False);
    const bool   measure_distribution = subargparams.get_with_default("measure_distribution",True);
    const int    specified_num_bins   = subargparams.get_with_default("num_bins",-1);
    const Scale  selectivity_scale    = Scale(subargparams.get_with_default("selectivity_scale",1.0));
    const bool   cyclic               = subargparams.get_with_default("cyclic",True);
    const bool   discrete_inputs      = subargparams.get_with_default("discrete_inputs",True);
    const int    num_bins             = (specified_num_bins>0? specified_num_bins :
                                         (cyclic? divisions : divisions+1));
    const int    discrete_levels      = (discrete_inputs? divisions : -1 );
    const string varname              = subargparams.get_with_default("varname",string(""));
    const string loopspecname         = (varname!=""? varname : name);
    const string valuegenspec         = subargparams.get_with_default("valuegenerator",string(""));
    StringArgs   valuegenargs         = dimensionargs.recursiveparser(valuegenspec);
    VGenerator*  valuegen             = (valuegenargs.empty()? 0 : vgf.create(valuegenargs));

    Loop* lp                          = new Loop(loopspecname,divisions,cyclic,valuegen,discrete_levels);
    loops.push_back(lp);
    
    /* Add new SPM to each region for this dimension */    
    if (registermap) {
      if (num_bins>0)
        for (SPMRs::iterator s=spmrs.begin(); s!=spmrs.end(); s++)
          (*s)->create_spm(name,*lp,num_bins,measure_distribution,weighted_average,cyclic,selectivity_scale);
      else
        message(Msg::Warning, "Can't register a map for " + name +
                " because it has no valid values (num_bins==" + String::stringrep(num_bins) +")");
    }
  }
  
  /* Give the user an idea how long this will take */
  const int num_loop_iterations =  std::accumulate(ISEQ(loops),1,&accum_num_calls<int,Loop>);
  message(Msg::Notify, "Presenting " + String::stringrep(num_loop_iterations) + " inputs");
  
  /* Execute the specified nested loops of dimensions to gather the raw data */
  measure_stimulus_map_iteration<Loops,SPMRs> iteration(input_command,loops,spmrs);
  LoopSpecs_ExecuteNested(loops, loops.begin(), iteration);

  /* Register a map plot for each dimension measured. */
  for (SPMRs::iterator s=spmrs.begin(); s!=spmrs.end(); s++) {
    const string warning = (*s)->register_maps();
    if (warning!="") message(Msg::Warning, warning);
  }
  
  Generic::delete_contents(loops);
  Generic::delete_contents(spmrs);
  
  return true;
}


cmdstat NeuralRegionMap::cmd_save_snapshot( CMD_ARGS )
{  
  CMD_ARG_PARAMS(save_snapshot);
  const string plotgroup        = "SavedState"; /* Hard-coded */
  const string filename_format  = arglist.next(argparams.get_with_default("filename",string()));
  RegionManagerList regions     = retrieve_matching_regions(argparams);
  const bool   verbose          = argparams.get_with_default("verbose",True);

  for (RegionManagerList::iterator r=regions.begin(); r!=regions.end(); r++) {
    message((verbose? Msg::Notify : Msg::Verbose), "Saving state of " + (*r)->region()->name());
    define_globals(*r,Uninitialized,Uninitialized,plotgroup);
    (*r)->region()->save_state(filenamebase(plotgroup,filename_format));
    define_globals();
  }
  
  CMD_ARG_ASSERT_EMPTY;
  return CMD_NO_ERROR;
}





bool NeuralRegionMap::restore_state(const ParamMap& argparams,
                                    const int iteration, const string& filename)
{
  RegionManagerList regions     = retrieve_matching_regions(argparams);
  const string plotgroup        = "SavedState"; /* Hard-coded */
  const bool   verbose          = argparams.get_with_default("verbose",True);
  bool status=false;

  for (RegionManagerList::iterator r=regions.begin(); r!=regions.end(); r++) {
    message((verbose? Msg::Notify : Msg::Verbose), "Restoring state of " + (*r)->region()->name());
    define_globals(*r,Uninitialized,Uninitialized,plotgroup);
    const bool newstatus = (*r)->region()->
      restore_state(iteration,filenamebase(plotgroup,filename));
    if (newstatus) status=true;
    define_globals();
  }
  
  return status;
}



cmdstat NeuralRegionMap::cmd_kill_connections( CMD_ARGS )
{
  CMD_ARG_PARAMS(kill_connections);
  RegionManagerList regions     = retrieve_matching_regions(argparams);
  const bool   verbose          = argparams.get_with_default("verbose",True);

  for (RegionManagerList::iterator r=regions.begin(); r!=regions.end(); r++) {
    message((verbose? Msg::Notify : Msg::Verbose), "Killing connections in " + (*r)->region()->name());
    (*r)->region()->prune();
  }
  
  CMD_ARG_ASSERT_EMPTY;
  return CMD_NO_ERROR;
}


cmdstat NeuralRegionMap::cmd_map_statistics( CMD_ARGS )
{
  CMD_ARG_PARAMS(map_statistics);

  const string mapname          = arglist.next(argparams.get_with_default("name",string("")));

  /* Currently the num_bins aren't useful to change, but if this command
     is extended they would be needed.. */
  //const int  divisions        = argparams.get_with_default("divisions",1);
  const int    divisions        = 1;
  const int    spec_num_bins    = argparams.get_with_default("num_bins",1);
  const bool   cyclic           = argparams.get_with_default("cyclic",True);
  const int    num_bins         = (spec_num_bins>0? spec_num_bins :
                                   (cyclic? divisions : divisions+1));
  const bool   verbose          = argparams.get_with_default("verbose",True);
  const bool   reset            = argparams.get_with_default("reset",False);
  const bool   cumulative       = argparams.get_with_default("cumulative",False);
  const bool   horizontal       = argparams.get_with_default("horizontal",True);
  const string label            = argparams.get_with_default("label",string());
  const bool   kurtosis         = argparams.get_with_default("kurtosis",False); /* yschoe */
  const bool   min_max          = argparams.get_with_default("min_max",False); /* yschoe */
  const string lineend          = label+"\n";

  RegionManagerList regions     = retrieve_matching_regions(argparams);
  
  static double cumulative_sum  = 0;
  static int    cumulative_count= 0;

  if (reset) {
    cumulative_sum=0;
    cumulative_count=0;
    return CMD_NO_ERROR;
  }

  /* String formatting */
  typedef String::StreamFormat SF;
  SF magsf (13,' ', 2,true ); /* Formatting for magnitudes */
  SF headsf(13,'_',-1,false); /* Formatting for headings   */
  SF strsf (14,' ',-1,false); /* Formatting for strings    */
  const string header = String::stringrep("",headsf);

  
  /* Print column headers, if needed */ 
  if (cumulative_count==0 || verbose) {
    for (RegionManagerList::iterator r=regions.begin(); r!=regions.end(); r++) {
      message(Msg::Requested,
              String::stringrep("Region",           strsf) +
              String::stringrep("Map",              strsf) +
              String::stringrep("Sum",              strsf) +
              (cumulative?
               String::stringrep("CumulativeAvg",   strsf) : "") +
              (min_max? /* yschoe */
               String::stringrep("Min",             strsf) +
               String::stringrep("Max",             strsf) : "") +
              (kurtosis? /* yschoe */
               String::stringrep("Kurtosis",        strsf) : "") +
              "  ",false);
      if (!horizontal) break;
    }
    message(Msg::Requested,"\n",false);
    
    for (RegionManagerList::iterator r=regions.begin(); r!=regions.end(); r++) {
      message(Msg::Requested,
              String::stringrep(header.c_str(),     strsf) +
              String::stringrep(header.c_str(),     strsf) +
              String::stringrep(header.c_str(),     strsf) +
              (cumulative?
               String::stringrep(header.c_str(),    strsf) : "") +
              (min_max? /* yschoe */
               String::stringrep(header.c_str(),    strsf) +
               String::stringrep(header.c_str(),    strsf) : "") +
              (kurtosis? /* yschoe */
               String::stringrep(header.c_str(),    strsf) : "") + 
              "  ",false);
      if (!horizontal) break;
    }
    message(Msg::Requested,"\n",false);
  }

  
  /* Measure and print statistics for each region */
  for (RegionManagerList::iterator r=regions.begin(); r!=regions.end(); r++) {
    const NeuralRegionManager* rm = *r;
    const NeuralRegion::MapBaseType* map = rm->region()->table().getptr(mapname);
    if (!map) continue;
  
    typedef Histo::OneDBinList<> Histogram;
    Histogram histo(num_bins);
    double tmp_kurt = 0.0; /* yschoe : store kurtosis value */
    double tmp_sum  = 0.0; /* yschoe : store sum value */
    double tmp_std  = 0.0; /* yschoe : store std value */
    double tmp_var  = 0.0; /* yschoe : store var value */
    double tmp_mean = 0.0; /* yschoe : store mean value */
    double min      = 1e20; /* yschoe */
    double max      = -1e20; /* yschoe */

    for   (int r=0; r<map->nrows(); r++)
      for (int c=0; c<map->ncols(); c++) {
        NeuralRegion::Magnitude val     = mat::elem(*map,r,c);
        NeuralRegion::Magnitude bin_mag = val; // Could accept any map here
        Histogram::size_type bin = (cyclic ?
                                    histo.bin_number(bin_mag) :
                                    histo.bin_number_inclusive(bin_mag));
        histo.add(bin,val);
        if (kurtosis) { /* yschoe */
          tmp_sum += val;       
        }

        if (min_max) {
          min = MIN(min,val);
          max = MAX(max,val);
        }
      }

    /* std(x)      = sqrt(sum((x-mean(x))^2)/(size(x)-1)); */
    /* kurtosis(x) = sum((x-mean(x))^4)/(size(x)*std(x)^4)-3; */
    if (kurtosis) { /* yschoe */
        tmp_mean = tmp_sum / (map->nrows()*map->ncols());       

        for   (int r=0; r<map->nrows(); r++)
          for (int c=0; c<map->ncols(); c++) {
            NeuralRegion::Magnitude val     = mat::elem(*map,r,c);
            NeuralRegion::Magnitude diff_val = val - tmp_mean;
            tmp_var += diff_val * diff_val;
            tmp_kurt += diff_val * diff_val * diff_val * diff_val;
          }

        if (tmp_var == 0 || (map->nrows()*map->ncols()<=1) ) {
          message(Msg::Error,"Division by zero; kurtosis undefined");
          tmp_kurt = 0.0;
        } else {
          tmp_var = tmp_var/(map->nrows()*map->ncols()-1);
          tmp_kurt = tmp_kurt / (map->nrows()*map->ncols()*tmp_var*tmp_var) - 3.0;
          tmp_std  = sqrt(tmp_var);
        }
    } 

    const double sum      = histo.sum_value();
    const string sumstr   = String::stringrep(sum,magsf);
    const double kurt     = tmp_kurt; /* yschoe */
    cumulative_sum += sum;
    cumulative_count++;
    message(  Msg::Requested,
              String::stringrep(rm->region()->name().c_str(), strsf) +
              String::stringrep(mapname.c_str(),    strsf) +
              String::stringrep(sum,                magsf) + " " +
              (cumulative? String::stringrep(cumulative_sum/cumulative_count, magsf) + " " : "") +
              (min_max? String::stringrep(min,magsf) + " " +
                        String::stringrep(max,magsf) + " " : "") + /* yschoe */
              (kurtosis? String::stringrep(kurt,magsf) + " " : "") + /* yschoe */
              (horizontal? "  " : lineend),false);
    
    /* Other quantities that would be useful to show:
    
       Min  histo.min_value()
       Avg  histo.average_value()
       Max  histo.max_value()
       Wsel (cyclic ? histo.vector_selectivity() : histo.relative_selectivity(),magsf)
       Wavg (cyclic ? histo.vector_direction()   : histo.weighted_average(),magsf)
  
     However, most of these operate on the values in a bin instead of
     all values encountered, which would be confusing.  Could extend
     Histogram to store the actual min, max, etc. values; presumably the
     above member function names would need to change to e.g.
     max_bin_value() for clarity.
    */
    
    //Could plot histogram as well 

  }
  if (horizontal) message(Msg::Requested,lineend,false);
    
  CMD_ARG_ASSERT_EMPTY;
  return CMD_NO_ERROR;
}




cmdstat NeuralRegionMap::cmd_backproject( CMD_ARGS )
{  
  CMD_ARG_PARAMS(backproject);

  RegionManagerList regions     = retrieve_matching_regions(argparams);
  const bool   verbose          = argparams.get_with_default("verbose",True);
  bool  status  = True;

  // we need to backproject from the highest region, i.e. in reverse order
  for (RegionManagerList::reverse_iterator r=regions.rbegin(); r!=regions.rend(); r++) {
    if ((*r)->region()->is_internal()) {
        message((verbose? Msg::Notify : Msg::Verbose), "Backprojecting from " + (*r)->region()->name());
        InternalNeuralRegion* ir = dynamic_cast<InternalNeuralRegion*>((*r)->region());
        if (ir) {
                ir->backproject();
        } else {
                status = False;
        }
    }
  }
  
  CMD_ARG_ASSERT_EMPTY;
  return (status ? CMD_NO_ERROR : CMD_PARAMETER_ERROR);
}

#ifdef OBJ_LISSOM

cmdstat NeuralRegionMap::cmd_resp_to_residual( CMD_ARGS )
{  
  CMD_ARG_PARAMS(resp_to_residual);

  RegionManagerList regions     = retrieve_matching_regions(argparams);
  const bool   verbose          = argparams.get_with_default("verbose",True);
  bool  status  = True;

  // Propagate the residuals forward into the output of the target map.
  // Also add in lateral response here.
  for (RegionManagerList::iterator i=regions.begin(); i!=regions.end(); i++) {

        message((verbose? Msg::Notify : Msg::Verbose), "Calculating response to residual in " + (*i)->region()->name());
        InternalNeuralRegion* ir = dynamic_cast<InternalNeuralRegion*>((*i)->region());
        if (ir) {
                ir->resp_to_residual();
        } else {
                status = False;
        }
  }
  
  CMD_ARG_ASSERT_EMPTY;
  return (status ? CMD_NO_ERROR : CMD_PARAMETER_ERROR);
}

cmdstat NeuralRegionMap::cmd_train_obj_weights( CMD_ARGS )
{  
  CMD_ARG_PARAMS(train_obj_weights);

  RegionManagerList regions     = retrieve_matching_regions(argparams);
  const bool   verbose          = argparams.get_with_default("verbose",True);
  bool  status  = True;

  for (RegionManagerList::iterator i=regions.begin(); i!=regions.end(); i++) {

        message((verbose? Msg::Notify : Msg::Verbose), "Training obj_weights in " + (*i)->region()->name());
        InternalNeuralRegion* ir = dynamic_cast<InternalNeuralRegion*>((*i)->region());
        if (ir) {
                // update weights and normalize
                ir->train_obj_weights();
        } else {
                status = False;
        }
  }
  
  CMD_ARG_ASSERT_EMPTY;
  return (status ? CMD_NO_ERROR : CMD_PARAMETER_ERROR);
}

cmdstat NeuralRegionMap::cmd_randomize_lat_wts( CMD_ARGS )
{  
  CMD_ARG_PARAMS(randomize_lat_wts);

  RegionManagerList regions     = retrieve_matching_regions(argparams);
  const bool   verbose          = argparams.get_with_default("verbose",True);
  bool  status  = True;

  for (RegionManagerList::iterator i=regions.begin(); i!=regions.end(); i++) {

        message((verbose? Msg::Notify : Msg::Verbose), "Randomizing lat wts in " + (*i)->region()->name());
        InternalNeuralRegion* ir = dynamic_cast<InternalNeuralRegion*>((*i)->region());
        if (ir) {
                // update weights and noramlize
                ir->randomize_lat_wts();
        } else {
                status = False;
        }
  }
  
  CMD_ARG_ASSERT_EMPTY;
  return (status ? CMD_NO_ERROR : CMD_PARAMETER_ERROR);
}
#endif /* OBJ_LISSOM */

---