gravity_model

caf.distribute.gravity_model.single_area.gravity_model(row_targets, col_targets, cost_function, costs, furness_max_iters, furness_tol, **cost_params)

Run a gravity model and returns the distributed row/col targets.

Uses the given cost function to generate an initial matrix which is used in a double constrained furness to distribute the row and column targets across a matrix. The cost_params can be used to achieve different results based on the cost function.

Parameters:

• row_targets (ndarray) – The targets for the rows to sum to. These are usually Productions in Trip Ends.

• col_targets (ndarray) – The targets for the columns to sum to. These are usually Attractions in Trip Ends.

• cost_function (CostFunction) – A cost function class defining how to calculate the seed matrix based on the given cost. cost_params will be passed directly into this function.

• costs (ndarray) – A matrix of the base costs to use. This will be passed into cost_function alongside cost_params. Usually this will need to be the same shape as (len(row_targets), len(col_targets)).

• furness_max_iters (int) – The maximum number of iterations for the furness to complete before giving up and outputting what it has managed to achieve.

• furness_tol (float) – The R2 difference to try and achieve between the row/col targets and the generated matrix. The smaller the tolerance the closer to the targets the return matrix will be.

• cost_params – Any additional parameters that should be passed through to the cost function.

Returns:

• distributed_matrix – A matrix of the row/col targets distributed into a matrix of shape (len(row_targets), len(col_targets))

• completed_iters – The number of iterations completed by the doubly constrained furness before exiting

• achieved_rmse – The Root Mean Squared Error achieved by the doubly constrained furness before exiting

Raises:

TypeError: – If some of the cost_params are not valid cost parameters, or not all cost parameters have been given.