pathforge 0.1.0__py3-none-any.whl

pathforge/__init__.py

@@ -0,0 +1,6 @@
+from pathforge.forge import PathForge
+from pathforge.result import SimulationResult
+
+__version__ = "0.1.0"
+
+__all__ = ["PathForge", "SimulationResult"]

pathforge/forge.py

@@ -0,0 +1,97 @@
+import numpy as np
+import pandas as pd
+from pathforge.result import SimulationResult
+
+## MAIN CLASS
+class PathForge:
+    """
+    Fits a statistical model to historical price data and generates
+    simulated future price paths.
+    """
+    def __init__(self, data):
+        self._prices = self._extract_prices(data)
+        self._returns = self._prices.pct_change().dropna()
+        self._model = None
+        self._fitted = False
+
+    def _extract_prices(self, data):
+        if isinstance(data, pd.Series):
+            return data.dropna()
+        if isinstance(data, pd.DataFrame):
+            return data.iloc[:, 0].dropna()
+        raise TypeError("data must be a pandas Series or DataFrame")
+    
+    def fit(self, model="garch"):
+        """
+        Fit a simulation model to the historical price data.
+
+        Parameters
+        ----------
+        model : str
+            "gbm", "garch", or "bootstrap"
+        """
+        if model == "gbm":
+            from pathforge.models.gbm import GBMModel
+            self._model = GBMModel(self._returns)
+        elif model == "garch":
+            from pathforge.models.garch import GARCHModel
+            self._model = GARCHModel(self._returns)
+        elif model == "bootstrap":
+            from pathforge.models.bootstrap import BlockBootstrapModel
+            self._model = BlockBootstrapModel(self._returns)
+        elif model == "jump_diffusion":
+            from pathforge.models.jump_diffusion import JumpDiffusionModel
+            self._model = JumpDiffusionModel(self._returns) 
+        else:
+            raise ValueError(f"Unknown model '{model}'. Choose from: gbm, garch, bootstrap")
+
+        self._model.fit()
+        self._fitted = True
+        return self #allows forge.fit("garch").simulate(...) in one line etc.
+
+    #Simulation method
+    def simulate(self, days=252, n_paths=100, start_price=None, seed=None):
+        """
+        Generate simulated price paths.
+
+        Parameters
+        ----------
+        days : int
+            Number of trading days to simulate. 252 is one trading year.
+        n_paths : int
+            Number of independent paths to generate.
+        start_price : float, optional
+            Starting price. Defaults to the last observed price.
+        seed : int, optional
+            Random seed for reproducibility.
+        """
+        if not self._fitted:
+            raise RuntimeError("Call .fit() before .simulate()")
+
+        if seed is not None:
+            np.random.seed(seed)
+
+        if start_price is None:
+            start_price = float(self._prices.iloc[-1])
+
+        returns_matrix = self._model.sample(days=days, n_paths=n_paths)
+        price_paths = self._build_price_paths(returns_matrix, start_price)
+
+        return SimulationResult(price_paths, historical_prices=self._prices, model_name=self._model.__class__.__name__)
+
+    #Build price paths is reverse of pct_change()
+    def _build_price_paths(self, returns_matrix, start_price):
+        """Convert a matrix of returns into price paths."""
+        n_days, n_paths = returns_matrix.shape
+        price_paths = np.empty((n_days + 1, n_paths))
+        price_paths[0] = start_price
+        for t in range(n_days):
+            price_paths[t + 1] = price_paths[t] * (1 + returns_matrix[t])
+        return price_paths
+    
+
+    
+
+        
+
+

pathforge/models/__init__.py

@@ -0,0 +1,6 @@
+from pathforge.models.gbm import GBMModel
+from pathforge.models.garch import GARCHModel
+from pathforge.models.bootstrap import BlockBootstrapModel
+from pathforge.models.jump_diffusion import JumpDiffusionModel
+
+__all__ = ["GBMModel", "GARCHModel", "BlockBootstrapModel", "JumpDiffusionModel"]

pathforge/models/base.py

