gcubed.model_parameters.capital_stock_returns

Shared arithmetic for capital stocks and rates of return.

LOW_RAW_VKB_TO_GDP_WARNING_BOUND: float = 2.0

Raw productive-capital-to-GDP ratios below this value are reported.

MAX_PLAUSIBLE_INVESTMENT_TO_CAPITAL_RATIO: float = 0.2

Upper inclusive bound for an investment-to-capital diagnostic.

CAPITAL_RETURN_PARAMETER_NAMES: tuple[str, str, str] = ('base_rate_of_return_on_capital', 'base_rate_of_return_on_capital_y', 'base_rate_of_return_on_capital_z')

The complete family of runtime-derived capital-return parameters.

ProductiveCapitalReturnSource = typing.Literal['VKB/IO', 'database/IO']

Supported provenance labels for standard-sector and Y returns.

HouseholdCapitalReturnSource = typing.Literal['WID/IO', 'database/IO']

Supported provenance labels for household-capital returns.

@dataclass(frozen=True)

class InvestmentToCapitalClassification:

Diagnostic classification for one investment-to-capital ratio.

Attributes

status: ok, warning, or error.

reason: Stable machine-readable reason for the classification.

InvestmentToCapitalClassification(status: str, reason: str)

status: str

reason: str

@dataclass(frozen=True)

class CapitalReturnCalibration:

Runtime-derived capital returns and their cell-level source audit.

CapitalReturnCalibration(parameters: pandas.DataFrame, diagnostics: pandas.DataFrame)

parameters: pandas.DataFrame

diagnostics: pandas.DataFrame

def productive_rate_of_return( *, capital_services: pandas.Series | numpy.ndarray, productive_capital_stock: float, final_io_nominal_gdp: float, region: str) -> float:

Calculate the common standard-sector and Y return from raw mapped VKB.

The raw productive capital benchmark is never clipped. A low benchmark to final-IO-GDP ratio is reported without changing the calculation.

Arguments

capital_services: Nonnegative services for all standard sectors and Y.

productive_capital_stock: Positive raw mapped regional VKB benchmark.

final_io_nominal_gdp: Positive reconciled final-IO nominal GDP.

region: Region label included in any low-ratio warning.

Returns

The common regional rate of return as a decimal.

Exceptions

Raises ValueError for non-finite, negative, or non-positive aggregate inputs.

def household_rate_of_return( *, capital_services: float, final_io_nominal_gdp: float, household_capital_to_gdp_multiplier: float) -> float:

Calculate the Z return implied by an explicit stock-to-GDP ratio.

Arguments

capital_services: Positive household capital services.

final_io_nominal_gdp: Positive reconciled final-IO nominal GDP.

household_capital_to_gdp_multiplier: Household-stock GDP multiple.

Returns

The regional household rate of return as a decimal.

Exceptions

Raises ValueError if any input is non-positive or non-finite.

Calculate a nominal capital stock from services and a positive return.

Arguments

capital_services: Nonnegative finite services, with labels preserved.

rate_of_return: Positive finite decimal rate.

Returns

Capital services divided by the rate, preserving the input container.

Convert nominal capital stock into database percent-of-GDP units.

Arguments

nominal_capital_stock: Nonnegative finite nominal capital stock.

final_io_nominal_gdp: Positive reconciled final-IO nominal GDP.

Returns

Capital stock in the database's percent-of-GDP convention.

def recover_rate_of_return( *, capital_services: float, final_io_nominal_gdp: float, capital_stock_percent_of_gdp: float) -> float:

Recover one return from IO services and a database capital stock.

Arguments

capital_services: Positive base-year IO capital services.

final_io_nominal_gdp: Positive base-year LGDPN value.

capital_stock_percent_of_gdp: Positive base-year CAP* value.

Returns

The matching sector-specific decimal rate of return.

def capital_return_parameter_labels(standard_sectors: Sequence[str]) -> list[str]:

Return complete capital-return row labels in user-parameter order.

Arguments

standard_sectors: Ordered, unique standard-sector members.

Returns

Standard-sector labels followed by unparenthesized Y and Z labels.

def capital_return_provenance_report( parameters: pandas.DataFrame, *, standard_sectors: Sequence[str], regions: Sequence[str], productive_source: Literal['VKB/IO', 'database/IO'], household_source: Literal['WID/IO', 'database/IO']) -> pandas.DataFrame:

Build a row-level audit of capital-return values and their sources.

Overview

Uses one stable vocabulary across source-stock construction and database/IO parameter recovery. Standard sectors and Y share the productive source; Z has its independent household source.

Arguments

parameters: Complete labelled capital-return parameter family.
standard_sectors: Ordered standard-sector members.
regions: Ordered model regions.
productive_source: VKB/IO or database/IO.
household_source: WID/IO or database/IO.

Returns

One record per parameter and region, retaining parameter and region order.

Exceptions

Raises ValueError for an invalid source label or parameter family.

def validate_capital_return_parameters( parameters: pandas.DataFrame, *, standard_sectors: Sequence[str], regions: Sequence[str]) -> None:

Validate labels, ordering, shape, and values of a return family.

Arguments

parameters: Complete combined user-parameter dataframe.

standard_sectors: Expected ordered standard-sector members.

regions: Expected ordered region columns.

Exceptions

Raises ValueError for duplicate, missing, reordered, non-finite, or non-positive content.

def calibrate_capital_return_parameters( *, io_tables: Mapping[str, pandas.DataFrame], database: pandas.DataFrame, base_year: int, standard_sectors: Sequence[str], regions: Sequence[str], parameter_calibration_year: int | None = None) -> CapitalReturnCalibration:

Derive the complete family from base-year IO services and stocks.

Arguments

io_tables: Region-keyed final base-year IO tables.

database: Database indexed by full variable name.

base_year: Model base year shared by the two sources.

standard_sectors: Expected ordered standard-sector members.

regions: Expected ordered model regions.

Returns

The complete validated runtime parameter table and cell-level diagnostic.

Exceptions

Raises ValueError for missing, duplicate, malformed, non-finite, or non-positive source data.

def recover_capital_return_parameters( *, io_tables: Mapping[str, pandas.DataFrame], database: pandas.DataFrame, base_year: int, standard_sectors: Sequence[str], regions: Sequence[str]) -> pandas.DataFrame:

Return the validated runtime capital-return parameter table.

def classify_investment_to_capital_ratio( ratio: float) -> InvestmentToCapitalClassification:

Classify a ratio without changing either investment or capital.

Arguments

ratio: Annual gross or installed investment divided by capital.

Returns

A classification warning below zero or strictly above 20 percent.