Clean up Causal Analysis of Success in Modern Society Tutorial #472

research/A_Causal_Analysis_of_Success_in_Modern_Society/.dockerignore

@@ -0,0 +1,143 @@
+# Exclude files from Docker build context. This prevents unnecessary files from
+# being sent to Docker daemon, reducing build time and image size.
+
+# Python artifacts
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+*.egg-info/
+
+# Virtual environments
+venv/
+.venv/
+env/
+.env
+.envrc
+client_venv.helpers/
+ENV/
+
+# Jupyter
+.ipynb_checkpoints/
+.jupyter/
+
+# Build artifacts
+build/
+dist/
+*.eggs/
+.eggs/
+
+# Cache and temporary files
+*.log
+*.tmp
+*.cache
+.pytest_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# Git and version control
+.git/
+.gitignore
+.gitattributes
+.github/
+
+# Docker build scripts (not needed at runtime)
+docker_build.sh
+docker_push.sh
+docker_clean.sh
+docker_exec.sh
+docker_cmd.sh
+docker_bash.sh
+docker_jupyter.sh
+docker_name.sh
+run_jupyter.sh
+Dockerfile.*
+.dockerignore
+
+# Documentation
+README.md
+README.admin.md
+docs/
+*.md
+CHANGELOG.md
+LICENSE
+
+# Configuration and secrets
+.env.*
+.env.local
+.env.development
+.env.production
+.DS_Store
+Thumbs.db
+
+# Shell configuration
+.bashrc
+.bash_history
+.zshrc
+
+# Large data files (mount via volume instead)
+data/
+*.csv
+*.pkl
+*.h5
+*.parquet
+*.feather
+*.arrow
+*.npy
+*.npz
+
+# Generated images
+*.png
+*.jpg
+*.jpeg
+*.gif
+*.svg
+*.pdf
+
+# Test files and examples
+tests/
+test_*
+*_test.py
+tutorials/
+examples/
+
+# IDE and editor files
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.project
+.pydevproject
+.settings/
+*.iml
+.sublime-project
+.sublime-workspace
+
+# Node and frontend (if applicable)
+node_modules/
+npm-debug.log
+yarn-error.log
+.npm
+
+# Requirements management
+requirements.in
+Pipfile
+Pipfile.lock
+poetry.lock
+setup.py
+setup.cfg
+
+# CI/CD configuration
+.gitlab-ci.yml
+.travis.yml
+Jenkinsfile
+.circleci/
+
+# Miscellaneous
+*.bak
+.venv.bak/
+*.whl
+*.tar.gz
+*.zip

research/A_Causal_Analysis_of_Success_in_Modern_Society/.gitignore

@@ -12,6 +12,7 @@ env/
 
 # ---- Jupyter Notebooks ----
 .ipynb_checkpoints/
+Untitled*.ipynb
 
 # ---- Logs and Text Output ----
 *.log
@@ -57,3 +58,4 @@ dist/
 # ---- Cache ----
 .cache/
 *.tmp
+.claude/

research/A_Causal_Analysis_of_Success_in_Modern_Society/Dockerfile

@@ -1,51 +1,30 @@
-FROM ubuntu:24.04
-ENV DEBIAN_FRONTEND noninteractive
+# Use Python 3.12 slim (already has Python and pip).
+FROM python:3.12-slim
 
-RUN apt-get -y update
-RUN apt-get -y upgrade
+# Avoid interactive prompts during apt operations.
+ENV DEBIAN_FRONTEND=noninteractive
 