@@ -0,0 +1,18 @@
+import numpy as np
+import pandas as pd
+
+
+class BaseModel:
+    """Base class for all PathForge simulation models."""
+
+    def __init__(self, returns):
+        self.returns = returns.values.astype(float)
+        self.params_ = {}
+
+    def fit(self):
+        raise NotImplementedError
+
+    def sample(self, days, n_paths):
+        raise NotImplementedError
+    
+    

pathforge/models/bootstrap.py

@@ -0,0 +1,58 @@
+import numpy as np
+from pathforge.models.base import BaseModel
+
+
+class BlockBootstrapModel(BaseModel):
+    """
+    Block Bootstrap model.
+
+    Resamples contiguous blocks of historical returns to generate
+    simulated paths. Makes no distributional assumptions — the
+    simulated paths are built entirely from real historical data.
+    """
+
+    def __init__(self, returns, block_size=None):
+        super().__init__(returns)
+        self._block_size_override = block_size
+
+    def fit(self):
+        if self._block_size_override is not None:
+            block_size = self._block_size_override
+        else:
+            block_size = self._estimate_block_size()
+
+        self.params_["block_size"] = block_size
+
+    def sample(self, days, n_paths):
+        block_size = self.params_["block_size"]
+        n = len(self.returns)
+        simulated = np.empty((days, n_paths))
+
+        for path in range(n_paths):
+            path_returns = []
+            while len(path_returns) < days:
+                start = np.random.randint(0, n - block_size + 1)
+                block = self.returns[start: start + block_size]
+                remaining = days - len(path_returns)
+                path_returns.extend(block[:remaining].tolist())
+            simulated[:, path] = path_returns
+
+        return simulated
+
+    def _estimate_block_size(self):
+        """Estimate block size from the autocorrelation of squared returns."""
+        sq_returns = self.returns ** 2
+        n = len(sq_returns)
+        max_lag = min(50, n // 5)
+        threshold = 1.96 / np.sqrt(n)
+
+        acf = np.array([
+            np.corrcoef(sq_returns[:-lag], sq_returns[lag:])[0, 1]
+            for lag in range(1, max_lag + 1)
+        ])
+
+        significant_lags = np.where(np.abs(acf) > threshold)[0]
+
+        if len(significant_lags) == 0:
+            return 10
+        return max(10, int(significant_lags[-1]) + 1)

pathforge/models/garch.py

@@ -0,0 +1,49 @@
+import numpy as np
+import warnings
+from pathforge.models.base import BaseModel
+
+
+class GARCHModel(BaseModel):
+    """
+    GARCH(1,1) model.
+
+    Captures volatility clustering — the tendency for large price
+    moves to be followed by more large moves.
+    """
+
+    def fit(self):
+        try:
+            from arch import arch_model
+        except ImportError:
+            raise ImportError("Install arch to use GARCH: pip install arch")
+
+        pct_returns = self.returns * 100
+
+        am = arch_model(pct_returns, mean="Constant", vol="GARCH", p=1, q=1)
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore")
+            result = am.fit(disp="off")
+
+        params = result.params
+        self.params_["mu"] = float(params["mu"]) / 100
+        self.params_["omega"] = float(params["omega"]) / 10000
+        self.params_["alpha"] = float(params["alpha[1]"])
+        self.params_["beta"] = float(params["beta[1]"])
+
+    def sample(self, days, n_paths):
+        mu = self.params_["mu"]
+        omega = self.params_["omega"]
+        alpha = self.params_["alpha"]
+        beta = self.params_["beta"]
+
+        hist_var = np.var(self.returns)
+        simulated = np.empty((days, n_paths))
+
+        for path in range(n_paths):
+            sigma2 = hist_var
+            for t in range(days):
+                eps = np.random.normal(0, np.sqrt(sigma2))
+                simulated[t, path] = mu + eps
+                sigma2 = omega + alpha * eps**2 + beta * sigma2
+
+        return simulated

pathforge/models/gbm.py

@@ -0,0 +1,26 @@
+import numpy as np
+from pathforge.models.base import BaseModel
+
+
+class GBMModel(BaseModel):
+    """
+    Geometric Brownian Motion model.
+
+    Fits a normal distribution to historical log-returns,
+    then simulates new returns using that distribution.
+    """
+
+    def fit(self):
+        log_returns = np.log1p(self.returns)
+        self.params_["mu"] = float(log_returns.mean())
+        self.params_["sigma"] = float(log_returns.std())
+
+    def sample(self, days, n_paths):
+        mu = self.params_["mu"]
+        sigma = self.params_["sigma"]
+
+        Z = np.random.standard_normal((days, n_paths))
+        log_returns = (mu - 0.5 * sigma**2) + sigma * Z
+        return np.expm1(log_returns)
+    
+    

pathforge/models/jump_diffusion.py

@@ -0,0 +1,62 @@
+import numpy as np
+from pathforge.models.base import BaseModel
+
+
+class JumpDiffusionModel(BaseModel):
+    """
+    Merton Jump Diffusion model.
+
+    Extends GBM by adding a Poisson jump component to capture
+    sudden large price moves such as crashes or earnings surprises.
+
+    Parameters
+    ----------
+    returns : pd.Series
+        Daily simple returns.
+    jump_threshold : float
+        Number of standard deviations beyond which a historical
+        return is classified as a jump. Default is 3.
+    """
+
+    def __init__(self, returns, jump_threshold=3.0):
+        super().__init__(returns)
+        self.jump_threshold = jump_threshold
+
+    def fit(self):
+        # Step 1 — fit the GBM component on normal days
+        std = self.returns.std()
+        jump_mask = np.abs(self.returns) > self.jump_threshold * std
+
+        normal_returns = self.returns[~jump_mask]
+        jump_returns = self.returns[jump_mask]
+
+        log_normal = np.log1p(normal_returns)
+        self.params_["mu"] = float(log_normal.mean())
+        self.params_["sigma"] = float(log_normal.std())
+
+        # Step 2 — fit the jump component
+        n_days = len(self.returns)
+        self.params_["lambda"] = float(len(jump_returns) / n_days)
+        self.params_["mu_j"] = float(jump_returns.mean()) if len(jump_returns) > 0 else 0.0
+        self.params_["sigma_j"] = float(jump_returns.std()) if len(jump_returns) > 1 else 0.01
+
+    
+    def sample(self, days, n_paths):
+        mu = self.params_["mu"]
+        sigma = self.params_["sigma"]
+        lam = self.params_["lambda"]
+        mu_j = self.params_["mu_j"]
+        sigma_j = self.params_["sigma_j"]
+
+        # GBM component
+        Z = np.random.standard_normal((days, n_paths))
+        log_returns = (mu - 0.5 * sigma**2) + sigma * Z
+
+        # Jump component
+        jumps_occur = np.random.poisson(lam, (days, n_paths))
+        jump_sizes = np.random.normal(mu_j, sigma_j, (days, n_paths))
+        jump_component = jumps_occur * jump_sizes
+
+        return np.expm1(log_returns + jump_component)
+    
+    

pathforge/result.py

@@ -0,0 +1,96 @@
+import numpy as np
+import pandas as pd
+
+
+class SimulationResult:
+    """
+    The output of a PathForge simulation.
+
+    Attributes
+    ----------
+    paths : np.ndarray, shape (days+1, n_paths)
+        Simulated price paths. Row 0 is the starting price.
+    """
+
+    def __init__(self, paths, historical_prices=None, model_name=""):
+        self.paths = paths
+        self.historical_prices = historical_prices
+        self.model_name = model_name
+
+    def to_dataframe(self):
+        """Return simulated paths as a pandas DataFrame."""
+        n_paths = self.paths.shape[1]
+        columns = [f"path_{i}" for i in range(n_paths)]
+        return pd.DataFrame(self.paths, columns=columns)
+
+    def summary(self):
+        """Print a statistical summary of the simulated paths."""
+        start = self.paths[0, 0]
+        final = self.paths[-1, :]
+        returns = (final - start) / start
+
+        print(f"Paths         : {self.paths.shape[1]}")
+        print(f"Days          : {self.paths.shape[0] - 1}")
+        print(f"Start price   : {start:.4f}")
+        print(f"")
+        print(f"Final price distribution:")
+        print(f"  Mean        : {final.mean():.4f}")
+        print(f"  Median      : {np.median(final):.4f}")
+        print(f"  Std         : {final.std():.4f}")
+        print(f"  5th pct     : {np.percentile(final, 5):.4f}")
+        print(f"  95th pct    : {np.percentile(final, 95):.4f}")
+        print(f"")
+        print(f"Return distribution:")
+        print(f"  Mean        : {returns.mean():.2%}")
+        print(f"  Median      : {np.median(returns):.2%}")
+        print(f"  5th pct     : {np.percentile(returns, 5):.2%}")
+        print(f"  95th pct    : {np.percentile(returns, 95):.2%}")
+
+    def plot(self, max_paths=50):
+        """
+        Plot simulated price paths.
+
+        Parameters
+        ----------
+        max_paths : int
+            Maximum number of paths to draw. Defaults to 50.
+        """
+        try:
+            import matplotlib.pyplot as plt
+        except ImportError:
+            raise ImportError("Install matplotlib to use .plot(): pip install matplotlib")
+
+        n = min(max_paths, self.paths.shape[1])
+        fig, ax = plt.subplots(figsize=(12, 6))
+
+        for i in range(n):
+            ax.plot(self.paths[:, i], alpha=0.3, lw=0.8, color="steelblue")
+
+        median_path = np.median(self.paths, axis=1)
+        ax.plot(median_path, color="darkblue", lw=2, label="Median path")
+
+        p5 = np.percentile(self.paths, 5, axis=1)
+        p95 = np.percentile(self.paths, 95, axis=1)
+        ax.fill_between(range(len(p5)), p5, p95, alpha=0.15, color="steelblue", label="5–95th percentile")
+
+        if self.historical_prices is not None:
+            hist = self.historical_prices[-126:]
+            hist_normalised = hist / hist.iloc[-1] * self.paths[0, 0]
+            ax.plot(
+                range(-len(hist), 0),
+                hist_normalised.values,
+                color="red",
+                lw=1.5,
+                label="Historical",
+                zorder=5
+            )
+
+        ax.set_title(f"PathForge Simulation — {self.model_name} ({self.paths.shape[1]} paths)")
+        ax.set_xlabel("Days")
+        ax.set_ylabel("Price")
+        ax.grid()
+        ax.legend()
+        plt.tight_layout()
+        plt.show()
+
+    

pathforge-0.1.0.dist-info/METADATA

@@ -0,0 +1,3 @@
+Metadata-Version: 2.4
+Name: pathforge
+Version: 0.1.0

pathforge-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+pathforge/__init__.py,sha256=M9tLY7ChgR_bZDHHTd1JzrLNLlJYVjLAsoibu7gtRK8,156
+pathforge/forge.py,sha256=_0TRjto1ywCosN0H1WRF8rEdpT4lNRWl4E35bg92vMM,3404
+pathforge/result.py,sha256=g09cOA4OGj7onQx5nrr-EdUaDxVU7hEcQ7Tv50hwRaU,3382
+pathforge/models/__init__.py,sha256=M5b7wJ82kLctw6oO66C-531nHFjDBIS3nS9BvsyNCks,299
+pathforge/models/base.py,sha256=r9bFFHv21nGEIDifJ2Pk_XOaaZ8D3iX18YyXtV3EKqE,380
+pathforge/models/bootstrap.py,sha256=-I8pvvnj9qFCS-1BG_c6cObQEldaqYfrWQkWDHb3u20,1945
+pathforge/models/garch.py,sha256=ZREtSz1AF8qi6YvqP9SOYdnBQUvM-ID1-oQYuuZ2eyA,1561
+pathforge/models/gbm.py,sha256=57p5LiLqe2454Df8poOX2uVkqkdbstZfUPJcc9J7Y9g,728
+pathforge/models/jump_diffusion.py,sha256=38jZTRF4Ofh6fGtzduAqmUQ52nCF3G7jgiEhgyBaI7w,2111
+pathforge-0.1.0.dist-info/METADATA,sha256=DMIIS0_zz-wgIDeucyk0Gakqqc1P_MJfPFVYCzZNE8Y,56
+pathforge-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+pathforge-0.1.0.dist-info/top_level.txt,sha256=WBWzGZygpfnpcOQxftawh_h2RpNF3NarOG6tYv62nHw,10
+pathforge-0.1.0.dist-info/RECORD,,

pathforge-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pathforge-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pathforge