MultiAreaGravityModelCalibrator#

class caf.distribute.gravity_model.multi_area.MultiAreaGravityModelCalibrator(row_targets, col_targets, cost_matrix, cost_function)#

Bases: GravityModelBase

A self-calibrating multi-area gravity model.

Parameters:

  • row_targets (np.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 (np.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_matrix (np.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)).

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

Attributes Summary

achieved_band_share

Overload achieved_band _share for multiple bands.

Methods Summary

calibrate(distributions, running_log_path, ...)

Find the optimal parameters for self.cost_function.

run(distributions, running_log_path[, ...])

Run the gravity_model without calibrating.

Attributes Documentation

achieved_band_share#

Overload achieved_band _share for multiple bands.

Methods Documentation

calibrate(distributions, running_log_path, gm_params, verbose=0, **kwargs)#

Find the optimal parameters for self.cost_function.

Optimal parameters are found using scipy.optimize.least_squares to fit the distributed row/col targets to target_cost_distribution.

NOTE: The achieved distribution is found by accessing self.achieved distribution of the object this method is called on. The output of this method shows the distribution and results for each individual TLD.

Parameters:

  • distributions (MultiCostDistribution) – distributions to use for the calibrations

  • running_log_path (os.PathLike,) – path to a csv to log the model iterations and results

  • gm_params (GMCalibParams) – defines the detailed parameters, see GMCalibParams documentation for more info

  • *args

  • verbose (int)

Return type:

dict[str, GravityModelResults]

:param : :param **kwargs: :param :

Returns:

containings the achieved distributions for each tld category. To access the combined distribution use self.achieved_distribution

Return type:

dict[str, GravityModelResults]

Parameters:

See also

caf.distribute.furness.doubly_constrained_furness() scipy.optimize.least_squares() caf.distribute.gravity_model.multi_area.GMCalibParams

run(distributions, running_log_path, furness_tol=1e-06)#

Run the gravity_model without calibrating.

This should be done when you have calibrating previously to find the correct parameters for the cost function.

Parameters:

  • distributions (MultiCostDistribution) – Distributions to use to run the gravity model

  • running_log_path (Path) – Csv path to log results and info

  • furness_tol (float, optional) – tolerance for difference in target and achieved value, at which to stop furnessing, by default 1e-6

Returns:

The results of the gravity model run for each distribution

Return type:

dict[str, GravityModelResults]