jsat.distributions.multivariate

Class MetricKDE

java.lang.Object

jsat.distributions.multivariate.MultivariateDistributionSkeleton

jsat.distributions.multivariate.MultivariateKDE

jsat.distributions.multivariate.MetricKDE

All Implemented Interfaces:

Serializable, Cloneable, MultivariateDistribution, Parameterized

public class MetricKDE
extends MultivariateKDE
implements Parameterized

MetricKDE is a generalization of the KernelDensityEstimator to the multivariate case. A KernelFunction is used to weight the contribution of each data point, and a DistanceMetric is used to effectively alter the shape of the kernel. The MetricKDE uses one bandwidth parameter, which can be estimated using a nearest neighbor approach, or tuned by hand. The bandwidth of the MetricKDE can not be estimated en the same way as the univariate case.

Author:

Edward Raff

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
static int	DEFAULT_K When estimating the bandwidth, the distances of the k'th nearest neighbors are used to perform the estimate.
static KernelFunction	DEFAULT_KF When estimating the bandwidth, the distances of the k'th nearest neighbors are used to perform the estimate.
static double	DEFAULT_STND_DEV When estimating the bandwidth, the distances of the k'th nearest neighbors are used to perform the estimate.

Constructor Summary

Constructors

Constructor and Description
MetricKDE() Creates a new KDE object that still needs a data set to model the distribution of
MetricKDE(DistanceMetric distanceMetric) Creates a new KDE object that still needs a data set to model the distribution of
MetricKDE(DistanceMetric distanceMetric, VectorCollectionFactory<VecPaired<Vec,Integer>> vcf) Creates a new KDE object that still needs a data set to model the distribution of
MetricKDE(KernelFunction kf, DistanceMetric distanceMetric)
MetricKDE(KernelFunction kf, DistanceMetric distanceMetric, VectorCollectionFactory<VecPaired<Vec,Integer>> vcf) Creates a new KDE object that still needs a data set to model the distribution of
MetricKDE(KernelFunction kf, DistanceMetric distanceMetric, VectorCollectionFactory<VecPaired<Vec,Integer>> vcf, int defaultK, double defaultStndDev) Creates a new KDE object that still needs a data set to model the distribution of

Method Summary

Modifier and Type	Method and Description
MetricKDE	clone()
double	getBandwith() Returns the current bandwidth used
int	getDefaultK() Returns the default value of the k'th nearest neighbor to use when not specified.
double	getDefaultStndDev() Returns the multiple of the standard deviations that is added to the bandwidth estimate
DistanceMetric	getDistanceMetric() Returns the distance metric that is used for density estimation
KernelFunction	getKernelFunction()
List<? extends VecPaired<VecPaired<Vec,Integer>,Double>>	getNearby(Vec x) Returns the list of vectors that have a non zero contribution to the density of the query point x.
List<? extends VecPaired<VecPaired<Vec,Integer>,Double>>	getNearbyRaw(Vec x) Returns the list of vectors that have a non zero contribution to the density of the query point x.
Parameter	getParameter(String paramName) Returns the parameter with the given name.
List<Parameter>	getParameters() Returns the list of parameters that can be altered for this learner.
double	pdf(Vec x) Returns the probability of a given vector from this distribution.
List<Vec>	sample(int count, Random rand) Sampling not yet supported
void	scaleBandwidth(double scale) A caller may want to increase or decrease the bandwidth after training has been completed to get smoother model, or decrease it to observe behavior.
void	setBandwith(double bandwidth) Sets the bandwidth used to estimate the density of the underlying distribution.
void	setDefaultK(int defaultK) When estimating the bandwidth, the mean of the k'th nearest neighbors to each data point is used.
void	setDefaultStndDev(double defaultStndDev) When estimating the bandwidth, the mean of the neighbor distances is used, and a multiple of the standard deviations is added.
void	setDistanceMetric(DistanceMetric distanceMetric) Sets the distance metric that is used for density estimation
void	setKernelFunction(KernelFunction kf)
<V extends Vec> boolean	setUsingData(List<V> dataSet) Sets the parameters of the distribution to attempt to fit the given list of vectors.
<V extends Vec> boolean	setUsingData(List<V> dataSet, double bandwith) Sets the KDE to model the density of the given data set with the specified bandwidth
<V extends Vec> boolean	setUsingData(List<V> dataSet, double bandwith, ExecutorService threadpool) Sets the KDE to model the density of the given data set with the specified bandwidth
<V extends Vec> boolean	setUsingData(List<V> dataSet, ExecutorService threadpool) Sets the parameters of the distribution to attempt to fit the given list of vectors.
<V extends Vec> boolean	setUsingData(List<V> dataSet, int k) Sets the KDE to model the density of the given data set by estimating the bandwidth by using the k nearest neighbors of each data point.
<V extends Vec> boolean	setUsingData(List<V> dataSet, int k, double stndDevs) Sets the KDE to model the density of the given data set by estimating the bandwidth by using the k nearest neighbors of each data data point.
<V extends Vec> boolean	setUsingData(List<V> dataSet, int k, double stndDevs, ExecutorService threadpool) Sets the KDE to model the density of the given data set by estimating the bandwidth by using the k nearest neighbors of each data data point.
<V extends Vec> boolean	setUsingData(List<V> dataSet, int k, ExecutorService threadpool) Sets the KDE to model the density of the given data set by estimating the bandwidth by using the k nearest neighbors of each data point.
boolean	setUsingDataList(List<DataPoint> dataPoints) Sets the parameters of the distribution to attempt to fit the given list of data points.
boolean	setUsingDataList(List<DataPoint> dataPoints, ExecutorService threadpool) Sets the parameters of the distribution to attempt to fit the given list of data points.

