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 (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_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.

  • 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)).

Methods Summary

calibrate(init_params, running_log_path, ...)

Find the optimal parameters for self.cost_function.

calibrate_with_perceived_factors(...[, ...])

Find the optimal parameters for self.cost_function.

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

Run the gravity model with set cost parameters.

run_with_perceived_factors(cost_params, ...)

Run the gravity model with set cost parameters.

Methods Documentation

calibrate(init_params, 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 (dict[str, Any]) – 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

See also

caf.distribute.furness.doubly_constrained_furness() scipy.optimize.least_squares()

calibrate_with_perceived_factors(init_params, running_log_path, target_cost_distribution, *args, failure_tol=0.5, **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 (dict[str, Any]) – 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 (CostDistribution) – 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 (float) – 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. Also used to determine whether perceived factors should be used, passed to cls._should_use_perceived_factors(). See docs for further info

  • 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

See also

caf.distribute.furness.doubly_constrained_furness() scipy.optimize.least_squares() cls._should_use_perceived_factors()

run(cost_params, running_log_path, target_cost_distribution=None, **kwargs)#

Run the gravity model with set cost parameters.

This function will run a single iteration of the gravity model using the given cost parameters.

Parameters:

  • cost_params (dict[str, Any]) – The cost parameters to use

  • 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 (CostDistribution | None) – If given, this is used to calculate the residuals in the return. The return cost_distribution will also use the same bins provided here.

  • 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 GravityModelRunResults containing the results of this run. If a target_cost_distribution is not given, the returning results.cost_distribution will dynamically create its own bins; cost_residuals and cost_convergence will also contain dummy values.

Return type:

results

See also

caf.distribute.furness.doubly_constrained_furness()

run_with_perceived_factors(cost_params, running_log_path, target_cost_distribution, target_cost_convergence=0.9, **kwargs)#

Run the gravity model with set cost parameters.

This function will run a single iteration of the gravity model using the given cost parameters. It is similar to the default run function but uses perceived factors to try to improve the performance of the run.

Perceived factors can be used to improve model performance. These factors slightly adjust the cost across bands to help nudge demand towards the expected distribution. These factors are only used when the performance is already reasonably good, otherwise they are ineffective. Only used when the achieved R^2 convergence meets the following criteria: lower_bound = target_cost_convergence - 0.15 upper_bound = target_cost_convergence + 0.03 lower_bound < achieved_convergence < upper_bound

Parameters:

  • cost_params (dict[str, Any]) – The cost parameters to use

  • 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_convergence (float) – A value between 0 and 1. Ignored unless use_perceived_factors is set. Used to define the bounds withing which perceived factors can be used to improve final distribution.

  • target_cost_distribution (CostDistribution) – If given,

  • 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 GravityModelRunResults containing the results of this run.

Return type:

results

See also

caf.distribute.furness.doubly_constrained_furness()