Programmer’s Reference¶

Below is a description of the public API of starman separated by functionality. In-depth discussion how to use the API can be found in the appropriate sections of the documentation.

State estimation¶

class starman.KalmanFilter(initial_state_estimate=None, process_matrix=None, process_covariance=None, control_matrix=None, state_length=None)¶

A KalmanFilter maintains an estimate of true state given noisy measurements.

The filter is initialised to have no state estimates. (Time step “-1” if you will.) Before calling update(), predict() must be called at least once.

The filter represents its state estimates as frozen MultivariateNormal instances.

Parameters:

initial_state_estimate (None or MultivariateNormal) – The initial estimate of the true state used for the first predict() step. If None, state_length must be specified and the initial state estimate is initialised to zero mean and a covariance of the identity matrix muiltiplied by a large value. (Specifically the value of KalmanFilter.LARGE_COVARIANCE.)
process_matrix (array or None) – The process matrix to use if none is passed to predict().
process_covariance (array or None) – The process noise covariance to use if none is passed to predict().
control_matrix – (array or None): The control matrix to use if none is passed to predict().
state_length (None or int) – Must only be specified if initial_state_estimate is None. In which case, this is used as the length of the state vector.

Raises:

ValueError – The passed matrices have inconsistent or invalid shapes.

prior_state_estimates¶

list of MultivariateNormal

Element k is the the a priori state estimate for time step k.

posterior_state_estimates¶

list of MultivariateNormal

Element k is the the a posteriori state estimate for time step k.

measurements¶

list of list of MultivariateNormal

Element k is a list of MultivariateNormal instances. These are the instances passed to update() for time step k.

process_matrices¶

list of array

Element k is the process matrix used by predict() at time step k.

process_covariances¶

list of array

Element k is the process covariance used by predict() at time step k.

measurement_matrices¶

list of list of array

Element k is a list of the measurement matrices passed to each call to update() for that time step.

state_length¶

int

Number of elements in the state vector.

clone()¶

Return a new KalmanFilter instance which is a shallow clone of this one. By “shallow”, although the lists of measurements, etc, are cloned, the MultivariateNormal instances within them are not. Since predict() and update() do not modify the elements of these lists, it is safe to run two cloned filters in parallel as long as one does not directly modify the states.

Returns:	(KalmanFilter) – A new `KalmanFilter` instance.

measurement_count¶: Property returning the total number of measurements which have been passed to this filter.

predict(control=None, control_matrix=None, process_matrix=None, process_covariance=None)¶

Predict the next a priori state mean and covariance given the last posterior. As a special case the first call to this method will initialise the posterior and prior estimates from the initial_state_estimate and initial_covariance arguments passed when this object was created. In this case the process_matrix and process_covariance arguments are unused but are still recorded in the process_matrices and process_covariances attributes.

Parameters:

control (array or None) – If specified, the control input for this predict step.
control_matrix (array or None) – If specified, the control matrix to use for this time step.
process_matrix (array or None) – If specified, the process matrix to use for this time step.
process_covariance (array or None) – If specified, the process covariance to use for this time step.

state_count¶: Property returning the number of states/time steps this filter has processed. Since the first time step is always 0, the final index will always be state_count - 1.

truncate(new_count)¶

Truncate the filter as if only new_count predict(), update() steps had been performed. If new_count is greater than state_count then this function is a no-op.

Measurements, state estimates, process matrices and process noises which are truncated are discarded.

Parameters:	new_count (int) – Number of states to retain.

update(measurement, measurement_matrix)¶

After each predict(), this method may be called repeatedly to provide additional measurements for each time step.

Parameters:	measurement (MultivariateNormal) – Measurement for this time step with specified mean and covariance. measurement_matrix (array) – Measurement matrix for this measurement.

starman.rts_smooth(kalman_filter, state_count=None)¶

Compute the Rauch-Tung-Striebel smoothed state estimates and estimate covariances for a Kalman filter.

Parameters:	kalman_filter (KalmanFilter) – Filter whose smoothed states should be returned state_count (int or None) – Number of smoothed states to return. If None, use `kalman_filter.state_count`.
Returns:	(list of MultivariateNormal) – List of multivariate normal distributions. The mean of the distribution is the estimated state and the covariance is the covariance of the estimate.

Feature association¶

starman.slh_associate(a_features, b_features, max_sigma=5)¶

An implementation of the Scott and Longuet-Higgins algorithm for feature association.

This function takes two lists of features. Each feature is a MultivariateNormal instance representing a feature location and its associated uncertainty.

Parameters:	a_features (list of MultivariateNormal) – b_features (list of MultivariateNormal) – max_sigma (float or int) – maximum number of standard deviations two features can be separated and still considered “associated”.
Returns:	(array) – A Nx2 array of feature associations. Column 0 is the index into the a_features list, column 1 is the index into the b_features list.

Representation of state estimates¶

class starman.MultivariateNormal(mean=None, cov=None)¶

MultivariateNormal represents a multivariate normal (or “Gaussian”) distribution parametrised in terms of a mean and covariance. The mean is a length-N vector and the covariance is a NxN matrix.

If mean is unspecified, it defaults to a zero-filled vector whose dimension matches the covariance.

If the covariance is unspecified, it defaults to an identity matrix whose shape matches the dimension of the mean.

If neither mean or covariance are specified, default values of 0 and 1 are used.

Parameters:	mean (None or array) – Distribution mean. cov (None or array) – Distribution covariance.

rvs(size=1)¶

Convenience method to sample from this distribution.

Parameters:	size (int or tuple) – Shape of return value. Each element is drawn independently from this distribution.

Helper functions for linear systems¶

The starman.linearsystem module contains some helper functions for systems with linear dynamics and a linear measurement model.

starman.linearsystem.generate_states(state_count, process_matrix, process_covariance, initial_state=None)¶

Generate states by simulating a linear system with constant process matrix and process noise covariance.

Parameters:	state_count (int) – Number of states to generate. process_matrix (array) – Square array process_covariance (array) – Square array specifying process noise covariance. initial_state (array or None) – If omitted, use zero-filled vector as initial state.

starman.linearsystem.measure_states(states, measurement_matrix, measurement_covariance)¶

Measure a list of states with a measurement matrix in the presence of measurement noise.

Parameters:	states (array) – states to measure. Shape is NxSTATE_DIM. measurement_matrix (array) – Each state in states is measured with this matrix. Should be MEAS_DIMxSTATE_DIM in shape. measurement_covariance (array) – Measurement noise covariance. Should be MEAS_DIMxMEAS_DIM.
Returns:	(array) – NxMEAS_DIM array of measurements.