mlpack_kmeans(1)

📦
version 4.8.0 · 5 versions
, in ubuntu stonking

💖 NAME 💖

mlpack_kmeans — k-means clustering, and yes it's as iconic as it sounds 🎀

✨ SYNOPSIS ✨

okay so here's the whole vibe in one line, no cap:

mlpack_kmeans -c int -i unknown [-a string] [-e bool] [-P bool] [-I unknown] [-E bool] [-K bool] [-l bool] [-m int] [-p double] [-r bool] [-S int] [-s int] [-V bool] [-C unknown] [-o unknown] [-h -v]

🦋 DESCRIPTION 🦋

So this program does K-Means clustering on whatever dataset you hand it. It can give you back the learned cluster assignments, and the centroids of the clusters. Empty clusters are NOT allowed by default — when a cluster goes empty, the point furthest from the centroid of the cluster with maximum variance gets yoinked to fill that cluster. like, it's giving "we don't leave seats empty in this house" 💀

Optionally, you can specify the strategy used to choose the initial centroids. The k-means++ algorithm can pick your initial centroids with the --kmeans_plus_plus (-K) parameter. The Bradley and Fayyad approach ("Refining initial points for k-means clustering", 1998) can be used to select initial points by specifying the --refined_start (-r) parameter. That approach works by taking random samplings of the dataset; to specify the number of samplings, you use the --samplings (-S) parameter, and to specify the percentage of the dataset used in each sample, you use the --percentage (-p) parameter (it should be a value between 0.0 and 1.0, bestie, don't be chaotic).

There are several options available for the algorithm used for each Lloyd iteration, specified with the --algorithm (-a) option. The standard O(kN) approach can be used (naive). Other options include the Pelleg-Moore tree-based algorithm (pelleg-moore), Elkan's triangle-inequality based algorithm (elkan), Hamerly's modification to Elkan's algorithm (hamerly), the dual-tree k-means algorithm (dualtree), and the dual-tree k-means algorithm using the cover tree (dualtree-covertree). pick your fighter, they're all serving 💅

The behavior for when an empty cluster is encountered can be modified with the --allow_empty_clusters (-e) option. When this option is specified and there is a cluster owning no points at the end of an iteration, that cluster's centroid will simply remain in its position from the previous iteration. If the --kill_empty_clusters (-E) option is specified, then when a cluster owns no points at the end of an iteration, the cluster centroid is simply filled with DBL_MAX, killing it and effectively reducing k for the rest of the computation. 😭 Note that the default option when neither empty cluster option is specified can be time-consuming to calculate; therefore, specifying either of these parameters will often accelerate runtime. slay for speed 🏃‍♀️

Initial clustering assignments may be specified using the --initial_centroids_file (-I) parameter, and the maximum number of iterations may be specified with the --max_iterations (-m) parameter.

As an example, to use Hamerly's algorithm to perform k-means clustering with k=10 on the dataset data.csv, saving the centroids to centroids.csv and the assignments for each point to assignments.csv, the following command could be used:

$ mlpack_kmeans --input_file data.csv --clusters 10 --output_file assignments.csv --centroid_file centroids.csv

To run k-means on that same dataset with initial centroids specified in initial.csv with a maximum of 500 iterations, storing the output centroids in final.csv the following command may be used:

$ mlpack_kmeans --input_file data.csv --initial_centroids_file initial.csv --clusters 10 --max_iterations 500 --centroid_file final.csv

👑 REQUIRED INPUT OPTIONS 👑

these are not optional, babe. main character requirements only.

  • --clusters (-c) [int] — Number of clusters to find (0 autodetects from initial centroids). zero means "idk you figure it out" ✨
  • --input_file (-i) [unknown] — Input dataset to perform clustering on. the whole point, fr fr 🍓

🌈 OPTIONAL INPUT OPTIONS 🌈

the glow-up section. mix and match, go off.

  • --algorithm (-a) [string] — Algorithm to use for the Lloyd iteration (naive, pelleg-moore, elkan, hamerly, dualtree, or dualtree-covertree). Default value naive.
  • --allow_empty_clusters (-e) [bool] — Allow empty clusters to be persist.
  • --help (-h) [bool] — Default help info.
  • --in_place (-P) [bool] — If specified, a column containing the learned cluster assignments will be added to the input dataset file. In this case, --output_file is overridden. (Do not use in Python.) heads up bestie — overridden means overridden 🫶
  • --info [string] — Print help on a specific option. Default value ''.
  • --initial_centroids_file (-I) [unknown] — Start with the specified initial centroids.
  • --kill_empty_clusters (-E) [bool] — Remove empty clusters when they occur. dramatic and effective 💀
  • --kmeans_plus_plus (-K) [bool] — Use the k-means++ initialization strategy to choose initial points.
  • --labels_only (-l) [bool] — Only output labels into output file.
  • --max_iterations (-m) [int] — Maximum number of iterations before k-means terminates. Default value 1000.
  • --percentage (-p) [double] — Percentage of dataset to use for each refined start sampling (use when --refined_start is specified). Default value 0.02.
  • --refined_start (-r) [bool] — Use the refined initial point strategy by Bradley and Fayyad to choose initial points.
  • --samplings (-S) [int] — Number of samplings to perform for refined start (use when --refined_start is specified). Default value 100.
  • --seed (-s) [int] — Random seed. If 0, std::time(NULL) is used. Default value 0.
  • --verbose (-v) [bool] — Display informational messages and the full list of parameters and timers at the end of execution.
  • --version (-V) [bool] — Display the version of mlpack.

🎀 OPTIONAL OUTPUT OPTIONS 🎀

where the receipts go 💖

  • --centroid_file (-C) [unknown] — If specified, the centroids of each cluster will be written to the given file.
  • --output_file (-o) [unknown] — Matrix to store output labels or labeled data to.

🔥 ADDITIONAL INFORMATION 🔥

For further information, including relevant papers, citations, and theory, consult the documentation found at http://www.mlpack.org or included with your distribution of mlpack. iykyk 📚

and that's the whole page, bestie!! this gorgeousness is mlpack-4.8.0, dated 22 June 2026 — from the mlpack_kmeans(1) manual, mwah 💅💖✨

📦 where this page comes from