Merge pull request #1496 from alanlujan91/distribution/updates

Reorganize HARK.distributions

Documentation/CHANGELOG.md

@@ -14,11 +14,12 @@ Release Date: TBD
 
 ### Major Changes
 
-- Adds a discretize method to DBlocks and RBlocks (#1460)[https://github.com/econ-ark/HARK/pull/1460]
+- Adds a discretize method to DBlocks and RBlocks [#1460](https://github.com/econ-ark/HARK/pull/1460)
 - Allows structural equations in model files to be provided in string form [#1427](https://github.com/econ-ark/HARK/pull/1427)
 - Introduces `HARK.parser' module for parsing configuration files into models [#1427](https://github.com/econ-ark/HARK/pull/1427)
 - Allows construction of shocks with arguments based on mathematical expressions [#1464](https://github.com/econ-ark/HARK/pull/1464)
 - YAML configuration file for the normalized consumption and portolio choice [#1465](https://github.com/econ-ark/HARK/pull/1465)
+- Reorganizes the `HARK.distribution` file into `HARK.distributions` submodule with various files for readability and extensibility [#1496](https://github.com/econ-ark/HARK/pull/1496)
 
 #### Minor Changes
 
@@ -66,7 +67,6 @@ This release drops support for Python 3.8 and 3.9, consistent with SPEC 0, and a
 
 #### Minor Changes
 
-
 - Add option to pass pre-built grid to `LinearFast`. [1388](https://github.com/econ-ark/HARK/pull/1388)
 - Moves calculation of stable points out of ConsIndShock solver, into method called by post_solve [#1349](https://github.com/econ-ark/HARK/pull/1349)
 - Adds cubic spline interpolation and value function construction to "warm glow bequest" models.
@@ -77,8 +77,7 @@ This release drops support for Python 3.8 and 3.9, consistent with SPEC 0, and a
 - Create functions for well-known and repeated calculations in single-function solvers. [1395](https://github.com/econ-ark/HARK/pull/1395)
 - Re-work WealthPortfolioSolver to use approximate EGM method [#1404](https://github.com/econ-ark/HARK/pull/1404)
 - Default parameter dictionaries for AgentType subclasses have been "flattened": all parameters appear in one place for each model, rather than inheriting from parent models' dictionaries. The only exception is submodels *within* a file when only 1 or 2 parameters are added or changed. [#1425](https://github.com/econ-ark/HARK/pull/1425)
-- Fix minor bug in `HARK.distribution.Bernoulli` to allow conversion into `DiscreteDistributionLabeled`. [#1432](https://github.com/econ-ark/HARK/pull/1432)
-
+- Fix minor bug in `HARK.distributions.Bernoulli` to allow conversion into `DiscreteDistributionLabeled`. [#1432](https://github.com/econ-ark/HARK/pull/1432)
 
 ### 0.14.1
 
@@ -124,7 +123,7 @@ Release Date: February 16, 2023
 - Changes the `DiscreteDistribution` class to allow for arbitrary array-valued random variables. [#1146](https://github.com/econ-ark/HARK/pull/1146)
 - Adds `IndShockRiskyAssetConsumerType` as agent which can invest savings all in safe asset, all in risky asset, a fixed share in risky asset, or optimize its portfolio. [#1107](https://github.com/econ-ark/HARK/issues/1107)
 - Updates all HARK models to allow for age-varying interest rates. [#1150](https://github.com/econ-ark/HARK/pull/1150)
-- Adds `DiscreteDistribution.expected` method which expects vectorized functions and is faster than `HARK.distribution.calc_expectation`. [#1156](https://github.com/econ-ark/HARK/pull/1156)
+- Adds `DiscreteDistribution.expected` method which expects vectorized functions and is faster than `HARK.distributions.calc_expectation`. [#1156](https://github.com/econ-ark/HARK/pull/1156)
 - Adds `DiscreteDistributionXRA` class which extends `DiscreteDistribution` to allow for underlying data to be stored in a `xarray.DataArray` object. [#1156](https://github.com/econ-ark/HARK/pull/1156)
 - Adds keyword argument `labels` to `expected()` when using `DiscreteDistributionXRA` to allow for expressive functions that use labeled xarrays. [#1156](https://github.com/econ-ark/HARK/pull/1156)
 - Adds a wrapper for [`interpolation.py`](https://github.com/EconForge/interpolation.py) for fast multilinear interpolation. [#1151](https://github.com/econ-ark/HARK/pull/1151)
@@ -137,7 +136,7 @@ Release Date: February 16, 2023
 - Updates the `numpy` random generator from `RandomState` to `Generator`. [#1193](https://github.com/econ-ark/HARK/pull/1193)
 - Turns the income and income+return distributions into `DiscreteDistributionLabeled` objects. [#1189](https://github.com/econ-ark/HARK/pull/1189)
 - Creates `UtilityFuncCRRA` which is an object oriented utility function with a coefficient of constant relative risk aversion and includes derivatives and inverses. Also creates `UtilityFuncCobbDouglas`, `UtilityFuncCobbDouglasCRRA`, and `UtilityFuncConstElastSubs`. [#1168](https://github.com/econ-ark/HARK/pull/1168)
-- Reorganizes `HARK.distribution`. All distributions now inherit all features from `scipy.stats`. New `ContinuousFrozenDistribution` and `DiscreteFrozenDistribution` to use `scipy.stats` distributions not yet implemented in HARK. New `Distribution.discretize(N, method = "***")` replaces `Distribution.approx(N)`. New `DiscreteDistribution.limit` attribute describes continuous origin and discretization method. [#1197](https://github.com/econ-ark/HARK/pull/1197).
+- Reorganizes `HARK.distributions`. All distributions now inherit all features from `scipy.stats`. New `ContinuousFrozenDistribution` and `DiscreteFrozenDistribution` to use `scipy.stats` distributions not yet implemented in HARK. New `Distribution.discretize(N, method = "***")` replaces `Distribution.approx(N)`. New `DiscreteDistribution.limit` attribute describes continuous origin and discretization method. [#1197](https://github.com/econ-ark/HARK/pull/1197).
 - Creates new class of _labeled_ models under `ConsLabeledModel` that use xarray for more expressive modeling of underlying mathematical and economics variables. [#1177](https://github.com/econ-ark/HARK/pull/1177)
 
 #### Minor Changes
@@ -148,7 +147,7 @@ Release Date: February 16, 2023
 - Adds `benchmark` utility to profile the performance of `HARK` solvers. [#1131](https://github.com/econ-ark/HARK/pull/1131)
 - Fixes scaling bug in Normal equiprobable approximation method. [1139](https://github.com/econ-ark/HARK/pull/1139)
 - Removes the extra-dimension that was returned by `calc_expectations` in some instances. [#1149](https://github.com/econ-ark/HARK/pull/1149)
-- Adds `HARK.distribution.expected` alias for `DiscreteDistribution.expected`. [#1156](https://github.com/econ-ark/HARK/pull/1156)
+- Adds `HARK.distributions.expected` alias for `DiscreteDistribution.expected`. [#1156](https://github.com/econ-ark/HARK/pull/1156)
 - Renames attributes in `DiscreteDistribution`: `X` to `atoms` and `pmf` to `pmv`. [#1164](https://github.com/econ-ark/HARK/pull/1164), [#1051](https://github.com/econ-ark/HARK/pull/1151), [#1159](https://github.com/econ-ark/HARK/pull/1159).
 - Remove or replace automated tests that depend on brittle simulation results. [#1148](https://github.com/econ-ark/HARK/pull/1148)
 - Updates asset grid constructor from `ConsIndShockModel.py` to allow for linearly-spaced grids when `aXtraNestFac == -1`. [#1172](https://github.com/econ-ark/HARK/pull/1172)
@@ -206,7 +205,7 @@ Release Date: March 4, 2021
 - Converts non-mathematical code to PEP8 compliant form [#953](https://github.com/econ-ark/HARK/pull/953)
 - Adds a constructor for LogNormal distributions from mean and standard deviation [#891](https://github.com/econ-ark/HARK/pull/891/)
 - Uses new LogNormal constructor in ConsPortfolioModel [#891](https://github.com/econ-ark/HARK/pull/891/)
-- calcExpectations method for taking the expectation of a distribution over a function [#884](https://github.com/econ-ark/HARK/pull/884/] (#897)[https://github.com/econ-ark/HARK/pull/897/)
+- calcExpectations method for taking the expectation of a distribution over a function [#884](<https://github.com/econ-ark/HARK/pull/884/>] (#897)[https://github.com/econ-ark/HARK/pull/897/)
 - Implements the multivariate normal as a supported distribution, with a discretization method. See [#948](https://github.com/econ-ark/HARK/pull/948).
 - Centralizes the definition of value, marginal value, and marginal marginal value functions that use inverse-space
   interpolation for problems with CRRA utility. See [#888](https://github.com/econ-ark/HARK/pull/888).

Documentation/overview/ARKitecture.md

@@ -29,7 +29,7 @@ from HARK.rewards import CRRAutility
 CRRAutility(1, 2)
 ```
 
-Python modules in HARK can generally be categorized into two types: tools and models. **Tool modules** contain functions and classes with general purpose tools that have no inherent ''economic content'', but that can be used in many economic models as building blocks or utilities; they could plausibly be useful in non-economic settings. Tools might include functions for data analysis (e.g. calculating Lorenz shares from data, or constructing a non-parametric kernel regression), functions to create and manipulate discrete approximations to continuous distributions, or classes for constructing interpolated approximations to non-parametric functions. The most commonly used tool modules reside in HARK's root directory and have names like **_HARK.distribution_** and **_HARK.interpolation_**.
+Python modules in HARK can generally be categorized into two types: tools and models. **Tool modules** contain functions and classes with general purpose tools that have no inherent ''economic content'', but that can be used in many economic models as building blocks or utilities; they could plausibly be useful in non-economic settings. Tools might include functions for data analysis (e.g. calculating Lorenz shares from data, or constructing a non-parametric kernel regression), functions to create and manipulate discrete approximations to continuous distributions, or classes for constructing interpolated approximations to non-parametric functions. The most commonly used tool modules reside in HARK's root directory and have names like **_HARK.distributions_** and **_HARK.interpolation_**.
 
 **Model modules** specify particular economic models, including classes to represent agents in the model (and the ''market structure'' in which they interact) and functions for solving the ''one period problem'' of those models. For example, **ConsIndShockModel.py** concerns consumption-saving models in which agents have CRRA utility over consumption and face idiosyncratic shocks to permanent and transitory income. The module includes classes for representing ''types'' of consumers, along with functions for solving (several flavors of) the one period consumption-saving problem. Model modules generally have **_Model_** in their name, and the classes for representing agents all have **_Type_** at the end of their name (as instances represent a collection of ex ante homogeneous agents who share common model and parameters-- a "type"). For example, **_HARK.ConsumptionSaving.ConsIndShockModel_** includes the class **_IndShockConsumerType_**.
 
@@ -59,9 +59,9 @@ Macroeconomic models in HARK use the **_Market_** class to represent a market (o
 
 The **_HARK.utilities_** module contains a variety of general purpose tools, including some data manipulation tools (e.g. for calculating an average of data conditional on being within a percentile range of different data), basic kernel regression tools, convenience functions for retrieving information about functions, and basic plotting tools using **_matplotlib.pyplot_**. See [here](https://docs.econ-ark.org/Documentation/reference/tools/utilities.html) for further documentation.
 
-#### HARK.distribution
+#### HARK.distributions
 
-The **_HARK.distribution_** module includes classes for representing continuous distributions in a relatively consistent framework. Critically for numeric purposes, it also has methods and functions for constructing discrete approximations to those distributions (e.g. **_approx\_lognormal()_** to approximate a log-normal distribution) as well as manipulating these representations (e.g. appending one outcome to an existing distribution, or combining independent univariate distributions into one multivariate distribution). As a convention in HARK, continuous distributions are approximated as finite discrete distributions when solving models. This both simplifies solution methods (reducing numeric integrals to simple dot products) and allows users to easily test whether their chosen degree of discretization yields a sufficient approximation to the full distribution. See [here](https://docs.econ-ark.org/Documentation/reference/tools/distribution.html) for further documentation.
+The **_HARK.distributions_** module includes classes for representing continuous distributions in a relatively consistent framework. Critically for numeric purposes, it also has methods and functions for constructing discrete approximations to those distributions (e.g. **_approx\_lognormal()_** to approximate a log-normal distribution) as well as manipulating these representations (e.g. appending one outcome to an existing distribution, or combining independent univariate distributions into one multivariate distribution). As a convention in HARK, continuous distributions are approximated as finite discrete distributions when solving models. This both simplifies solution methods (reducing numeric integrals to simple dot products) and allows users to easily test whether their chosen degree of discretization yields a sufficient approximation to the full distribution. See [here](https://docs.econ-ark.org/Documentation/reference/tools/distribution.html) for further documentation.
 
 #### HARK.interpolation
 

Documentation/reference/tools/distribution.rst

@@ -1,7 +1,7 @@
 Distribution
 -------------
 
-.. automodule:: HARK.distribution
+.. automodule:: HARK.distributions
    :members:
    :undoc-members:
    :show-inheritance:

HARK/Calibration/Assets/AssetProcesses.py

@@ -5,7 +5,7 @@
 
 import numpy as np
 from scipy.optimize import minimize_scalar
-from HARK.distribution import (
+from HARK.distributions import (
     combine_indep_dstns,
     DiscreteDistributionLabeled,
     IndexDistribution,

HARK/Calibration/Income/IncomeProcesses.py

@@ -4,7 +4,7 @@
 
 import numpy as np
 from HARK.metric import MetricObject
-from HARK.distribution import (
+from HARK.distributions import (
     add_discrete_outcome_constant_mean,
     combine_indep_dstns,
     DiscreteDistribution,

HARK/ConsumptionSaving/ConsAggShockModel.py

@@ -22,7 +22,7 @@
     init_idiosyncratic_shocks,
 )
 from HARK.ConsumptionSaving.ConsMarkovModel import MarkovConsumerType
-from HARK.distribution import (
+from HARK.distributions import (
     MarkovProcess,
     MeanOneLogNormal,
     Uniform,

HARK/ConsumptionSaving/ConsBequestModel.py

@@ -36,7 +36,7 @@
     make_portfolio_solution_terminal,
 )
 from HARK.ConsumptionSaving.ConsRiskyAssetModel import make_simple_ShareGrid
-from HARK.distribution import expected
+from HARK.distributions import expected
 from HARK.interpolation import (
     BilinearInterp,
     ConstantFunction,

HARK/ConsumptionSaving/ConsGenIncProcessModel.py

@@ -23,7 +23,7 @@
     ConsumerSolution,
     IndShockConsumerType,
 )
-from HARK.distribution import Lognormal, expected
+from HARK.distributions import Lognormal, expected
 from HARK.interpolation import (
     BilinearInterp,
     ConstantFunction,

HARK/ConsumptionSaving/ConsIndShockModel.py

@@ -30,7 +30,7 @@
 from HARK.Calibration.SCF.WealthIncomeDist.SCFDistTools import (
     income_wealth_dists_from_scf,
 )
-from HARK.distribution import (
+from HARK.distributions import (
     Lognormal,
     MeanOneLogNormal,
     Uniform,

HARK/ConsumptionSaving/ConsLabeledModel.py

@@ -22,7 +22,7 @@
 )
 from HARK.ConsumptionSaving.LegacyOOsolvers import ConsIndShockSetup
 from HARK.core import make_one_period_oo_solver
-from HARK.distribution import DiscreteDistributionLabeled
+from HARK.distributions import DiscreteDistributionLabeled
 from HARK.metric import MetricObject
 from HARK.rewards import UtilityFuncCRRA
 

HARK/ConsumptionSaving/ConsMarkovModel.py

@@ -19,7 +19,7 @@
     PerfForesightConsumerType,
     make_basic_CRRA_solution_terminal,
 )
-from HARK.distribution import MarkovProcess, Uniform, expected
+from HARK.distributions import MarkovProcess, Uniform, expected
 from HARK.interpolation import (
     CubicInterp,
     LinearInterp,

HARK/ConsumptionSaving/ConsMedModel.py

@@ -21,7 +21,7 @@
     VariableLowerBoundFunc2D,
 )
 from HARK.ConsumptionSaving.ConsIndShockModel import ConsumerSolution
-from HARK.distribution import Lognormal, add_discrete_outcome_constant_mean, expected
+from HARK.distributions import Lognormal, add_discrete_outcome_constant_mean, expected
 from HARK.interpolation import (
     BilinearInterp,
     BilinearInterpOnInterp1D,

HARK/ConsumptionSaving/ConsPortfolioModel.py

@@ -26,7 +26,7 @@
     RiskyAssetConsumerType,
     make_simple_ShareGrid,
 )
-from HARK.distribution import expected
+from HARK.distributions import expected
 from HARK.interpolation import (
     BilinearInterp,
     ConstantFunction,

HARK/ConsumptionSaving/ConsPrefShockModel.py

@@ -22,7 +22,7 @@
     get_PermShkDstn_from_IncShkDstn,
     get_TranShkDstn_from_IncShkDstn,
 )
-from HARK.distribution import MeanOneLogNormal, expected
+from HARK.distributions import MeanOneLogNormal, expected
 from HARK.interpolation import (
     CubicInterp,
     LinearInterp,

HARK/ConsumptionSaving/ConsRepAgentModel.py

@@ -17,7 +17,7 @@
     make_basic_CRRA_solution_terminal,
 )
 from HARK.ConsumptionSaving.ConsMarkovModel import MarkovConsumerType
-from HARK.distribution import MarkovProcess
+from HARK.distributions import MarkovProcess
 from HARK.interpolation import LinearInterp, MargValueFuncCRRA
 from HARK.utilities import make_assets_grid
 

HARK/ConsumptionSaving/ConsRiskyAssetModel.py

@@ -22,7 +22,7 @@
     get_PermShkDstn_from_IncShkDstn,
     get_TranShkDstn_from_IncShkDstn,
 )
-from HARK.distribution import (
+from HARK.distributions import (
     Bernoulli,
     expected,
     IndexDistribution,

HARK/ConsumptionSaving/ConsRiskyContribModel.py

@@ -45,7 +45,7 @@
     init_risky_asset,
     IndShockRiskyAssetConsumerType_constructor_default,
 )
-from HARK.distribution import calc_expectation
+from HARK.distributions import calc_expectation
 from HARK.interpolation import BilinearInterp  # 2D interpolator
 from HARK.interpolation import (
     ConstantFunction,  # Interpolator-like class that returns constant value

HARK/ConsumptionSaving/ConsWealthPortfolioModel.py

@@ -6,7 +6,7 @@
     PortfolioSolution,
     make_portfolio_solution_terminal,
 )
-from HARK.distribution import expected
+from HARK.distributions import expected
 from HARK.interpolation import (
     BilinearInterp,
     CubicInterp,

HARK/ConsumptionSaving/LegacyOOsolvers.py

@@ -10,7 +10,7 @@
 from dataclasses import dataclass
 import numpy as np
 from HARK import NullFunc
-from HARK.distribution import expected, calc_expectation, DiscreteDistribution
+from HARK.distributions import expected, calc_expectation, DiscreteDistribution
 from HARK.interpolation import (
     BilinearInterp,
     BilinearInterpOnInterp1D,

HARK/ConsumptionSaving/TractableBufferStockModel.py

@@ -27,7 +27,7 @@
 from scipy.optimize import brentq, newton
 
 from HARK import AgentType, NullFunc
-from HARK.distribution import Bernoulli, Lognormal
+from HARK.distributions import Bernoulli, Lognormal
 from HARK.interpolation import CubicInterp
 
 # Import the HARK library.

HARK/ConsumptionSaving/tests/test_ConsAggShockModel.py

@@ -11,7 +11,7 @@
     KrusellSmithEconomy,
     KrusellSmithType,
 )
-from HARK.distribution import Uniform
+from HARK.distributions import Uniform
 from HARK.tests import HARK_PRECISION
 
 

HARK/ConsumptionSaving/tests/test_ConsMarkovModel.py

@@ -7,7 +7,7 @@
     MarkovConsumerType,
     init_indshk_markov,
 )
-from HARK.distribution import (
+from HARK.distributions import (
     DiscreteDistribution,
     DiscreteDistributionLabeled,
     MeanOneLogNormal,

HARK/ConsumptionSaving/tests/test_SmallOpenEconomy.py

@@ -8,7 +8,7 @@
     SmallOpenEconomy,
     init_cobb_douglas,
 )
-from HARK.distribution import Uniform
+from HARK.distributions import Uniform
 
 
 class testSmallOpenEconomy(unittest.TestCase):

HARK/ConsumptionSaving/tests/test_modelcomparisons.py

@@ -19,7 +19,7 @@
 )
 from HARK.ConsumptionSaving.ConsMarkovModel import MarkovConsumerType
 from HARK.ConsumptionSaving.TractableBufferStockModel import TractableConsumerType
-from HARK.distribution import DiscreteDistributionLabeled
+from HARK.distributions import DiscreteDistributionLabeled
 
 
 class Compare_PerfectForesight_and_Infinite(unittest.TestCase):