mlpack_kde(1)

📦
version 4.8.0 · 5 versions
, in ubuntu stonking

💖 NAME 💖

mlpack_kde — kernel density estimation, bestie. Yes, it's the mlpack_kde(1) page, and no, you don't have to be scared of it. Sit down, grab a strawberry 🍓, we're doing this.

✨ SYNOPSIS ✨

mlpack_kde [-E double] [-a string] [-b double] [-s int] [-m unknown] [-k string] [-c double] [-C double] [-P double] [-S bool] [-q unknown] [-r unknown] [-e double] [-t string] [-V bool] [-M unknown] [-p unknown] [-h -v]

That's the whole vibe-check of the flags right there, and each one gets its own lil moment further down. 🫶

🌸 DESCRIPTION 🌸

Okay so this program does a Kernel Density Estimation. KDE is a non-parametric way of estimating a probability density function — no cap, no assumptions about the shape, it just figures it out. For every query point, the program estimates its probability density by applying a kernel function to each reference point. Gorgeous. Iconic. 💅

Heads up though: the computational complexity of this is O(N^2), where there are N query points and N reference points. But don't panic — this implementation will typically see better performance, because it uses an approximate dual or single tree algorithm for acceleration. So it's giving speed. ✨

Now, dual or single tree optimization avoids many barely relevant calculations (as kernel function values decrease with distance), which means: it is an approximate computation. Not a bug, a whole design choice. You can specify the maximum relative error tolerance for each query value with --rel_error (-e), and the maximum absolute error tolerance with the parameter --abs_error (-E). This program runs using an Euclidean metric. The kernel function can be selected using the --kernel (-k) option, and you can also choose which type of tree to use for the dual-tree algorithm with --tree (-t). It is also possible to select whether to use the dual-tree algorithm or the single-tree algorithm using the --algorithm (-a) option. Pick your fighter. 🧚

Monte Carlo estimations can be used to accelerate the KDE estimate when the Gaussian Kernel is used. This provides a probabilistic guarantee on the error of the resulting KDE instead of an absolute guarantee. To enable Monte Carlo estimations, the --monte_carlo (-S) flag can be used, and the success probability can be set with the --mc_probability (-P) option. It is possible to set the initial sample size for the Monte Carlo estimation using --initial_sample_size (-s). This implementation will only consider a node as a candidate for the Monte Carlo estimation if its number of descendant nodes is bigger than the initial sample size. This can be controlled using a coefficient that will multiply the initial sample size, and it can be set using --mc_entry_coef (-C). To avoid using the same amount of computations an exact approach would take, this program recurses the tree whenever a fraction of the amount of the node's descendant points have already been computed. This fraction is set using --mc_break_coef (-c). So many knobs, and every single one is slaying. 🎀

the example that makes it click 🦋

For example, the following will run KDE using the data in ref_data.csv for training and the data in qu_data.csv as query data. It will apply an Epanechnikov kernel with a 0.2 bandwidth to each reference point and use a KD-Tree for the dual-tree optimization. The returned predictions will be within 5% of the real KDE value for each query point.

$ mlpack_kde --reference_file ref_data.csv --query_file qu_data.csv --bandwidth 0.2 --kernel epanechnikov --tree kd-tree --rel_error 0.05 --predictions_file out_data.csv

The predicted density estimations will be stored in out_data.csv. If no --query_file (-q) is provided, then KDE will be computed on the --reference_file (-r) dataset. It is possible to select either a reference dataset or an input model, but not both at the same time — pick one, bestie, you can't have both. If an input model is selected and parameter values are not set (e.g. --bandwidth (-b)), then default parameter values will be used.

In addition to the last program call, it is also possible to activate Monte Carlo estimations if a Gaussian kernel is used. This can provide faster results, but the KDE will only have a probabilistic guarantee of meeting the desired error bound (instead of an absolute guarantee). The following example will run KDE using a Monte Carlo estimation when possible. The results will be within a 5% of the real KDE value with a 95% probability. Initial sample size for the Monte Carlo estimation will be 200 points, and a node will be a candidate for the estimation only when it contains 700 (i.e. 3.5*200) points. If a node contains 700 points and 420 (i.e. 0.6*700) have already been sampled, then the algorithm will recurse instead of keep sampling. The way that math lines up? Chefs kiss. 😭

$ mlpack_kde --reference_file ref_data.csv --query_file qu_data.csv --bandwidth 0.2 --kernel gaussian --tree kd-tree --rel_error 0.05 --predictions_file out_data.csv --monte_carlo --mc_probability 0.95 --initial_sample_size 200 --mc_entry_coef 3.5 --mc_break_coef 0.6

👑 OPTIONAL INPUT OPTIONS 👑

Every flag, in order, no skips, no shortcuts. We're being thorough in this house. 💜

  • --abs_error (-E) [double] — Relative error tolerance for the prediction. Default value 0.
  • --algorithm (-a) [string] — Algorithm to use for the prediction. ('dual-tree', 'single-tree'). Default value 'dual-tree'.
  • --bandwidth (-b) [double] — Bandwidth of the kernel. Default value 1.
  • --help (-h) [bool] — Default help info.
  • --info [string] — Print help on a specific option. Default value ''.
  • --initial_sample_size (-s) [int] — Initial sample size for Monte Carlo estimations. Default value 100.
  • --input_model_file (-m) [unknown] — Contains pre-trained KDE model.
  • --kernel (-k) [string] — Kernel to use for the prediction. ('gaussian', 'epanechnikov', 'laplacian', 'spherical', 'triangular'). Default value 'gaussian'.
  • --mc_break_coef (-c) [double] — Controls what fraction of the amount of node's descendants is the limit for the sample size before it recurses. Default value 0.4.
  • --mc_entry_coef (-C) [double] — Controls how much larger does the amount of node descendants has to be compared to the initial sample size in order to be a candidate for Monte Carlo estimations. Default value 3.
  • --mc_probability (-P) [double] — Probability of the estimation being bounded by relative error when using Monte Carlo estimations. Default value 0.95.
  • --monte_carlo (-S) [bool] — Whether to use Monte Carlo estimations when possible.
  • --query_file (-q) [unknown] — Query dataset to KDE on.
  • --reference_file (-r) [unknown] — Input reference dataset use for KDE.
  • --rel_error (-e) [double] — Relative error tolerance for the prediction. Default value 0.05.
  • --tree (-t) [string] — Tree to use for the prediction. ('kd-tree', 'ball-tree', 'cover-tree', 'octree', 'r-tree'). Default value 'kd-tree'.
  • --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 💅

The part where you tell it where to put the goods. 🎁

  • --output_model_file (-M) [unknown] — If specified, the KDE model will be saved here.
  • --predictions_file (-p) [unknown] — Vector to store density predictions.

🌈 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. Go read it, iykyk. 📚✨

Reminder bestie: dual-tree and single-tree are approximate, and Monte Carlo gives you a probabilistic guarantee, not an absolute one. Choose your error tolerance accordingly and stay safe out there. 💖

okay that's the whole page!! this was mlpack_kde from mlpack-4.8.0, dated 22 June 2026 — go estimate some densities, you absolute main character. periodt. 👑🦋💖

📦 where this page comes from