Skip to content

Commit a3dd249

Browse files
alanlujan91alanlujan91
committed
Squashed commit of the following:
commit d639dc9 Author: alanlujan91 <alanlujan91@gmail.com> Date: Mon Oct 20 09:11:59 2025 -0400 Update README.md commit 149a277 Author: alanlujan91 <alanlujan91@gmail.com> Date: Mon Oct 20 09:08:44 2025 -0400 Exclude abstract and acknowledgments in word count Updated count_words.sh to remove the Abstract and Acknowledgments sections from word counting, aligning with journal requirements. Also deleted test_wordcount.md, which was used for testing the script. commit 6a86b71 Author: alanlujan91 <alanlujan91@gmail.com> Date: Mon Oct 20 08:59:57 2025 -0400 Add reproducibility scripts and Binder support Introduces reproduce.sh and reproduce_min.sh scripts for full and minimal project reproduction, respectively. Adds Binder configuration files (environment.yml, postBuild) for interactive environments. Updates .gitignore for new files, enhances CITATION.cff with metadata and abstract, and expands README with reproducibility instructions. Removes duplicate PDF files and updates paper appendix and moderation letters PDFs. commit 3d9e7d9 Author: alanlujan91 <alanlujan91@gmail.com> Date: Fri Oct 17 16:17:01 2025 -0400 Update author info and clarify technical content Added Karsten Chipeniuk as an author and updated affiliations for several authors across metadata, LaTeX, and YAML files. Clarified and condensed technical explanations in appendix and moderation letters, removing extended discussion of endogenous gridpoints method and related bibliography entries. commit 17ec7ab Author: alanlujan91 <alanlujan91@gmail.com> Date: Fri Oct 17 15:28:38 2025 -0400 Add appendix materials for 'The Method of Moderation' Added appendix_letters.md, appendix_letters.pdf, and LaTeX source files (appendix_letters.tex, main.bib, preprint.sty) providing detailed mathematical derivations and technical results supporting the Method of Moderation. Also added supporting files for moderation_letters and updated moderation.md, moderation.pdf, and moderation.tex. Introduced word count script and documentation in scripts/. Updated myst.yml configuration. commit bb6fd2f Author: alanlujan91 <alanlujan91@gmail.com> Date: Fri Oct 17 09:03:51 2025 -0400 Normalize line endings across project files commit a859427 Author: alanlujan91 <alanlujan91@gmail.com> Date: Fri Oct 17 08:58:52 2025 -0400 Update moderation paper with expanded theory Expanded and refined the theoretical exposition in moderation.md, including improved notation, additional mathematical derivations, and clarifications of key concepts. The changes enhance readability and provide more rigorous foundations for the method of moderation in dynamic stochastic optimization. commit ea80bed Author: alanlujan91 <alanlujan91@gmail.com> Date: Wed Oct 8 16:45:49 2025 -0400 Add figures and update moderation paper files Added new PDF figures to the moderation_pdf_tex/files directory and updated the main bibliography and moderation.tex source. These changes improve the completeness and accuracy of the paper's references and figures for the latest draft. commit 1e80cca Author: alanlujan91 <alanlujan91@gmail.com> Date: Wed Oct 8 16:45:41 2025 -0400 Update notation and formulas for clarity and consistency Standardized mathematical notation in macros.yml and moderation.md, replacing superscript derivatives with prime notation and updating formulas to use PDVCoverc instead of PDVCoverc^T where appropriate. Cleaned up README.md by removing emoji icons from section headers for a more consistent style. commit d6dabcf Author: alanlujan91 <alanlujan91@gmail.com> Date: Wed Oct 8 16:45:16 2025 -0400 Refactor Method of Moderation variable names and docs Standardizes variable names in code/moderation.py from Greek letters (e.g., κ, μ, ω, χ) to their ASCII equivalents (kappa, mu, omega, chi) for consistency and clarity. Updates docstrings, comments, and mathematical explanations throughout to match the new naming convention, improves documentation, and enhances derivative logic for moderated functions. No functional changes to algorithms; notebook execution metadata updated. commit e7c0327 Author: alanlujan91 <alanlujan91@gmail.com> Date: Wed Oct 8 15:37:08 2025 -0400 Refactor macros and clarify moderation framework Reorganized and expanded macro definitions in macros.yml for clarity, including new indicator and moderation-related macros, and improved naming consistency. Updated moderation.md to clarify notation, streamline exposition, and improve mathematical definitions and explanations of the optimist/pessimist/realist framework, moderation ratio, and logit transformation. Enhanced technical accuracy and readability throughout, with more explicit variable definitions and improved references to supporting literature. commit 1c77646 Author: alanlujan91 <alanlujan91@gmail.com> Date: Wed Oct 8 13:37:41 2025 -0400 Refactor moderation logic for ML consistency Updated moderation ratio, logit, and expit functions in moderation.py to follow standard machine learning conventions. Adjusted mathematical definitions, documentation, and implementation to ensure consistency with ML/statistics practices. Updated usage in TransformedFunctionMoM and fixed related derivative logic. Minor import addition in notebook.ipynb for GridType.
1 parent ec1759d commit a3dd249

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

