stokestrel 0.1.0__py3-none-any.whl

kestrel/__init__.py

@@ -0,0 +1,32 @@
+# kestrel/__init__.py
+"""
+Kestrel: A Modern Stochastic Modelling Library.
+
+Provides unified interface for fitting and simulating stochastic processes.
+"""
+
+__version__ = "0.1.0"
+
+from kestrel.base import StochasticProcess
+from kestrel.diffusion import (
+    BrownianMotion,
+    GeometricBrownianMotion,
+    OUProcess,
+    CIRProcess,
+)
+from kestrel.jump_diffusion import MertonProcess
+from kestrel.utils import KestrelResult
+
+__all__ = [
+    # Base
+    "StochasticProcess",
+    # Diffusion processes
+    "BrownianMotion",
+    "GeometricBrownianMotion",
+    "OUProcess",
+    "CIRProcess",
+    # Jump diffusion processes
+    "MertonProcess",
+    # Utilities
+    "KestrelResult",
+]

kestrel/base.py

@@ -0,0 +1,77 @@
+# kestrel/base.py
+from abc import ABC, abstractmethod
+import pandas as pd
+import numpy as np
+from kestrel.utils.kestrel_result import KestrelResult
+from typing import Optional
+
+class StochasticProcess(ABC):
+    """
+    Abstract Base Class for Kestrel's stochastic processes.
+    Defines common interface for parameter fitting and path simulation.
+    """
+
+    def __init__(self):
+        self._fitted = False
+        self._params = {} # Stores estimated parameters
+
+    @abstractmethod
+    def fit(self, data: pd.Series, dt: float = None):
+        """
+        Estimates process parameters from time-series data.
+
+        Args:
+            data (pd.Series): Time-series data for model fitting.
+            dt (float, optional): Time step between observations.
+                                   If None, inferred from data; defaults to 1.0.
+        """
+        pass
+
+    @abstractmethod
+    def sample(self, n_paths: int = 1, horizon: int = 1, dt: float = None) -> KestrelResult:
+        """
+        Simulates future process paths.
+
+        Args:
+            n_paths (int): Number of simulation paths to generate.
+            horizon (int): Number of future time steps to simulate.
+            dt (float, optional): Simulation time step.
+                                   If None, uses fitted dt; defaults to 1.0.
+
+        Returns:
+            pd.DataFrame: DataFrame where each column is a simulated path.
+        """
+        pass
+
+    def _set_params(self, last_data_point: float = None, dt: float = None, freq: str = None, param_ses: dict = None, **kwargs):
+        """
+        Sets estimated parameters, their standard errors, and marks model as fitted.
+        """
+        for k, v in kwargs.items():
+            setattr(self, f"{k}_", v) # Underscore denotes estimated parameters
+            self._params[k] = v
+        self._fitted = True
+        if last_data_point is not None:
+            self._last_data_point = last_data_point
+        if dt is not None:
+            self._dt_ = dt
+        if freq is not None:
+            self._freq_ = freq
+        if param_ses is not None:
+            for k, v in param_ses.items():
+                setattr(self, f"{k}_se_", v) # Store standard errors
+                self._params[f"{k}_se"] = v # Also add to params dictionary
+
+    @property
+    def is_fitted(self) -> bool:
+        """
+        Returns True if model fitted, False otherwise.
+        """
+        return self._fitted
+
+    @property
+    def params(self) -> dict:
+        """
+        Returns dictionary of estimated parameters.
+        """
+        return self._params

kestrel/diffusion/__init__.py

@@ -0,0 +1,12 @@
+"""Continuous diffusion processes."""
+
+from kestrel.diffusion.brownian import BrownianMotion, GeometricBrownianMotion
+from kestrel.diffusion.ou import OUProcess
+from kestrel.diffusion.cir import CIRProcess
+
+__all__ = [
+    "BrownianMotion",
+    "GeometricBrownianMotion",
+    "OUProcess",
+    "CIRProcess",
+]

kestrel/diffusion/brownian.py

