udcgac/parallel-fst repository overview

⁠Parallel-FST: a Parallel Feature Selection Toolbox

Feature selection toolbox based on FEAST⁠ and the MIToolbox⁠ parallelized with Threads and MPI Processes.

⁠Quick reference

• Mantained by: Bieito Beceiro⁠
• Source: Official repository⁠

⁠Supported tags and Dockerfile links

• jpdc21, 0.0.2⁠

⁠How to use this image

Parallel-FST was initially developed as an standalone MPI+multithreading program. The image includes all the needed dependencies, as well as the compiled Parallel-FST binary.

Parallel-FST can be configured with CLI arguments, except from the number of MPI processes, which need to be specified with the -n numProcs option from mpiexec. The compiled binary can be run using this command and configured with the following options:

$ mpiexec -n numProcs ./Parallel-FST -a algorithm [--original] -i inputFile [-w weightsFile] -o outputFile -s numSelecFeat [-d] [-t numTh] [-m] [--beta b --gamma g]

⁠Parameters

• -a (string) algorithm (mRMR_D | CMIM | JMI | DISR | ICAP | CondMI | MIM | BetaGamma)
• -i (string) inputFile
• -w (string) (optional) weightsFile
• -o (string) outputFile
• -s (int) number of features to select
• -d (int) (optional) indicates that the input must be discretized and the number of bins used. By default no discretization is required
• -t (int) (optional) number of threads. By default: (hardware concurrency)
• -m (optional) if present, map feature values before applying algorithm. Useful for datasets where feature values >> number of samples
• --original (optional) if present, use original sequential implementation of the specified algorithm
• --beta (double) (BetaGamma only) value of beta parameter for BetaGamma algorithm
• --gamma (double) (BetaGamma only) value of gamma parameter for BetaGamma algorithm
• -h print out the usage of the program

⁠Examples of Parallel-FST configurations

The following commands are examples of the usage of Parallel-FST to select 20 features from a dataset mnist.libsvm (discretized with a binning approach and 128 bins) using the mRMR_D algorithm. Output would be saved to results.tsv.

⁠Using the original FEAST implementation

$ mpiexec -n 1 ./Parallel-FST -i mnist.libsvm -d 128 -o results.tsv -a mRMR_D -s 20 --original
$ mpiexec -n 1 ./Parallel-FST -i mnist.libsvm -d 128 -o results.tsv -a mRMR_D -s 20 --original -m  # same as previous, but applying range compression

⁠Using multithreading only (1 MPI process that launchs T threads)

$ mpiexec -n 1 ./Parallel-FST -i mnist.libsvm -d 128 -o results.tsv -a mRMR_D -s 20       # number of threads is auto-selected
$ mpiexec -n 1 ./Parallel-FST -i mnist.libsvm -d 128 -o results.tsv -a mRMR_D -s 20 -t 8  # use 8 threads

⁠Using MPI only (NP MPI processes that launch 1 thread each)

$ mpiexec -n 8 ./Parallel-FST -i mnist.libsvm -d 128 -o results.tsv -a mRMR_D -s 20 -t 1

⁠Using MPI and threads (NP MPI processes that launch T threads each)

$ mpiexec -n 2 ./Parallel-FST -i mnist.libsvm -d 128 -o results.tsv -a mRMR_D -s 20 -t 4  # 2 MPI processes x 4 threads/process
$ mpiexec -n 4 ./Parallel-FST -i mnist.libsvm -d 128 -o results.tsv -a mRMR_D -s 20 -t 2  # 4 MPI processes x 2 threads/process

⁠Examples of usage with the Docker image

The parallel-fst image can be used to perform the feature selection using the Parallel-FST binary. To do so, the image can be used as follows:

$ docker run [DOCKER_OPTIONS] udcgac/parallel-fst:jpdc21  # runs the test example
$ docker run [DOCKER_OPTIONS] udcgac/parallel-fst:jpdc21 mpiexec -n <NP> ./Parallel-FST [PARALLEL_FST_OPTIONS]

Where PARALLEL_FST_OPTIONS are configuration options accepted by the Parallel-FST binary as stated in the 'Usage' section⁠, and <NP> is the number of MPI processes to launch.

Next, some concrete examples of commonly requested usages are proposed.

⁠Run the test example

This will use the mRMR_D algorithm to select 20 features from the MNIST dataset included with the image. The results will be printed to the stdout.

$ docker run udcgac/parallel-fst:jpdc21

⁠Perform feature selection on a dataset stored at the host system

The easiest way to perform the feature selection on an external dataset (<dataset_name>) is to mount a volume that contains it (<path_to_dataset_folder>), and then pass the path of the dataset in the mounted directory (<mountpoint>) to Parallel-FST as follows:

$ docker run -v <path_to_dataset_folder>:<mountpoint> udcgac/parallel-fst:jpdc21 mpiexec -n 1 ./Parallel-FST -i <mountpoint>/<dataset_name> [PARALLEL_FST_OPTIONS]

A concrete example can be the next one. We have the breast.libsvm dataset in the ~/Downloads/Datasets host directory, so we mount it to the container directory /home/user/datasets. This way, Parallel-FST can access the dataset at /home/user/datasets/breast.libsvm and perform the specified feature selection:

$ docker run -v ~/Downloads/Datasets:/home/user/datasets udcgac/parallel-fst:jpdc21 mpiexec -n 1 ./Parallel-FST -i /home/user/datasets/breast.libsvm -d 128 -m -o /dev/stdout -a JMI -s 10

⁠Perform feature selection and store the output to a file

As well as in the previous example, here we will be mounting other volume, so the output of Parallel-FST is stored to persistent storage. With the following command, we will analyze the dataset mnist.libsvm and the output, written to /home/user/results/mnist.tsv in the container, will be mapped to the host file results/mnist.tsv.

$ mkdir ~/results
$ docker run -v ~/results:/home/user/results udcgac/parallel-fst:jpdc21 mpiexec -n 1 ./Parallel-FST -i /home/user/datasets/mnist.libsvm -d 128 -m -o /home/user/results/mnist.tsv -a JMI -s 10
$ cat ~/results/mnist.tsv  # show results

⁠Image variants

All images contain the built Parallel-FST binary as well as the dependencies. The MNIST dataset has also been added so quick tests can be executed. The dataset was downloaded from the LIBSVM⁠ project website.

⁠parallel-fst:jpdc21

This image is frozen with the code that produced the results included in our article sent to the Journal on Parallel and Distributed Computing on 2021/2022.

It is based on Debian Bullseye, and the installed dependencies are:

• C/C++ Compiler: gcc 10.2.1-6
• make: GNU make 4.3
• CMake: CMAKE 3.18.4
• MPI: MPICH 3.4.1