MultiAreaGravityModelCalibrator#

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

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.
params (Optional[MultiDistInput]) – Info needed for a multi-distribution gravity model. See documentation for MultiDistInput.

Attributes Summary

achieved_band_share

Overload achieved_band _share for multiple bands.

Methods Summary

`calibrate`(running_log_path, args, *kwargs)	Find the optimal parameters for self.cost_function.
`process_tlds`()	Get distributions in the right format for a multi-area gravity model.
`run`()	Run the gravity_model without calibrating.

Attributes Documentation

achieved_band_share#: Overload achieved_band _share for multiple bands.

Methods Documentation

calibrate(running_log_path, *args, **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.

Parameters:

init_params – A dictionary of {parameter_name: parameter_value} to pass into the cost function as initial parameters.
running_log_path (PathLike) – Path to output the running log to. This log will detail the performance of the run and is written in .csv format.
target_cost_distribution – The cost distribution to calibrate towards during the calibration process.
diff_step – Copied from scipy.optimize.least_squares documentation, where it is passed to: Determines the relative step size for the finite difference approximation of the Jacobian. The actual step is computed as x * diff_step. If None (default), then diff_step is taken to be a conventional “optimal” power of machine epsilon for the finite difference scheme used
ftol – The tolerance to pass to scipy.optimize.least_squares. The search will stop once this tolerance has been met. This is the tolerance for termination by the change of the cost function
xtol – The tolerance to pass to scipy.optimize.least_squares. The search will stop once this tolerance has been met. This is the tolerance for termination by the change of the independent variables.
grav_max_iters – The maximum number of calibration iterations to complete before termination if the ftol has not been met.
failure_tol – If, after initial calibration using init_params, the achieved convergence is less than this value, calibration will be run again with the default parameters from self.cost_function.
default_retry – If, after running with init_params, the achieved convergence is less than failure_tol, calibration will be run again with the default parameters of self.cost_function. This argument is ignored if the default parameters are given as `init_params.
n_random_tries – If, after running with default parameters of self.cost_function, the achieved convergence is less than failure_tol, calibration will be run again using random values for the cost parameters this number of times.
verbose – Copied from scipy.optimize.least_squares documentation, where it is passed to: Level of algorithm’s verbosity: - 0 (default) : work silently. - 1 : display a termination report. - 2 : display progress during iterations (not supported by ‘lm’ method).
kwargs – Additional arguments passed to self.gravity_furness. Empty by default. The calling signature is: self.gravity_furness(seed_matrix, **kwargs)

Returns:

An instance of GravityModelCalibrateResults containing the results of this run.

Return type:

results