Main Content

initialize

Initialize the state of the particle filter

collapse all in page

Syntax

initialize(pf,numParticles,mean,covariance)
initialize(pf,numParticles,stateBounds)
initialize(___,Name,Value)

Description

initialize(pf,numParticles,mean,covariance) initializes a particle filter object with a specified number of particles. The initial states of the particles in the state space are determined by sampling from the multivariate normal distribution with the specified mean and covariance. The number of state variables (NumStateVariables) is retrieved automatically based on the length of the mean vector.

example

initialize(pf,numParticles,stateBounds) determines the initial location of numParticles particles by sampling from the multivariate uniform distribution with the given stateBounds.

initialize(___,Name,Value) initializes the particles with additional options specified by one or more Name,Value pair arguments.

Examples

collapse all

Open Live Script

To create a particle filter object for estimating the states of your system, create appropriate state transition function and measurement function for the system.

In this example, the functions vdpParticleFilterStateFcn and vdpMeasurementLikelihoodFcn describe a discrete-approximation to van der Pol oscillator with nonlinearity parameter, mu, equal to 1.

Create the particle filter object. Use function handles to provide the state transition and measurement likelihood functions to the object.

myPF = particleFilter(@vdpParticleFilterStateFcn,@vdpMeasurementLikelihoodFcn);

Initialize the particle filter at state [2; 0] with unit covariance, and use 1000 particles.

initialize(myPF, 1000, [2;0], eye(2));
myPF
myPF = 
  particleFilter with properties:

           NumStateVariables: 2
                NumParticles: 1000
          StateTransitionFcn: @vdpParticleFilterStateFcn
    MeasurementLikelihoodFcn: @vdpMeasurementLikelihoodFcn
     IsStateVariableCircular: [0 0]
            ResamplingPolicy: [1x1 particleResamplingPolicy]
            ResamplingMethod: 'multinomial'
       StateEstimationMethod: 'mean'
            StateOrientation: 'column'
                   Particles: [2x1000 double]
                     Weights: [1.0000e-03 1.0000e-03 1.0000e-03 1.0000e-03 1.0000e-03 1.0000e-03 1.0000e-03 1.0000e-03 1.0000e-03 1.0000e-03 1.0000e-03 1.0000e-03 1.0000e-03 1.0000e-03 1.0000e-03 1.0000e-03 1.0000e-03 1.0000e-03 ... ] (1x1000 double)
                       State: 'Use the getStateEstimate function to see the value.'
             StateCovariance: 'Use the getStateEstimate function to see the value.'

To estimate the states and state estimation error covariance from the constructed object, use the predict and correct commands.

This example uses:

Open Live Script

Create a particle filter object and use function handles to provide the state transition and measurement likelihood functions to the object. 

myPF = particleFilter(@vdpParticleFilterStateFcn,@vdpMeasurementLikelihoodFcn);

To initialize this particle filter object using a custom distribution, first initialize it using a Gaussian or uniform distribution. Then generate and assign particles of the desired custom distribution to the particle filter object.

For this example, initialize the particle filter, using Gaussian distribution, at state [2; 0] with unit covariance, and use 1000 particles.

initialize(myPF,1000,[2;0],eye(2));
myPF
myPF = 
  particleFilter with properties:

           NumStateVariables: 2
                NumParticles: 1000
          StateTransitionFcn: @vdpParticleFilterStateFcn
    MeasurementLikelihoodFcn: @vdpMeasurementLikelihoodFcn
     IsStateVariableCircular: [0 0]
            ResamplingPolicy: [1x1 particleResamplingPolicy]
            ResamplingMethod: 'multinomial'
       StateEstimationMethod: 'mean'
            StateOrientation: 'column'
                   Particles: [2x1000 double]
                     Weights: [1.0000e-03 1.0000e-03 1.0000e-03 1.0000e-03 1.0000e-03 1.0000e-03 1.0000e-03 1.0000e-03 1.0000e-03 1.0000e-03 1.0000e-03 1.0000e-03 1.0000e-03 1.0000e-03 1.0000e-03 1.0000e-03 1.0000e-03 1.0000e-03 ... ] (1x1000 double)
                       State: 'Use the getStateEstimate function to see the value.'
             StateCovariance: 'Use the getStateEstimate function to see the value.'

Choose a distribution and create a probability distribution object for it using the makedist (Statistics and Machine Learning Toolbox) function.

pd = makedist('Poisson');

Generate particles of the desired distribution using the random (Statistics and Machine Learning Toolbox) function.

Particles = random(pd,myPF.NumStateVariables,myPF.NumParticles);

Assign these particles to the Particles property of the particle filter to initialize the object with the custom distribution.

myPF.Particles = Particles;

To estimate the states and state estimation error covariance from the constructed object, use the predict and correct commands.

Input Arguments

collapse all

Particle filter, specified as an object. See particleFilter for more information.

Number of particles used in the filter, specified as a scalar.

Unless performance is an issue, do not use fewer than 1000 particles. A higher number of particles can improve the estimate but sacrifices performance speed, because the algorithm has to process more particles. Tuning the number of particles is the best way to improve the tracking of your particle filter.

Mean of particle distribution, specified as a vector. The NumStateVariables property of pf is set based on the length of this vector.

Covariance of particle distribution, specified as an N-by-N matrix, where N is the value of NumStateVariables property from pf.

Bounds of state variables, specified as an n-by-2 matrix. The NumStateVariables property of pf is set based on the value of n. Each row corresponds to the lower and upper limit of the corresponding state variable. The number of state variables (NumStateVariables) is retrieved automatically based on the number of rows of the stateBounds array.

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: ...'StateOrientation','row'

Circular variables, the comma-separated pair consisting of CircularVariables and specified as a logical vector. Each state variable that uses circular or angular coordinates is indicated with a 1. The length of the vector is equal to the NumStateVariables property of particleFilter.

Orientation of states, specified as the comma-separated pair consisting of StateOrientation as one of these values: 'column' or 'row'. If it is 'column', State property and getStateEstimate method of the object pf returns the states as a column vector, and the Particles property has dimensions NumStateVariables-by-NumParticles. If it is 'row', the states have the row orientation and Particles has dimensions NumParticles-by-NumStateVariables.

Version History

Introduced in R2017b

See Also

| | | | |

Topics