Reproducibility Rules for Final Project (Agentic Coding Guide)

Description

# Reproducibility Rules for Final Project (Agentic Coding Guide) **Project**: MacroEconomic Uncertainty database replication (Comunale & Nguyen 2025) **Environment**: Pixi + pytask + Python 3.14 **Critical Rule**: Everything must be reproducible from `main` branch with zero uncommitted changes --- ## 1. CARDINAL RULES (Never Break These) ### 1.1 Always Use Pixi ```bash # CORRECT: Run through pixi pixi run pytask pixi run pytest pixi run prek # WRONG: Direct Python calls (breaks reproducibility) python script.py # ❌ Uses wrong Python/environment pytest # ❌ Uses system pytest, not project version ``` **Why**: Pixi ensures exact package versions via `pixi.lock`. Direct calls use system Python. ### 1.2 Source vs Output Separation ``` src/ # Hand-written code ONLY (version controlled) bld/ # Generated outputs (safe to delete, NOT committed) _build/ # Document outputs (safe to delete, NOT committed) ``` **Rules**: - ✅ Edit files in `src/` - ❌ Never edit generated files in `bld/` or `_build/` - ❌ Never commit `bld/` or `_build/` contents (they're in `.gitignore`) - ✅ Final results must regenerate from clean checkout via `pixi run pytask` ### 1.3 No Hardcoded Paths ```python # CORRECT: Portable paths from pathlib import Path from meu_replication.config import BLD, SRC output_path = BLD / "data" / "cleaned.csv" # WRONG: Breaks on other machines output_path = "C:/Users/nikla/Projects/..." # ❌ ``` --- ## 2. DEPENDENCY MANAGEMENT (Pixi + pixi.lock) ### 2.1 How to Add Dependencies ```bash # Conda packages (prefer this) pixi add pandas numpy # PyPI-only packages pixi add --pypi some-package # Or manually edit pyproject.toml: [tool.pixi.dependencies] pandas = ">=2.0" [tool.pixi.pypi-dependencies] some-package = ">=1.0" ``` **Then**: ```bash pixi install # Updates pixi.lock ``` ### 2.2 Lockfile Policy (Critical for Reproducibility) - **Always commit `pixi.lock`** when dependencies change - `pixi.lock` pins exact versions (e.g., `pandas==2.2.1` not `pandas>=2.0`) - At submission time: verify all versions are pinned and consistent - **Never** edit `pixi.lock` manually --- ## 3. PYTASK: Building the Computational DAG ### 3.1 Task Discovery Rules pytask auto-discovers: - Files named `task_*.py` - Functions named `task_*` inside them ### 3.2 Task Function Signature (STRICT) ```python from pathlib import Path from meu_replication.config import BLD # CORRECT: Explicit dependencies and products def task_clean_data( depends_on: Path = BLD / "data" / "raw.csv", produces: Path = BLD / "data" / "cleaned.csv", ) -> None: """Clean raw data.""" raw = pd.read_csv(depends_on) cleaned = clean_data(raw) # Pure function cleaned.to_csv(produces, index=False) # WRONG: No produces declared def task_clean_data(): # ❌ pd.read_csv("raw.csv").to_csv("cleaned.csv") # pytask can't track this ``` **Rules**: - Use `produces` for all outputs - Use other default arguments for dependencies - pytask uses these signatures to build the DAG - **Never write files not declared in `produces`** ### 3.3 Multiple Products ```python # Option 1: Dict of products (for related outputs) def task_fit_models( depends_on: Path = BLD / "data" / "cleaned.csv", produces: dict[str, Path] = { "model_1": BLD / "models" / "model_1.pkl", "model_2": BLD / "models" / "model_2.pkl", }, ) -> None: ... # Option 2: Loop with @task(id=...) for distinct tasks from meu_replication.config import COUNTRIES for country in COUNTRIES: @pytask.task(id=country) def task_fetch_data( produces: Path = BLD / "data" / f"{country}.csv", ) -> None: ... ``` ### 3.4 Task Hygiene - Task functions should be **short and boring** (read → transform → write) - Real logic goes in **pure helper functions** under `src/` - Never mutate raw inputs - Never write outside `produces` --- ## 4. DATA CLEANING: The Three Functional Rules ### 4.1 The Rules (Mandatory for All Cleaning Code) 1. **Start with an empty DataFrame** (construct cleaned columns from raw) 2. **Touch every variable only once** (each cleaned column assigned exactly once) 3. **Touch with a pure function** (no side effects, depends only on inputs) ### 4.2 Example: Good vs Bad ```python # GOOD: Functional cleaning def clean_data(raw: pd.DataFrame) -> pd.DataFrame: """Clean raw data following the three rules.""" return pd.DataFrame({ "date": clean_dates(raw["date_raw"]), "value": clean_values(raw["value_raw"]), "country": clean_country_codes(raw["geo"]), }) def clean_dates(dates: pd.Series) -> pd.Series: """Convert YYYY-MM format to datetime.""" return pd.to_datetime(dates, format="%Y-%m") # BAD: Mutating transformations def clean_data(df): # ❌ df["date"] = pd.to_datetime(df["date"]) # Mutates input df["value"] = df["value"].fillna(0) # Mutates again df.drop(columns=["old_col"], inplace=True) # More mutation return df # Unclear what happened ``` ### 4.3 Why These Rules Matter - **Debuggability**: Search for `"column_name"` finds exactly where it's defined - **No hidden state**: Can't have accidental dependencies between transformations - **Testability**: Pure functions are trivial to test - **Reproducibility**: Same inputs → same outputs, always --- ## 5. TESTING (Minimum Standard) ### 5.1 What to Test Test **behavior**, not implementation: - Typical inputs - Corner cases (empty data, missing values, edge values) - Error conditions (invalid inputs should raise informative errors) - **Every bug you've encountered** (regression tests) ### 5.2 Test Structure ```python import pytest import pandas as pd from meu_replication.data_management.clean import clean_dates def test_clean_dates_typical(): """Test typical YYYY-MM input.""" raw = pd.Series(["2024-01", "2024-02"]) result = clean_dates(raw) expected = pd.to_datetime(["2024-01-01", "2024-02-01"]) pd.testing.assert_series_equal(result, expected) def test_clean_dates_invalid(): """Test that invalid dates raise ValueError.""" raw = pd.Series(["not-a-date"]) with pytest.raises(ValueError, match="does not match format"): clean_dates(raw) @pytest.mark.parametrize("input_val,expected", [ ("2024-01", "2024-01-01"), ("2024-12", "2024-12-01"), ]) def test_clean_dates_parametrized(input_val, expected): """Parametrized tests for multiple cases.""" result = clean_dates(pd.Series([input_val])) assert result.iloc[0] == pd.Timestamp(expected) ``` ### 5.3 Testing Checklist - ✅ One assertion per test (when possible) - ✅ Test fails when it should (verify counterexample) - ✅ Use `pytest.raises(...)` for expected errors - ✅ Use `@pytest.mark.parametrize` to avoid duplication - ❌ No "or-style" assertions that can pass for wrong reasons --- ## 6. PLOTLY EXPORT (Static Figures for Documents) ### 6.1 Setup Kaleido (Browser for Static Export) ```bash # One-time setup in pixi environment pixi run plotly_get_chrome ``` ### 6.2 Export in pytask Tasks ```python import plotly.express as px from pathlib import Path def task_create_figure( depends_on: Path = BLD / "data" / "cleaned.csv", produces: Path = BLD / "figures" / "plot.png", ) -> None: """Create publication-ready static figure.""" df = pd.read_csv(depends_on) fig = px.line(df, x="date", y="value", title="My Plot") # Update layout for publication fig.update_layout( font=dict(size=14), title_font_size=16, showlegend=False, # Avoid unnecessary legends ) # Write static export fig.write_image(produces, width=800, height=600) ``` --- ## 7. DOCUMENTATION REQUIREMENTS ### 7.1 README Must Cover 1. **What**: Project purpose and pipeline entry point 2. **How**: Exact commands to install and run ```bash pixi install pixi run pytask pixi run pytest ``` 3. **Where**: Directory layout (src, bld, documents, etc.) 4. **Special requirements**: Runtime, memory, data restrictions, credentials ### 7.2 Replication Package Checklist For final submission: - ✅ Data availability statement - ✅ Variable definitions and metadata - ✅ Code for all transformations - ✅ Software dependencies (via `pixi.lock`) - ✅ Expected runtime estimate - ✅ License information - ✅ Document any omissions/deviations --- ## 8. DEBUGGING PLAYBOOK When something breaks: 1. **State expected behavior**: "What should this do?" 2. **Check environment**: Are you in the right pixi env? 3. **Minimal failing case**: Reduce to smallest example 4. **Isolate**: Test individual functions separately 5. **One change at a time**: Form hypothesis, test, repeat 6. **Write it down**: Turn failure into a regression test 7. **Prefer debugger over print**: Use `pdbp` breakpoints ```python # Add breakpoint for debugging import pdbp pdbp.set_trace() # Execution pauses here ``` --- ## 9. DEFINITION OF DONE (Checklist Before Commit) Before considering any change "done": - [ ] `pixi run pytest` passes - [ ] `pixi run pytask` completes successfully - [ ] No raw/source inputs edited in place - [ ] New outputs declared in `produces` and written only there - [ ] Logic in reusable helper functions (pure where feasible) - [ ] Bug fixes include regression tests - [ ] README/docs updated if commands/deps/outputs changed - [ ] `pixi.lock` committed if dependencies changed - [ ] No uncommitted changes remain - [ ] Code follows style (`pixi run prek` passes) --- ## 10. QUICK REFERENCE: Common Commands ```bash # Full pipeline pixi run pytask # Tests pixi run pytest # All tests pixi run pytest tests/test_specific.py # One file pixi run pytest -k test_function_name # One test # Pre-commit checks pixi run prek # Clean build (when DAG is confused) rm -rf bld/ _build/ pixi run pytask # View outputs pixi run view-paper # Paper with live reload pixi run view-pres # Presentation with live reload # Documentation pixi run -e docs docs # Build docs pixi run -e docs view-docs ``` --- ## 11. ANTI-PATTERNS TO AVOID ❌ **Mutating DataFrames in place** ```python df["new_col"] = ... # Creates side effects ``` ✅ **Constructing new DataFrames** ```python cleaned = pd.DataFrame({"new_col": ...}) ``` --- ❌ **Hardcoded absolute paths** ```python data = pd.read_csv("C:/Users/...") ``` ✅ **Relative paths from config** ```python from meu_replication.config import BLD data = pd.read_csv(BLD / "data" / "file.csv") ``` --- ❌ **Direct Python/pip calls** ```bash python script.py pip install pandas ``` ✅ **Always through Pixi** ```bash pixi run python script.py pixi add pandas ``` --- ❌ **Writing undeclared outputs** ```python def task_clean(): df.to_csv("output.csv") # pytask doesn't know about this ``` ✅ **Declaring all products** ```python def task_clean(produces: Path = ...): df.to_csv(produces) ``` --- ## 12. PROJECT-SPECIFIC NOTES ### Data Fetchers (Current State) - `eurostat.py`: 87 variables (Categories 1-6) — **Hardcoded to DE** - `ecb.py`: 52 variables (Cat 4, 7, 8) — **Cat 8 is EA-level (shared)** - `bis.py`: 1 variable (Cat 7 NEER) — **Already parameterized** - `oecd.py`: 8 variables (Cat 6, 7) — **Already parameterized** ### Next Phase: Multi-Country Expansion **To parameterize**: 1. Eurostat: Replace `geo="DE"` and `"DE_"` prefixes with country parameter 2. ECB Cat 4/7: Replace `.DE.` in SDMX keys with `{country}` placeholder 3. ECB Cat 8: Fetch once (EA-level), share across all countries **19 EA members to support**: DE, FR, IT, ES, NL, BE, AT, FI, GR, PT, IE, SK, SI, LT, LV, EE, LU, CY, MT --- ## 13. REVIEW RULES ADDED FROM THE 2026-04-16 AUDIT ### 13.1 Docstrings Must Describe Behavior First - Start the first sentence with what the function does in domain terms. - Mention purity, determinism, or EPP rules only after the behavior is clear. - Avoid openings like `Pure function`, `Short and boring`, or `Follows EPP rules` as the main explanation. ### 13.2 Validation Must Fail Loudly or Be Explicitly Documented - If code checks an argument, dependency, or intermediate object, either raise an informative exception immediately or return a clearly documented sentinel result. - Do not silently continue after detecting invalid state. - If writing an empty output is intentional, say so in the docstring and cover that branch with tests. ### 13.3 Prefer Named Results Over Complex Return Statements - Avoid multi-step DataFrame construction, filtering, and sorting chains directly inside `return`. - Assign the final object to a well-named variable, then return that variable. - Treat this as especially important in cleaning and standardization code. ### 13.4 Separate Heavy Computation From Lightweight Reporting - Keep long-running estimation tasks separate from normalization, README, plot, and report-rendering tasks. - If a task writes both audit tables and a markdown report, keep rendering thin and consider splitting it once the task becomes hard to scan. ### 13.5 Treat Registry Expansion As Pipeline-Critical - The registry is not just an auxiliary file; it defines fetch, cleaning, and transformation behavior. - Either integrate registry expansion into the DAG or keep a strong parity test plus a clearly documented regeneration command. - Never allow templates, countries, and committed registry to drift silently. ### 13.6 Use Evidence-Based Reproducibility Reviews - For a reproducibility audit, run: - `pixi run pytest` - `pixi run pytest --cov=src/meu_replication --cov-report=term-missing` - `pixi run pytask collect` - Only claim that the full pipeline was verified if `pixi run pytask` was actually run to completion. --- ## FINAL REMINDER **Reproducibility = Someone else can get your exact results** This requires: 1. Exact environment (`pixi.lock`) 2. Complete DAG (`pytask` with all `produces` declared) 3. No hidden mutations (functional data cleaning) 4. No manual steps (everything scripted) 5. No uncommitted changes (main branch is source of truth) **When in doubt, ask: "Could a collaborator reproduce this from a clean checkout?"**

Security Status