py_wlc.economics package

Submodules

py_wlc.economics.cost module

Representation of cost objects in various bases and forms.

class py_wlc.economics.cost.Cost(value, type_, year, discount, deflator, adjustment_factor)

Bases: object

Represents costs and holds data for type conversions.

The type_ of a cost is necessary for conversion between the different types; costs can be provide in real or nominal terms and as a factor (or “resource”) cost or a market price. Additionally, a cost can be a Present Value (discounted real factor cost or market price).

It is essential for an accurate calculation that the appropriate cost type is used for conversion to consistent output values.

Note

The default assumptions for type_ are NOMINAL and FACTOR_COST. For example:

Cost(100, Cost.REAL, ...)

is equivalent to:

Cost(100, Cost.REAL | Cost.FACTOR_COST, ...)

The exception is PRESENT_VALUE, which is always a real cost.

Parameters:

• value (float) – The value of the cost.
• type (int) – The type of the cost.
• year (int) – The year in which the cost is incurred.
• discount (Discount) – The discount factors to use for conversion to Present Value.
• deflator (GdpDeflator) – The GDP deflator factors to use for conversion to real prices.
• adjustment_factor (float) – The factor to use for conversion to market prices.

cost

float

The nominal factor cost.

year

int

The year in which the cost is incurred.

discount_factor

float

The factor for conversion to Present Value (from real factor costs or market prices).

deflation_factor

float

The factor for conversion to real prices (from nominal prices).

adjustment_factor

float

The factor for conversion to market prices (from factor costs).

Raises:ValueError – If the type_ argument is invalid.

FACTOR_COST = 1

Factor cost, excluding taxation.

MARKET_PRICE = 2

Market price, including taxation.

NOMINAL = 4

Nominal price, as paid in the year incurred.

PRESENT_VALUE = 16

Discounted real costs.

REAL = 8

Real price, in a constant price base year.

RESOURCE_COST = 1

Synonym of FACTOR_COST.

as_type(type_)

Convert the nominal factor cost to the specified type_.

Parameters:type (int) – The type to convert to. Returns:The converted value. Return type:float

classmethod validate_type(type_)

Validate a cost type argument.

Costs cannot be both market price and factor/resource cost, or both nominal and real. Present values are necessarily discounted real factor costs or market prices.

Parameters:type (int) – The type of the cost. Raises:ValueError – If the type_ is invalid.

py_wlc.economics.discount module

discount enables the calculation of Present Value.

class py_wlc.economics.discount.Discount(base_year, rates=None, year_zero=None)

Bases: py_wlc.generic.growth.IndexSeries

Discount rates and factors for calculating Present Value.

The discount rate is assumed to be zero prior to year_zero, and remain at the rate corresponding to the last year in self.rates indefinitely. Similarly, the factor is assumed to be 1.0 prior to the base year.

The initial rate, i.e. the rate corresponding to the smallest year in the rates dictionary, is assumed to be the rate from the base_year onwards.

Parameters:

• base_year (int) – The base year for discounting, i.e. the year in which the factor is 1.0.
• rates (dict of int: float, optional) – The discount rates, where the key is the start year and the value is the rate to apply. Defaults to HM Treasury Green Book rates.
• year_zero (int, optional) – Year zero, the year from which the applicable rate is incremented. Defaults to base_year.

RATES = {0: 0.035, 201: 0.015, 76: 0.025, 301: 0.01, 126: 0.02, 31: 0.03}

Default HM Treasury “Green Book” discount rates.

rate(year)

The rate used in the specified year.

Parameters:year (int) – The year to retrieve the rate for. Returns:The rate used in that year. Return type:float

rebase(year_zero)

Create a Discount with new year_zero.

Parameters:year_zero (int) – The new year_zero to use. Returns:class:~.Discount: The new Discount object. Return type::py

py_wlc.economics.gdp_deflator module

Provides conversion between nominal and real prices.

class py_wlc.economics.gdp_deflator.GdpDeflator(base_year, rates, extend=False)

