SingleAreaGravityModelCalibrator#

class caf.distribute.gravity_model.single_area.SingleAreaGravityModelCalibrator(row_targets, col_targets, cost_function, cost_matrix)#

Bases: GravityModelBase

A self-calibrating single area gravity model.

Parameters:

  • row_targets (ndarray) – The targets for each row that the gravity model should be aiming to match. This can alternatively be thought of as the rows that wish to be distributed.

  • col_targets (ndarray) – The targets for each column that the gravity model should be aiming to match. This can alternatively be thought of as the columns that wish to be distributed.

  • cost_function (CostFunction) – The cost function to use when calibrating the gravity model. This function is applied to cost_matrix before Furnessing during calibration.

  • cost_matrix (ndarray) – A matrix detailing the cost between each and every zone. This matrix must be the same size as (len(row_targets), len(col_targets)).

Methods Summary

estimate_optimal_cost_params(init_params, ...)

Guesses what the initial params should be.

gravity_furness(seed_matrix, **kwargs)

Run a doubly constrained furness on the seed matrix.

jacobian_furness(seed_matrix, row_targets, ...)

Run a doubly constrained furness on the seed matrix.

Methods Documentation

estimate_optimal_cost_params(init_params, target_cost_distribution)#

Guesses what the initial params should be.

Uses the average cost in each band to estimate what changes in the cost_params would do to the final cost distributions. This is a very coarse-grained estimation, but can be used to guess around about where the best init params are.

Parameters:

  • init_params (dict[str, Any]) –

  • target_cost_distribution (CostDistribution) –

Return type:

dict[str, Any]

gravity_furness(seed_matrix, **kwargs)#

Run a doubly constrained furness on the seed matrix.

Wrapper around furness.doubly_constrained_furness, using class attributes to set up the function call.

Parameters:

  • seed_matrix (ndarray) – Initial values for the furness.

  • kwargs – Additional arguments from the caller to pass to self.doubly_constrained_furness.

Returns:

  • furnessed_matrix – The final furnessed matrix

  • completed_iters – The number of completed iterations before exiting

  • achieved_rmse – The Root Mean Squared Error difference achieved before exiting

Return type:

tuple[ndarray, int, float]

jacobian_furness(seed_matrix, row_targets, col_targets)#

Run a doubly constrained furness on the seed matrix.

Wrapper around furness.doubly_constrained_furness, to be used when running the furness withing the jacobian calculation.

Parameters:

  • seed_matrix (ndarray) – Initial values for the furness.

  • row_targets (ndarray) – The target values for the sum of each row. i.e. np.sum(seed_matrix, axis=1)

  • col_targets (ndarray) – The target values for the sum of each column i.e. np.sum(seed_matrix, axis=0)

Returns:

  • furnessed_matrix – The final furnessed matrix

  • completed_iters – The number of completed iterations before exiting

  • achieved_rmse – The Root Mean Squared Error difference achieved before exiting

Return type:

tuple[ndarray, int, float]