turkiye-housing-real-return-timing

KO | EN

gitlite — search

#http #react-native #web #ruby #sql #python #large-language-models #generative-ai #json #macos

turkiye-housing-real-return-timing

(★ 9)

Ex-post analysis of real Housing Price Index returns in Türkiye using TCMB EVDS data.

파일 탐색기

ZIP 다운로드

- - tests.yml
- project.yaml
- - .gitkeep
- - .gitkeep
- METHODOLOGY.md
- - .gitkeep
  - 01_nominal_real_kfe.png
  - 01_nominal_real_kfe.svg
  - 02_real_return_heatmap.png
  - 02_real_return_heatmap.svg
  - 03_annualized_real_return.png
  - 03_annualized_real_return.svg
  - 04_return_distribution.png
  - 04_return_distribution.svg
  - 05_volatility_drawdown.png
  - 05_volatility_drawdown.svg
  - 06_walk_forward_returns.png
  - 06_walk_forward_returns.svg
  - 07_model_coefficients.png
  - 07_model_coefficients.svg
  - 08_model_performance.png
  - 08_model_performance.svg
  - 09_lag_sensitivity.png
  - 09_lag_sensitivity.svg
- - .gitkeep
  - continuous_timing_scores.csv
  - feature_mean_std.csv
  - historical_real_returns.csv
  - model_coefficients.csv
  - model_performance.csv
  - model_predictions.csv
  - model_run.json
  - sensitivity_by_month.csv
- figure_manifest.json
- run_metadata.json
- - __init__.py
  - __main__.py
  - cli.py
  - config.py
  - demo.py
  - evds.py
  - features.py
  - finance.py
  - io.py
  - model.py
  - pipeline.py
  - plotting.py
  - readme.py
  - returns.py
  - scoring.py
  - transform.py
- __init__.py
- test_cli.py
- test_config.py
- test_evds.py
- test_features_scoring.py
- test_model.py
- test_pipeline.py
- test_returns.py
- test_transform.py
.env.example
.gitignore
LICENSE
pyproject.toml
README.md
setup.cfg
setup.py

# CDN으로 사용하기

jsDelivr

jsDelivr는 공개 GitHub 리포지토리를 별도 설정 없이 CDN으로 즉시 서빙합니다. 버전과 파일을 고르면 웹페이지에 바로 붙일 수 있는 링크와 예시 코드가 만들어집니다.

버전

파일

링크

예시

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

> **Data status — synthetic methodology demo:** This run uses deterministic synthetic data. The dates, returns, and model metrics below are not economic findings about Türkiye; they validate the software and research workflow only.

## Research question and scope

Which purchase months in Türkiye were followed by higher real Housing Price Index returns over the next 1 and 3 years?

- Common HPI–CPI sample: 2010-01 to 2026-07.
- The sample begins in 2010; rent-data availability after 2018 does not constrain it.
- The study measures the housing index's own nominal and CPI-adjusted performance.
- It does not compare buying with renting, deposits, mortgage payments, or terminal household wealth.
- A 1- or 3-year outcome is realized only after its full holding horizon has completed.
- The pipeline emits continuous forecasts, percentile scores, and uncertainty intervals—never Buy, Wait, or Neutral labels.

## Target variables

```text
NominalReturn(t,h) = HPI(t+h) / HPI(t) - 1

RealReturn(t,h) = [HPI(t+h) / HPI(t)] / [CPI(t+h) / CPI(t)] - 1

AnnualizedRealReturn(t,h) = (1 + RealReturn(t,h))^(12/h) - 1
```

## Nominal and real HPI