Methods inherited from class jsat.distributions.multivariate.MultivariateDistributionSkeleton

logPdf, logPdf, pdf, setUsingData, setUsingData

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_K

public static final int DEFAULT_K

When estimating the bandwidth, the distances of the k'th nearest neighbors are used to perform the estimate. The default value of this k is 3

See Also:

Constant Field Values

DEFAULT_STND_DEV

public static final double DEFAULT_STND_DEV

When estimating the bandwidth, the distances of the k'th nearest neighbors are used to perform the estimate. The default number of standard deviations from the mean to add to the bandwidth estimate is 2.0

See Also:

Constant Field Values

DEFAULT_KF

public static final KernelFunction DEFAULT_KF

When estimating the bandwidth, the distances of the k'th nearest neighbors are used to perform the estimate. The weight of each neighbor is controlled by the kernel function.

Constructor Detail

MetricKDE

public MetricKDE()

Creates a new KDE object that still needs a data set to model the distribution of

MetricKDE

public MetricKDE(DistanceMetric distanceMetric)

Creates a new KDE object that still needs a data set to model the distribution of

Parameters:

distanceMetric - the distance metric to use

MetricKDE

public MetricKDE(DistanceMetric distanceMetric,
                 VectorCollectionFactory<VecPaired<Vec,Integer>> vcf)

Creates a new KDE object that still needs a data set to model the distribution of

Parameters:

distanceMetric - the distance metric to use

vcf - a factory to generate vector collection from

MetricKDE

public MetricKDE(KernelFunction kf,
                 DistanceMetric distanceMetric)

MetricKDE

public MetricKDE(KernelFunction kf,
                 DistanceMetric distanceMetric,
                 VectorCollectionFactory<VecPaired<Vec,Integer>> vcf)

Creates a new KDE object that still needs a data set to model the distribution of

Parameters:

kf - the kernel function to use

distanceMetric - the distance metric to use

vcf - a factory to generate vector collection from

MetricKDE

public MetricKDE(KernelFunction kf,
                 DistanceMetric distanceMetric,
                 VectorCollectionFactory<VecPaired<Vec,Integer>> vcf,
                 int defaultK,
                 double defaultStndDev)

Creates a new KDE object that still needs a data set to model the distribution of

Parameters:

kf - the kernel function to use

distanceMetric - the distance metric to use

vcf - a factory to generate vector collection from

defaultK - the default neighbor to use when estimating the bandwidth

defaultStndDev - the default multiple of standard deviations to add when estimating the bandwidth

Method Detail

setBandwith

public void setBandwith(double bandwidth)

Sets the bandwidth used to estimate the density of the underlying distribution. Too small a bandwidth results in high variance, while too large causes high bias.

Parameters:

bandwidth - the bandwidth to use for estimation

Throws:

ArithmeticException - if the bandwidth given is not a positive number

getBandwith

public double getBandwith()

Returns the current bandwidth used

Returns:

the current bandwidth

setDefaultK

public void setDefaultK(int defaultK)

When estimating the bandwidth, the mean of the k'th nearest neighbors to each data point is used. This value controls the default value of k used when it is not specified.

Parameters:

defaultK -

getDefaultK

