panelbox 0.2.0__tar.gz

panelbox-0.2.0/.gitignore

@@ -0,0 +1,70 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json

panelbox-0.2.0/CHANGELOG.md

@@ -0,0 +1,237 @@
+# Changelog
+
+All notable changes to PanelBox will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Planned
+- Additional GMM estimators (LIML, CUE)
+- Advanced diagnostics (weak instrument tests, C-statistic)
+- Panel VAR models
+- Cointegration tests
+- Visualization tools
+
+## [0.2.0] - 2026-01-21
+
+### Added - Dynamic Panel GMM
+
+**Core Features:**
+- **Difference GMM** implementation (Arellano-Bond 1991)
+  - One-step, two-step, and iterative GMM
+  - Automatic instrument generation (GMM-style and IV-style)
+  - Collapse option to avoid instrument proliferation
+  - Windmeijer (2005) finite-sample standard error correction
+
+- **System GMM** implementation (Blundell-Bond 1998)
+  - Combines differenced and level equations
+  - Level instruments for highly persistent series
+  - More efficient than Difference GMM for weak instruments
+  - Difference-in-Hansen test for level instrument validity
+
+**Specification Tests:**
+- Hansen J-test for overidentification
+- Sargan test (homoskedastic version)
+- Arellano-Bond AR(1) and AR(2) tests
+- Instrument ratio monitoring (instruments / groups)
+
+**Unbalanced Panel Support:**
+- Smart instrument selection based on data availability
+- Automatic filtering of lags with <10% coverage
+- Pre-estimation warnings for problematic specifications
+- Post-estimation warnings for low observation retention
+- Panel balance diagnostics
+
+**Results Class:**
+- Comprehensive `GMMResults` class
+- Publication-ready summary tables
+- Coefficient tables with significance stars
+- Specification test interpretation
+- Diagnostic assessment tools
+
+### Added - Documentation
+
+**GMM Documentation:**
+- `panelbox/gmm/README.md` - Complete GMM reference (540 lines)
+- `docs/gmm/tutorial.md` - Comprehensive tutorial (650 lines)
+- `docs/gmm/interpretation_guide.md` - Results interpretation (420 lines)
+
+**Example Scripts:**
+- `examples/gmm/ols_fe_gmm_comparison.py` - Bias comparison (410 lines)
+- `examples/gmm/firm_growth.py` - Intermediate example (500 lines)
+- `examples/gmm/production_function.py` - Simultaneity bias (602 lines)
+- `examples/gmm/unbalanced_panel_guide.py` - Practical guide (532 lines)
+
+**Enhanced Docstrings:**
+- Added 4 practical examples to `DifferenceGMM` class
+- Added 3 comparison examples to `SystemGMM` class
+- Added 5 usage patterns to `GMMResults` class
+
+### Added - Infrastructure
+
+**Package Configuration:**
+- Updated `pyproject.toml` for v0.2.0
+- Created `MANIFEST.in` for distribution
+- Updated `__init__.py` with GMM exports
+- Version management in `__version__.py`
+
+**Quality Assurance:**
+- `.flake8` configuration for linting
+- `.pre-commit-config.yaml` for automated checks
+- `scripts/qa.sh` for quality checks
+- `QA_GUIDE.md` documentation
+
+### Improved - Robustness
+
+**Validation (Subfase 4.2):**
+- Validation against Arellano-Bond (1991) employment data
+- 72.8% observation retention (vs 0% before improvements)
+- Coefficient within credible range [0.733, 1.045]
+- All specification tests pass (AR(2) p=0.724)
+
+**Warning System:**
+- Pre-estimation warnings for:
+  - Unbalanced panels with many time dummies
+  - Not using collapse option
+- Post-estimation warnings for:
+  - Low observation retention (<30%)
+- Actionable recommendations in all warnings
+
+**Instrument Selection:**
+- `_analyze_lag_availability()` method
+- Automatic filtering of weak instruments
+- Coverage-based lag selection (≥10% threshold)
+- Prevents instrument proliferation
+
+### Changed
+
+- Updated package status from "Alpha" to "Beta"
+- Improved package description for PyPI
+- Updated Python version classifiers (3.9-3.12)
+- Enhanced main `__init__.py` with GMM imports
+
+### Fixed
+
+- Arellano-Bond validation now works with unbalanced panels
+- Time dummies no longer cause 0% observation retention
+- System GMM more robust with error handling
+- Better handling of missing observations in instruments
+
+### Performance
+
+- Smart instrument selection reduces computation time
+- Efficient NumPy operations throughout
+- Optimized instrument matrix construction
+- Reduced memory footprint with collapse option
+
+## [0.1.0] - 2025-12
+
+### Added - Core Framework
+
+**Core Classes:**
+- `PanelData` - Panel data container with validation
+- `FormulaParser` - R-style formula parsing (patsy integration)
+- `PanelResults` - Base results class
+
+**Static Models:**
+- `PooledOLS` - Pooled OLS estimation
+- `FixedEffects` - Within (FE) estimation
+- `RandomEffects` - GLS (RE) estimation
+
+**Specification Tests:**
+- `HausmanTest` - Test for fixed vs random effects
+- `HausmanTestResult` - Results container
+
+**Standard Errors:**
+- Homoskedastic (default)
+- Heteroskedasticity-robust
+- Clustered (one-way and two-way)
+
+**Infrastructure:**
+- Project structure setup
+- Testing framework (pytest)
+- Basic documentation
+- MIT License
+
+### Added - Validation Framework
+
+**Statistical Tests:**
+- Autocorrelation tests
+- Heteroskedasticity tests
+- Cross-sectional dependence tests
+- Unit root tests (panel)
+
+**Reporting:**
+- HTML reports with Plotly
+- Static reports with Matplotlib
+- LaTeX table export
+- Publication-ready formatting
+
+---
+
+## Release Notes
+
+### v0.2.0 - GMM Implementation Complete
+
+This release marks a major milestone with complete implementation of dynamic panel GMM estimation, bringing Stata's `xtabond2` capabilities to Python with improved robustness and user experience.
+
+**Key Highlights:**
+- 🎉 Difference GMM and System GMM fully implemented
+- 🎯 72.8% improvement in unbalanced panel handling
+- 📚 3,800+ lines of documentation and examples
+- ⚠️ Smart warning system for problematic specifications
+- ✅ Validated against Arellano-Bond (1991)
+
+**Migration from v0.1.0:**
+No breaking changes. All v0.1.0 code continues to work. New GMM features are additive:
+
+```python
+# v0.1.0 code still works
+from panelbox import FixedEffects, RandomEffects
+
+# v0.2.0 adds GMM
+from panelbox import DifferenceGMM, SystemGMM  # NEW!
+```
+
+**Known Limitations:**
+- System GMM may fail with very sparse synthetic data (add appropriate try/except)
+- Type hints are partial (gradual typing in progress)
+- Some specification tests may be under-powered with T < 5
+
+**Upcoming in v0.3.0:**
+- Comprehensive test suite (target: >80% coverage)
+- Advanced diagnostic tools (weak instrument tests)
+- Performance benchmarks
+- More example datasets
+
+---
+
+## Versioning
+
+We use [Semantic Versioning](https://semver.org/):
+- **Major** (X.0.0): Incompatible API changes
+- **Minor** (0.X.0): New features, backwards compatible
+- **Patch** (0.0.X): Bug fixes, backwards compatible
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for how to contribute to PanelBox.
+
+## Support
+
+- 📫 Issues: [GitHub Issues](https://github.com/guhaase/panelbox/issues)
+- 💬 Discussions: [GitHub Discussions](https://github.com/guhaase/panelbox/discussions)
+
+---
+
+**Legend:**
+- `Added` - New features
+- `Changed` - Changes to existing features
+- `Deprecated` - Soon-to-be removed features
+- `Removed` - Removed features
+- `Fixed` - Bug fixes
+- `Security` - Security fixes
+- `Performance` - Performance improvements
+- `Improved` - Quality improvements

panelbox-0.2.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,47 @@
+# Código de Conduta do Contributor Covenant
+
+## Nosso Compromisso
+
+No interesse de promover um ambiente aberto e acolhedor, nós, como contribuidores e mantenedores, nos comprometemos a tornar a participação em nosso projeto e em nossa comunidade uma experiência livre de assédio para todos, independentemente de idade, tamanho corporal, deficiência, etnia, características sexuais, identidade e expressão de gênero, nível de experiência, educação, status socioeconômico, nacionalidade, aparência pessoal, raça, religião ou identidade e orientação sexual.
+
+## Nossos Padrões
+
+Exemplos de comportamento que contribuem para criar um ambiente positivo incluem:
+
+* Usar linguagem acolhedora e inclusiva
+* Respeitar pontos de vista e experiências diferentes
+* Aceitar críticas construtivas de forma graciosa
+* Focar no que é melhor para a comunidade
+* Mostrar empatia com outros membros da comunidade
+
+Exemplos de comportamento inaceitável por participantes incluem:
+
+* Uso de linguagem ou imagens sexualizadas e atenção ou avanços sexuais indesejados
+* Comentários insultuosos/depreciativos (trolling) e ataques pessoais ou políticos
+* Assédio público ou privado
+* Publicar informações privadas de outros, como endereço físico ou eletrônico, sem permissão explícita
+* Outras condutas que possam ser razoavelmente consideradas inapropriadas em um ambiente profissional
+
+## Nossas Responsabilidades
+
+Os mantenedores do projeto são responsáveis por esclarecer os padrões de comportamento aceitável e devem tomar ações corretivas apropriadas e justas em resposta a quaisquer instâncias de comportamento inaceitável.
+
+Os mantenedores do projeto têm o direito e a responsabilidade de remover, editar ou rejeitar comentários, commits, código, edições de wiki, issues e outras contribuições que não estejam alinhadas com este Código de Conduta, ou banir temporária ou permanentemente qualquer contribuidor por outros comportamentos que considerem inapropriados, ameaçadores, ofensivos ou prejudiciais.
+
+## Escopo
+
+Este Código de Conduta se aplica tanto em espaços do projeto quanto em espaços públicos quando um indivíduo está representando o projeto ou sua comunidade. Exemplos de representação do projeto ou comunidade incluem usar um endereço de e-mail oficial do projeto, postar através de uma conta oficial de mídia social, ou atuar como representante nomeado em um evento online ou offline. A representação do projeto pode ser posteriormente definida e esclarecida pelos mantenedores do projeto.
+
+## Aplicação
+
+Instâncias de comportamento abusivo, de assédio ou de outra forma inaceitável podem ser reportadas entrando em contato com a equipe do projeto em gustavo.haase@gmail.com. Todas as reclamações serão revisadas e investigadas e resultarão em uma resposta considerada necessária e apropriada às circunstâncias. A equipe do projeto é obrigada a manter confidencialidade em relação ao relator de um incidente. Mais detalhes de políticas de aplicação específicas podem ser publicados separadamente.
+
+Mantenedores do projeto que não seguirem ou aplicarem o Código de Conduta de boa fé podem enfrentar repercussões temporárias ou permanentes conforme determinado por outros membros da liderança do projeto.
+
+## Atribuição
+
+Este Código de Conduta é adaptado do [Contributor Covenant][homepage], versão 1.4, disponível em https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
+
+[homepage]: https://www.contributor-covenant.org
+
+Para respostas a perguntas comuns sobre este código de conduta, veja https://www.contributor-covenant.org/faq

panelbox-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,271 @@
+# Guia de Contribuição
+
+Obrigado por considerar contribuir para o PanelBox! Este documento fornece diretrizes para contribuir com o projeto.
+
+## Código de Conduta
+
+Este projeto adere ao [Código de Conduta](CODE_OF_CONDUCT.md). Ao participar, você deve seguir este código.
+
+## Como Contribuir
+
+### Reportando Bugs
+
+Se você encontrar um bug, por favor abra uma issue com:
+
+- Descrição clara do problema
+- Passos para reproduzir
+- Comportamento esperado vs atual
+- Versão do Python e do PanelBox
+- Sistema operacional
+- Código mínimo para reproduzir o erro
+
+**Template de Bug Report:**
+
+```markdown
+**Descrição do Bug**
+Descrição clara e concisa do bug.
+
+**Para Reproduzir**
+Passos para reproduzir:
+1. Importar panelbox
+2. Executar código X
+3. Observar erro Y
+
+**Comportamento Esperado**
+O que deveria acontecer.
+
+**Código para Reproduzir**
+```python
+import panelbox as pb
+# código mínimo aqui
+```
+
+**Ambiente**
+- Python version: 3.10
+- PanelBox version: 0.1.0
+- OS: Ubuntu 22.04
+
+**Informações Adicionais**
+Qualquer contexto adicional.
+```
+
+### Sugerindo Melhorias
+
+Para sugerir melhorias ou novas funcionalidades:
+
+1. Verifique se já não existe uma issue similar
+2. Abra uma issue descrevendo:
+   - Motivação para a melhoria
+   - Descrição detalhada
+   - Exemplos de uso propostos
+   - Alternativas consideradas
+
+### Pull Requests
+
+#### Processo
+
+1. **Fork** o repositório
+2. **Clone** seu fork: `git clone https://github.com/seu-usuario/panelbox.git`
+3. **Crie uma branch** para sua feature: `git checkout -b feature/MinhaFeature`
+4. **Configure o ambiente de desenvolvimento**:
+   ```bash
+   python -m venv venv
+   source venv/bin/activate  # Linux/Mac
+   # ou
+   venv\Scripts\activate  # Windows
+   pip install -e ".[dev]"
+   ```
+5. **Faça suas alterações** seguindo as diretrizes de código
+6. **Adicione testes** para novas funcionalidades
+7. **Execute os testes**:
+   ```bash
+   pytest
+   pytest --cov=panelbox tests/
+   ```
+8. **Execute os linters**:
+   ```bash
+   black panelbox/ tests/
+   isort panelbox/ tests/
+   flake8 panelbox/ tests/
+   mypy panelbox/
+   ```
+9. **Commit suas mudanças**:
+   ```bash
+   git commit -m "feat: Adiciona funcionalidade X"
+   ```
+10. **Push para sua branch**: `git push origin feature/MinhaFeature`
+11. **Abra um Pull Request** no repositório principal
+
+#### Diretrizes de Código
+
+**Estilo de Código**
+
+- Siga [PEP 8](https://peps.python.org/pep-0008/)
+- Use [Black](https://black.readthedocs.io/) para formatação (line-length=100)
+- Use [isort](https://pycqa.github.io/isort/) para ordenar imports
+- Use type hints em todas as funções públicas
+- Docstrings no estilo Google
+
+**Exemplo de Docstring:**
+
+```python
+def estimate_model(
+    data: pd.DataFrame,
+    formula: str,
+    entity_col: str,
+    time_col: str
+) -> PanelResults:
+    """
+    Estima um modelo de painel.
+
+    Args:
+        data: DataFrame com dados em formato long
+        formula: Fórmula no estilo R (e.g., "y ~ x1 + x2")
+        entity_col: Nome da coluna de entidade
+        time_col: Nome da coluna de tempo
+
+    Returns:
+        Objeto PanelResults com resultados da estimação
+
+    Raises:
+        ValueError: Se a fórmula for inválida
+        KeyError: Se colunas não existirem no DataFrame
+
+    Examples:
+        >>> data = load_grunfeld()
+        >>> results = estimate_model(data, "invest ~ value", "firm", "year")
+        >>> print(results.summary())
+    """
+    pass
+```
+
+**Commits**
+
+Use [Conventional Commits](https://www.conventionalcommits.org/):
+
+- `feat:` Nova funcionalidade
+- `fix:` Correção de bug
+- `docs:` Mudanças na documentação
+- `style:` Formatação (sem mudança de código)
+- `refactor:` Refatoração de código
+- `test:` Adição ou correção de testes
+- `chore:` Manutenção (build, CI, etc.)
+
+Exemplos:
+```
+feat: adiciona suporte para System GMM
+fix: corrige cálculo de estatística de Hansen
+docs: atualiza tutorial de modelos dinâmicos
+test: adiciona testes para validação de fórmulas
+```
+
+**Testes**
+
+- Toda nova funcionalidade deve ter testes
+- Manter cobertura de testes ≥ 90%
+- Usar pytest como framework
+- Organizar testes em `tests/` espelhando `panelbox/`
+- Testes unitários para funções individuais
+- Testes de integração para workflows completos
+- Testes de benchmark contra Stata/R quando aplicável
+
+**Exemplo de Teste:**
+
+```python
+import pytest
+import pandas as pd
+import panelbox as pb
+from panelbox.datasets import load_grunfeld
+
+class TestFixedEffects:
+    """Testes para o modelo Fixed Effects."""
+
+    @pytest.fixture
+    def data(self):
+        """Fixture com dados de exemplo."""
+        return load_grunfeld()
+
+    def test_basic_estimation(self, data):
+        """Testa estimação básica de FE."""
+        model = pb.FixedEffects("invest ~ value", data, "firm", "year")
+        results = model.fit()
+
+        assert results.params is not None
+        assert len(results.params) > 0
+        assert results.nobs == len(data)
+
+    def test_coefficients_match_stata(self, data):
+        """Testa se coeficientes coincidem com Stata."""
+        model = pb.FixedEffects("invest ~ value + capital", data, "firm", "year")
+        results = model.fit()
+
+        # Valores obtidos de Stata xtreg, fe
+        expected_value = 0.1101
+        expected_capital = 0.3100
+
+        assert pytest.approx(results.params['value'], rel=1e-3) == expected_value
+        assert pytest.approx(results.params['capital'], rel=1e-3) == expected_capital
+```
+
+#### Documentação
+
+- Toda função/classe pública deve ter docstring
+- Atualizar README.md se necessário
+- Adicionar exemplos em `examples/` para funcionalidades complexas
+- Atualizar documentação técnica em `docs/`
+- Adicionar entrada no CHANGELOG.md
+
+#### Code Review
+
+Seu PR será revisado considerando:
+
+- Qualidade do código
+- Cobertura de testes
+- Documentação
+- Compatibilidade com versões Python suportadas
+- Performance (se aplicável)
+- Consistência com arquitetura do projeto
+
+## Áreas para Contribuição
+
+### Prioridade Alta
+- [ ] Implementação de modelos core (Pooled OLS, FE, RE)
+- [ ] Parser de fórmulas
+- [ ] Testes de validação básicos
+- [ ] Sistema de reports
+
+### Prioridade Média
+- [ ] Modelos dinâmicos (GMM)
+- [ ] Testes de validação avançados
+- [ ] Erros padrão robustos
+- [ ] CLI
+
+### Prioridade Baixa
+- [ ] Testes de raiz unitária
+- [ ] Testes de cointegração
+- [ ] Otimizações de performance
+- [ ] Integrações com outras bibliotecas
+
+### Documentação
+- [ ] Tutoriais em português e inglês
+- [ ] Exemplos de uso
+- [ ] Comparações com Stata/R
+- [ ] Papers técnicos
+
+## Comunicação
+
+- **Issues**: Para bugs, melhorias e discussões
+- **Pull Requests**: Para contribuições de código
+- **Email**: gustavo.haase@gmail.com para questões privadas
+
+## Reconhecimento
+
+Todos os contribuidores serão reconhecidos no README.md e na documentação.
+
+## Dúvidas?
+
+Se tiver dúvidas sobre como contribuir, abra uma issue com a tag `question` ou entre em contato.
+
+---
+
+Obrigado por contribuir para o PanelBox! 🎉

panelbox-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gustavo Haase, Paulo Dourado
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

panelbox-0.2.0/MANIFEST.in

@@ -0,0 +1,51 @@
+# MANIFEST.in - Specifies additional files to include in distribution
+
+# Documentation
+include README.md
+include LICENSE
+include CHANGELOG.md
+include CONTRIBUTING.md
+include CODE_OF_CONDUCT.md
+include QUICKSTART.md
+
+# Configuration files
+include pyproject.toml
+include .gitignore
+
+# Include all markdown files in docs/
+recursive-include docs *.md
+recursive-include docs *.png
+recursive-include docs *.jpg
+
+# Include example scripts
+recursive-include examples *.py
+recursive-include examples *.md
+recursive-include examples *.csv
+
+# Include validation data (for testing/examples)
+recursive-include validation/data *.csv
+recursive-include validation/data *.dta
+
+# Include templates for reporting
+recursive-include panelbox/templates *.html
+recursive-include panelbox/templates *.css
+recursive-include panelbox/templates *.js
+
+# Exclude development and build artifacts
+global-exclude __pycache__
+global-exclude *.py[co]
+global-exclude .DS_Store
+global-exclude *.so
+global-exclude .coverage
+global-exclude .pytest_cache
+
+# Exclude development directories
+prune desenvolvimento
+prune .pytest_cache
+prune .coverage
+prune htmlcov
+prune .mypy_cache
+prune .tox
+prune build
+prune dist
+prune *.egg-info