GravityModelResults

class caf.distribute.gravity_model.core.GravityModelResults(cost_distribution, target_cost_distribution, cost_convergence, value_distribution, cost_function, cost_params)

Bases: object

A collection of results from the Gravity Model.

Attributes Summary

cost_convergence	The achieved cost convergence value of the run.
cost_distribution	The achieved cost distribution of the results.
cost_function	The cost function used in the gravity model run.
cost_params	The final/used cost parameters used by the cost function.
summary	Summary of the GM calibration parameters as a series.
target_cost_distribution	The target cost distribution used to obtain the results.
value_distribution	The achieved distribution of the given values (usually trip values between different places).

Methods Summary

plot_distributions([truncate_last_bin])

Plot a comparison of the achieved and target distributions.

Attributes Documentation

Parameters:

• cost_distribution (CostDistribution)

• target_cost_distribution (CostDistribution)

• cost_convergence (float)

• value_distribution (ndarray)

• cost_function (CostFunction)

• cost_params (dict[str, Any])

cost_convergence: float = <dataclasses._MISSING_TYPE object>

The achieved cost convergence value of the run. If target_cost_distribution is not set, then this should be 0. This will be the same as calculating the convergence of cost_distribution and target_cost_distribution.

cost_distribution: CostDistribution = <dataclasses._MISSING_TYPE object>

The achieved cost distribution of the results.

cost_function: CostFunction = <dataclasses._MISSING_TYPE object>

The cost function used in the gravity model run.

cost_params: dict[str, Any] = <dataclasses._MISSING_TYPE object>

The final/used cost parameters used by the cost function.

summary

Summary of the GM calibration parameters as a series.

Outputs the gravity model achieved parameters and the convergence.

Returns:

a summary of the calibration

Return type:

pd.DataFrame

target_cost_distribution: CostDistribution = <dataclasses._MISSING_TYPE object>

The target cost distribution used to obtain the results.

value_distribution: ndarray = <dataclasses._MISSING_TYPE object>

The achieved distribution of the given values (usually trip values between different places).

Methods Documentation

plot_distributions(truncate_last_bin=False)

Plot a comparison of the achieved and target distributions.

This method returns a matplotlib figure which can be saved or plotted as the user decides.

Parameters:

truncate_last_bin (bool, optional) – whether to truncate the graph to 1.2x the lower bin edge, by default False

Returns:

the plotted distributions

Return type:

figure.Figure

Raises:

ValueError – when the target and achieved distributions have different binning