46 files changed

+15646
-13172
lines changed

‎.gitignore‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,9 @@
1+
# Private directory
2+
.private/
3+
4+
# GitHub Copilot instructions (local configuration)
5+
.github/copilot-instructions.md
6+
17
# Byte-compiled / optimized / DLL files
28
__pycache__/
39
*.py[cod]

‎CITATION.cff‎

Lines changed: 59 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -1,34 +1,59 @@
1-
cff-version: 1.2.0
2-
message: Please cite the following works when using this project.
3-
title: The Method of Moderation
4-
authors:
5-
- family-names: Carroll
6-
given-names: Christopher D.
7-
affiliation: Johns Hopkins University
8-
address: Baltimore, MD
9-
orcid: 0000-0003-3732-9312
10-
email: ccarroll@jhu.edu
11-
- family-names: Lujan
12-
given-names: Alan
13-
affiliation: Johns Hopkins University
14-
address: Baltimore, MD
15-
orcid: 0000-0002-5289-7054
16-
email: alujan@jhu.edu
17-
- family-names: Tokuoka
18-
given-names: Kiichi
19-
affiliation: European Central Bank
20-
email: ktokuoka@imf.org
21-
- family-names: Wu
22-
given-names: Weifeng
23-
affiliation: Fannie Mae
24-
address: Washington, DC
25-
contact:
26-
- family-names: Lujan
27-
given-names: Alan
28-
affiliation: Johns Hopkins University
29-
address: Baltimore, MD
30-
orcid: 0000-0002-5289-7054
31-
email: alujan@jhu.edu
32-
license: CC-BY-SA-3.0
33-
license-url: https://creativecommons.org/licenses/by-sa/3.0/
34-
repository: https://github.com/econ-ark/method-of-moderation
1+
cff-version: 1.2.0
2+
message: Please cite the following works when using this project.
3+
title: The Method of Moderation
4+
type: software
5+
authors:
6+
- family-names: Carroll
7+
given-names: Christopher D.
8+
affiliation: Johns Hopkins University
9+
address: Baltimore, MD
10+
orcid: 0000-0003-3732-9312
11+
email: ccarroll@jhu.edu
12+
- family-names: Lujan
13+
given-names: Alan
14+
affiliation: Johns Hopkins University
15+
address: Baltimore, MD
16+
orcid: 0000-0002-5289-7054
17+
email: alujan@jhu.edu
18+
- family-names: Chipeniuk
19+
given-names: Karsten
20+
affiliation: Reserve Bank of New Zealand
21+
- family-names: Tokuoka
22+
given-names: Kiichi
23+
affiliation: Japanese Ministry of Finance
24+
- family-names: Wu
25+
given-names: Weifeng
26+
affiliation: Fannie Mae
27+
address: Washington, DC
28+
contact:
29+
- family-names: Lujan
30+
given-names: Alan
31+
affiliation: Johns Hopkins University
32+
address: Baltimore, MD
33+
orcid: 0000-0002-5289-7054
34+
email: alujan@jhu.edu
35+
abstract: >
36+
In a risky world, a pessimist assumes the worst will happen. Someone who
37+
ignores risk altogether is an optimist. Consumption decisions are
38+
mathematically simple for both the pessimist and the optimist because both
39+
behave as if they live in a riskless world. A realist (someone who wants
40+
to respond optimally to risk) faces a much more difficult problem, but
41+
(under standard conditions) will choose a level of spending somewhere
42+
between pessimist's and the optimist's. We use this fact to redefine the
43+
space in which the realist searches for optimal consumption rules. The
44+
resulting solution accurately represents the numerical consumption rule
45+
over the entire interval of feasible wealth values with remarkably few
46+
computations.
47+
keywords:
48+
- consumption
49+
- saving
50+
- dynamic stochastic optimization
51+
- endogenous grid method
52+
- computational economics
53+
- Econ-ARK
54+
- REMARK
55+
license: CC-BY-SA-3.0
56+
license-url: https://creativecommons.org/licenses/by-sa/3.0/
57+
repository: https://github.com/econ-ark/method-of-moderation
58+
repository-code: https://github.com/econ-ark/method-of-moderation
59+
url: https://github.com/econ-ark/method-of-moderation

