BCCh Macro Data Lab

Build Chile macro-financial research datasets from the Banco Central de Chile BDE API.

This project downloads selected Banco Central de Chile time series, stores the raw observations, builds monthly and daily research panels, writes validation files, and generates reports. It can be used from a desktop GUI or from the command line.

Main features

• Search and cache the Banco Central series catalog.
• Select and document BDE time series in configs/selected_series.yml.
• Download raw observations to CSV.
• Build monthly and daily panels.
• Validate coverage, missing values, and failed downloads.
• Export datasets to CSV, Excel, Parquet, and Stata.
• Generate Markdown and PDF reports.

Requirements

• Python
• uv
• Banco Central de Chile BDE credentials for live downloads

Offline tests do not require BDE credentials.

Setup

uv sync

Create a local .env file:

cp .env.example .env

Add your BDE credentials:

BCCH_USER=your_email@example.com
BCCH_PASSWORD=your_password_here

The .env file is ignored by Git.

Quick start

GUI

uv run bcch-gui

You can also launch the GUI with the platform scripts:

macOS:   open_gui.command
Windows: open_gui.bat
Linux:   ./open_gui.sh

The GUI can save credentials, build the catalog, select series, download data, build the monthly panel, export files, and generate the report.

Terminal workflow

uv run bcch-wizard

The wizard walks through credentials, catalog building, series selection, downloads, dataset creation, reports, tests, and exports.

Common commands

uv run bcch-catalog build
uv run bcch-catalog search "IMACEC"
uv run bcch-download
uv run bcch-build-dataset
uv run bcch-report
uv run bcch-export --all
uv run pytest

Outputs

Path	Description
data/catalog/series_catalog.csv	Local searchable BDE catalog
data/raw/*.csv	Raw downloaded observations
data/processed/chile_macro_monthly.csv	Monthly research panel
data/processed/chile_macro_daily.csv	Daily panel for selected daily series
data/processed/variable_dictionary.csv	Variable definitions and source metadata
data/processed/validation_summary.csv	Download and coverage checks
data/processed/data_quality_issues.csv	Data quality warnings and errors
reports/bcch_macro_data_report.md	Editable report
reports/bcch_macro_data_report.pdf	PDF report, when rendering succeeds
data/exports/	CSV, Excel, Parquet, and Stata exports

Generated data, exports, reports, and figures are ignored by Git.

Selecting series

Start with a concept and search the local catalog:

uv run bcch-catalog search "tasa de política"
uv run bcch-catalog search "tipo de cambio"
uv run bcch-catalog search "cobre"

Then edit configs/selected_series.yml.

Each selected variable should include the BDE series_id, units, source frequency, target frequency, and monthly conversion rule. Leave series_id as TODO_VERIFY_FROM_CATALOG until the catalog confirms it.

Sample periods

The selected sample period is stored in configs/selected_series.yml:

sample_period:
  start_date: 2000-01-01
  end_date:

Dates use YYYY-MM-DD. A blank start_date uses the full available history. A blank end_date uses the latest available observation.

Supported monthly conversions:

• average: monthly mean
• direct: source monthly value
• end_of_period: last available observation in the month

Daily panel and policy-rate events

Build the daily panel:

uv run bcch-build-daily

Build descriptive event-window data around policy-rate changes:

uv run bcch-event-study
uv run bcch-event-study --window-start -10 --window-end 10

The event outputs are descriptive research data. They do not claim causal identification.

Snapshots

Create and compare local data vintages:

uv run bcch-snapshot create
uv run bcch-snapshot list
uv run bcch-snapshot compare SNAPSHOT_OLD SNAPSHOT_NEW

Snapshot comparisons write data/processed/revision_report.csv.

Banco Central de Chile BDE API

The project uses two BDE API services:

• SearchSeries: catalog metadata by frequency
• GetSeries: observations for a selected timeseries ID

Official documentation:

• BCCh BDE API documentation in English
• BCCh BDE API documentation in Spanish

Development

Run the offline tests:

uv run pytest

License

This project is licensed under the MIT License. See LICENSE for details.