de.unihalle.informatik.MiToBo.math.distributions.impl
Class ParticleDistribution<G extends Copyable<? extends G>>

java.lang.Object
  extended by de.unihalle.informatik.MiToBo.math.distributions.impl.ParticleDistribution<G>
Type Parameters:
G - type of a particle
All Implemented Interfaces:
SamplingDistribution<G>
Direct Known Subclasses:
MultiTargetRBMCDA

public class ParticleDistribution<G extends Copyable<? extends G>>
extends java.lang.Object
implements SamplingDistribution<G>

A distribution represented by weighted particles

Author:
Oliver Gress

Field Summary
protected  double[] cweights
           
protected  boolean equalWeights
           
protected  G[] particles
           
protected  java.util.Random rand
           
protected  double[] weights
           
 
Constructor Summary
protected ParticleDistribution()
          Constructor where all fields are initialized by null.
  ParticleDistribution(java.util.Random rand, G[] particles)
          Constructor with equally weighted particles that must be specified.
  ParticleDistribution(java.util.Random rand, G[] particles, double[] weights)
          Constructor with equally weighted particles that must be specified.
  ParticleDistribution(java.util.Random rand, SamplingDistribution<G> density, int numParticles)
          Constructor that samples numParticles from density.
 
Method Summary
 double computeESS()
          Compute effective sample size (ESS).
 G drawSample()
          Generate a new sample from this density.
 boolean equalWeights()
          Returns true if all particle weights are equal
 int getNumOfParticles()
          Get number of particles
 G getParticle(int idx)
          Get idx-th particle
 G[] getParticles()
          Get particles
 double getWeight(int idx)
          Get weight of idx-th particle
 double[] getWeights()
          Get particle weights
(package private)  double getWeightsSum()
          Get sum of weights
 void normalizeWeights()
          Normalize the particle weights to sum to 1.
 void resample()
          Resample this distribution and equalize weights
 void setEqualWeightsFlag(boolean equalWeights)
          Set the "equal weights"-flag
 void setParticle(int idx, G particle)
          Set idx-th particle
 void setWeight(int idx, double weight)
          Set weight for particle specified by idx.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

cweights

protected double[] cweights

equalWeights

protected boolean equalWeights

particles

protected G extends Copyable<? extends G>[] particles

rand

protected java.util.Random rand

weights

protected double[] weights
Constructor Detail

ParticleDistribution

protected ParticleDistribution()
Constructor where all fields are initialized by null.


ParticleDistribution

public ParticleDistribution(java.util.Random rand,
                            G[] particles)
Constructor with equally weighted particles that must be specified.

Parameters:
rand - random generator for sampling
particles - equally weighted particles

ParticleDistribution

public ParticleDistribution(java.util.Random rand,
                            G[] particles,
                            double[] weights)
                     throws java.lang.IllegalArgumentException
Constructor with equally weighted particles that must be specified.

Parameters:
rand - random generator for sampling
particles - particles
weights - weights of the particles
Throws:
java.lang.IllegalArgumentException - when particles- and weights-array do not have same length

ParticleDistribution

public ParticleDistribution(java.util.Random rand,
                            SamplingDistribution<G> density,
                            int numParticles)
Constructor that samples numParticles from density.

Parameters:
rand - random generator for sampling
density - distribution to sample from
numParticles - number of particles to be sampled
Method Detail

computeESS

public double computeESS()
Compute effective sample size (ESS). If many particles have weights approximately 0 the distribution resampling might be required e.g. for good exploration of the random variable's space in case of a particle filter. High variance in the weight is a good indicator for this situation. The ESS returns values from 1 to N (number of particles), where 1 corresponds to a single particle with weight 1 and N to weights 1/N for each particle. Resampling is suggested if ESS drops below a certain threshold.


drawSample

public G drawSample()
Description copied from interface: SamplingDistribution
Generate a new sample from this density. This method should create a new object.

Specified by:
drawSample in interface SamplingDistribution<G extends Copyable<? extends G>>
Returns:
new sample object

equalWeights

public boolean equalWeights()
Returns true if all particle weights are equal


getNumOfParticles

public int getNumOfParticles()
Get number of particles


getParticle

public G getParticle(int idx)
Get idx-th particle


getParticles

public G[] getParticles()
Get particles


getWeight

public double getWeight(int idx)
Get weight of idx-th particle


getWeights

public double[] getWeights()
Get particle weights


getWeightsSum

double getWeightsSum()
Get sum of weights


normalizeWeights

public void normalizeWeights()
Normalize the particle weights to sum to 1. If all weights are 0, equal weights are given to all particles!


resample

public void resample()
Resample this distribution and equalize weights


setEqualWeightsFlag

public void setEqualWeightsFlag(boolean equalWeights)
Set the "equal weights"-flag


setParticle

public void setParticle(int idx,
                        G particle)
Set idx-th particle


setWeight

public void setWeight(int idx,
                      double weight)
Set weight for particle specified by idx. Don't forget to normalize after setting weights, because cumulative weight are not updated in this method.

Parameters:
idx - index of particle
weight - weight of particle