view release on metacpan or  search on metacpan

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

file, with the first line indicating the left and the right limits of the horizontal
coordinates and the second line indicating the lower and the upper limits of the
vertical coordinates.  (The values shown above are the longitude and the latitude
limits for a region in Chile, in case you are curious.)

=back 

=head2 Constructor Parameters:

=over 8

=item C<input_histogram_file>:

This required parameter supplies the name of the file that contains a 2D histogram as
the desired density function for the random points that the module will generate.
Each line record in this file must correspond to one row of the 2D histogram.  The
left-to-right direction in the file will be considered to be positive direction for
the x-axis.  As for the positive direction for the y-axis, it is common for that to
be from top to bottom when the histogram is written out to a text file as an array of
integers.  It is important to bear in mind this orientation of the histogram in light
of the fact that a bounding box is specified typically with its y-axis going upwards
(whereas the x-axis continues to be positive from left to right).  This inconsistency
between how a 2D histogram is typically stored in a text file and how a bounding box
is likely to be specified means that if the events occur more frequently in the upper
right hand corner of the bounding box, those high counts would show up in the lower
right hand corner of the histogram in a text file (or in a terminal display of the
contents of such a file). B<You can use the constructor option
C<y_axis_pos_direction> to reverse the positive sense of the y direction for the
histogram.  If you set C<y_axis_pos_direction> to the string C<up>, then the
orientation of the y axis in both the histogram and the bounding box will be the
same.>

=item C<bounding_box_file>:

This required parameter supplies the name of the file that contains the bounding box
information.  By bounding box is meant the part of the XY-plane that corresponds to
the histogram supplied through the C<input_histogram_file> option.  Apart from any
comment lines, this file must contain exactly two lines and each line must contain
exactly two numeric entries.  Additionally, the first entry in each of the two lines
must be smaller than the second entry in the same line.  The two entries in the first
line define the lower and the upper bounds on the x-axis and the two entries in the
second line do the same for the y-axis.

=item C<number_of_points>:

This parameter specifies the number of random points that you want the module to
generate.

=item C<how_many_to_discard>:

The Metropolis-Hastings algorithm belongs to a category of algorithms known as
random-walk algorithms. Since the random walk carried out by such algorithms must be
initialized with user input, it is necessary to discard the points produced until the
effects the initial state have died out.  This parameter specifies how many of the
generated points will be discarded.  This parameter is optional in the sense that it
has a default value of 500.

=item C<proposal_density_width>:

Given the current point, the Metropolis-Hastings randomly chooses a candidate for the
next point.  This random selection of a candidate point is carried out using what is
known as the "proposal density".  The module uses a bivariate Gaussian for the
proposal density.  The value supplied through this parameter controls the standard
deviations of the proposal Gaussian in the x and the y directions.  The default value
for this parameter is 0.1.  With that value for the parameter, the standard deviation
of the proposal density along the x direction will be set to 0.1 times the width of
the bounding box, and the standard deviation of the same along the y-direction to 0.1
times the height of the bounding box.

=item C<y_axis_pos_direction>:

See the explanation above for the constructor parameter C<input_histogram_file> for
why you may need to use the C<y_axis_pos_direction> parameter.  The parameter takes
one of two values, C<up> and C<down>.  The usual interpretation of a 2D histogram in
a text file --- with the positive direction of the y-axis pointing downwards ---
corresponds to the case when this parameter takes the default value of C<down>.

=item C<output_hist_bins_along_x>:

This parameter controls the resolution with which the histogram of the generated
random points will be displayed.  The value you supply is for the number of bins
along the x-direction.  The number of bins along the y-direction is set according to
the aspect ratio of the bounding box.

=back  

=over 

=item B<read_histogram_file_for_desired_density():>

    $generator->read_histogram_file_for_desired_density();

This is a required call after the constructor is invoked. As you would expect, this
call reads in the histogram data for the desired probability density function for
random point generation.

=item B<read_file_for_bounding_box():>

    $generator->read_file_for_bounding_box();

This is also a required call.  This call reads in the left and the right limits on
the x-axis and the lower and the upper limits on the y-axis for the portion of the
XY-plane for which the random points are needed.

=item B<normalize_input_histogram():>

    $generator->normalize_input_histogram();

This normalizes the input histogram to turn it into an approximation to the desired
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.