# Tradução Python auditável do repositório OSF 8br39 (Van de Werfhorst, 2024)

**Data:** outubro de 2026. **Escopo:** código efetivamente inspecionado no ZIP `8br39-osfstorage-archive.zip`. **Não representa replicação integral dos 40 países, nem inclusão brasileira validada.**

## O que foi traduzido e executado

O repositório disponibilizado contém **três scripts Stata `.do` e duas bases auxiliares `.dta`**. No presente trabalho foram implementados, em Python, procedimentos estatísticos essenciais do fluxo original, incluindo:

| Procedimento Stata original | Python | Estado |
|---|---|---|
| `02` linhas 1380–1406: coortes, três níveis educacionais ESS | `prepare_common.py` | Implementação e teste sintético possível; requer dados ESS para verificação empírica |
| `02` linhas 741–746: indicadores `unicap` na idade 15 | `prepare_common.py` | Implementado; `unicap.dta` disponível |
| `01` e `02` linhas 1443–1485: ajuste da distribuição educacional quando ocupação parental falta | `oed_python.py`: `missing_parent_education_correction` | Implementado; fonte completa antes do filtro OED exigida |
| `02` linhas 1492–1495: `wridit` por país-coorte ponderado por `w8i` | `oed_python.py`: `ridits_by_cohort` | Implementado; **equivalência exata a versão do plugin `wridit` ainda a validar** |
| `03` linhas 89–132: seleção, três níveis educacionais, n_e>20 | `oed_python.py`: `estimate_cohort_frame` | Implementado |
| `03` linhas 295–532: persistência e decomposição OED com variâncias do Stata | `oed_python.py`: `oed_first_stage` | Implementado e testado linha-a-linha na álgebra principal |
| `03` linhas 150–273 e 375–530: simulações educacionais 1/2/4 | `oed_python.py`: `oed_first_stage` | Implementado; simulação 3 requer referência da distribuição de 1950–54 por país e dados completos |
| `03` linhas 673–689: pesos de precisão `1/se`, depois multiplicados por `w8i` | `oed_python.py`: `estimate_cohort_frame` | Implementado; não confundir com ponderação da regressão de primeiro estágio |
| `03` linhas 809–922, 1189–1230: FE de país ponderados para BB/BW | `oed_second_stage.py`: `matrix_fe`, `main_models` | Implementado com sanduíche robusto conjunto **aproximado ao `suest`**, requer validação com Stata |
| `03` linhas 930–975: IV com FE e instrumento `compend` | `oed_second_stage.py`: `iv_country_fe` | **Somente coeficiente pontual 2SLS**, sem replicação dos testes de endogeneidade, variâncias e diagnósticos `ivreg2` |

### O que NÃO foi traduzido/validado na íntegra

- A enorme recodificação **país × ano × onda** do ISSP em `01` (~8 mil linhas); faltam 13 entradas internacionais específicas, tabelas de correspondência ocupacional e documentação de suas versões. O `.do` original é incluído intacto.
- A harmonização ESS detalhada em `02`, especialmente a correspondência de ocupações parentais e auxiliares privados; não temos `ess1_10_OED.dta`, `ESS1234567.dta`, `isco08_isco88.dta`, `reform_data_track.dta`, `tertgross.dta`.
- A estimação `slogit` (modelo estereotípico), pacotes específicos Stata, todos os gráficos e tabelas suplementares; `suest` foi aproximado no nível de equações e não confrontado numericamente.
- A reconstrução dos **175.804 registros internacionais** e de seus coeficientes: falta o arquivo `dataready.dta` gerado ao fim do processamento original. `agg.dta` também não integra o ZIP.

## Achado metodológico decisivo

O script `03` **não** utiliza apenas `Cov(O,D|E)/Var(O)` como coeficiente direto. Os comandos fazem, por combinação país-coorte:

1. `reg d o` fornece o erro-padrão de uma regressão simples **não ponderada** no primeiro nível.
2. `bw_e` é a inclinação da regressão OD dentro de cada nível educacional.
3. O coeficiente direto no script usa **variâncias amostrais** `Var(O|E=e)` (Stata `summ`, divisor `n_e−1`):

   `bw = Σ_e [p_e × Var_{n−1}(O|e) × bw_e] / Σ_e [p_e × Var_{n−1}(O|e)]`.

