feat: Add Bollinger Bands factor

Implements BollingerBandsFactor to compute z-score of price vs rolling mean and std.
Includes tests and integration into factors module.

Closes #3

Author: Satvik-Singh192

src/quant_research_starter/factors/bollinger.py

@@ -0,0 +1,29 @@
+import pandas as pd
+from .base import Factor
+
+
+class BollingerBandsFactor(Factor):
+    """
+    Compute Bollinger Bands z-score:
+    z = (price - rolling_mean) / rolling_std
+    """
+
+    def __init__(self, name: str = "bollinger_bands", lookback: int = 20, num_std: float = 2.0):
+        super().__init__(name=name, lookback=lookback)
+        self.num_std = num_std
+
+    def compute(self, prices: pd.DataFrame) -> pd.DataFrame:
+        # Validate data
+        self._validate_data(prices)
+
+        # Rolling statistics
+        rolling_mean = prices.rolling(self.lookback).mean()
+        rolling_std = prices.rolling(self.lookback).std()
+
+        # Bollinger z-score
+        zscore = (prices - rolling_mean) / rolling_std
+
+        # Save results
+        self._values = zscore
+
+        return zscore

tests/test_factors.py

@@ -9,6 +9,7 @@
     SizeFactor,
     ValueFactor,
     VolatilityFactor,
+    BollingerBandsFactor,
 )
 
 
@@ -195,3 +196,31 @@ def test_volatility_calculation(self):
         assert (
             spearman_corr < -0.5
         ), f"volatility factor should be negatively correlated with realized volatility (spearman={spearman_corr})"
+
+class TestBollingerBandsFactor:
+    """Test Bollinger Bands factor calculations."""
+
+    def test_bollinger_basic(self, sample_prices):
+        """Test basic Bollinger Bands z-score calculation."""
+        factor = BollingerBandsFactor(lookback=20, num_std=2.0)
+        result = factor.compute(sample_prices)
+
+        # Must be a DataFrame with same shape as prices
+        assert isinstance(result, pd.DataFrame)
+        assert not result.empty
+        assert set(result.columns) == set(sample_prices.columns)
+
+        # Values should be finite where enough data exists
+        valid_values = result.iloc[factor.lookback:].values.flatten()
+        assert np.all(np.isfinite(valid_values)), "NaNs found after lookback period"
+
+        # Mean of z-scores should be roughly centered near 0
+        mean_z = np.nanmean(valid_values)
+        assert abs(mean_z) < 0.5, f"Z-scores not centered: mean={mean_z}"
+
+    def test_bollinger_lookback_validation(self, sample_prices):
+        """Ensure _validate_data raises for insufficient data."""
+        short_data = sample_prices.iloc[:5]
+        factor = BollingerBandsFactor(lookback=10)
+        with pytest.raises(ValueError):
+            factor.compute(short_data)