feat(backtest): add weekly/monthly rebalancing (W/M)

- Apply rebalance_freq in run()

- Add tests for W/M and invalid freq

- Update README with usage

Fixes #4

Author: saumya1317

.coverage

@@ -22,7 +22,7 @@ QuantResearchStarter provides a clean, well-documented starting point for quanti
 
 * **Data management** — download market data or generate synthetic price series for experiments.
 * **Factor library** — example implementations of momentum, value, size, and volatility factors.
-* **Vectorized backtesting engine** — supports transaction costs, slippage, and portfolio constraints.
+* **Vectorized backtesting engine** — supports configurable rebalancing frequencies (daily, weekly, monthly), transaction costs, slippage, and portfolio constraints.
 * **Risk & performance analytics** — returns, drawdowns, Sharpe, turnover, and other risk metrics.
 * **CLI & scripts** — small tools to generate data, compute factors, and run backtests from the terminal.
 * **Production-ready utilities** — type hints, tests, continuous integration, and documentation scaffolding.
@@ -80,17 +80,29 @@ streamlit run src/quant_research_starter/dashboard/streamlit_app.py
 ## Minimal example
 
 ```python
-from quant_research_starter.backtest import Backtester
+from quant_research_starter.backtest import VectorizedBacktest
 from quant_research_starter.data import load_prices
 from quant_research_starter.factors import Momentum
 
 prices = load_prices("data_sample/sample_prices.csv")
 factor = Momentum(window=63)
 scores = factor.compute(prices)
 
-bt = Backtester(prices, signals=scores, capital=1_000_000)
-results = bt.run()
-print(results.performance.summary())
+# Daily rebalancing (default)
+bt_daily = VectorizedBacktest(prices, signals=scores, capital=1_000_000)
+results_daily = bt_daily.run()
+
+# Weekly rebalancing
+bt_weekly = VectorizedBacktest(prices, signals=scores, capital=1_000_000, rebalance_freq="W")
+results_weekly = bt_weekly.run()
+
+# Monthly rebalancing
+bt_monthly = VectorizedBacktest(prices, signals=scores, capital=1_000_000, rebalance_freq="M")
+results_monthly = bt_monthly.run()
+
+print(f"Daily: {results_daily['total_return']:.2%}")
+print(f"Weekly: {results_weekly['total_return']:.2%}")
+print(f"Monthly: {results_monthly['total_return']:.2%}")
 ```
 
 > See the `examples/` directory for fully working notebooks and scripts.

README.md

@@ -43,24 +43,43 @@ Dynamic: license-file
 
 # QuantResearchStarter
 
