Provided by: mlpack-bin_3.4.2-5ubuntu1_amd64 
NAME
mlpack_kde - kernel density estimation
SYNOPSIS
mlpack_kde [-E double] [-a string] [-b double] [-s int] [-m unknown] [-k string] [-c double] [-C double] [-P double] [-S bool] [-q string] [-r string] [-e double] [-t string] [-V bool] [-M unknown] [-p string] [-h -v]
DESCRIPTION
This program performs a Kernel Density Estimation. KDE is a non-parametric way of
estimating probability density function. For each query point the program will estimate
its probability density by applying a kernel function to each reference point. The
computational complexity of this is O(N^2) where there are N query points and N reference
points, but this implementation will typically see better performance as it uses an
approximate dual or single tree algorithm for acceleration.
Dual or single tree optimization avoids many barely relevant calculations (as kernel
function values decrease with distance), so it is an approximate computation. You can
specify the maximum relative error tolerance for each query value with '--rel_error (-e)'
as well as the maximum absolute error tolerance with the parameter '--abs_error (-E)'.
This program runs using an Euclidean metric. Kernel function can be selected using the
'--kernel (-k)' option. You can also choose what which type of tree to use for the dual-
tree algorithm with '--tree (-t)'. It is also possible to select whether to use dual-tree
algorithm or single-tree algorithm using the '--algorithm (-a)' option.
Monte Carlo estimations can be used to accelerate the KDE estimate when the Gaussian
Kernel is used. This provides a probabilistic guarantee on the 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 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 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)'.
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. 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.
$ 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
--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) [string]
Query dataset to KDE on.
--reference_file (-r) [string]
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
--output_model_file (-M) [unknown]
If specified, the KDE model will be saved here.
--predictions_file (-p) [string]
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.