Households API Reference

This section documents the Households agent in the macromodel package, which represents the household sector and models income, consumption, investment, property, credit, and wealth decisions.

macromodel.agents.households.households.Households

Economic agent representing household sector behavior.

This class implements household economic decisions through: - Income generation (employment, transfers, rental, financial) - Consumption allocation across industries - Investment in real and financial assets - Housing market participation (buying, renting) - Credit market interactions (mortgages, loans) - Wealth management and allocation

The implementation considers: - Household demographics and composition - Income sources and distribution - Consumption patterns and preferences - Investment strategies - Property ownership and rental decisions - Financial asset holdings - Debt levels and servicing

Attributes:

Name	Type	Description
functions	dict	Mapping of function names to implementations
independents	list	Independent variables for calculations
consumption_weights	ndarray	Industry-specific consumption shares
consumption_weights_by_income	ndarray	Income-based consumption patterns
investment_weights	ndarray	Industry-specific investment shares
use_consumption_weights_by_income	bool	Whether to use income-based weights

from_pickled_agent(synthetic_population: SyntheticPopulation, synthetic_country: SyntheticCountry, configuration: HouseholdsConfiguration, country_name: str, all_country_names: list[str], industries: list[str], initial_consumption_by_industry: np.ndarray, value_added_tax: float, scale: int, add_emissions: bool = False) -> Households classmethod

Create household agent from synthetic data.

Initializes household agent using: - Synthetic population demographics - Country-specific parameters - Initial consumption/investment patterns - Tax rates and scaling factors

Parameters:

Name	Type	Description	Default
synthetic_population	SyntheticPopulation	Synthetic household data	required
synthetic_country	SyntheticCountry	Country-specific parameters	required
configuration	HouseholdsConfiguration	Household behavior config	required
country_name	str	Name of the country	required
all_country_names	list[str]	List of all country names	required
industries	list[str]	List of industry names	required
initial_consumption_by_industry	ndarray	Initial consumption	required
value_added_tax	float	VAT rate	required
scale	int	Scaling factor for histograms	required
add_emissions	bool	Whether to track emissions	False

Returns:

Name	Type	Description
Households	Households	Initialized household agent

Functions

Consumption

macromodel.agents.households.func.consumption.HouseholdConsumption

Abstract base class for household consumption behavior.

Defines interface for computing target consumption levels based on: - Income and saving rates - Historical consumption patterns - Price level changes - Industry allocations - Tax considerations

Attributes:

Name	Type	Description
consumption_smoothing_fraction	float	Weight on historical consumption
consumption_smoothing_window	int	Periods for smoothing calculation
minimum_consumption_fraction	float	Floor on consumption/income ratio

Property Demand

macromodel.agents.households.func.property.HouseholdDemandForProperty

Abstract base class for household property demand behavior.

Defines interface for property market participation through: - Demand determination - Price/rent willingness - Market participation decisions - Property value adjustments

Attributes:

Name	Type	Description
probability_stay_in_rented_property	float	Probability of remaining in rental
probability_stay_in_owned_property	float	Probability of keeping ownership
maximum_price_income_coefficient	float	Price/income ratio coefficient
maximum_price_income_exponent	float	Price/income ratio exponent
maximum_price_noise_mean	float	Price noise distribution mean
maximum_price_noise_variance	float	Price noise distribution variance
maximum_rent_income_coefficient	float	Rent/income ratio coefficient
maximum_rent_income_exponent	float	Rent/income ratio exponent
psychological_pressure_of_renting	float	Renting preference factor
cost_comparison_temperature	float	Decision sensitivity parameter
price_initial_markup	float	Initial price markup factor
price_decrease_probability	float	Price reduction probability
price_decrease_mean	float	Price reduction mean
price_decrease_variance	float	Price reduction variance
rent_initial_markup	float	Initial rent markup factor
rent_decrease_probability	float	Rent reduction probability
rent_decrease_mean	float	Rent reduction mean
rent_decrease_variance	float	Rent reduction variance
partial_rent_inflation_indexation	float	Inflation pass-through
partial_rent_inflation_delay	int	Inflation adjustment lag

Rent Setting

macromodel.agents.households.func.rent.RentSetter

Abstract base class for rental price management.

Defines interface for determining rental prices through: - Current rent updates - New property pricing - Existing property adjustments - Inflation consideration

Attributes:

Name	Type	Description
partial_rent_inflation_indexation	float	Inflation pass-through rate
new_property_rent_markup	float	Initial rent markup
offered_rent_decrease	float	Rent reduction rate

Wealth Management

macromodel.agents.households.func.wealth.WealthSetter

Abstract base class for household wealth management.

Defines interface for managing wealth through: - Wealth allocation decisions - Asset value tracking - Financial holdings - Deposit management

Attributes:

Name	Type	Description
other_real_assets_depreciation_rate	float	Asset depreciation rate
independents	list[str]	Independent variables for wealth decisions

Financial Assets

macromodel.agents.households.func.financial_assets.FinancialAssets

Abstract base class for household financial asset management.

Defines interface for managing financial asset returns through: - Income expectation calculation - Actual income realization - Return coefficient application - Stochastic adjustments

Attributes:

Name	Type	Description
income_from_fa_noise_std	float	Standard deviation for return noise

Credit Demand

macromodel.agents.households.func.target_credit.HouseholdTargetCredit

Abstract base class for household credit demand behavior.

Defines interface for determining credit needs based on: - Consumption financing - Property purchases - Asset holdings - Income flows

Attributes:

Name	Type	Description
down_payment_fraction	float	Required down payment ratio