initial import: etf strategy project

README.md

@@ -0,0 +1,42 @@
+# Quant Factor Research (QFR)
+
+A lightweight, reproducible workspace for researching, backtesting, and evaluating quantitative equity factors.
+
+## Goals
+
+- Factor definition library (cross-sectional / time-series)
+- Data ingestion + caching
+- Standardized preprocessing (winsorize, z-score, neutralization)
+- IC / rank IC / turnover / decay analysis
+- Simple backtests (long-short / top-k) with transaction cost hooks
+
+## Quickstart
+
+1) Create env (pick one)
+
+- Conda:
+  - `conda create -n qfr python=3.11 -y`
+  - `conda activate qfr`
+  - `pip install -r requirements.txt`
+
+- venv:
+  - `python3 -m venv .venv && source .venv/bin/activate`
+  - `pip install -r requirements.txt`
+  - Note: some servers ship Python without ensurepip/venv support; you may need the OS package `python3-venv` (root required).
+
+2) Run a smoke test
+
+- `python -c "import qfr; print('ok')"`
+
+## Layout
+
+- `src/qfr/` core library
+- `notebooks/` research notebooks
+- `data/raw/` raw data (not committed)
+- `data/processed/` derived data (not committed)
+- `configs/` config templates
+- `scripts/` CLI utilities
+
+## Notes
+
+- Keep secrets out of git. Use `.env` locally.