-# Install system utilities.
-RUN apt install -y --no-install-recommends \
-    sudo \
-    curl \
-    systemctl \
-    gnupg \
-    git \
-    vim
-
-# Install Python and build deps (venv requires python3-venv on Debian/Ubuntu).
-RUN apt-get update && apt-get install -y --no-install-recommends \
-    build-essential \
-    python3 \
-    python3-pip \
-    python3-dev \
-    python3-venv \
+# Install CA certificates (needed for HTTPS).
+RUN apt-get update && apt-get install -y \
+    ca-certificates \
     && rm -rf /var/lib/apt/lists/*
 
-# Create virtual environment.
-RUN python3 -m venv /venv
-
-# Make the venv the default Python.
-ENV PATH="/venv/bin:$PATH"
-
-# Upgrade pip inside the venv.
-RUN python -m pip install --upgrade pip
-
 # Install project specific packages.
-COPY requirements.txt requirements.txt
+RUN mkdir -p /install
+COPY requirements.txt /install/requirements.txt
 RUN pip install --upgrade pip && \
-    pip install --no-cache-dir jupyterlab jupyterlab_vim jupytext -r requirements.txt
-
-RUN mkdir /install
+    pip install --no-cache-dir jupyterlab jupyterlab_vim jupytext -r /install/requirements.txt
 
 # Config.
-ADD etc_sudoers /install/
+COPY etc_sudoers /install/
 COPY etc_sudoers /etc/sudoers
 COPY bashrc /root/.bashrc
 
 # Report package versions.
-ADD version.sh /install/
+COPY version.sh /install/
 RUN /install/version.sh 2>&1 | tee version.log
 
 # Jupyter.
 EXPOSE 8888
+
+CMD ["/bin/bash"]

research/A_Causal_Analysis_of_Success_in_Modern_Society/README.md

@@ -1,38 +1,34 @@
-# Causal Success Tutorial
+# A Causal Analysis of Success in Modern Society
 
-- This folder contains the setup for running the Causal Analysis of Success
-  tutorials within a containerized environment.
+This project simulates talent-versus-luck dynamics in an agent-based model and
+uses causal inference to quantify how much luck actually drives inequality.
 
 ## Quick Start
 
-- From the root of the repository, change your directory to the causal_success
-  tutorial folder:
-  ```bash
-  > cd tutorials/causal_success
-  ```
-
-- Once the location has been changed to the repo run the command to build the
-  image to run dockers:
-  ```bash
-  > ./docker_build.sh
-  ```
-
-- Once the docker has been built you can then go ahead and run the container and
-  launch jupyter notebook using the created image using the command:
-  ```bash
-  > ./docker_jupyter.sh
-  ```
-
-- Once the `./docker_jupyter.sh` script is running, follow this sequence to
-  explore the tutorials:
-  1. **`causal_success.API.ipynb`**: Start here to understand the building
-     blocks — the Agent class, simulation engine, inequality metrics, policy
-     simulation, and Bayesian inference functions.
-  2. **`causal_success.example.ipynb`**: Run the full end-to-end analysis:
-     simulation → DML → Causal Forests → policy comparison.
-
-- Both notebooks run end-to-end in about 3 minutes on a laptop. All seeds are
-  fixed, so you will get the same results every time.
-
-- For more information on the Docker build system refer to [Project template
-  readme](https://github.com/gpsaggese/umd_classes/blob/master/class_project/project_template/README.md).
+Build the image and launch Jupyter from the project directory.
+
+```bash
+cd research/A_Causal_Analysis_of_Success_in_Modern_Society
+./docker_build.sh
+./docker_jupyter.sh
+```
+
+For Docker build-system details, see the
+[project template README](../../class_project/project_template/README.md).
+
+## Notebooks
+
+Work through the notebooks in the order listed below.
+
+1. [`causal_success.API.ipynb`](causal_success.API.ipynb) walks through every
+   building block on its own: the Agent class, the simulation engine, Gini
+   metrics, policy simulation, and the Bayesian inference helpers.
+2. [`causal_success.example.ipynb`](causal_success.example.ipynb) runs the
+   full pipeline end to end, including DML and Causal Forest estimation and
+   a comparison of five allocation strategies.
+
+Reusable logic lives in [`causal_success_utils.py`](causal_success_utils.py).
+
+## Changelog
+
+2026-04-05: Cleanup pass against tutorial format rules. 2026-02-25: Initial release.

research/A_Causal_Analysis_of_Success_in_Modern_Society/__init__.py

@@ -0,0 +1 @@
+