CostDistribution

class cost_utils.CostDistribution(df, min_col='min', max_col='max', avg_col='ave', trips_col='trips', units='km')

Bases: object

Distribution of cost values between variable bounds.

Parameters:

• df (DataFrame) –

• min_col (str) –

• max_col (str) –

• avg_col (str) –

• trips_col (str) –

• units (str) –

df

The raw Pandas DataFrame containing the cost distribution data.

Type:

pandas.core.frame.DataFrame

min_vals

Minimum values of the cost distribution bin edges.

max_vals

Maximum values of the cost distribution bin edges.

bin_edges

Bin edges for the cost distribution.

avg_vals

Average values for each of the cost distribution bins.

trip_vals

Trip values for each of the cost distribution bins.

band_share_vals

Band share values for each of the cost distribution bins.

Attributes Summary

avg_col
avg_vals	Average values for each of the cost distribution bins.
band_share_vals	Band share values for each of the cost distribution bins.
bin_edges	Bin edges for the cost distribution.
max_col
max_vals	Maximum values of the cost distribution in edges.
min_col
min_vals	Minimum values of the cost distribution bin edges.
n_bins	Bin edges for the cost distribution.
trip_vals	Trip values for each of the cost distribution bins.
trips_col
units

Methods Summary

band_share_convergence(other)	Calculate the convergence between this and other.
band_share_residuals(other)	Calculate the band share residuals between this and other.
check_df_col_names()	Check the given columns are in the given dataframe.
copy()	Create a copy of this instance.
create_similar(trip_vals)	Create a similar cost distribution with different trip values.
from_data(matrix, cost_matrix[, min_bounds, ...])	Convert values and a cost matrix into a CostDistribution.
from_data_no_bins(matrix, cost_matrix, ...)	Convert values and a cost matrix into a CostDistribution.
from_file(filepath[, min_col, max_col, ...])	Build an instance from a file on disk.
trip_residuals(other)	Calculate the trip residuals between this and other.

Attributes Documentation

avg_col: str = 'ave'

avg_vals

Average values for each of the cost distribution bins.

band_share_vals

Band share values for each of the cost distribution bins.

bin_edges

Bin edges for the cost distribution.

max_col: str = 'max'

max_vals

Maximum values of the cost distribution in edges.

min_col: str = 'min'

min_vals

Minimum values of the cost distribution bin edges.

n_bins

Bin edges for the cost distribution.

trip_vals

Trip values for each of the cost distribution bins.

trips_col: str = 'trips'

units: str = 'km'

Methods Documentation

band_share_convergence(other)

Calculate the convergence between this and other.

Residuals are calculated as: math_utils.curve_convergence(self.band_share_vals, other.band_share_vals)

Parameters:

other (CostDistribution) – Another instance of CostDistribution using the same bins.

Returns:

A float value between 0 and 1. Values closer to 1 indicate a better convergence.

Return type:

convergence

See also

None

band_share_residuals(other)

Calculate the band share residuals between this and other.

Residuals are calculated as: self.band_share_vals - other.band_share_vals

Parameters:

other (CostDistribution) – Another instance of CostDistribution using the same bins.

Returns:

The residual difference between this and other.

Return type:

residuals

check_df_col_names()

Check the given columns are in the given dataframe.

Return type:

CostDistribution

copy()

Create a copy of this instance.

Return type:

CostDistribution

create_similar(trip_vals)

Create a similar cost distribution with different trip values.

Parameters:

trip_vals (ndarray) – A numpy array of trip values that will replace the current trip values.

Returns:

A copy of this instance, with different trip values.

Return type:

cost_distribution

classmethod from_data(matrix, cost_matrix, min_bounds=None, max_bounds=None, bin_edges=None)

Convert values and a cost matrix into a CostDistribution.

Parameters:

• matrix (ndarray) – The matrix to calculate the cost distribution for. This matrix should be the same shape as cost_matrix

• cost_matrix (ndarray) – A matrix of cost relating to matrix. This matrix should be the same shape as matrix

• min_bounds (list[float] | ndarray | None) – A list of minimum bounds for each edge of a distribution band. Corresponds to max_bounds.

• max_bounds (list[float] | ndarray | None) – A list of maximum bounds for each edge of a distribution band. Corresponds to min_bounds.

• bin_edges (list[float] | ndarray | None) – Defines a monotonically increasing array of bin edges, including the rightmost edge, allowing for non-uniform bin widths. This argument is passed straight into numpy.histogram

Returns:

An instance of CostDistribution containing the given data.

Return type:

cost_distribution

See also

None

static from_data_no_bins(matrix, cost_matrix, *args, **kwargs)

Convert values and a cost matrix into a CostDistribution.

create_log_bins will be used to generate some bin edges.

Parameters:

• matrix (ndarray) – The matrix to calculate the cost distribution for. This matrix should be the same shape as cost_matrix

• cost_matrix (ndarray) – A matrix of cost relating to matrix. This matrix should be the same shape as matrix

• *args – arguments to pass through to create_log_bins

• **kwargs – arguments to pass through to create_log_bins

Returns:

An instance of CostDistribution containing the given data.

Return type:

cost_distribution

See also

None

static from_file(filepath, min_col='min', max_col='max', avg_col='ave', trips_col='trips')

Build an instance from a file on disk.

Parameters:

• filepath (PathLike) – Path to the file to read in.

• min_col (str) – The column of data at filepath that contains the minimum cost value of each band.

• max_col (str) – The column of data at filepath that contains the maximum cost value of each band.

• avg_col (str) – The column of data at filepath that contains the average cost value of each band.

• trips_col (str) – The column of data at filepath that contains the number of trips of each cost band.

Returns:

An instance containing the data at filepath.

Return type:

cost_distribution

trip_residuals(other)

Calculate the trip residuals between this and other.

Residuals are calculated as: self.trip_vals - other.trip_vals

Parameters:

other (CostDistribution) – Another instance of CostDistribution using the same bins.

Returns:

The residual difference between this and other.

Return type:

residuals