@wentorai/research-plugins 1.0.0 → 1.2.0

package/skills/analysis/econometrics/econml-causal-guide/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: econml-causal-guide
+description: "Apply EconML for causal inference combining machine learning and econometrics"
+metadata:
+  openclaw:
+    emoji: "🔬"
+    category: "analysis"
+    subcategory: "econometrics"
+    keywords: ["causal-inference", "machine-learning", "treatment-effects", "econometrics", "microsoft", "double-ml"]
+    source: "https://github.com/py-why/EconML"
+---
+
+# EconML Causal Inference Guide
+
+## Overview
+
+EconML is a Python package developed by Microsoft Research as part of the ALICE (Automated Learning and Intelligence for Causation and Economics) project. It provides a comprehensive suite of methods for estimating heterogeneous treatment effects from observational data, bridging the gap between modern machine learning and classical econometric techniques for causal inference.
+
+Traditional econometric approaches to causal inference often rely on strong parametric assumptions and struggle with high-dimensional data. Pure machine learning methods excel at prediction but do not inherently distinguish correlation from causation. EconML combines the strengths of both paradigms, offering methods that leverage the flexibility of ML for nuisance parameter estimation while maintaining the rigorous causal identification guarantees of econometric theory.
+
+The library implements cutting-edge methods from the academic literature including Double Machine Learning (DML), Causal Forests, Doubly Robust Learners, Orthogonal Random Forests, and Instrumental Variable methods with ML first stages. These tools are essential for researchers across economics, public health, education policy, and any field where understanding causal mechanisms from non-experimental data is critical.
+
+## Installation and Setup
+
+Install EconML via pip:
+
+```bash
+pip install econml
+```
+
+For the full feature set including optional dependencies:
+
+```bash
+pip install econml[all]
+```
+
+EconML builds on top of scikit-learn and integrates with the broader Python data science ecosystem. Core dependencies include numpy, scipy, pandas, scikit-learn, and statsmodels. Optional dependencies for specific estimators include LightGBM and PyTorch.
+
+Verify installation:
+
+```python
+import econml
+print(econml.__version__)
+
+from econml.dml import LinearDML
+from econml.orf import DMLOrthoForest
+print("EconML loaded successfully")
+```
+
+## Core Estimators and Methods
+
+**Double Machine Learning (DML)**: The workhorse method for estimating average and heterogeneous treatment effects while controlling for high-dimensional confounders. DML uses cross-fitting and orthogonalization to eliminate regularization bias:
+
+```python
+from econml.dml import LinearDML, CausalForestDML
+from sklearn.ensemble import GradientBoostingRegressor
+
+# Linear DML for parametric treatment effect estimation
+est = LinearDML(
+    model_y=GradientBoostingRegressor(),
+    model_t=GradientBoostingRegressor(),
+    cv=5,
+    random_state=42
+)
+est.fit(Y, T, X=X, W=W)
+
+# Get treatment effect estimates with confidence intervals
+effect = est.effect(X_test)
+ci = est.effect_interval(X_test, alpha=0.05)
+print(f"ATE: {est.ate():.4f}")
+print(f"ATE 95% CI: {est.ate_interval(alpha=0.05)}")
+```
+
+Here `Y` is the outcome, `T` is the treatment, `X` contains effect modifiers (features for heterogeneity), and `W` contains additional confounders.
+
+**Causal Forest DML**: Combines DML orthogonalization with Causal Forest estimation for flexible, nonparametric heterogeneous treatment effects:
+
+```python
+from econml.dml import CausalForestDML
+
+cf_est = CausalForestDML(
+    model_y=GradientBoostingRegressor(),
+    model_t=GradientBoostingRegressor(),
+    n_estimators=200,
+    min_samples_leaf=10,
+    cv=5,
+    random_state=42
+)
+cf_est.fit(Y, T, X=X, W=W)
+
+# Heterogeneous treatment effects
+hte = cf_est.effect(X_test)
+# Feature importance for treatment effect heterogeneity
+importances = cf_est.feature_importances_
+```
+
+**Doubly Robust Learner**: Provides consistent treatment effect estimates when either the outcome model or the propensity score model is correctly specified:
+
+```python
+from econml.dr import DRLearner
+from sklearn.ensemble import RandomForestClassifier, RandomForestRegressor
+
+dr_est = DRLearner(
+    model_propensity=RandomForestClassifier(),
+    model_regression=RandomForestRegressor(),
+    model_final=RandomForestRegressor(),
+    cv=5
+)
+dr_est.fit(Y, T, X=X, W=W)
+```
+
+**Instrumental Variable Methods**: For settings where unobserved confounding is present but valid instruments are available:
+
+```python
+from econml.iv.dml import DMLIV
+
+iv_est = DMLIV(
+    model_y_xw=GradientBoostingRegressor(),
+    model_t_xw=GradientBoostingRegressor(),
+    model_t_xwz=GradientBoostingRegressor(),
+    cv=5
+)
+iv_est.fit(Y, T, Z=Z, X=X, W=W)
+```
+
+## Research Workflow Integration
+
+**Experiment Analysis**: When randomized experiments suffer from non-compliance or attrition, use IV methods in EconML to recover local average treatment effects. The ML-based first stages handle complex relationships between instruments and treatment uptake.
+
+**Policy Evaluation**: Estimate heterogeneous treatment effects to identify which subpopulations benefit most from an intervention. The CATE (Conditional Average Treatment Effect) estimates can directly inform targeted policy design:
+
+```python
+# Identify subgroups with largest treatment effects
+import pandas as pd
+
+effects_df = pd.DataFrame({
+    "effect": cf_est.effect(X_test).flatten(),
+    "ci_lower": cf_est.effect_interval(X_test, alpha=0.05)[0].flatten(),
+    "ci_upper": cf_est.effect_interval(X_test, alpha=0.05)[1].flatten()
+}, index=X_test.index)
+
+# Top beneficiaries
+top_group = effects_df.nlargest(100, "effect")
+```
+
+**Sensitivity Analysis**: Combine EconML estimates with sensitivity analysis frameworks to assess robustness to potential unobserved confounders. Report how much unmeasured confounding would be required to explain away your findings.
+
+**Publication-Ready Results**: EconML provides confidence intervals and hypothesis tests based on asymptotic theory, producing results suitable for peer-reviewed publications. Use the summary methods to generate formatted regression-style output.
+
+## Best Practices for Academic Research
+
+1. **Always validate assumptions**: DML requires conditional ignorability (selection on observables). Document your identification strategy clearly.
+2. **Cross-fitting is essential**: Never skip the cross-fitting step, as it prevents overfitting bias in the nuisance estimates.
+3. **Report multiple estimators**: Present results from DML, DR Learner, and Causal Forest side by side to assess robustness.
+4. **Check overlap**: Verify sufficient overlap in covariate distributions between treated and control groups before estimation.
+5. **Use honest estimation**: EconML Causal Forests use sample splitting for honesty by default, ensuring valid inference.
+
+## References
+
+- EconML repository: https://github.com/py-why/EconML
+- EconML documentation: https://econml.azurewebsites.net/
+- Chernozhukov et al. (2018), Double/Debiased Machine Learning for Treatment and Structural Parameters
+- Athey and Imbens (2019), Machine Learning Methods That Economists Should Know About

