METHODS

new AI::NeuralNet::BackProp($layers, $size [, $outputs, $topology_flag])

Returns a newly created neural network from an "AI::NeuralNet::BackProp" object. The network will have $layers number layers in it and each layer will have $size number of neurons in that layer.

There is an optional parameter of $outputs, which specifies the number of output neurons to provide. If $outputs is not specified, $outputs defaults to equal $size. $outputs may not exceed $size. If $outputs exceeds $size, the new() constructor will return undef.

The optional parameter, $topology_flag, defaults to 0 when not used. There are three valid topology flag values:

0 default My feed-foward style: Each neuron in layer X is connected to one input of every neuron in layer Y. The best and most proven flag style.

        ^   ^   ^               
        O\  O\ /O       Layer Y
        ^\\/^/\/^
        | //|\/\|
        |/ \|/ \|               
        O   O   O       Layer X
        ^   ^   ^
    

(Sorry about the bad art...I am no ASCII artist! :-)

1 In addition to flag 0, each neuron in layer X is connected to every input of the neurons ahead of itself in layer X.

2 ("L-U Style") No, its not "Learning-Unit" style. It gets its name from this: In a 2 layer, 3 neuron network, the connections form a L-U pair, or a W, however you want to look at it.

        ^   ^   ^
        |   |   |
        O-->O-->O
        ^   ^   ^
        |   |   |
        |   |   |
        O-->O-->O
        ^   ^   ^
        |   |   |
    

As you can see, each neuron is connected to the next one in its layer, as well as the neuron directly above itself.

Before you can really do anything useful with your new neural network object, you need to teach it some patterns. See the learn() method, below.

$net->learn($input_map_ref, $desired_result_ref [, options ]);

This will 'teach' a network to associate an new input map with a desired resuly. It will return a string containg benchmarking information. You can retrieve the pattern index that the network stored the new input map in after learn() is complete with the pattern() method, below.

UPDATED: You can now specify strings as inputs and ouputs to learn, and they will be crunched automatically. Example:

        $net->learn('corn', 'cob');
        # Before update, you have had to do this:
        # $net->learn($net->crunch('corn'), $net->crunch('cob'));
    

Note, the old method of calling crunch on the values still works just as well.

UPDATED: You can now learn inputs with a 0 value. Beware though, it may not learn() a 0 value in the input map if you have randomness disabled. See NOTES on using a 0 value with randomness disabled.

The first two arguments may be array refs (or now, strings), and they may be of different lengths.

Options should be written on hash form. There are three options:

         inc    =>      $learning_gradient
         max    =>      $maximum_iterations
         error  =>      $maximum_allowable_percentage_of_error
    

$learning_gradient is an optional value used to adjust the weights of the internal connections. If $learning_gradient is ommitted, it defaults to 0.20.

$maximum_iterations is the maximum numbers of iteration the loop should do. It defaults to 1024. Set it to 0 if you never want the loop to quit before the pattern is perfectly learned.

$maximum_allowable_percentage_of_error is the maximum allowable error to have. If this is set, then learn() will return when the perecentage difference between the actual results and desired results falls below $maximum_allowable_percentage_of_error. If you do not include 'error', or $maximum_allowable_percentage_of_error is set to -1, then learn() will not return until it gets an exact match for the desired result OR it reaches $maximum_iterations.

$net->learn_set(\@set, [ options ]);

UPDATE: Inputs and outputs in the dataset can now be strings. See information on auto-crunching in learn()

This takes the same options as learn() and allows you to specify a set to learn, rather than individual patterns. A dataset is an array refrence with at least two elements in the array, each element being another array refrence (or now, a scalar string). For each pattern to learn, you must specify an input array ref, and an ouput array ref as the next element. Example:

        my @set = (
                # inputs        outputs
                [ 1,2,3,4 ],  [ 1,3,5,6 ],
                [ 0,2,5,6 ],  [ 0,2,1,2 ]
        );
    

See the paragraph on measuring forgetfulness, below. There are two learn_set()-specific option tags available:

        flag     =>  $flag
        pattern  =>  $row
    

If "flag" is set to some TRUE value, as in "flag => 1" in the hash of options, or if the option "flag" is not set, then it will return a percentage represting the amount of forgetfullness. Otherwise, learn_set() will return an integer specifying the amount of forgetfulness when all the patterns are learned.

If "pattern" is set, then learn_set() will use that pattern in the data set to measure forgetfulness by. If "pattern" is omitted, it defaults to the first pattern in the set. Example:

        my @set = (
                [ 0,1,0,1 ],  [ 0 ],
                [ 0,0,1,0 ],  [ 1 ],
                [ 1,1,0,1 ],  [ 2 ],  #  <---
                [ 0,1,1,0 ],  [ 3 ]
        );
    

