usecasen

Python Library for CASEN Survey Analysis (Chile)

Professional Python library for downloading and analyzing data from Chile's CASEN Survey (Encuesta de Caracterización Socioeconómica Nacional). Features 100% in-memory operations, intelligent file scoring, and Stata 17+ integration.

Author: Maykol Medrano | Email: mmedrano2@uc.cl | GitHub: @MaykolMedrano

Features

• 100% In-Memory: Download and decompress without disk I/O
• Intelligent Scoring: Smart file detection ported from MATA
• Stata Integration: Vectorized injection (100x faster than loops)
• Variable Search: Efficient search without loading full datasets
• Codebook Access: Automatic value label extraction
• Cache System: Instant searches after first download
• Cross-Platform: Windows, macOS, Linux compatible

Installation

PyPI (Recommended)

pip install usecasen

From Source

git clone https://github.com/MaykolMedrano/usecasen.git
cd usecasen/python
pip install -e .

Quick Start

import casen

# Download single year
df = casen.download(2022)
# Returns: DataFrame with 202,231 rows × 918 columns

# Download multiple years
results = casen.download_batch([2017, 2022])
# Returns: {2017: DataFrame, 2022: DataFrame}

# Search variables
results = casen.search("educacion")

# Get value labels
labels = casen.get_labels("region", year=2022)
# Returns: {1: 'Tarapacá', 2: 'Antofagasta', ...}

API Reference

Functions

Options

Stata 17+ Integration

python:
import casen
df = casen.download(2022, to_stata=True)
end

describe
summarize

* Search variables from Stata
python:
import casen
results = casen.search("ingreso", verbose=True)
end

Package Structure

python/
├── casen/
│   ├── __init__.py      # Public API
│   ├── downloader.py    # Download and scraping logic
│   ├── metadata.py      # Search and labels
│   ├── stata_io.py      # Stata integration
│   └── utils.py         # Shared utilities
├── setup.py
├── requirements.txt
├── LICENSE
└── README.md

Scoring System (MATA Port)

The library uses an intelligent scoring system to detect the correct files:

Rewards: "casen" (+30), "stata" (+100), ".dta" (+80), year (+50)

Penalties: "spss" (-100), "sas" (-80), "csv" (-50), "manual" (-60)

Compatibility

Citation

@software{usecasen2025,
  author = {Maykol Medrano},
  title = {usecasen: Python Library for CASEN Survey Analysis},
  version = {1.0.0},
  year = {2025},
  url = {https://github.com/MaykolMedrano/usecasen}
}

Contributing

1. Fork the repository
2. Create feature branch: git checkout -b feature/NewFeature
3. Commit changes: git commit -m 'Add NewFeature'
4. Push: git push origin feature/NewFeature
5. Open Pull Request

Data Source

Data provided by Chile's Ministry of Social Development: https://observatorio.ministeriodesarrollosocial.gob.cl/

License

MIT License — See LICENSE for details.

Version: 1.0.0 | Python: 3.8+ | Stata: 17+ (optional)