view release on metacpan or  search on metacpan

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

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

None by design.


=head1 BUGS

Please notify the author if you encounter any bugs.  When sending email, please place
the string 'RandomPointGenerator' in the subject line.

=head1 INSTALLATION

Download the archive from CPAN in any directory of your choice.  Unpack the archive
with a command that on a Linux machine would look like:

    tar zxvf Algorithm-RandomPointGenerator-1.01.tar.gz

This will create an installation directory for you whose name will be
C<Algorithm-RandomPointGenerator-1.01>.  Enter this directory and execute the
following commands for a standard install of the module if you have root privileges:

    perl Makefile.PL
    make
    make test
    sudo make install