If you wish to measure forgetfulness as indicated by the line with the arrow, then you would pass 2 as the "pattern" option, as in "pattern => 2".

Now why the heck would anyone want to measure forgetfulness, you ask? Maybe you wonder how I even measure that. Well, it is not a vital value that you have to know. I just put in a "forgetfulness measure" one day because I thought it would be neat to know.

How the module measures forgetfulness is this: First, it learns all the patterns in the set provided, then it will run the very first pattern (or whatever pattern is specified by the "row" option) in the set after it has finished learning. It will compare the run() output with the desired output as specified in the dataset. In a perfect world, the two should match exactly. What we measure is how much that they don't match, thus the amount of forgetfulness the network has.

NOTE: In version 0.77 percentages were disabled because of a bug. Percentages are now enabled.

Example (from examples/ex_dow.pl):

        # Data from 1989 (as far as I know..this is taken from example data on BrainMaker)
        my @data = ( 
                #       Mo  CPI  CPI-1 CPI-3    Oil  Oil-1 Oil-3    Dow   Dow-1 Dow-3   Dow Ave (output)
                [       1,      229, 220,  146,         20.0, 21.9, 19.5,       2645, 2652, 2597],      [       2647  ],
                [       2,      235, 226,  155,         19.8, 20.0, 18.3,       2633, 2645, 2585],      [       2637  ],
                [       3,      244, 235,  164,         19.6, 19.8, 18.1,       2627, 2633, 2579],      [       2630  ],
                [       4,      261, 244,  181,         19.6, 19.6, 18.1,       2611, 2627, 2563],      [       2620  ],
                [       5,      276, 261,  196,         19.5, 19.6, 18.0,       2630, 2611, 2582],      [       2638  ],
                [       6,      287, 276,  207,         19.5, 19.5, 18.0,       2637, 2630, 2589],      [       2635  ],
                [       7,      296, 287,  212,         19.3, 19.5, 17.8,       2640, 2637, 2592],      [       2641  ]                 
        );
        
        # Learn the set
        my $f = learn_set(\@data, 
                                          inc   =>      0.1,    
                                          max   =>      500,
                                          p             =>      1
                                         );
                        
        # Print it 
        print "Forgetfullness: $f%";
    

This is a snippet from the example script examples/ex_dow.pl, which demonstrates DOW average prediction for the next month. A more simple set defenition would be as such:

        my @data = (
                [ 0,1 ], [ 1 ],
                [ 1,0 ], [ 0 ]
        );
        
        $net->learn_set(\@data);
    

Same effect as above, but not the same data (obviously).

$net->learn_set_rand(\@set, [ options ]);

UPDATE: Inputs and outputs in the dataset can now be strings. See information on auto-crunching in learn()

This takes the same options as learn() and allows you to specify a set to learn, rather than individual patterns.

learn_set_rand() differs from learn_set() in that it learns the patterns in a random order, each pattern once, rather than in the order that they are in the array. This returns a true value (1) instead of a forgetfullnes factor.

Example:

        my @data = (
                [ 0,1 ], [ 1 ],
                [ 1,0 ], [ 0 ]
        );
        
        $net->learn_set_rand(\@data);
    

$net->run($input_map_ref);

UPDATE: run() will now automatically crunch() a string given as the input.

This method will apply the given array ref at the input layer of the neural network, and it will return an array ref to the output of the network.

Example:

        my $inputs  = [ 1,1,0,1 ];
        my $outputs = $net->run($inputs);
    

With the new update you can do this:

        my $outputs = $net->run('cloudy, wind is 5 MPH NW');
        # Old method:
        # my $outputs = $net->run($net->crunch('cloudy, wind is 5 MPH NW'));
    

See also run_uc() below.

$net->run_uc($input_map_ref);

This method does the same thing as this code:

        $net->uncrunch($net->run($input_map_ref));
    

All that run_uc() does is that it automatically calls uncrunch() on the output, regardless of whether the input was crunch() -ed or not.

$net->range();

This allows you to limit the possible outputs to a specific set of values. There are several ways you can specify the set of values to limit the output to. Each method is shown below. When called without any arguements, it will disable output range limits. You will need to re-learn any data previously learned after disabling ranging, as disabling range invalidates the current weight matrix in the network.

range() automatically scales the networks outputs to fit inside the size of range you allow, and, therefore, it keeps track of the maximum output it can expect to scale. Therefore, you will need to learn() the whole data set again after calling range() on a network.