‎LICENSE‎

Lines changed: 19 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,19 @@
1-
Copyright 2025 Alan Lujan
2-
3-
Permission is hereby granted, free of charge, to any person obtaining a copy of
4-
this software and associated documentation files (the "Software"), to deal in
5-
the Software without restriction, including without limitation the rights to
6-
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
7-
of the Software, and to permit persons to whom the Software is furnished to do
8-
so, subject to the following conditions:
9-
10-
The above copyright notice and this permission notice shall be included in all
11-
copies or substantial portions of the Software.
12-
13-
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
14-
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
15-
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
16-
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
17-
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
18-
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
19-
SOFTWARE.
1+
Copyright 2025 Alan Lujan
2+
3+
Permission is hereby granted, free of charge, to any person obtaining a copy of
4+
this software and associated documentation files (the "Software"), to deal in
5+
the Software without restriction, including without limitation the rights to
6+
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
7+
of the Software, and to permit persons to whom the Software is furnished to do
8+
so, subject to the following conditions:
9+
10+
The above copyright notice and this permission notice shall be included in all
11+
copies or substantial portions of the Software.
12+
13+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
14+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
15+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
16+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
17+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
18+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
19+
SOFTWARE.

‎README.md‎

Lines changed: 122 additions & 98 deletions
Original file line numberDiff line numberDiff line change
@@ -1,98 +1,122 @@
1-
# The Method of Moderation
2-
3-
[![Actions Status][actions-badge]][actions-link]
4-
[![Documentation Status][rtd-badge]][rtd-link]
5-
6-
[![PyPI version][pypi-version]][pypi-link]
7-
[![Conda-Forge][conda-badge]][conda-link]
8-
[![PyPI platforms][pypi-platforms]][pypi-link]
9-
10-
[![GitHub Discussion][github-discussions-badge]][github-discussions-link]
11-
12-
## Authors
13-
14-
- **Christopher D. Carroll** - Johns Hopkins University ([ORCID: 0000-0003-3732-9312](https://orcid.org/0000-0003-3732-9312))
15-
- **Alan Lujan** - Johns Hopkins University ([ORCID: 0000-0002-5289-7054](https://orcid.org/0000-0002-5289-7054)) *Corresponding Author*
16-
- **Kiichi Tokuoka** - European Central Bank / International Monetary Fund
17-
- **Weifeng Wu** - Fannie Mae
18-
19-
## Abstract
20-
21-
In a risky world, a pessimist assumes the worst will happen. Someone who ignores risk altogether is an optimist. Consumption decisions are mathematically simple for both the pessimist and the optimist because both behave as if they live in a riskless world. A realist (someone who wants to respond optimally to risk) faces a much more difficult problem, but (under standard conditions) will choose a level of spending somewhere between pessimist's and the optimist's. We use this fact to redefine the space in which the realist searches for optimal consumption rules. The resulting solution accurately represents the numerical consumption rule over the entire interval of feasible wealth values with remarkably few computations.
22-
23-
**Keywords**: Dynamic Stochastic Optimization
24-
**JEL Classification**: D14; C61; G11
25-
26-
## Content
27-
28-
### 📄 Paper
29-
- [**Read the Paper**](content/paper/moderation.md) - Full paper in MyST Markdown format
30-
- [**Download PDF**](content/paper/moderation.pdf) - Paper in PDF format
31-
32-
### 💻 Code & Interactive Content
33-
- [**Jupyter Notebook**](code/notebook.ipynb) - Complete computational notebook with examples
34-
- [**Interactive Dashboard**](code/dashboard.ipynb) - Interactive visualizations using Voila
35-
36-
### 🔗 Links
37-
- **Documentation**: [Read the Docs](https://moderation.readthedocs.io)
38-
- **Paper Repository**: [REMARK](https://github.com/econ-ark/REMARK)
39-
- **Package**: [PyPI](https://pypi.org/project/moderation/)
40-
41-
## Installation
42-
43-
```bash
44-
pip install moderation
45-
```
46-
47-
or
48-
49-
```bash
50-
conda install -c conda-forge moderation
51-
```
52-
53-
## Usage
54-
55-
For development and interactive use:
56-
57-
```bash
58-
git clone https://github.com/econ-ark/method-of-moderation.git
59-
cd MethodOfModeration
60-
pip install -e .
61-
```
62-
63-
## Citation
64-
65-
```bibtex
66-
@misc{carroll2024moderation,
67-
title={The Method of Moderation},
68-
author={Carroll, Christopher D. and Lujan, Alan and Tokuoka, Kiichi and Wu, Weifeng},
69-
year={2024},
70-
url={https://github.com/econ-ark/method-of-moderation}
71-
}
72-
```
73-
74-
## Acknowledgments
75-
76-
This work was supported by the Alfred P. Sloan Foundation under grant G-2017-9832. The views presented in this paper are those of the authors, and should not be attributed to the International Monetary Fund, its Executive Board, or management, or to the European Central Bank.
77-
78-
## License
79-
80-
- **Content**: [CC-BY-SA-3.0](https://creativecommons.org/licenses/by-sa/3.0/)
81-
- **Code**: [MIT](LICENSE)
82-
83-
<!-- SPHINX-START -->
84-
85-
<!-- prettier-ignore-start -->
86-
[actions-badge]: https://github.com/econ-ark/method-of-moderation/workflows/CI/badge.svg
87-
[actions-link]: https://github.com/econ-ark/method-of-moderation/actions
88-
[conda-badge]: https://img.shields.io/conda/vn/conda-forge/moderation
89-
[conda-link]: https://github.com/conda-forge/moderation-feedstock
90-
[github-discussions-badge]: https://img.shields.io/static/v1?label=Discussions&message=Ask&color=blue&logo=github
91-
[github-discussions-link]: https://github.com/econ-ark/method-of-moderation/discussions
92-
[pypi-link]: https://pypi.org/project/moderation/
93-
[pypi-platforms]: https://img.shields.io/pypi/pyversions/moderation
94-
[pypi-version]: https://img.shields.io/pypi/v/moderation
95-
[rtd-badge]: https://readthedocs.org/projects/moderation/badge/?version=latest
96-
[rtd-link]: https://moderation.readthedocs.io/en/latest/?badge=latest
97-
98-
<!-- prettier-ignore-end -->
1+
# The Method of Moderation
2+
3+
[![Actions Status][actions-badge]][actions-link]
4+
[![Documentation Status][rtd-badge]][rtd-link]
5+
6+
[![PyPI version][pypi-version]][pypi-link]
7+
[![Conda-Forge][conda-badge]][conda-link]
8+
[![PyPI platforms][pypi-platforms]][pypi-link]
9+
10+
[![GitHub Discussion][github-discussions-badge]][github-discussions-link]
11+
12+
<!-- Uncomment after REMARK indexing:
13+
[![REMARK](https://img.shields.io/badge/REMARK-indexed-blue)](https://github.com/econ-ark/REMARK)
14+
-->
15+
16+
## Reproducibility
17+
18+
This project is structured as a [REMARK](https://github.com/econ-ark/REMARK) (Replications and Explorations Made using ARK). To reproduce all results:
19+
20+
```bash
21+
./reproduce.sh # Full reproduction (all tests, paper, notebooks)
22+
./reproduce_min.sh # Quick validation (<5 minutes)
23+
```
24+
25+
## Authors
26+
27+
- **Christopher D. Carroll** - Johns Hopkins University ([ORCID: 0000-0003-3732-9312](https://orcid.org/0000-0003-3732-9312))
28+
- **Alan Lujan** - Johns Hopkins University ([ORCID: 0000-0002-5289-7054](https://orcid.org/0000-0002-5289-7054)) *Corresponding Author*
29+
- **Kiichi Tokuoka** - European Central Bank / International Monetary Fund
30+
- **Weifeng Wu** - Fannie Mae
31+
32+
## Abstract
33+
34+
In a risky world, a pessimist assumes the worst will happen. Someone who ignores risk altogether is an optimist. Consumption decisions are mathematically simple for both the pessimist and the optimist because both behave as if they live in a riskless world. A realist (someone who wants to respond optimally to risk) faces a much more difficult problem, but (under standard conditions) will choose a level of spending somewhere between pessimist's and the optimist's. We use this fact to redefine the space in which the realist searches for optimal consumption rules. The resulting solution accurately represents the numerical consumption rule over the entire interval of feasible wealth values with remarkably few computations.
35+
36+
**Keywords**: Dynamic Stochastic Optimization
37+
**JEL Classification**: D14; C61; G11
38+
39+
## Content
40+
41+
### Paper
42+
- [**Read the Paper**](content/paper/moderation.md) - Full paper in MyST Markdown format
43+
- [**Download PDF**](content/paper/moderation.pdf) - Full paper in PDF format
44+
- [**Letters Version**](content/paper/moderation_letters.md) - Economics Letters submission format
45+
46+
### Code & Interactive Content
47+
- [**Jupyter Notebook**](code/notebook.ipynb) - Complete computational notebook with examples
48+
49+
### Links
50+
- **Documentation**: [MyST Build](_build/html/index.html) (local build)
51+
- **REMARK**: [Catalog Entry](https://github.com/econ-ark/REMARK/blob/master/REMARKs/MethodOfModeration.yml)
52+
- **Source Code**: [GitHub Repository](https://github.com/econ-ark/method-of-moderation)
53+
54+
## Installation
55+
56+
### For Users (when published)
57+
58+
```bash
59+
pip install moderation
60+
```
61+
62+
or
63+
64+
```bash
65+
conda install -c conda-forge moderation
66+
```
67+
68+
### For Development
69+
70+
This project uses [uv](https://github.com/astral-sh/uv) for dependency management:
71+
72+
```bash
73+
git clone https://github.com/econ-ark/method-of-moderation.git
74+
cd method-of-moderation
75+
uv sync # Install dependencies
76+
uv run pytest # Run tests
77+
uv run myst build --html # Build documentation
78+
```
79+
80+
See [REMARK reproduction](#reproducibility) section above for full reproduction instructions.
81+
82+
## Citation
83+
84+
```bibtex
85+
@software{carroll2025moderation,
86+
title={The Method of Moderation},
87+
author={Carroll, Christopher D. and
88+
Lujan, Alan and
89+
Chipeniuk, Karsten and
90+
Tokuoka, Kiichi and
91+
Wu, Weifeng},
92+
year={2025},
93+
url={https://github.com/econ-ark/method-of-moderation},
94+
license={CC-BY-SA-3.0}
95+
}
96+
```
97+
98+
## Acknowledgments
99+
100+
This work was supported by the Alfred P. Sloan Foundation under grant G-2017-9832. The views presented in this paper are those of the authors, and should not be attributed to the International Monetary Fund, its Executive Board, or management, or to the European Central Bank.
101+
102+
## License
103+
104+
- **Content**: [CC-BY-SA-3.0](https://creativecommons.org/licenses/by-sa/3.0/)
105+
- **Code**: [MIT](LICENSE)
106+
107+
<!-- SPHINX-START -->
108+
109+
<!-- prettier-ignore-start -->
110+
[actions-badge]: https://github.com/econ-ark/method-of-moderation/workflows/CI/badge.svg
111+
[actions-link]: https://github.com/econ-ark/method-of-moderation/actions
112+
[conda-badge]: https://img.shields.io/conda/vn/conda-forge/moderation
113+
[conda-link]: https://github.com/conda-forge/moderation-feedstock
114+
[github-discussions-badge]: https://img.shields.io/static/v1?label=Discussions&message=Ask&color=blue&logo=github
115+
[github-discussions-link]: https://github.com/econ-ark/method-of-moderation/discussions
116+
[pypi-link]: https://pypi.org/project/moderation/
117+
[pypi-platforms]: https://img.shields.io/pypi/pyversions/moderation
118+
[pypi-version]: https://img.shields.io/pypi/v/moderation
119+
[rtd-badge]: https://readthedocs.org/projects/moderation/badge/?version=latest
120+
[rtd-link]: https://moderation.readthedocs.io/en/latest/?badge=latest
121+
122+
<!-- prettier-ignore-end -->

‎binder/environment.yml‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Binder environment configuration
2+
# This file delegates to uv for dependency management from pyproject.toml
3+
# ensuring single-source-of-truth for dependencies
4+
5+
name: moderation
6+
channels:
7+
- conda-forge
8+
dependencies:
9+
- python=3.12
10+
- uv
11+
- pip
12+
- pip:
13+
- -e ../.

‎binder/postBuild‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
#!/bin/bash
2+
# Post-build script for Binder
3+
# Uses uv to install all dependencies from pyproject.toml
4+
5+
set -e
6+
7+
# Navigate to repository root
8+
cd "${HOME}"
9+
10+
# Install dependencies using uv (which reads from pyproject.toml)
11+
uv sync --all-extras
12+
13+
# Ensure Jupyter extensions are enabled
14+
jupyter labextension list
15+
16+
echo "Binder environment ready!"

0 commit comments

Comments
 (0)