package/skills/analysis/econometrics/empirical-paper-analysis/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: empirical-paper-analysis
+description: "Systematic framework for analyzing empirical law and economics papers"
+metadata:
+  openclaw:
+    emoji: "⚖️"
+    category: "analysis"
+    subcategory: "econometrics"
+    keywords: ["empirical analysis", "law and economics", "identification strategy", "causal inference", "robustness checks", "research methodology"]
+    source: "https://clawhub.ai/zhouziyue233/empirical-paper-analysis-skill"
+---
+
+# Empirical Paper Analysis Framework
+
+## Overview
+
+This framework provides a systematic approach to reading, evaluating, and critiquing empirical research papers in law and economics and related social science fields. It covers identification strategy assessment, data evaluation, robustness check analysis, and constructive critique formulation. Use this when reviewing papers for seminars, referee reports, or your own literature reviews.
+
+## The 6-Step Analysis Framework
+
+### Step 1: Identify the Research Question
+
+Extract the core question and decompose it:
+
+```
+Template:
+- Research Question: [What causal/descriptive claim does the paper make?]
+- Unit of analysis: [individual / firm / state / country-year]
+- Outcome variable (Y): [What is being explained?]
+- Key explanatory variable (X): [What is the treatment or variable of interest?]
+- Claimed relationship: [X → Y via what mechanism?]
+```
+
+**Red flags**:
+- Vague or shifting research question across sections
+- Mismatch between stated question and actual regression specification
+- Question that is purely correlational framed as causal
+
+### Step 2: Evaluate the Identification Strategy
+
+The identification strategy is how the paper argues for causal interpretation. Map it to a known framework:
+
+| Strategy | Key Assumption | What to Check |
+|----------|---------------|---------------|
+| **OLS** | No omitted variable bias (E[u\|X]=0) | Control variable completeness, R² sensitivity |
+| **IV / 2SLS** | Exclusion restriction (instrument affects Y only through X) | First stage F-stat (>10), instrument validity argument |
+| **Difference-in-Differences** | Parallel trends (absent treatment, treated and control would trend similarly) | Pre-treatment parallel trends test, event study plot |
+| **Regression Discontinuity** | No manipulation at cutoff, continuity of potential outcomes | McCrary density test, covariate balance at cutoff |
+| **Matching / PSM** | Selection on observables (no unobservable confounders) | Balance tables, common support, sensitivity to caliper |
+| **Synthetic Control** | Pre-treatment fit quality, no spillovers | RMSPE ratio, placebo tests on donor pool |
+
+**Questions to ask**:
+- Is the identification assumption stated explicitly?
+- Is there a **falsification test** (placebo treatment, placebo outcome)?
+- Could there be **reverse causality**?
+- Are there **spillover effects** that violate SUTVA?
+
+### Step 3: Assess the Data
+
+```
+Data Evaluation Checklist:
+□ Source: Is the data publicly available or proprietary?
+□ Sample period: Does it match the question? Any structural breaks?
+□ Sample size: Sufficient for the method? Power analysis?
+□ Attrition: Is there selective dropout? Attrition tables?
+□ Measurement: Are key variables measured directly or proxied?
+□ External validity: Is the sample representative of the population of interest?
+```
+
+**Common data issues in law and economics**:
+- Court case data: selection into litigation (Priest-Klein hypothesis)
+- Regulatory data: endogenous timing of policy changes
+- Survey data: response bias, recall bias
+- Administrative data: measurement captures legal definitions, not economic concepts
+
+### Step 4: Evaluate the Empirical Specification
+
+Examine the main regression equation:
+
+```
+Y_it = α + β·X_it + γ·Controls_it + θ_i + λ_t + ε_it
+
+Where:
+  Y_it        = outcome for unit i at time t
+  X_it        = treatment / variable of interest
+  Controls_it = control variables
+  θ_i         = unit fixed effects
+  λ_t         = time fixed effects
+  ε_it        = error term
+  β           = coefficient of interest
+```
+
+**Check**:
+- Is `β` the causal parameter of interest, or just an association?
+- Are fixed effects appropriate? (Individual FE removes time-invariant confounders)
+- What is the **clustering level** for standard errors? (Should match treatment assignment level)
+- Are control variables themselves **bad controls** (post-treatment variables that are affected by X)?
+
+### Step 5: Scrutinize Robustness Checks
+
+A well-executed paper should include several:
+
+| Robustness Check | Purpose | What to Look For |
+|-----------------|---------|-----------------|
+| **Alternative specifications** | Drop/add controls | Does β sign/magnitude change? |
+| **Alternative samples** | Trim outliers, restrict subgroups | Is result driven by a small subset? |
+| **Placebo tests** | Fake treatment date, fake outcome | Should find null results |
+| **Alternative clustering** | State vs. county vs. firm | Does significance survive? |
+| **Bounding exercises** | Oster (2019) bounds, Altonji ratio | How large would selection on unobservables need to be? |
+| **Leave-one-out** | Drop each unit/period | Is result driven by a single observation? |
+| **Event study** | Dynamic treatment effects plot | Are pre-treatment coefficients zero? |
+
+**Warning signs**:
+- Only showing robustness checks that "work" (selective reporting)
+- No sensitivity analysis on key assumptions
+- Robustness table hidden in appendix with different significance levels
+
+### Step 6: Formulate Constructive Critique
+
+Structure your critique as:
+
+```markdown
+## Summary
+[2-3 sentences on what the paper does and finds]
+
+## Strengths
+- [Identification strategy strength]
+- [Data quality strength]
+- [Policy relevance]
+
+## Main Concerns
+
+### Concern 1: [Identification]
+- Issue: [What specific assumption is violated or untested?]
+- Evidence: [What in the paper supports your concern?]
+- Suggestion: [What analysis would address this?]
+
+### Concern 2: [Data/Measurement]
+- Issue: ...
+- Evidence: ...
+- Suggestion: ...
+
+### Concern 3: [Specification]
+- Issue: ...
+- Evidence: ...
+- Suggestion: ...
+
+## Minor Comments
+- [Table formatting, typos, unclear notation]
+```
+
+## Quick Reference: Common Mistakes
+
+| Mistake | Why It's Wrong | Fix |
+|---------|---------------|-----|
+| Clustering at wrong level | Understated SEs, inflated t-stats | Cluster at treatment assignment level |
+| Bad controls | Including post-treatment variables biases β | Only control for pre-treatment variables |
+| Cherry-picked specification | Overfitting to significance | Pre-register or show full specification curve |
+| Ignoring multiple testing | Family-wise error rate inflation | Bonferroni or Benjamini-Hochberg correction |
+| Log of zero | Undefined, ad hoc fixes (log(Y+1)) introduce bias | IHS transform or Poisson pseudo-MLE |
+| Winner's curse | Published effect sizes are biased upward | Check if effect is plausible given prior literature |
+
+## Example: Analyzing a DiD Paper
+
+```
+Paper claim: "Adopting e-filing reduces case processing time by 15%"
+
+Step 1: RQ = Does e-filing (X) cause faster case processing (Y)?
+Step 2: DiD with staggered adoption across courts
+  - Check: parallel trends plot for early vs. late adopters
+  - Check: recent DiD literature (de Chaisemartin & D'Haultfoeuille 2020)
+    warns that TWFE with staggered treatment can be biased
+Step 3: Data from court administrative records (2005-2020)
+  - Check: is adoption timing truly exogenous? (Courts with backlogs
+    might adopt earlier → selection bias)
+Step 4: log(processing_days)_it = β·efiling_it + court_FE + year_FE + ε_it
+  - Concern: no controls for court budgets, judge turnover
+Step 5: Robustness: event study plot, drop large courts, alternative
+  measure of processing time → β stable around -0.15
+Step 6: Credible but could be strengthened with:
+  - Callaway & Sant'Anna (2021) estimator for staggered DiD
+  - Instrument for adoption timing
+  - Heterogeneity by court size and case type
+```
+
+## References
+
+- Angrist, J. D., & Pischke, J. S. (2009). *Mostly Harmless Econometrics*. Princeton University Press.
+- Oster, E. (2019). "Unobservable Selection and Coefficient Stability." *Journal of Business & Economic Statistics*.
+- de Chaisemartin, C., & D'Haultfoeuille, X. (2020). "Two-Way Fixed Effects Estimators with Heterogeneous Treatment Effects." *AER*.
+- Callaway, B., & Sant'Anna, P. H. (2021). "Difference-in-Differences with Multiple Time Periods." *Journal of Econometrics*.
+- [Empirical Legal Studies Resources](https://www.law.northwestern.edu/research-faculty/clbe/events/empiricallegalstudies/)

package/skills/analysis/econometrics/mostly-harmless-guide/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: mostly-harmless-guide
+description: "Replication code and guide for Mostly Harmless Econometrics methods"
+version: 1.0.0
+author: wentor-community
+source: https://github.com/vikjam/mostly-harmless-replication
+metadata:
+  openclaw:
+    category: "analysis"
+    subcategory: "econometrics"
+    keywords:
+      - econometrics
+      - causal-inference
+      - replication
+      - regression
+      - instrumental-variables
+      - difference-in-differences
+---
+
+# Mostly Harmless Econometrics Guide
+
+A skill providing replication code, explanations, and practical guidance for the econometric methods presented in Angrist and Pischke's "Mostly Harmless Econometrics" (MHE). Based on the mostly-harmless-replication repository (642 stars), this skill helps researchers understand and correctly apply core causal inference techniques.
+
+## Overview
+
+"Mostly Harmless Econometrics" is one of the most influential applied econometrics textbooks, providing accessible explanations of the methods that dominate modern empirical research in economics and increasingly in other social sciences. This skill translates the book's core methods into practical guidance that the agent can use to help researchers design studies, select appropriate estimators, and interpret results correctly.
+
+The skill covers regression, instrumental variables, difference-in-differences, regression discontinuity, and related methods, with emphasis on the practical decisions researchers face when applying these techniques to real data.
+
+## Regression Fundamentals
+
+**Ordinary Least Squares (OLS)**
+- OLS provides the best linear approximation to the conditional expectation function
+- The regression anatomy theorem: each coefficient can be obtained from a bivariate regression of the outcome on the residualized regressor
+- Omitted variable bias formula: bias equals the effect of the omitted variable times its correlation with the included regressor
+- Control variables should be selected based on the conditional independence assumption, not on statistical significance
+- Robust standard errors (Huber-White) should be the default; cluster when observations are not independent
+
+**Regression Interpretation**
+- The causal interpretation of regression requires the conditional independence assumption (CIA)
+- CIA states that treatment is as good as randomly assigned after conditioning on controls
+- Saturated models (fully interacted categorical variables) are always correctly specified
+- Linear regression with continuous variables approximates the true conditional expectation
+- Report both statistical and economic significance; a large t-statistic does not mean a large effect
+
+**Practical Decisions**
+- Include controls that are correlated with both the treatment and outcome
+- Do not include controls that are consequences of treatment (bad controls)
+- Use the most parsimonious specification that satisfies the CIA
+- Test sensitivity to alternative control sets to assess robustness
+- Report multiple specifications to demonstrate that results are not driven by a particular set of controls
+
+## Instrumental Variables
+
+**Core Concepts**
+- IV addresses endogeneity when the treatment is correlated with unobserved factors affecting the outcome
+- A valid instrument must be relevant (correlated with treatment) and excludable (affects outcome only through treatment)
+- Two-stage least squares (2SLS) is the standard IV estimator
+- The Wald estimator (reduced form divided by first stage) gives the IV estimate in the simplest case
+- IV estimates the Local Average Treatment Effect (LATE) for compliers
+
+**Implementation Guide**
+- Always report the first-stage F-statistic; values below 10 indicate weak instruments
+- Use the Anderson-Rubin test for inference robust to weak instruments
+- Over-identification tests (Sargan-Hansen) can detect violations of the exclusion restriction with multiple instruments, but cannot validate a just-identified model
+- Report the first stage, reduced form, and IV estimates together
+- Compare OLS and IV estimates; if IV is much larger, consider LATE interpretation or measurement error
+
+**Common Applications**
+- Returns to education using quarter of birth as an instrument
+- Effect of institutions on growth using settler mortality as an instrument
+- Peer effects using random assignment to groups
+- Supply and demand estimation using shift variables
+- Policy evaluation using eligibility rules as instruments
+
+## Difference-in-Differences
+
+**Design Principles**
+- DID compares changes in outcomes over time between treated and control groups
+- The parallel trends assumption: absent treatment, both groups would have followed the same trend
+- DID removes time-invariant unobserved confounders
+- The standard estimator is a two-way fixed effects regression (unit and time fixed effects plus treatment indicator)
+- Staggered adoption designs require careful attention to treatment timing heterogeneity
+
+**Implementation**
+- Always plot pre-treatment trends to assess the parallel trends assumption visually
+- Include leads of the treatment indicator to test for pre-trends formally
+- Cluster standard errors at the group level (state, firm, school)
+- With few clusters (fewer than 50), use wild cluster bootstrap for inference
+- Consider synthetic control methods when the control group is not a natural comparator
+
+**Recent Developments**
+- Callaway and Sant'Anna (2021): heterogeneity-robust DID with staggered treatment
+- Sun and Abraham (2021): interaction-weighted estimator for event studies
+- de Chaisemartin and D'Haultfoeuille (2020): decomposition of two-way FE estimator
+- Goodman-Bacon (2021): DID with variation in treatment timing decomposition
+- These methods address bias in standard two-way FE when treatment effects are heterogeneous
+
+## Regression Discontinuity
+
+**Sharp RD Design**
+- Treatment is a deterministic function of a running variable at a known cutoff
+- Causal effect is identified at the cutoff by comparing outcomes just above and just below
+- Local linear regression is preferred over global polynomial fitting
+- Bandwidth selection should use data-driven methods (Imbens-Kalyanaraman, Calonico-Cattaneo-Titiunik)
+- Always show the RD plot: binned means of the outcome against the running variable
+
+**Fuzzy RD Design**
+- Treatment probability jumps at the cutoff but is not deterministic
+- Fuzzy RD is analogous to IV where the instrument is being above the cutoff
+- Estimates a LATE for units whose treatment status is changed by crossing the cutoff
+- Report both the first stage (jump in treatment probability) and the reduced form (jump in outcome)
+- Validity requires that other covariates do not jump at the cutoff (density test, covariate balance)
+
+**Practical Guidance**
+- Test for manipulation of the running variable using the McCrary density test
+- Show robustness to alternative bandwidth choices
+- Include covariates to improve precision but the estimate should not change substantially
+- Avoid high-order polynomial specifications that can be misleading
+- Report the effective sample size used in the local estimation
+
+## Integration with Research-Claw
+
+This skill enhances the Research-Claw econometric analysis workflow:
+
+- Guide researchers in selecting the appropriate causal inference method for their question
+- Help implement estimators correctly with proper standard errors and diagnostics
+- Provide code templates for common econometric analyses in R, Stata, and Python
+- Connect with data wrangling skills for cleaning and preparing analysis datasets
+- Support writing skills with correctly formatted regression tables and result descriptions
+
+## Best Practices
+
+- Start by clearly stating the causal question and the source of identification
+- Draw a directed acyclic graph (DAG) to clarify assumptions about causal relationships
+- Report all relevant diagnostics (first-stage F, pre-trends, balance tests)
+- Show robustness across specifications rather than selecting a single preferred model
+- Distinguish between statistical significance, economic significance, and policy relevance
+- Be transparent about the limitations of your identification strategy