4. O total salvo como `b` em `03` é **reconstruído** pela soma de termos usando as variâncias com denominador `N` de Bloome et al.; pode diferir ligeiramente do coeficiente `reg d o`. O código Python reporta ambos em `b` e `b_reg_ols`.
5. O componente indireto é `bb = b − bw`.
6. A segunda etapa normaliza `1/se(reg d o)`, multiplica por `w8i` e agrega as observações ao nível país-coorte.

A diferença amostral `bw − coeficiente de reg d o i.e` pode ser minúscula, mas não deve ser ocultada numa replicação exata. O Python produz também `bw_reg_fe` para auditoria. O modelo está preservado *como codificado*, sem impor outra decomposição teórica.

## Execução real com os dados brasileiros fornecidos

Executamos `run_brasil_pnad2014.py` sobre a amostra individual PNAD 2014 **sem identificadores**, usando o mapa CBO-Domiciliar → ISCO-88 de 2 dígitos e ISEI agregado. O resultado:

- 15.727 observações na amostra analítica previamente extraída.
- 14.954 com duas ocupações classificáveis na escala ISEI2 sob a concordância atual (ainda auditável).
- 7 coortes de 1945–1979; cada nível educacional tem mais de 20 registros.
- `ridit` de origem e destino por coorte calculado com os pesos disponíveis da PNAD; regressões da primeira etapa sem ponderação, conforme `03`.
- Correções provisórias ocupacionais CBO-Dom `5121` e `5174`. Revisão de ISCO de quatro dígitos **pendente**.
- **Ainda falta** usar o universo original com ocupação parental ausente para a correção diferencial por educação (`w8_e`) e verificar a correspondência de todas as classificações internacionais e desenho amostral.

Resultados: `resultados/Brasil_PNAD2014_OED_formula_OSF_isei2.csv`. Não devem ser comparados inferencialmente à média publicada dos 40 países antes de harmonização completa.

```bash
python run_brasil_pnad2014.py \
  --pnad insumos_brasil/amostra_analitica_sem_identificadores.csv \
  --crosswalk insumos_brasil/concordancia_ampliada_CBO_ISCO88.csv \
  --isei insumos_brasil/isei_ISCO88_2digitos_publicado.csv \
  --out resultados/
```

## Como executar quando `dataready.dta` dos 40 países estiver disponível

```bash
pip install -r requirements.txt
python run_original_40.py \
  --input /CAMINHO/dataready.dta \
  --validcc original/validcc.dta \
  --out resultados_internacionais/
```

Esse fluxo executará o núcleo de estimação Python nos dados originais e confrontará seus coeficientes com as metas do artigo, mas exigirá auditoria dos filtros, ponderação, `suest` e microdados originais. Sem o arquivo, a função encerra com erro explícito em vez de fabricar observações.

## Testes executáveis

```bash
python -m pytest -q testes/test_osf_python.py
```

Os testes incluem identidades dos componentes, equivalência de `reg d o`/`reg d o i.e` aos modelos de referência em dados **sintéticos**, verificação de `bw` calculado com variâncias amostrais, idades e coortes, pesos de origem, regressão contextual e validade das 297 combinações país-coorte. Não constituem reprodução dos coeficientes de 40 países.

## Próxima dependência crítica

Solicitar `dataready.dta` ao autor para validar os coeficientes originais, ou reunir todos os arquivos ESS/ISSP e respectivas concordâncias para reconstruí-lo. **A tradução de linguagem de programação não fornece os microdados ausentes.**

## Conteúdo do pacote e advertência de privacidade

O pacote inclui a amostra analítica brasileira **sem identificadores nominativos** produzida na etapa anterior, junto com duas tabelas de correspondência e resultados derivados. Isso não substitui a reconstrução do suplemento PNAD original: o filtro prévio significa que faltam respondentes com ocupação parental ausente e é impossível calibrar o ajuste de seleção parental com este CSV sozinho. As bases ESS/ISSP ausentes **não** são incluídas.