Subsequent calls to range() invalidate any previous calls to range()

NOTE: It is recomended, you call range() before you call learn() or else you will get unexpected results from any run() call after range() .

$net->range($bottom..$top);

This is a common form often used in a "for my $x (0..20)" type of for() constructor. It works the exact same way. It will allow all numbers from $bottom to $top, inclusive, to be given as outputs of the network. No other values will be possible, other than those between $bottom and $top, inclusive.

$net->range(\@values);

This allows you to specify a range of values as an array refrence. As the ranges are stored internally as a refrence, this is probably the most natural way. Any value specified by an element in @values will be allows as an output, no other values will be allowed.

$net->range("string of values");

With this construct you can specify a string of values to be allowed as the outputs. This string is simply taken an crunch() -ed internally and saved as an array ref. This has the same effect as calling:

        $net->range($net->crunch("string of values"));
    

$net->range("first string","second string");

This is the same as calling:

        $net->range($net->crunch("first string"),$net->crunch("second string"));
    

Or:

        @range = ($net->crunch("first string"),
                          $net->crunch("second string"));
        $net->range(\@range);
    

$net->range($value1,$value2);

This is the same as calling:

        $net->range([$value1,$value2]);
    

Or:

        @range = ($value1,$value2);
        $net->range(\@range);
    

The second example is the same as the first example.

$net->benchmarked();

UPDATE: bencmarked() now returns just the string from timestr() for the last run() or loop() call. Exception: If the last call was a loop the string will be prefixed with "%d loops and ".

This returns a benchmark info string for the last learn() or the last run() call, whichever occured later. It is easily printed as a string, as following:

        print $net->benchmarked() . "\n";
    

$net->debug($level)

Toggles debugging off if called with $level = 0 or no arguments. There are four levels of debugging.

Level 0 ($level = 0) : Default, no debugging information printed. All printing is left to calling script.

Level 1 ($level = 1) : This causes ALL debugging information for the network to be dumped as the network runs. In this mode, it is a good idea to pipe your STDIO to a file, especially for large programs.

Level 2 ($level = 2) : A slightly-less verbose form of debugging, not as many internal data dumps.

Level 3 ($level = 3) : JUST prints weight mapping as weights change.

Level 4 ($level = 4) : JUST prints the benchmark info for EACH learn loop iteteration, not just learning as a whole. Also prints the percentage difference for each loop between current network results and desired results, as well as learning gradient ('incremenet').

Level 4 is useful for seeing if you need to give a smaller learning incrememnt to learn() . I used level 4 debugging quite often in creating the letters.pl example script and the small_1.pl example script.

Toggles debuging off when called with no arguments.

$net->save($filename);

This will save the complete state of the network to disk, including all weights and any words crunched with crunch() . Also saves any output ranges set with range() .

This has now been modified to use a simple flat-file text storage format, and it does not depend on any external modules now.

$net->load($filename);

This will load from disk any network saved by save() and completly restore the internal state at the point it was save() was called at.

$net->join_cols($array_ref,$row_length_in_elements,$high_state_character,$low_state_character);

This is more of a utility function than any real necessary function of the package. Instead of joining all the elements of the array together in one long string, like join() , it prints the elements of $array_ref to STDIO, adding a newline (\n) after every $row_length_in_elements number of elements has passed. Additionally, if you include a $high_state_character and a $low_state_character, it will print the $high_state_character (can be more than one character) for every element that has a true value, and the $low_state_character for every element that has a false value. If you do not supply a $high_state_character, or the $high_state_character is a null or empty or undefined string, it join_cols() will just print the numerical value of each element seperated by a null character (\0). join_cols() defaults to the latter behaviour.

$net->pdiff($array_ref_A, $array_ref_B);

This function is used VERY heavily internally to calculate the difference in percent between elements of the two array refs passed. It returns a %.10f (sprintf-format) percent sting.

$net->p($a,$b);

Returns a floating point number which represents $a as a percentage of $b.

$net->intr($float);

Rounds a floating-point number rounded to an integer using sprintf() and int() , Provides better rounding than just calling int() on the float. Also used very heavily internally.

$net->high($array_ref);

Returns the index of the element in array REF passed with the highest comparative value.

$net->low($array_ref);

Returns the index of the element in array REF passed with the lowest comparative value.

$net->show();

This will dump a simple listing of all the weights of all the connections of every neuron in the network to STDIO.

$net->crunch($string);

UPDATE: Now you can use a variabled instead of using qw(). Strings will be split internally. Do not use qw() to pass strings to crunch.