public int getDefaultK()

Returns the default value of the k'th nearest neighbor to use when not specified.

Returns:

the default neighbor used to estimate the bandwidth when not specified

setDefaultStndDev

public void setDefaultStndDev(double defaultStndDev)

When estimating the bandwidth, the mean of the neighbor distances is used, and a multiple of the standard deviations is added. This controls the multiplier value used when the bandwidth is not specified. Zero and negative multipliers are allowed, but a negative multiplier may result in the fitting failing.

Parameters:

defaultStndDev - the multiple of the standard deviation to add the to bandwidth estimate

getDefaultStndDev

public double getDefaultStndDev()

Returns the multiple of the standard deviations that is added to the bandwidth estimate

Returns:

the multiple of the standard deviations that is added to the bandwidth estimate

getDistanceMetric

public DistanceMetric getDistanceMetric()

Returns the distance metric that is used for density estimation

Returns:

the metric used

setDistanceMetric

public void setDistanceMetric(DistanceMetric distanceMetric)

Sets the distance metric that is used for density estimation

Parameters:

distanceMetric - the metric to use

clone

public MetricKDE clone()

Specified by:

clone in interface MultivariateDistribution

Specified by:

clone in class MultivariateKDE

getNearby

public List<? extends VecPaired<VecPaired<Vec,Integer>,Double>> getNearby(Vec x)

Description copied from class: MultivariateKDE

Returns the list of vectors that have a non zero contribution to the density of the query point x. Each vector is paired with its integer index from the original constructing list vectors, and a double indicating its weight given the kernel function in use.

Specified by:

getNearby in class MultivariateKDE

Parameters:

x - the query point

Returns:

the list of near by vectors and their weights

getNearbyRaw

public List<? extends VecPaired<VecPaired<Vec,Integer>,Double>> getNearbyRaw(Vec x)

Description copied from class: MultivariateKDE

Returns the list of vectors that have a non zero contribution to the density of the query point x. Each vector is paired with its integer index from the original constructing list vectors, and a double indicating its distance from the query point divided by the bandwidth of the point.

Specified by:

getNearbyRaw in class MultivariateKDE

Parameters:

x - the query point

Returns:

the list of near by vectors and their weights

pdf

public double pdf(Vec x)

Description copied from interface: MultivariateDistribution

Returns the probability of a given vector from this distribution. By definition, the probability will always be in the range [0, 1].

Specified by:

pdf in interface MultivariateDistribution

Parameters:

x - the vector the get the log probability of

Returns:

the probability

setUsingData

public <V extends Vec> boolean setUsingData(List<V> dataSet,
                                            double bandwith)

Sets the KDE to model the density of the given data set with the specified bandwidth

Parameters:

dataSet - the data set to model the density of

bandwith - the bandwidth

Returns:

true if the model was fit, false if it could not be fit.

setUsingData

public <V extends Vec> boolean setUsingData(List<V> dataSet,
                                            double bandwith,
                                            ExecutorService threadpool)

Sets the KDE to model the density of the given data set with the specified bandwidth

Parameters:

dataSet - the data set to model the density of

bandwith - the bandwidth

threadpool - the source of threads for parallel construction

Returns:

true if the model was fit, false if it could not be fit.

setUsingData

public <V extends Vec> boolean setUsingData(List<V> dataSet,
                                            int k)

Sets the KDE to model the density of the given data set by estimating the bandwidth by using the k nearest neighbors of each data point.

Parameters:

dataSet - the data set to model the density of

k - the number of neighbors to use to estimate the bandwidth

Returns:

true if the model was fit, false if it could not be fit.

setUsingData

public <V extends Vec> boolean setUsingData(List<V> dataSet,
                                            int k,
                                            ExecutorService threadpool)

Sets the KDE to model the density of the given data set by estimating the bandwidth by using the k nearest neighbors of each data point.

Parameters:

dataSet - the data set to model the density of

k - the number of neighbors to use to estimate the bandwidth

threadpool - the source of threads for computation

Returns:

true if the model was fit, false if it could not be fit.

setUsingData

public <V extends Vec> boolean setUsingData(List<V> dataSet,
                                            int k,
                                            double stndDevs)

Sets the KDE to model the density of the given data set by estimating the bandwidth by using the k nearest neighbors of each data data point.
The bandwidth estimate is calculate as the mean of the distances of the k'th nearest neighbor plus stndDevs standard deviations added to the mean.

Parameters:

dataSet - the data set to model the density of

