view release on metacpan or  search on metacpan

lib/Algorithm/RandomPointGenerator.pm  view on Meta::CPAN

probability density function for the random points.

=item B<set_sigmas_for_proposal_density():>

    $generator->set_sigmas_for_proposal_density();

The Metropolis-Hastings algorithm is a random-walk algorithm that at each point first
creates a candidate for the next point and then makes a probabilistic decision
regarding the acceptance of the candidate point as the next point on the walk.  The
candidate point is drawn from what is known as the proposal density function.  This
module uses a bivariate Gaussian for the proposal density.  You set the width of the
proposal density by calling this method.

=item B<metropolis_hastings():>

This is the workhorse of the module, as you would expect.  As its name implies, it
uses the Metropolis-Hastings random-walk algorithm to generate a set of random points
whose probability distribution corresponds to the input histogram.

=item B<write_generated_points_to_a_file():>

    $generator->write_generated_points_to_a_file();

This method writes the generated points to a disk file whose name is keyed to the
name of the input histogram file. The two coordinates for each generated random point
are written out to a new line in this file.

=item B<make_output_histogram_for_generated_points():>

    $generator->make_output_histogram_for_generated_points();

The name of the method speaks for itself.

=item B<plot_histogram_3d_surface():>

    $generator->plot_histogram_3d_surface();

This method uses a Perl wrapper for Gnuplot, as provided by the module
Graphics::GnuplotIF, for creating a 3D surface plot of the histogram of the random
points generated by the module.

=item B<plot_histogram_lineplot():>

    $generator->plot_histogram_lineplot(); 

This creates a 3D line plot display of the histogram of the generated random points.

=item B<display_output_histogram_in_terminal_window():>

    $generator->display_output_histogram_in_terminal_window();

Useful for debugging purposes, it displays in the terminal window a two dimensional
array of numbers that is the histogram of the random points generated by the module.

=back

=head1 THE C<examples> DIRECTORY

Probably the most useful item in the C<examples> directory is the command-line script
C<genRand2D> that can be called simply with two arguments for generating a set of
random points.  A call to this script looks like

    genRand2D  --histfile  your_histogram_file.csv  --bbfile  your_bounding_box_file.csv

where the C<--histfile> option supplies the name of the file that contains a 2D input
histogram and the C<--bbfile> option the name of the file that defines the bounding
box in the XY-plane.  You can also execute the command line

    genRand2D  --help

for displaying information as to what is required by the two options for the
C<genRand2D> command.  The command-line invocation of C<genRand2D> gives you 2000
random points that are deposited in a file whose name is printed out in the terminal
window in which you execute the command.

To become more familiar with all of the different options you can use with this
module, you should experiment with the script:

    generate_random_points.pl

You can feed it different 2D histograms --- even made-up 2D histograms --- and look
at the histogram of the generated random points to see how well the module is
working.  Keep in mind, though, if your made-up input histogram has disconnected
blobs in it, the random-points that are generated may correspond to just one of the
blobs.  Since the process of random-point generation involves a random walk, the
algorithm may not be able to hop from one blob to another in the input histogram if
they are too far apart.  As to what exactly you'll get by way of the output histogram
would depend on your choice of the width of the proposal density.

The C<examples> directory contains the following histogram and bounding-box files
for you to get started:

    hist1.csv   bb1.csv

    hist2.csv   bb2.csv    

If you run the C<generate_random_points.pl> script with the C<hist1.csv> and
C<bb1.csv> files, the histogram you get for the 2000 random points generated by the
module will look like what you see in the file C<output_histogram_for_hist1.png>.  On
a Linux machine, you can see this histogram with the usual C<display> command from
the ImageMagick library.  And if you run C<generate_random_points.pl> script with the
C<hist2.csv> and C<bb2.csv> files, you'll see an output histogram that should look
like what you see in C<output_histogram_for_hist2.png>.

You should also try invoking the command-line calls:

    genRand2D --histfile hist1.csv --bbfile bb1.csv

    genRand2D --histfile hist2.csv --bbfile bb2.csv


=head1 REQUIRED

This module requires the following three modules:

   List::Util
   Graphics::GnuplotIF
   Math::Big
   Math::Random

=head1 EXPORT