Using the Binaries

Once you have downloaded the binaries, you will need to unzip them. After extraction, you will have access it. On Unix based systems this will be voroclust and on Windows it will be voroclust.exe.

The next thing that you will need will be a data file and configure file. The data file will need to be a .csv file and the configure file will need to end with extension .in.

VoroClust expects a csv datafile where each row is an n-dimensional data point. The data file will look similar to this one:

Image of datafileexample.png

And the configure file should look similar to this. The format is just a simple set of key-value pairs.

DATA_FILE=path/to/data.csv
OUTPUT_FOLDER=path/to/output/folder/
RADIUS=.115
NOISE_THRESHOLD=.05
DETAIL_CEILING=.9
DESCENT_LIMIT=.25
NUM_THREADS=-1
WRITE_SPHERE_FILE=path/to/spheres.bin
#READ_SPHERE_FILE=path/to/spheres.bin

The parameters include-able in the configure file are:

  • DATA_FILE – This parameter specifies which data file you want to use
  • OUTPUT_FOLDER – This allows user to choose where the output is written to
  • RADIUS – The radius of spheres used to cover the domain
  • NOISE_THRESHOLD – Determines the fraction of data points which will be labeled as noise in a post processing step
  • DETAIL_CEILING – Value between 0 and 1. Controls clustering propagation.
  • DESCENT_LIMIT – Value between 0 and 1. Controls clustering propagation. DETAIL_CEILING should be greater than DESCENT_LIMIT.
  • FIXED_SEED – Set a fixed seed. Defaults to -1 (random operation)
  • NUM_THREADS – Number of OpenMP threads to use. Defaults to 1.
  • READ_DATA_TREE_FILE – To save time, we can load the data’s Kd-Tree from a .bin file, rather than recomputing it.
  • WRITE_DATA_TREE_FILE – Write the Kd-Tree to a .bin file for future use.
  • READ_SPHERE_FILE – To save time, we can load the sphere cover from a .bin file, rather than recomputing it.
  • WRITE_SPHERE_FILE – Write the sphere cover to a .bin file for future use.
  • WRITE_DATA_BIN_FILE – Given a .csv DATA_FILE, writes the data to a .bin for reduced storage and faster loading. If this parameter is present, will skip clustering and ONLY write the file.

Using the Executable

Once you have built the executable and you have the config and data file, the command line usage is as follows:

./voroclust config.in

data_labels_0.100000_0.850000_0.150000.csv, the significance of the file name being the parameters used during the execution.

Additional Help

If you need any additional help with using VoroClust please do not hesitate to reach out to us.