Filter modules¶
Filter¶
Particle Filter class for solving an estimation problem defined by a model class.
- class pftracker.modules.filter.Filter.ParticleFilter(model, algorithm, N, output, resample, resamplePercent, robustPercent=None)[source]¶
Run a particle filter algorithm for an estimation problem.
This class creates particle filter estimates corresponding to a model class. This model class contains the calculation way of methods that vary with each model where to apply particle filter estimations. This model methods are:
initialization: Create initial particles distribution.
prediction: Predict next state of the particles.
update: Evaluate predicted particles with an observation model.
update_apf: Evaluate predicted particles for second stage weights in auxiliary particle filter algorithm.
visualize: Visualize the estimate resulting from particle filter algorithm.
saveEstimation: Save particle filter estimates into a .txt file.
saveOutputModel: Save the visualization produced by visualize method into a file.
get_error: Get the particle filter estimation error.
get_estimation: Get all the particle filter estimates.
The ParticleFilter class interface model class with the PF algorithms and their methods:
filtering: Runs particle filter algorithm.
estimate: Returns the expected particle filter estimation.
resample: Runs resampling step.
- Parameters
model – Especific model where to apply the particle filter estimation
algorithm (str) – particle filter algorithm to apply
N (int) – Number of particles
output (str) – Output estimate method
resample (str) – Resampling method
resamplePercent (int) – Resampling percent
robustPercent (int, optional) – Particles percent to use in the robust mean estimation algorithm.
- estimate(particles, weights)[source]¶
Returns the expected particle filter estimation.
- Parameters
particles – predicted particles x_{k}
weights – particle weigths after update process
- filtering(pf, particles)[source]¶
Runs particle filter algorithm.
- Parameters
pf (ParticleFilter) – ParticleFilter class object
particles (array) – particles at time k-1
- Returns
(array) of particles x_{k} with (state_vector_size,N) dimension
- get_error(gt_file)[source]¶
Returns the particle filter estimation error.
This function is depedent on the model class.
- Parameters
gt_file (str) – path to ground truth .txt file
- prediction(particles)[source]¶
Predict next state of the particles from time k-1 to k.
Predicts the a priori pdf p(x_{k}|z_{k-1}) that describes particles distribution x_{k} using the dynamic model p(x_{k}|x_{k-1}) (state transition model).
x_{k}: state vector of particles at time k.
x_{k-1}: state vector of particles at time k-1.
z_{k-1}: observations at time k-1.
This function is depedent on the model class.
- Parameters
particles (array) – Model specific representation of particles x_{k-1}.
- Returns
2-element tuple containing
particles (array): particles array x_{k} with (state_vector_size, N) dimension.
uk (array): u_{k} array with (state_vector_size, N) dimension. This is a characterization of x_{k}|x_{k-1} (move particles from x_{k-1} to x_{k} without include process noise).
- resample(weights)[source]¶
Runs resampling step.
Resampling methods supported: systematic, stratified, residual and multinomial.
- Parameters
weights (array) – particle weigths after update process
- Returns
(array) of indixes resulting from resampling with (1,N) dimension
- saveEstimation(file_name)[source]¶
Save particle filter estimates into a .txt file.
This function is depedent on the model class.
- saveOutputModel()[source]¶
Save the visualization produced by visualize method into a file.
This function is depedent on the model class.
- update(particles)[source]¶
Evaluate predicted particles x_{k} with an observation model.
This function is depedent on the model class.
- Returns
(array) of likelihoods of predicted particles x_{k}, with (1, N) dimension. This is p(z_{k}|x_{k}).
- update_apf(particles)[source]¶
Evaluate predicted particles x_{k}^{idx} with an observation model.
Evaluate predicted particles x_{k}^{idx} for the second stage weights of auxiliary particle filter algorithm with an observation model. Here idx are the indixes resulting from resampling of the first stage weigths of auxiliary particle filter algorithm.
This function is depedent on the model class.
- Parameters
particles (array) – predicted particles array x_{k}^{idx} with (state_vector_size, N) dimension
- Returns
(array) of likelihoods of particles x_{k}^{idx}, with (1, N) dimension. This is p(z_{k}|x_{k}^{idx}).
pfAlgorithms¶
- class pftracker.modules.filter.pfiltering(N)[source]¶
Particle filter algorithms.
This class contains four particle filter algorithms and the needed methods for running them.
- Supported particle filter algorithms:
SIS: Sequential Importance Sampling filter
SIR: Sequential Importance Resampling filter
G_PF: Generic particle filter
APF: Auxilliary particle filter
- Parameters
N (int) – Number of particles
- APF(pf, particles)[source]¶
Run auxilliary particle filter (APF).
The APF calculates the weights in a two-stage process. The first stage weights uses a characterization (u_{k}) of the distribution p(x_{k}|x_{k-1}) and calculates the weigths of it. Then the algorithm tries to predict which particles are located in regions of high likelihood that constitute the best representation of the set of predicted samples at time k.
Second stage weights uses this information to resample particles (x_{k-1}) at time k-1, propagate them to time k and calculate the likelihoods. Final weights are obtained dependent on the actual likelihoods and the likelihood obtained from the characterization u_{k}.
- Parameters
pf (particlefilter) – particlefilter class object
particles (array) – particles at time k-1 with (state_vector_size,N) dimension
- Returns
(array) of particles x_{k} with (state_vector_size,N) dimension
- G_PF(pf, particles, resamplePercent)[source]¶
Run generic particle filter.
This filter includes the resampling step only in some iterations of the SIS algorithm. Resampling is applied when the effective number of particles (N_{eff}^{(k)}) is below a threshold N_{T}.
- Parameters
pf (particlefilter) – particlefilter class object
particles (array) – particles at time k-1 with (state_vector_size,N) dimension
- Returns
(array) of particles x_{k} with (state_vector_size,N) dimension
- SIR(pf, particles)[source]¶
Run Sequential Importance Sampling (SIR) filter.
This filter includes an additional resampling step in each SIS algorithm iteration. Resampling generates a new set of particles from the normalized weight, resampling N times from the pdf p(x_{k}|z_{k}). This is done by copying particles with higher weight and discarding low weight particles. This step tries to concentrate particles around state space regions with high importance.
- Parameters
pf (particlefilter) – particlefilter class object
particles (array) – particles at time k-1 with (state_vector_size,N) dimension
- Returns
(array) of particles x_{k} with (state_vector_size,N) dimension
- SIS(pf, particles)[source]¶
Run Sequential Importance Sampling (SIS) filter.
- Parameters
pf (particlefilter) – particlefilter class object
particles (array) – particles at time k-1 with (state_vector_size,N) dimension
- Returns
(array) of particles x_{k} with (state_vector_size,N) dimension
- calc_uk_with_kf(pf, particles)[source]¶
Calculate characterization u_{k} of the distribution p(x_{k}|x_{k-1}).
The characterization u_{k} is used in the first stage weigths of th APF algorithm and is obtained using a Kalman filter in which the observation comes from the distribution p(x_{k}|x_{k-1}), without include the noise of the dynamic model employed. The magnitude of the noise associated with the distribution p(x_{k}|x_{k-1}) can afect the performance of the APF.
- Parameters
pf (particlefilter) – particlefilter class object
particles (array) – particles at time k-1 with (state_vector_size,N) dimension
- Returns
(array) of particles u_{k} with (state_vector_size,N) dimension
- kalman_filter(particles_0)[source]¶
Initialize Kalman filter algorithm.
- Parameters
particles_0 (array) – initial particles distribution with (state_vector_size,N) dimension