k - the number of neighbors to use to estimate the bandwidth

stndDevs - the multiple of the standard deviation to add to the mean of the distances

Returns:

true if the model was fit, false if it could not be fit.

setUsingData

public <V extends Vec> boolean setUsingData(List<V> dataSet,
                                            int k,
                                            double stndDevs,
                                            ExecutorService threadpool)

Sets the KDE to model the density of the given data set by estimating the bandwidth by using the k nearest neighbors of each data data point.
The bandwidth estimate is calculate as the mean of the distances of the k'th nearest neighbor plus stndDevs standard deviations added to the mean.

Parameters:

dataSet - the data set to model the density of

k - the number of neighbors to use to estimate the bandwidth

stndDevs - the multiple of the standard deviation to add to the mean of the distances

threadpool - the source of threads to use for computation

Returns:

true if the model was fit, false if it could not be fit.

setUsingData

public <V extends Vec> boolean setUsingData(List<V> dataSet)

Description copied from interface: MultivariateDistribution

Sets the parameters of the distribution to attempt to fit the given list of vectors. All vectors are assumed to have the same weight.

Specified by:

setUsingData in interface MultivariateDistribution

Type Parameters:

V - the vector type

Parameters:

dataSet - the list of data points

Returns:

true if the distribution was fit to the data, or false if the distribution could not be fit to the data set.

setUsingData

public <V extends Vec> boolean setUsingData(List<V> dataSet,
                                            ExecutorService threadpool)

Description copied from interface: MultivariateDistribution

Sets the parameters of the distribution to attempt to fit the given list of vectors. All vectors are assumed to have the same weight.

Specified by:

setUsingData in interface MultivariateDistribution

Overrides:

setUsingData in class MultivariateDistributionSkeleton

Type Parameters:

V - the vector type

Parameters:

dataSet - the list of data points

threadpool - the source of threads for computation

Returns:

true if the distribution was fit to the data, or false if the distribution could not be fit to the data set.

setUsingDataList

public boolean setUsingDataList(List<DataPoint> dataPoints)

Description copied from interface: MultivariateDistribution

Sets the parameters of the distribution to attempt to fit the given list of data points. The weights of the data points will be used.

Specified by:

setUsingDataList in interface MultivariateDistribution

Parameters:

dataPoints - the list of data points to use

Returns:

true if the distribution was fit to the data, or false if the distribution could not be fit to the data set.

setUsingDataList

public boolean setUsingDataList(List<DataPoint> dataPoints,
                                ExecutorService threadpool)

Description copied from interface: MultivariateDistribution

Sets the parameters of the distribution to attempt to fit the given list of data points. The weights of the data points will be used.

Specified by:

setUsingDataList in interface MultivariateDistribution

Overrides:

setUsingDataList in class MultivariateDistributionSkeleton

Parameters:

dataPoints - the list of data points to use

threadpool - the source of threads for computation

Returns:

true if the distribution was fit to the data, or false if the distribution could not be fit to the data set.

sample

public List<Vec> sample(int count,
                        Random rand)

Sampling not yet supported

Specified by:

sample in interface MultivariateDistribution

Parameters:

count -

rand -

Returns:

will not return

Throws:

UnsupportedOperationException - not yet implemented

getKernelFunction

public KernelFunction getKernelFunction()

Specified by:

getKernelFunction in class MultivariateKDE

Returns:

the kernel function used

setKernelFunction

public void setKernelFunction(KernelFunction kf)

scaleBandwidth

public void scaleBandwidth(double scale)

Description copied from class: MultivariateKDE

A caller may want to increase or decrease the bandwidth after training has been completed to get smoother model, or decrease it to observe behavior. This method will scaled the bandwidth of each data point by the given factor

Specified by:

scaleBandwidth in class MultivariateKDE

Parameters:

scale - the value to scale the bandwidth used

getParameters

public List<Parameter> getParameters()

Description copied from interface: Parameterized

Returns the list of parameters that can be altered for this learner.

Specified by:

getParameters in interface Parameterized

Returns:

the list of parameters that can be altered for this learner.

getParameter

public Parameter getParameter(String paramName)

Description copied from interface: Parameterized

Returns the parameter with the given name. Two different strings may map to a single Parameter object. An ASCII only string, and a Unicode style string.

Specified by:

getParameter in interface Parameterized

Parameters:

paramName - the name of the parameter to obtain

Returns:

the Parameter in question, or null if no such named Parameter exists.