Bases: py_wlc.generic.growth.IndexSeries

If extension beyond the specified _rates is required, the rates argument is replaced with an ExtendedDict, such that the first and last rates are continued indefinitely. Otherwise, there is no growth outside the predefined data-set (i.e. assumed rate of 0.0).

Parameters:

• base_year (int) – The price base year to deflate to.
• rates (dict of int: str) – The annual rates.
• extend (bool, optional) – Whether or not to extend the rates beyond the predefined data. Defaults to False.

conversion_factor(year_from, year_to=None)

Calculate the factor to convert costs between two years.

Parameters:

• year_from (int) – The year to convert from.
• year_to (int, optional) – The year to convert to. Defaults to base_year.

Returns:

The conversion factor between the two years.

Return type:

float

py_wlc.economics.residual_value module

Calculation methods for residual value of assets.

class py_wlc.economics.residual_value.ResidualValueCalculator(method)

Bases: object

A calculator to generate residual values of assets.

Parameters:method (str) – The method to use for the calculation (must be in METHODS, see Wikipedia for method details). Raises:ValueError – If method is not in METHODS.

METHODS = {"sum of years' digits": 'sum_of_years', 'linear': 'linear', 'double-declining': 'double_declining'}

Available methods for calculation of residual value.

classmethod available_methods()

Show the methods available in METHODS.

Returns:The available methods. Return type:list of str

calculate(value, life, build_year, target_year, scrap_value=0.0)

Calculate residual value, using selected method.

Residual value is assumed to be the scrap_value after the life expires (build_year + life). The residual value is never allowed to fall below the scrap_value.

Parameters:

• value (float) – The initial asset value.
• life (int) – The life of the asset, in years.
• build_year (int) – The year in which the asset is built.
• target_year (int) – The year in which to calculate the asset’s residual value.
• scrap_value (float, optional) – The asset’s value after life expiry. Defaults to 0.0.

Returns:

The calculated residual value.

Return type:

float

Raises:

ValueError – If target_year precedes the build_year.

static double_declining(value, life, build_year, target_year, scrap_value)

Calculate residual value with double-declining method.

The double-declining method, a specific declining balance method, assumes that the same proportion of the remaining value is lost in each year of the asset’s life. In this case, the proportion is double the proportion lost in each year under the linear() method.

Parameters:

• value (float) – The initial asset value.
• life (int) – The life of the asset, in years.
• build_year (int) – The year in which the asset is built.
• target_year (int) – The year in which to calculate the asset’s residual value.
• scrap_value (float) – The asset’s value after life expiry.

Returns:

The calculated residual value.

Return type:

float

static linear(value, life, build_year, target_year, scrap_value)

Calculate residual value with linear (straight-line) method.

The linear (or straight-line depreciation) method assumes that the same amount of the asset’s value is lost in every year of its life.

Parameters:

• value (float) – The initial asset value.
• life (int) – The life of the asset, in years.
• build_year (int) – The year in which the asset is built.
• target_year (int) – The year in which to calculate the asset’s residual value.
• scrap_value (float) – The asset’s value after life expiry.

Returns:

The calculated residual value.

Return type:

float

method

The current method for residual value calculations.

Returns:The name of the current method (read-only). Return type:str

static sum_of_years(value, life, build_year, target_year, scrap_value)

Calculate residual value with sum of years’ digits method.

The sum of years’ digits method uses a “schedule of fractions” to depreciate the value, based on summing the digits of all years in the life for the denominator.

Parameters:

• value (float) – The initial asset value.
• life (int) – The life of the asset, in years.
• build_year (int) – The year in which the asset is built.
• target_year (int) – The year in which to calculate the asset’s residual value.
• scrap_value (float) – The asset’s value after life expiry.

Returns:

The calculated residual value.

Return type:

float

py_wlc.economics.residual_value.sum_of_years_digits(year)

Calculate the sum of years’ digits.

Parameters:year (int) – The year to calculate up to. Returns:The sum of years’ digits. Return type:int

Module contents

The economics module provides core economic models.