---
title: "Introduction to heter_endo_gmm in order to estimate heterogeneous peer effect when identity equals eligibility"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Introduction to two_step_gmm in order to estimate heterogeneous peer effect}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

```{r setup}
library(heterogeneouspeereffects)
```
# Heterogeneous Peer Effects

The package **"Heterogeneous Peer Effects"** aims to estimate individual responses within groups. Our contribution to the standard linear-in-means model is that we allow individuals to respond differently to the outcomes of their peers depending on both their **identity** and **eligibility** for treatment.

- **Identity** refers to an observable characteristic of an individual (e.g., race, gender).
- **Eligibility** indicates whether an individual is allowed to receive the treatment.

In the function `heter_endo_gmm`, we assume that identity and eligibility coincide, meaning that eligibility is determined by identity (e.g., being Black or White). Specifically, we distinguish between:
- **Within-group peer effects** (*theta within*): interactions between individuals sharing the same identity.
- **Between-group peer effects** (*theta between*): interactions between individuals of different identities.

We propose a simple methodology to identify and estimate the model using **partial population experiments**, where only a subset of individuals within a group is eligible for treatment, and the proportion of eligible individuals varies across groups. The estimation procedure relies on the **Generalized Method of Moments (GMM)**.

---

## Assumptions

Our method is based on the following key assumptions:

1. **Linear-in-Means Model with Panel Data**  
   - The outcome depends linearly on both the average outcome and the treatment status.

2. **Treatment Distribution Assumption**  
   - For each observed share of eligible individuals in the population, there exist both treated and control groups.

3. **Conditional Common Trends**  
   - In the absence of treatment, the average change in aggregate outcomes among eligible individuals in treated groups would have been the same as in control groups.

4. **Stable Share of Eligibles**  
   - The proportion of eligible individuals within a group remains constant over time.

---

## Data Requirements

To apply this methodology, the data must meet the following criteria:

- Each group (e.g., districts) must contain both **Eligible** and **Non-Eligible** individuals.
- Groups must be categorized as either **Treated** or **Non-Treated**.
- Example: In analyzing the impact of **Rosenwald schools** on school attendance:
  - **Eligible individuals** = Black residents
  - **Non-Eligible individuals** = White residents
  - **Treated groups** = Districts that received Rosenwald schools

The analysis is conducted at an **aggregate level**, considering average outcomes within each group.

---

## Estimation Procedure

To estimate the model, the following variables are required:

- `s` : Proportion of eligible individuals in the group (vector)
- `YN` : Average outcome for **non-eligible** individuals in the group (vector)
- `YE` : Average outcome for **eligible** individuals in the group (vector)
- `D` : Binary treatment indicator for the group (vector)
- `n_param` : Number of parameters to estimate (`=5` by default or `=3` for a restricted model)

---

## Usage Examples

### Estimating `delta`, `theta_within`, and `theta_between` with 5 parameters:
```r
# Run estimation with default parameters (5 parameters)
test_nocov <- heter_endo_gmm(YE, YN, D, s)

# View results
print(test_nocov)
```

### Estimating with a 3-parameter model:
```r
# Run estimation with 3 parameters
test_bis <- heter_endo_gmm(YE, YN, D, s, n_param = 3)
```

---

### Outcomes

This package return the estimated coefficients (and their p_values of ):
- direct effect of treatment (delta)
- intra group effect of treatment (theta_within)
- inter group effect of treatment (theta_between)
---

This package provides a flexible and robust framework for estimating heterogeneous peer effects in grouped data, making it applicable to various empirical settings, such as education, labor markets, and social networks.