This splits a string passed with /[\s\t]/ into an array ref containing unique indexes to the words. The words are stored in an intenal array and preserved across load() and save() calls. This is designed to be used to generate unique maps sutible for passing to learn() and run() directly. It returns an array ref.

The words are not duplicated internally. For example:

        $net->crunch("How are you?");
    

Will probably return an array ref containing 1,2,3. A subsequent call of:

    $net->crunch("How is Jane?");
    

Will probably return an array ref containing 1,4,5. Notice, the first element stayed the same. That is because it already stored the word "How". So, each word is stored only once internally and the returned array ref reflects that.

$net->uncrunch($array_ref);

Uncrunches a map (array ref) into an scalar string of words seperated by ' ' and returns the string. This is ment to be used as a counterpart to the crunch() method, above, possibly to uncrunch() the output of a run() call. Consider the below code (also in ./examples/ex_crunch.pl):

        use AI::NeuralNet::BackProp;
        my $net = AI::NeuralNet::BackProp->new(2,3);
        
        for (0..3) {            # Note: The four learn() statements below could 
                                                # be replaced with learn_set() to do the same thing,
                                                # but use this form here for clarity.

                $net->learn($net->crunch("I love chips."),  $net->crunch("That's Junk Food!"));
                $net->learn($net->crunch("I love apples."), $net->crunch("Good, Healthy Food."));
                $net->learn($net->crunch("I love pop."),    $net->crunch("That's Junk Food!"));
                $net->learn($net->crunch("I love oranges."),$net->crunch("Good, Healthy Food."));
        }
        
        my $response = $net->run($net->crunch("I love corn."));
        
        print $net->uncrunch($response),"\n";
    

On my system, this responds with, "Good, Healthy Food." If you try to run crunch() with "I love pop.", though, you will probably get "Food! apples. apples." (At least it returns that on my system.) As you can see, the associations are not yet perfect, but it can make for some interesting demos!

$net->crunched($word);

This will return undef if the word is not in the internal crunch list, or it will return the index of the word if it exists in the crunch list.

$net->col_width($width);

This is useful for formating the debugging output of Level 4 if you are learning simple bitmaps. This will set the debugger to automatically insert a line break after that many elements in the map output when dumping the currently run map during a learn loop.

It will return the current width when called with a 0 or undef value.

$net->random($rand);

This will set the randomness factor from the network. Default is 0.001. When called with no arguments, or an undef value, it will return current randomness value. When called with a 0 value, it will disable randomness in the network. See NOTES on learning a 0 value in the input map with randomness disabled.

$net->load_pcx($filename);

Oh heres a treat... this routine will load a PCX-format file (yah, I know ... ancient format ... but it is the only one I could find specs for to write it in Perl. If anyone can get specs for any other formats, or could write a loader for them, I would be very grateful!) Anyways, a PCX-format file that is exactly 320x200 with 8 bits per pixel, with pure Perl. It returns a blessed refrence to a AI::NeuralNet::BackProp::PCX object, which supports the following routinges/members. See example files ex_pcxl.pl and ex_pcx.pl in the ./examples/ directory.

$pcx->{image}

This is an array refrence to the entire image. The array containes exactly 64000 elements, each element contains a number corresponding into an index of the palette array, details below.

$pcx->{palette}

This is an array ref to an AoH (array of hashes). Each element has the following three keys:

        $pcx->{palette}->[0]->{red};
        $pcx->{palette}->[0]->{green};
        $pcx->{palette}->[0]->{blue};
    

Each is in the range of 0..63, corresponding to their named color component.

$pcx->get_block($array_ref);

Returns a rectangular block defined by an array ref in the form of:

        [$left,$top,$right,$bottom]
    

These must be in the range of 0..319 for $left and $right, and the range of 0..199 for $top and $bottom. The block is returned as an array ref with horizontal lines in sequental order. I.e. to get a pixel from [2,5] in the block, and $left-$right was 20, then the element in the array ref containing the contents of coordinates [2,5] would be found by [5*20+2] ($y*$width+$x).

        print (@{$pcx->get_block(0,0,20,50)})[5*20+2];
    

This would print the contents of the element at block coords [2,5].

$pcx->get($x,$y);

Returns the value of pixel at image coordinates $x,$y. $x must be in the range of 0..319 and $y must be in the range of 0..199.

$pcx->rgb($index);

Returns a 3-element array (not array ref) with each element corresponding to the red, green, or blue color components, respecitvely.

$pcx->avg($index);

Returns the mean value of the red, green, and blue values at the palette index in $index.