-A modular, open-source quantitative research and backtesting framework designed for clarity and extensibility. Perfect for researchers, students, and developers interested in quantitative finance.
-
-![Python Version](https://img.shields.io/badge/python-3.10%2B-blue)
-![License](https://img.shields.io/badge/license-MIT-green)
+[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 [![CI](https://github.com/username/QuantResearchStarter/actions/workflows/ci.yml/badge.svg)](https://github.com/username/QuantResearchStarter/actions)
 
+A modular, open-source quantitative research and backtesting framework built for clarity, reproducibility, and extensibility. Ideal for researchers, students, and engineers building and testing systematic strategies.
+
+---
+
+## Why this project
+
+QuantResearchStarter provides a clean, well-documented starting point for quantitative research and backtesting. Its priorities are:
+
+* **Readability**: idiomatic Python, type hints, and small modules you can read and change quickly.
+* **Testability**: deterministic vectorized backtests with unit tests and CI.
+* **Extensibility**: plugin-friendly factor & data adapters so you can try new ideas fast.
+
+---
+
 ## Features
 
-- **Data Management**: Download real data or generate synthetic data for testing
-- **Factor Library**: Implement momentum, value, size, and volatility factors
-- **Backtesting Engine**: Vectorized backtester with transaction costs and constraints
-- **Risk Metrics**: Comprehensive performance and risk analytics
-- **Modular Design**: Easy to extend with new factors and strategies
-- **Production Ready**: Type hints, tests, CI/CD, and documentation
+* **Data management** — download market data or generate synthetic price series for experiments.
+* **Factor library** — example implementations of momentum, value, size, and volatility factors.
+* **Vectorized backtesting engine** — supports transaction costs, slippage, and portfolio constraints.
+* **Risk & performance analytics** — returns, drawdowns, Sharpe, turnover, and other risk metrics.
+* **CLI & scripts** — small tools to generate data, compute factors, and run backtests from the terminal.
+* **Production-ready utilities** — type hints, tests, continuous integration, and documentation scaffolding.
 
-## Quick Start
+---
 
-### Installation
+## Quick start
+
+### Requirements
+
+* Python 3.10+
+* pip
+
+### Install locally
 
 ```bash
 # Clone the repository
@@ -70,5 +89,125 @@ cd QuantResearchStarter
 # Install package in development mode
 pip install -e .
 
-# Install development dependencies
+# Install development dependencies (tests, linters, docs)
 pip install -e ".[dev]"
+
+# Optional UI dependencies
+pip install streamlit plotly
+```
+
+### Demo (one-line)
+
+```bash
+make demo
+```
+
+### Step-by-step demo
+
+```bash
+# generate synthetic sample price series
+qrs generate-data -o data_sample/sample_prices.csv -s 5 -d 365
+
+# compute example factors
+qrs compute-factors -d data_sample/sample_prices.csv -f momentum -f value -o output/factors.csv
+
+# run a backtest
+qrs backtest -d data_sample/sample_prices.csv -s output/factors.csv -o output/backtest_results.json
+
+# optional: start the Streamlit dashboard
+streamlit run src/quant_research_starter/dashboard/streamlit_app.py
+```
+
+---
+
+## Minimal example
+
+```python
+from quant_research_starter.backtest import Backtester
+from quant_research_starter.data import load_prices
+from quant_research_starter.factors import Momentum
+
+prices = load_prices("data_sample/sample_prices.csv")
+factor = Momentum(window=63)
+scores = factor.compute(prices)
+
+bt = Backtester(prices, signals=scores, capital=1_000_000)
+results = bt.run()
+print(results.performance.summary())
+```
+
+> See the `examples/` directory for fully working notebooks and scripts.
+
+---
+
+## CLI reference
+
+Run `qrs --help` or `qrs <command> --help` for full usage. Main commands include:
+
+* `qrs generate-data` — create synthetic price series or download data from adapters
+* `qrs compute-factors` — calculate and export factor scores
+* `qrs backtest` — run the vectorized backtest and export results
+
+---
+
+## Project structure (overview)
+
+```
+QuantResearchStarter/
+├─ src/quant_research_starter/
+│  ├─ data/              # data loaders & adapters
+│  ├─ factors/           # factor implementations
+│  ├─ backtest/          # backtester & portfolio logic
+│  ├─ analytics/         # performance and risk metrics
+│  ├─ cli/               # command line entry points
+│  └─ dashboard/         # optional Streamlit dashboard
+├─ examples/             # runnable notebooks & example strategies
+├─ tests/                # unit + integration tests
+└─ docs/                 # documentation source
+```
+
+---
+
+## Tests & CI
+
+Run unit tests locally with:
+
+```bash
+pytest -q
+```
+
+CI runs linting (ruff), formatting checks (black), and unit tests across supported Python versions. The workflow is defined in `.github/workflows/ci.yml`.
+
+---
+
+## Contributing
+
+Contributions are welcome. Please follow these steps:
+
+1. Fork the repository
+2. Create a descriptive branch (feature or fix)
+3. Add tests for new behavior
+4. Open a pull request with a clear description and rationale
+
+Before submitting, ensure your tests pass and formatting/linting checks succeed.
+
+---
+
+## AI policy (short & practical)
+
+**Yes — you may use AI tools** (ChatGPT, Copilot, etc.) to help write or review code and documentation. Please follow these guidelines:
+
+* **Disclose** substantial AI assistance in the PR or commit message (e.g., "Generated with ChatGPT; reviewed and adapted by @your-username").
+* **Review thoroughly** all AI-generated code for correctness, security, numerical stability, and licensing concerns.
+* **Add tests** for AI-generated logic when applicable.
+* **Respect licenses**: do not paste or rely on large verbatim copyrighted snippets without appropriate permission or attribution.
+
+This policy encourages fast iteration while maintaining quality and transparency.
+
+---
+
+## License
+
+This project is available under the MIT License — see the `LICENSE` file for details.
+
+---

src/quant_research_starter.egg-info/PKG-INFO

@@ -12,6 +12,7 @@ src/quant_research_starter.egg-info/requires.txt
 src/quant_research_starter.egg-info/top_level.txt
 src/quant_research_starter/backtest/__init__.py
 src/quant_research_starter/backtest/vectorized.py
+src/quant_research_starter/dashboard/streamlit_app.py
 src/quant_research_starter/data/__init__.py
 src/quant_research_starter/data/downloaders.py
 src/quant_research_starter/data/init.py

src/quant_research_starter.egg-info/SOURCES.txt

@@ -1,16 +1,15 @@
 """Vectorized backtesting engine."""
 
 from typing import Dict, Optional
-
+import numpy as np
 import pandas as pd
 
-
 class VectorizedBacktest:
     """
     Vectorized backtester for quantitative strategies.
 
     Features:
-    - Daily rebalancing with position sizing
+    - Configurable rebalancing frequency (daily, weekly, monthly)
     - Transaction costs (fixed and proportional)
     - Portfolio constraints (leverage, concentration)
     - Realistic market dynamics (slippage, execution)
@@ -23,9 +22,21 @@ def __init__(
         initial_capital: float = 1_000_000,
         transaction_cost: float = 0.001,  # 10 bps
         max_leverage: float = 1.0,
-        min_position_size: float = 0.001,  # 0.1% of portfolio
+        min_position_size: float = 0.001,  
         rebalance_freq: str = "D",
     ):
+        """
+        Initialize vectorized backtester.
+
+        Args:
+            prices: DataFrame with price data (symbols as columns, dates as index)
+            signals: DataFrame with trading signals (symbols as columns, dates as index)
+            initial_capital: Starting capital amount
+            transaction_cost: Transaction cost as fraction of trade value
+            max_leverage: Maximum portfolio leverage
+            min_position_size: Minimum position size as fraction of portfolio
+            rebalance_freq: Rebalancing frequency ("D"=daily, "W"=weekly, "M"=monthly)
+        """
         self.prices = prices
         self.signals = signals
         self.initial_capital = initial_capital
@@ -64,7 +75,7 @@ def run(self, weight_scheme: str = "rank") -> Dict:
         """
         print("Running backtest...")
 
-        # Vectorized returns-based backtest with daily rebalancing
+        # Vectorized returns-based backtest with configurable rebalancing frequency
         returns_df = self.prices.pct_change().dropna()
         aligned_signals = self.signals.loc[returns_df.index]
 
@@ -75,6 +86,16 @@ def run(self, weight_scheme: str = "rank") -> Dict:
         # Ensure full DataFrame with same columns order
         weights = weights.reindex(columns=self.prices.columns).fillna(0.0)
 
+        # Apply rebalancing frequency - only rebalance on specified dates
+        rebalance_mask = weights.index.map(self._should_rebalance)
+        # Broadcast mask to match DataFrame shape
+        rebalance_mask_df = pd.DataFrame(
+            np.tile(rebalance_mask.values.reshape(-1, 1), (1, len(weights.columns))), 
+            index=weights.index, 
+            columns=weights.columns
+        )
+        weights = weights.where(rebalance_mask_df, weights.shift(1).fillna(0.0))
+
         # Previous day weights for PnL calculation
         weights_prev = weights.shift(1).fillna(0.0)
 
@@ -106,9 +127,16 @@ def run(self, weight_scheme: str = "rank") -> Dict:
 
     def _should_rebalance(self, date: pd.Timestamp) -> bool:
         """Check if we should rebalance on given date."""
-        # Simple daily rebalancing for now
-        # Could be extended for weekly/monthly rebalancing
-        return True
+        if self.rebalance_freq == "D":
+            return True
+        elif self.rebalance_freq == "W":
+            # Rebalance on Mondays (week start)
+            return date.weekday() == 0
+        elif self.rebalance_freq == "M":
+            # Rebalance on first trading day of month
+            return date.day == 1
+        else:
+            raise ValueError(f"Unsupported rebalance frequency: {self.rebalance_freq}")
 
     def _calculate_weights(self, signals: pd.Series, scheme: str) -> pd.Series:
         """Convert signals to portfolio weights."""