![Nominal and real HPI](https://raw.githubusercontent.com/mdenizcoskun/turkiye-housing-real-return-timing/main/outputs/figures/01_nominal_real_kfe.png)

**How to read it:** The upper panel shows the HPI level in nominal terms. The lower panel deflates the same series by headline CPI. A rising nominal line does not by itself mean housing outpaced inflation; the real index and its distance from prior peaks carry that information.

This is a level chart, not a return chart. The forward-return figures below should be used to compare investment outcomes between purchase months.

## Real return by purchase month

![Real-return heatmap](https://raw.githubusercontent.com/mdenizcoskun/turkiye-housing-real-return-timing/main/outputs/figures/02_real_return_heatmap.png)

**How to read it:** Each row is a holding horizon and each column is a purchase month. Green marks higher positive completed real returns; red marks negative outcomes. Different colors for the same month across horizons show that timing results depend on holding length.

Hatched regions are still open and are not treated as realized outcomes. The heatmap is historical description, not a forward purchase signal.

## Annualized real return

![Annualized real return](https://raw.githubusercontent.com/mdenizcoskun/turkiye-housing-real-return-timing/main/outputs/figures/03_annualized_real_return.png)

**How to read it:** Each point is the compound annual real return obtained after the corresponding purchase month and completed holding period. Values above zero are positive after inflation; values below zero are negative.

Annualization puts 1- and 3-year outcomes on a common scale without changing cumulative return. The two horizons can move differently and should be read as distinct timing regimes.

## Return distribution

![Return distribution](https://raw.githubusercontent.com/mdenizcoskun/turkiye-housing-real-return-timing/main/outputs/figures/04_return_distribution.png)

**How to read it:** The histograms describe the distribution of completed annualized real returns. Width reflects dispersion, the left tail captures adverse periods, and the adjacent bars show the historical share of positive completed outcomes.

The positive-return share is not a success probability or investment recommendation. Observations use the national HPI and overlapping holding periods.

### Completed historical outcome summary

| Horizon | Completed purchase months | Positive real-return share | Median annual real return |
|---:|---:|---:|---:|
| 1 year | 187 | 67.4% | 3.50% |
| 3 years | 163 | 69.3% | 3.98% |

## Volatility and real drawdown

![Volatility and drawdown](https://raw.githubusercontent.com/mdenizcoskun/turkiye-housing-real-return-timing/main/outputs/figures/05_volatility_drawdown.png)

**How to read it:** The upper panel annualizes the volatility of monthly real-HPI movements over trailing 24/36-month windows. A higher line means larger fluctuations, not necessarily higher or lower returns.

The lower panel measures the real HPI's percentage loss from its previous peak. Returning to zero means the prior real peak has been regained. Drawdown describes past risk; it does not forecast the next trough.

## Model information set

The predictive target is the annualized real return so that different horizons share a common scale. Cumulative nominal and real returns remain available in descriptive outputs.

The 1- and 3-year specifications use at most three lagged price features. High-correlation and VIF checks are repeated within each training window.

HPI and CPI predictors use a 2-month publication-availability lag.

Mean–standard-deviation scaling, target winsorization, and prediction bounds are estimated only from each model's training sample. Walk-forward training includes only earlier purchases whose forward returns were complete before the forecast month.

At each forecast date, purged rolling-origin validation compares Ridge, Elastic Net, and different shrinkage weights toward an expanding mean. The model falls back to the expanding mean when no regularized candidate beats it on both inner-sample MAE and RMSE.

## Walk-forward forecasts and realized returns

![Walk-forward forecasts](https://raw.githubusercontent.com/mdenizcoskun/turkiye-housing-real-return-timing/main/outputs/figures/06_walk_forward_returns.png)

**How to read it:** The blue line is the subsequently realized annualized real return. The green line is the expanding walk-forward forecast produced only from information available at the time. Their distance is the forecast error.

The dashed orange full-sample OLS line is explanatory and must not be read as a real-time forecast. The orange band combines moving-block bootstrap uncertainty with prior completed OOS errors. Hatched final regions contain forecasts whose target horizons are still open.

Interval coverage is validated separately from point accuracy. A point model may pass the benchmark gate even when its nominal 95% interval is undercovered.

## Explanatory coefficients

![Model coefficients](https://raw.githubusercontent.com/mdenizcoskun/turkiye-housing-real-return-timing/main/outputs/figures/07_model_coefficients.png)

**How to read it:** Each blue point is the full-sample association between a one-standard-deviation predictor increase and annual real return. Horizontal lines are 95% HAC intervals; an interval crossing zero indicates greater uncertainty. Orange crosses show the corresponding Ridge coefficients.

OLS covariance uses Newey–West HAC because forward returns overlap. The chart does not establish causality and is separate from walk-forward model selection.

The highest VIF in the main specification is 15.9. Because it exceeds 10, individual OLS coefficients should be interpreted cautiously; the Ridge path is shown as a stability comparison.

## Out-of-sample performance

![Model performance](https://raw.githubusercontent.com/mdenizcoskun/turkiye-housing-real-return-timing/main/outputs/figures/08_model_performance.png)

**How to read it:** Lower MAE and RMSE than the grey expanding-mean benchmark are preferred. Positive OOS R² means the model reduces squared forecast error relative to that benchmark. Direction accuracy is supplementary and cannot validate a model by itself.

| Horizon | Specification | OOS months | MAE | RMSE | OOS R² | Direction accuracy | Benchmark MAE | Benchmark RMSE | Interval coverage | Interval status | Model status |
|---:|---|---:|---:|---:|---:|---:|---:|---:|---:|---|---|
| 1 year | main | 119 | 0.081 | 0.100 | 0.172 | 0.655 | 0.098 | 0.110 | 0.681 | undercovered | validated |
| 3 years | main | 71 | 0.059 | 0.073 | 0.217 | 0.873 | 0.072 | 0.082 | 0.423 | undercovered | validated |

A horizon is validated only with enough OOS observations, positive OOS R², and lower MAE and RMSE than the expanding-mean benchmark. Continuous scores remain auditable when this gate fails but are not validated economic guidance.

Nominal 95% intervals are marked undercovered when realized OOS coverage is below 90%, independently of point-model validation.

## Publication-lag and assumption sensitivity

![Publication-lag sensitivity](https://raw.githubusercontent.com/mdenizcoskun/turkiye-housing-real-return-timing/main/outputs/figures/09_lag_sensitivity.png)

**How to read it:** The upper panel varies HPI/CPI publication lags between 1/2/3 months and volatility windows between 24/36 months, then displays the median annualized forecast. The lower panel shows agreement in forecast sign across these variants.

High sign agreement is not accuracy. The sensitivity chart must not be treated as a decision rule when the model fails its benchmark gate or its interval coverage is weak.

## Limitations

- This is an ex-post national-average study, not a causal estimate or investment recommendation.
- Current revised EVDS data need not match the first releases available historically.
- The HPI is based on valuation reports rather than completed transaction prices.
- Forward returns overlap; HAC and block bootstrap reduce but do not eliminate dependence.
- Recent 3-year holding periods may still be incomplete.
- Regional and dwelling-level heterogeneity is outside the national model.
- No period-level claim about Türkiye is valid without a real EVDS run.

## Technical use and reproducibility

The `plot` and `run-all` commands refresh this root `README.md` directly. No separate generated Markdown report is maintained.

### TCMB EVDS series

| Series | EVDS code | Frequency | Configured start | Status | Use |
|---|---|---:|---:|---|---|
| Housing Price Index | `TP.KFE.TR` | Monthly | 2010-01 | Required | Primary price, nominal-return, and real-return series |
| Consumer Price Index | `TP.TUKFIY2025.GENEL` | Monthly | 2010-01 | Required | Deflator for real HPI returns |
| New Housing Price Index | `TP.YKFE.TR` | Monthly | 2010-01 | Optional | Optional new-home diagnostic |
| Existing Housing Price Index | `TP.YOKFEND.TR` | Monthly | 2010-01 | Optional | Optional existing-home diagnostic |

HPI and CPI are required. New/existing-home HPI series are diagnostic only and do not alter the target. Every run records actual data coverage in `data/processed/data_quality.json`.

### Installation

Python 3.9 or newer is required.

```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip setuptools wheel
python -m pip install -e ".[dev,parquet]"
```

Copy `.env.example` to `.env` and keep the EVDS key local:

```text
EVDS_API_KEY=your-local-evds-key
```

`.env`, raw/processed data, `.venv`, `work/`, and OS metadata are excluded from Git.

### Security guardrails

- The EVDS credential is accepted only for the official `https://evds2.tcmb.gov.tr/service/evds/` endpoint.
- HTTP redirects are refused so the credential cannot be forwarded to another origin.
- Series aliases are restricted to flat identifier-style names before any raw CSV read or write.
- The GitHub Actions workflow requests read-only repository contents permission and does not enable live EVDS tests or receive an EVDS key.

### Running the project

Complete real-data run:

```bash
python -m housing_timing run-all
```

Deterministic software validation without an EVDS key:

```bash
python -m housing_timing run-all --demo
```

Individual stages:

```bash
python -m housing_timing fetch
python -m housing_timing build
python -m housing_timing analyze
python -m housing_timing plot
```

Demo figures carry a small synthetic-data footer. Real-data figures replace it with a TCMB EVDS source note.

### Pipeline

```mermaid
flowchart LR
    A[TCMB HPI and CPI] --> B[Common monthly panel from 2010]
    B --> C[1/3-year nominal and real returns]
    B --> D[Publication-lagged trend, momentum, and volatility]
    C --> E[Full-sample OLS / HAC]
    D --> E
    C --> F[Nested-CV Ridge / Elastic Net / benchmark fallback]
    D --> F
    F --> G[OOS performance, intervals, and continuous scores]
    E --> H[Figures and README]
    G --> H
```

### Main output files

- `outputs/tables/historical_real_returns.csv`
- `outputs/tables/model_predictions.csv`
- `outputs/tables/model_coefficients.csv`
- `outputs/tables/model_performance.csv`
- `outputs/tables/continuous_timing_scores.csv`
- `outputs/tables/sensitivity_by_month.csv`
- `outputs/run_metadata.json`

The reproducible output snapshot is versioned for direct GitHub review. `run_metadata.json` records whether it came from a synthetic demo or a real EVDS run.

### Repository structure

```text
config/project.yaml       Data-series and model configuration
src/housing_timing/       Data, feature, model, plotting, and README code
tests/                    Offline unit and pipeline tests
docs/METHODOLOGY.md       Detailed methodology and reproducibility notes
outputs/                  Published figures, tables, and run metadata
```

The former buy-versus-rent experiment remains isolated as legacy code in `housing_timing.finance`; the active pipeline does not import it.

### Tests

Offline test suite:

```bash
python -m pytest
```

Optional live EVDS smoke test:

```bash
EVDS_LIVE_TEST=1 python -m pytest tests/test_evds.py
```

GitHub Actions runs the offline suite on Python 3.9 and 3.11.

### License

Code and documentation are released under the [MIT License](LICENSE).

turkiye-housing-real-return-timing

오너의 다른 레포

파일 탐색기

# CDN으로 사용하기

Was this content helpful?

Recent Feedback

turkiye-housing-real-return-timing

오너의 다른 레포

파일 탐색기

# CDN으로 사용하기

Was this content helpful?

Recent Feedback

Download README