feat: add weekly/monthly rebalancing option (#4)

- Update _should_rebalance to respect W and M frequencies

- Refactor run method to use conditional rebalancing logic

- Add comprehensive tests for D/W/M rebalancing

- Document rebalance_freq parameter in README

- All tests pass; daily default unchanged

Author: saumya1317

README.md

@@ -22,7 +22,7 @@ QuantResearchStarter aims to provide a clean, well-documented starting point for
 
 * **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 transaction costs, slippage, portfolio constraints, and configurable rebalancing frequencies (daily, weekly, monthly).
 * **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.
@@ -93,6 +93,30 @@ results = bt.run()
 print(results.performance.summary())
 ```
 
+### Rebalancing Frequency
+
+The backtester supports different rebalancing frequencies to match your strategy needs:
+
+```python
+from quant_research_starter.backtest import VectorizedBacktest
+
+# Daily rebalancing (default)
+bt_daily = VectorizedBacktest(prices, signals, rebalance_freq="D")
+
+# Weekly rebalancing (reduces turnover and transaction costs)
+bt_weekly = VectorizedBacktest(prices, signals, rebalance_freq="W")
+
+# Monthly rebalancing (lowest turnover)
+bt_monthly = VectorizedBacktest(prices, signals, rebalance_freq="M")
+
+results = bt_monthly.run()
+```
+
+Supported frequencies:
+- `"D"`: Daily rebalancing (default)
+- `"W"`: Weekly rebalancing (rebalances when the week changes)
+- `"M"`: Monthly rebalancing (rebalances when the month changes)
+
 > The code above is illustrative—see `examples/` for fully working notebooks and scripts.
 
 ---

src/quant_research_starter/backtest/vectorized.py

@@ -64,16 +64,26 @@ 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
         returns_df = self.prices.pct_change().dropna()
         aligned_signals = self.signals.loc[returns_df.index]
 
-        # Compute daily target weights from signals
-        weights = aligned_signals.apply(
-            lambda row: self._calculate_weights(row, weight_scheme), axis=1
-        )
-        # Ensure full DataFrame with same columns order
-        weights = weights.reindex(columns=self.prices.columns).fillna(0.0)
+        # Track rebalancing
+        prev_rebalance_date = None
+        current_weights = pd.Series(0.0, index=self.prices.columns)
+        
+        # Compute daily weights from signals (rebalance only on rebalance dates)
+        weights_list = []
+        for date in returns_df.index:
+            if self._should_rebalance(date, prev_rebalance_date):
+                # Rebalance: compute new target weights
+                current_weights = self._calculate_weights(aligned_signals.loc[date], weight_scheme)
+                prev_rebalance_date = date
+            
+            # Append current weights (maintain between rebalances)
+            weights_list.append(current_weights)
+        
+        weights = pd.DataFrame(weights_list, index=returns_df.index, columns=self.prices.columns).fillna(0.0)
 
         # Previous day weights for PnL calculation
         weights_prev = weights.shift(1).fillna(0.0)
@@ -104,11 +114,34 @@ def run(self, weight_scheme: str = "rank") -> Dict:
 
         return self._generate_results()
 
-    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
+    def _should_rebalance(self, date: pd.Timestamp, prev_rebalance_date: Optional[pd.Timestamp] = None) -> bool:
+        """Check if we should rebalance on given date.
+        
+        Args:
+            date: Current date to check
+            prev_rebalance_date: Last rebalance date (None for first rebalance)
+            
+        Returns:
+            True if should rebalance, False otherwise
+        """
+        # Always rebalance on first date
+        if prev_rebalance_date is None:
+            return True
+            
+        if self.rebalance_freq == "D":
+            # Daily rebalancing
+            return True
+        elif self.rebalance_freq == "W":
+            # Weekly rebalancing - rebalance if week changed
+            return date.isocalendar()[1] != prev_rebalance_date.isocalendar()[1] or \
+                   date.year != prev_rebalance_date.year
+        elif self.rebalance_freq == "M":
+            # Monthly rebalancing - rebalance if month changed
+            return date.month != prev_rebalance_date.month or \
+                   date.year != prev_rebalance_date.year
+        else:
+            raise ValueError(f"Unsupported rebalance frequency: {self.rebalance_freq}. "
+                           f"Supported frequencies: 'D' (daily), 'W' (weekly), 'M' (monthly)")
 
     def _calculate_weights(self, signals: pd.Series, scheme: str) -> pd.Series:
         """Convert signals to portfolio weights."""

tests/test_backtest.py

@@ -125,3 +125,77 @@ def test_transaction_costs(self, sample_data):
 
         # With costs should have lower final value (or equal)
         assert results_with_cost["final_value"] <= results_no_cost["final_value"]
+
+    def test_rebalance_frequency_daily(self, sample_data):
+        """Test daily rebalancing (default behavior)."""
+        prices, signals = sample_data
+        backtest = VectorizedBacktest(prices, signals, rebalance_freq="D")
+        results = backtest.run()
+
+        # Check that backtest runs successfully
+        assert results["final_value"] > 0
+        assert len(results["portfolio_value"]) == len(prices)
+
+    def test_rebalance_frequency_weekly(self, sample_data):
+        """Test weekly rebalancing."""
+        prices, signals = sample_data
+        backtest = VectorizedBacktest(prices, signals, rebalance_freq="W")
+        results = backtest.run()
+
+        # Check that backtest runs successfully
+        assert results["final_value"] > 0
+        assert len(results["portfolio_value"]) == len(prices)
+
+        # Weekly rebalancing should result in fewer position changes
+        # Count the number of times weights change
+        positions = results["positions"]
+        position_changes = (positions.diff().abs().sum(axis=1) > 0).sum()
+        
+        # Should be significantly fewer than daily (100 days)
+        # Approximately ~14 weeks in 100 days
+        assert position_changes < len(prices) - 1
+
+    def test_rebalance_frequency_monthly(self, sample_data):
+        """Test monthly rebalancing."""
+        prices, signals = sample_data
+        backtest = VectorizedBacktest(prices, signals, rebalance_freq="M")
+        results = backtest.run()
+
+        # Check that backtest runs successfully
+        assert results["final_value"] > 0
+        assert len(results["portfolio_value"]) == len(prices)
+
+        # Monthly rebalancing should result in fewer position changes than weekly
+        positions = results["positions"]
+        position_changes = (positions.diff().abs().sum(axis=1) > 0).sum()
+        
+        # Should be significantly fewer than daily
+        # Approximately ~3 months in 100 days
+        assert position_changes < len(prices) - 1
+
+    def test_rebalance_frequency_invalid(self, sample_data):
+        """Test that invalid rebalance frequency raises error."""
+        prices, signals = sample_data
+        backtest = VectorizedBacktest(prices, signals, rebalance_freq="X")
+        
+        with pytest.raises(ValueError, match="Unsupported rebalance frequency"):
+            backtest.run()
+
+    def test_rebalance_reduces_turnover(self, sample_data):
+        """Test that less frequent rebalancing reduces turnover."""
+        prices, signals = sample_data
+
+        # Daily rebalancing
+        backtest_daily = VectorizedBacktest(prices, signals, rebalance_freq="D", transaction_cost=0.001)
+        results_daily = backtest_daily.run()
+
+        # Monthly rebalancing
+        backtest_monthly = VectorizedBacktest(prices, signals, rebalance_freq="M", transaction_cost=0.001)
+        results_monthly = backtest_monthly.run()
+
+        # Count position changes as proxy for turnover
+        daily_changes = (results_daily["positions"].diff().abs().sum(axis=1) > 0).sum()
+        monthly_changes = (results_monthly["positions"].diff().abs().sum(axis=1) > 0).sum()
+
+        # Monthly should have fewer rebalances
+        assert monthly_changes < daily_changes