
The `examples' directory:

This directory contains the following four scripts that you might want to play with
in order to become familiar with the module:

    example1.pl

    example2.pl

    example3.pl

    example4.pl

These scripts demonstrate linear-manifold based clustering on the data in the
following three files:

    3_clusters_on_a_sphere_498_samples.csv            (used in example1.pl and example4.pl)

    3_clusters_on_a_sphere_3000_samples.csv           (used in example2.pl)

    4_clusters_on_a_sphere_1000_samples.csv           (used in example3.pl)

Note that even though the first two of these files both contain exactly three
clusters, the clusters look very different in the two data files.  The clusters are
much more spread out in 3_clusters_on_a_sphere_3000_samples.csv.

The code in example4.pl is special because it shows how you can call the
auto_retry_clusterer() method of the module for automatic repeated invocation of the
clustering program until success is achieved.  As currently programmed, the value of
the constructor parameter cluster_search_multiplier is set to 1, which means that
Phase 1 of the algorithm will only look for K clusters and there would be no need to
invoke Phase II of the algorithm for merging subclusters.

This directory also includes PNG image files that show some intermediate and the best
final results that can be achieved by the first three examples, that is, for the
scripts example1.pl, example2.pl, and example3.pl. If you are on a Linux machine and
if you have the ImageMagick library installed, you can use the `display' command to
see the results in the PNG images.  The results you get with your own runs of the
three example scripts may or may not look like what you see in the outputs shown in
the PNG files depending on how the module seeds the clusters.  Your best results
should look like what you see in the PNG images.

This directory also contains the following utility scripts:

For generating the data for experiments with clustering:

    generate_data_on_a_sphere.pl

For visualizing the data generated by the above script:

    data_visualizer.pl

For cleaning up the examples directory:

    cleanup_directory.pl

Invoking the cleanup_directory.pl script will get rid of all the PNG image files that
are generated by the module when you run it with the constructor option
make_png_for_each_iteration set to 1.