@@ -0,0 +1,404 @@
+# kestrel/diffusion/brownian.py
+"""Brownian motion and Geometric Brownian Motion implementations."""
+
+import numpy as np
+import pandas as pd
+from scipy.optimize import minimize
+from kestrel.base import StochasticProcess
+from kestrel.utils.kestrel_result import KestrelResult
+
+
+class BrownianMotion(StochasticProcess):
+    """
+    Standard Brownian Motion (Wiener Process) with drift.
+
+    SDE: dX_t = mu * dt + sigma * dW_t
+
+    Parameters
+    ----------
+    mu : float, optional
+        Drift coefficient.
+    sigma : float, optional
+        Volatility (diffusion coefficient).
+    """
+
+    def __init__(self, mu: float = None, sigma: float = None):
+        super().__init__()
+        self.mu = mu
+        self.sigma = sigma
+
+    def fit(self, data: pd.Series, dt: float = None, method: str = 'mle'):
+        """
+        Estimates (mu, sigma) from time-series data.
+
+        Parameters
+        ----------
+        data : pd.Series
+            Observed time-series.
+        dt : float, optional
+            Time step between observations.
+        method : str
+            Estimation method: 'mle' or 'moments'.
+
+        Raises
+        ------
+        ValueError
+            If data not pandas Series or unknown method.
+        """
+        if not isinstance(data, pd.Series):
+            raise ValueError("Input data must be a pandas Series.")
+
+        if dt is None:
+            dt = self._infer_dt(data)
+
+        self.dt_ = dt
+
+        if method == 'mle':
+            param_ses = self._fit_mle(data, dt)
+        elif method == 'moments':
+            param_ses = self._fit_moments(data, dt)
+        else:
+            raise ValueError(f"Unknown estimation method: {method}. Choose 'mle' or 'moments'.")
+
+        self._set_params(
+            last_data_point=data.iloc[-1],
+            mu=self.mu,
+            sigma=self.sigma,
+            dt=self.dt_,
+            param_ses=param_ses
+        )
+
+    def _infer_dt(self, data: pd.Series) -> float:
+        """Infers dt from DatetimeIndex or defaults to 1.0."""
+        if isinstance(data.index, pd.DatetimeIndex):
+            if len(data.index) < 2:
+                return 1.0
+
+            inferred_timedelta = data.index[1] - data.index[0]
+            current_freq = pd.infer_freq(data.index)
+            if current_freq is None:
+                current_freq = 'B'
+
+            if current_freq in ['B', 'C', 'D']:
+                dt = inferred_timedelta / pd.Timedelta(days=252.0)
+            elif current_freq.startswith('W'):
+                dt = inferred_timedelta / pd.Timedelta(weeks=52)
+            elif current_freq in ['M', 'MS', 'BM', 'BMS']:
+                dt = inferred_timedelta / pd.Timedelta(days=365 / 12)
+            elif current_freq in ['Q', 'QS', 'BQ', 'BQS']:
+                dt = inferred_timedelta / pd.Timedelta(days=365 / 4)
+            elif current_freq in ['A', 'AS', 'BA', 'BAS', 'Y', 'YS', 'BY', 'BYS']:
+                dt = inferred_timedelta / pd.Timedelta(days=365)
+            else:
+                dt = inferred_timedelta.total_seconds() / (365 * 24 * 3600)
+
+            return max(dt, 1e-10)
+        return 1.0
+
+    def _fit_mle(self, data: pd.Series, dt: float) -> dict:
+        """Estimates parameters using Maximum Likelihood."""
+        if len(data) < 2:
+            raise ValueError("MLE estimation requires at least 2 data points.")
+
+        x = data.values
+        dx = np.diff(x)
+        n = len(dx)
+
+        # MLE estimates for Brownian motion
+        self.mu = np.mean(dx) / dt
+        self.sigma = np.std(dx, ddof=1) / np.sqrt(dt)
+
+        # Standard errors
+        se_mu = self.sigma / np.sqrt(n * dt)
+        se_sigma = self.sigma / np.sqrt(2 * n)
+
+        return {'mu': se_mu, 'sigma': se_sigma}
+
+    def _fit_moments(self, data: pd.Series, dt: float) -> dict:
+        """Estimates parameters using method of moments."""
+        if len(data) < 2:
+            raise ValueError("Moments estimation requires at least 2 data points.")
+
+        x = data.values
+        dx = np.diff(x)
+        n = len(dx)
+
+        # First moment: E[dX] = mu * dt
+        self.mu = np.mean(dx) / dt
+
+        # Second moment: Var[dX] = sigma^2 * dt
+        self.sigma = np.sqrt(np.var(dx, ddof=1) / dt)
+
+        # Standard errors (approximate)
+        se_mu = self.sigma / np.sqrt(n * dt)
+        se_sigma = self.sigma / np.sqrt(2 * n)
+
+        return {'mu': se_mu, 'sigma': se_sigma}
+
+    def sample(self, n_paths: int = 1, horizon: int = 1, dt: float = None) -> KestrelResult:
+        """
+        Simulates future Brownian motion paths.
+
+        Parameters
+        ----------
+        n_paths : int
+            Number of simulation paths.
+        horizon : int
+            Number of time steps to simulate.
+        dt : float, optional
+            Simulation time step. Uses fitted dt if None.
+
+        Returns
+        -------
+        KestrelResult
+            Simulation results.
+        """
+        if not self.is_fitted and (self.mu is None or self.sigma is None):
+            raise RuntimeError("Model must be fitted or initialised with parameters before sampling.")
+
+        if dt is None:
+            dt = self._dt_ if self.is_fitted and hasattr(self, '_dt_') else 1.0
+
+        mu = self.mu_ if self.is_fitted else self.mu
+        sigma = self.sigma_ if self.is_fitted else self.sigma
+
+        if any(p is None for p in [mu, sigma]):
+            raise RuntimeError("Parameters (mu, sigma) must be set or estimated to sample.")
+
+        paths = np.zeros((horizon + 1, n_paths))
+        if self.is_fitted and hasattr(self, '_last_data_point'):
+            initial_val = self._last_data_point
+        else:
+            initial_val = 0.0
+
+        paths[0, :] = initial_val
+
+        for t in range(horizon):
+            dW = np.random.normal(loc=0.0, scale=np.sqrt(dt), size=n_paths)
+            paths[t + 1, :] = paths[t, :] + mu * dt + sigma * dW
+
+        return KestrelResult(pd.DataFrame(paths), initial_value=initial_val)
+
+
+class GeometricBrownianMotion(StochasticProcess):
+    """
+    Geometric Brownian Motion (GBM).
+
+    Standard model for stock prices.
+    SDE: dS_t = mu * S_t * dt + sigma * S_t * dW_t
+
+    Equivalent to: d(log S_t) = (mu - 0.5*sigma^2) dt + sigma dW_t
+
+    Parameters
+    ----------
+    mu : float, optional
+        Drift (expected return).
+    sigma : float, optional
+        Volatility.
+    """
+
+    def __init__(self, mu: float = None, sigma: float = None):
+        super().__init__()
+        self.mu = mu
+        self.sigma = sigma
+
+    def fit(self, data: pd.Series, dt: float = None, method: str = 'mle'):
+        """
+        Estimates (mu, sigma) from price time-series.
+
+        Parameters
+        ----------
+        data : pd.Series
+            Price time-series (must be strictly positive).
+        dt : float, optional
+            Time step between observations.
+        method : str
+            Estimation method: 'mle' only currently supported.
+
+        Raises
+        ------
+        ValueError
+            If data not pandas Series, contains non-positive values, or unknown method.
+        """
+        if not isinstance(data, pd.Series):
+            raise ValueError("Input data must be a pandas Series.")
+
+        if (data <= 0).any():
+            raise ValueError("GBM requires strictly positive price data.")
+
+        if dt is None:
+            dt = self._infer_dt(data)
+
+        self.dt_ = dt
+
+        if method == 'mle':
+            param_ses = self._fit_mle(data, dt)
+        else:
+            raise ValueError(f"Unknown estimation method: {method}. Choose 'mle'.")
+
+        self._set_params(
+            last_data_point=data.iloc[-1],
+            mu=self.mu,
+            sigma=self.sigma,
+            dt=self.dt_,
+            param_ses=param_ses
+        )
+
+    def _infer_dt(self, data: pd.Series) -> float:
+        """Infers dt from DatetimeIndex or defaults to 1.0."""
+        if isinstance(data.index, pd.DatetimeIndex):
+            if len(data.index) < 2:
+                return 1.0
+
+            inferred_timedelta = data.index[1] - data.index[0]
+            current_freq = pd.infer_freq(data.index)
+            if current_freq is None:
+                current_freq = 'B'
+
+            if current_freq in ['B', 'C', 'D']:
+                dt = inferred_timedelta / pd.Timedelta(days=252.0)
+            elif current_freq.startswith('W'):
+                dt = inferred_timedelta / pd.Timedelta(weeks=52)
+            elif current_freq in ['M', 'MS', 'BM', 'BMS']:
+                dt = inferred_timedelta / pd.Timedelta(days=365 / 12)
+            elif current_freq in ['Q', 'QS', 'BQ', 'BQS']:
+                dt = inferred_timedelta / pd.Timedelta(days=365 / 4)
+            elif current_freq in ['A', 'AS', 'BA', 'BAS', 'Y', 'YS', 'BY', 'BYS']:
+                dt = inferred_timedelta / pd.Timedelta(days=365)
+            else:
+                dt = inferred_timedelta.total_seconds() / (365 * 24 * 3600)
+
+            return max(dt, 1e-10)
+        return 1.0
+
+    def _fit_mle(self, data: pd.Series, dt: float) -> dict:
+        """Estimates parameters using Maximum Likelihood on log-returns."""
+        if len(data) < 2:
+            raise ValueError("MLE estimation requires at least 2 data points.")
+
+        prices = data.values
+        log_returns = np.diff(np.log(prices))
+        n = len(log_returns)
+
+        # MLE for log-returns: r_t = (mu - 0.5*sigma^2)*dt + sigma*sqrt(dt)*Z
+        mean_r = np.mean(log_returns)
+        var_r = np.var(log_returns, ddof=1)
+
+        # Estimate sigma from variance
+        self.sigma = np.sqrt(var_r / dt)
+
+        # Estimate mu from mean and sigma
+        # mean_r = (mu - 0.5*sigma^2) * dt => mu = mean_r/dt + 0.5*sigma^2
+        self.mu = mean_r / dt + 0.5 * self.sigma ** 2
+
+        # Standard errors
+        se_sigma = self.sigma / np.sqrt(2 * n)
+        se_mu = np.sqrt((self.sigma ** 2 / (n * dt)) + (se_sigma ** 2))
+
+        return {'mu': se_mu, 'sigma': se_sigma}
+
+    def sample(self, n_paths: int = 1, horizon: int = 1, dt: float = None) -> KestrelResult:
+        """
+        Simulates future GBM price paths.
+
+        Parameters
+        ----------
+        n_paths : int
+            Number of simulation paths.
+        horizon : int
+            Number of time steps to simulate.
+        dt : float, optional
+            Simulation time step. Uses fitted dt if None.
+
+        Returns
+        -------
+        KestrelResult
+            Simulation results (all paths strictly positive).
+        """
+        if not self.is_fitted and (self.mu is None or self.sigma is None):
+            raise RuntimeError("Model must be fitted or initialised with parameters before sampling.")
+
+        if dt is None:
+            dt = self._dt_ if self.is_fitted and hasattr(self, '_dt_') else 1.0
+
+        mu = self.mu_ if self.is_fitted else self.mu
+        sigma = self.sigma_ if self.is_fitted else self.sigma
+
+        if any(p is None for p in [mu, sigma]):
+            raise RuntimeError("Parameters (mu, sigma) must be set or estimated to sample.")
+
+        paths = np.zeros((horizon + 1, n_paths))
+        if self.is_fitted and hasattr(self, '_last_data_point'):
+            initial_val = self._last_data_point
+        else:
+            initial_val = 1.0  # Default to 1.0 for prices
+
+        paths[0, :] = initial_val
+
+        # Simulate using exact solution: S_{t+dt} = S_t * exp((mu - 0.5*sigma^2)*dt + sigma*sqrt(dt)*Z)
+        for t in range(horizon):
+            Z = np.random.normal(loc=0.0, scale=1.0, size=n_paths)
+            paths[t + 1, :] = paths[t, :] * np.exp((mu - 0.5 * sigma ** 2) * dt + sigma * np.sqrt(dt) * Z)
+
+        return KestrelResult(pd.DataFrame(paths), initial_value=initial_val)
+
+    def expected_price(self, t: float, s0: float = None) -> float:
+        """
+        Computes expected price at time t.
+
+        E[S_t] = S_0 * exp(mu * t)
+
+        Parameters
+        ----------
+        t : float
+            Time horizon.
+        s0 : float, optional
+            Initial price. Uses last fitted value if None.
+
+        Returns
+        -------
+        float
+            Expected price at time t.
+        """
+        mu = self.mu_ if self.is_fitted else self.mu
+        if mu is None:
+            raise RuntimeError("Parameters must be set or estimated first.")
+
+        if s0 is None:
+            if self.is_fitted and hasattr(self, '_last_data_point'):
+                s0 = self._last_data_point
+            else:
+                raise ValueError("Initial price s0 must be provided.")
+
+        return s0 * np.exp(mu * t)
+
+    def variance_price(self, t: float, s0: float = None) -> float:
+        """
+        Computes variance of price at time t.
+
+        Var[S_t] = S_0^2 * exp(2*mu*t) * (exp(sigma^2*t) - 1)
+
+        Parameters
+        ----------
+        t : float
+            Time horizon.
+        s0 : float, optional
+            Initial price. Uses last fitted value if None.
+
+        Returns
+        -------
+        float
+            Variance of price at time t.
+        """
+        mu = self.mu_ if self.is_fitted else self.mu
+        sigma = self.sigma_ if self.is_fitted else self.sigma
+        if any(p is None for p in [mu, sigma]):
+            raise RuntimeError("Parameters must be set or estimated first.")
+
+        if s0 is None:
+            if self.is_fitted and hasattr(self, '_last_data_point'):
+                s0 = self._last_data_point
+            else:
+                raise ValueError("Initial price s0 must be provided.")
+
+        return (s0 ** 2) * np.exp(2 * mu * t) * (np.exp(sigma ** 2 * t) - 1)