stokestrel 0.1.0__tar.gz

stokestrel-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

stokestrel-0.1.0/PKG-INFO

@@ -0,0 +1,234 @@
+Metadata-Version: 2.4
+Name: stokestrel
+Version: 0.1.0
+Summary: A modern stochastic modelling library for parameter estimation and Monte Carlo simulation.
+Author-email: April Kidd <bk0851@outlook.com>
+License: MIT
+Project-URL: Homepage, https://github.com/april-webm/kestrel
+Project-URL: Documentation, https://github.com/april-webm/kestrel#readme
+Project-URL: Repository, https://github.com/april-webm/kestrel
+Project-URL: Issues, https://github.com/april-webm/kestrel/issues
+Project-URL: Changelog, https://github.com/april-webm/kestrel/releases
+Keywords: stochastic,sde,monte-carlo,simulation,ornstein-uhlenbeck,brownian-motion,quantitative-finance,time-series
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.20
+Requires-Dist: scipy>=1.7
+Requires-Dist: pandas>=1.3
+Requires-Dist: matplotlib>=3.4
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Dynamic: license-file
+
+# Kestrel
+
+<!-- TODO: Add kestrel image -->
+<p align="center">
+  <img src="assets/kestrel.png" alt="Kestrel" width="200">
+</p>
+
+[![PyPI version](https://img.shields.io/pypi/v/stokestrel.svg)](https://pypi.org/project/stokestrel/)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A modern Python library for stochastic process modelling, parameter estimation, and Monte Carlo simulation.
+
+## Overview
+
+Kestrel provides a unified, scikit-learn-style interface for working with stochastic differential equations (SDEs). The library supports parameter estimation from time-series data and path simulation for a variety of continuous and jump-diffusion processes.
+
+### Supported Processes
+
+| Process | Module | Description |
+|---------|--------|-------------|
+| Brownian Motion | `kestrel.diffusion` | Standard Wiener process with drift |
+| Geometric Brownian Motion | `kestrel.diffusion` | Log-normal price dynamics (Black-Scholes) |
+| Ornstein-Uhlenbeck | `kestrel.diffusion` | Mean-reverting Gaussian process |
+| Cox-Ingersoll-Ross | `kestrel.diffusion` | Mean-reverting process with state-dependent volatility |
+| Merton Jump Diffusion | `kestrel.jump_diffusion` | GBM with Poisson-distributed jumps |
+
+### Key Features
+
+- **Consistent API**: All processes follow `fit()` / `sample()` pattern
+- **Multiple Estimation Methods**: MLE, AR(1) regression, least squares
+- **Standard Error Reporting**: Parameter uncertainty quantification
+- **Flexible Time Handling**: Automatic dt inference from DatetimeIndex
+- **Simulation Engine**: Euler-Maruyama discretisation with exact solutions where available
+
+## Installation
+
+**Requirements**: Python 3.9+
+
+```bash
+pip install stokestrel
+```
+
+For development installation:
+
+```bash
+git clone https://github.com/april-webm/kestrel.git
+cd kestrel
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+```python
+from kestrel import OUProcess
+import pandas as pd
+
+# Load or generate time-series data
+data = pd.Series([...])  # Your observed data
+
+# Fit model parameters
+model = OUProcess()
+model.fit(data, dt=1/252, method='mle')
+
+# View estimated parameters and standard errors
+print(f"Mean reversion speed: {model.theta_:.4f} ± {model.theta_se_:.4f}")
+print(f"Long-run mean: {model.mu_:.4f} ± {model.mu_se_:.4f}")
+print(f"Volatility: {model.sigma_:.4f} ± {model.sigma_se_:.4f}")
+
+# Simulate future paths
+paths = model.sample(n_paths=1000, horizon=252)
+paths.plot(title="OU Process Simulation")
+```
+
+## Usage Examples
+
+### Ornstein-Uhlenbeck Process
+
+Mean-reverting process commonly used for interest rates and volatility modelling.
+
+```python
+from kestrel import OUProcess
+
+model = OUProcess()
+model.fit(data, dt=1/252, method='mle')  # or method='ar1'
+
+# Simulate from fitted model
+simulation = model.sample(n_paths=100, horizon=50)
+```
+
+### Geometric Brownian Motion
+
+Standard model for equity prices.
+
+```python
+from kestrel import GeometricBrownianMotion
+
+model = GeometricBrownianMotion()
+model.fit(price_data, dt=1/252)
+
+# Expected price and variance at horizon
+expected = model.expected_price(t=1.0, s0=100)
+variance = model.variance_price(t=1.0, s0=100)
+```
+
+### Cox-Ingersoll-Ross Process
+
+Ensures non-negativity; suitable for interest rate modelling.
+
+```python
+from kestrel import CIRProcess
+
+model = CIRProcess()
+model.fit(rate_data, dt=1/252, method='mle')
+
+# Check Feller condition for strict positivity
+if model.feller_condition_satisfied():
+    print("Process guaranteed to remain positive")
+```
+
+### Merton Jump Diffusion
+
+Captures sudden market movements via Poisson jumps.
+
+```python
+from kestrel import MertonProcess
+
+model = MertonProcess()
+model.fit(log_returns, dt=1/252)
+
+# Jump-adjusted expected return
+total_drift = model.expected_return()
+total_var = model.total_variance()
+```
+
+## API Reference
+
+### Base Interface
+
+All stochastic processes inherit from `StochasticProcess` and implement:
+
+| Method | Description |
+|--------|-------------|
+| `fit(data, dt, method)` | Estimate parameters from time-series |
+| `sample(n_paths, horizon, dt)` | Generate Monte Carlo paths |
+| `is_fitted` | Property indicating fit status |
+| `params` | Dictionary of estimated parameters |
+
+### Fitted Attributes
+
+After calling `fit()`, estimated parameters are available as attributes with trailing underscore:
+
+```python
+model.theta_      # Estimated parameter value
+model.theta_se_   # Standard error of estimate
+```
+
+## Dependencies
+
+- numpy
+- scipy
+- pandas
+- matplotlib
+
+## Testing
+
+```bash
+pytest tests/ -v
+```
+
+## Contributing
+
+Contributions are welcome. Please ensure:
+
+1. Code follows existing style conventions
+2. New features include appropriate tests
+3. Documentation is updated accordingly
+
+## License
+
+Released under the MIT License. See [LICENSE](LICENSE) for details.
+
+## Citation
+
+If Kestrel is used in academic research, citation is appreciated:
+
+```bibtex
+@software{stokestrel,
+  title = {Stokestrel: A Modern Stochastic Modelling Library},
+  author = {Kidd, April},
+  url = {https://github.com/april-webm/kestrel},
+  version = {0.1.0},
+  year = {2024}
+}
+```

stokestrel-0.1.0/README.md

@@ -0,0 +1,195 @@
+# Kestrel
+
+<!-- TODO: Add kestrel image -->
+<p align="center">
+  <img src="assets/kestrel.png" alt="Kestrel" width="200">
+</p>
+
+[![PyPI version](https://img.shields.io/pypi/v/stokestrel.svg)](https://pypi.org/project/stokestrel/)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A modern Python library for stochastic process modelling, parameter estimation, and Monte Carlo simulation.
+
+## Overview
+
+Kestrel provides a unified, scikit-learn-style interface for working with stochastic differential equations (SDEs). The library supports parameter estimation from time-series data and path simulation for a variety of continuous and jump-diffusion processes.
+
+### Supported Processes
+
+| Process | Module | Description |
+|---------|--------|-------------|
+| Brownian Motion | `kestrel.diffusion` | Standard Wiener process with drift |
+| Geometric Brownian Motion | `kestrel.diffusion` | Log-normal price dynamics (Black-Scholes) |
+| Ornstein-Uhlenbeck | `kestrel.diffusion` | Mean-reverting Gaussian process |
+| Cox-Ingersoll-Ross | `kestrel.diffusion` | Mean-reverting process with state-dependent volatility |
+| Merton Jump Diffusion | `kestrel.jump_diffusion` | GBM with Poisson-distributed jumps |
+
+### Key Features
+
+- **Consistent API**: All processes follow `fit()` / `sample()` pattern
+- **Multiple Estimation Methods**: MLE, AR(1) regression, least squares
+- **Standard Error Reporting**: Parameter uncertainty quantification
+- **Flexible Time Handling**: Automatic dt inference from DatetimeIndex
+- **Simulation Engine**: Euler-Maruyama discretisation with exact solutions where available
+
+## Installation
+
+**Requirements**: Python 3.9+
+
+```bash
+pip install stokestrel
+```
+
+For development installation:
+
+```bash
+git clone https://github.com/april-webm/kestrel.git
+cd kestrel
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+```python
+from kestrel import OUProcess
+import pandas as pd
+
+# Load or generate time-series data
+data = pd.Series([...])  # Your observed data
+
+# Fit model parameters
+model = OUProcess()
+model.fit(data, dt=1/252, method='mle')
+
+# View estimated parameters and standard errors
+print(f"Mean reversion speed: {model.theta_:.4f} ± {model.theta_se_:.4f}")
+print(f"Long-run mean: {model.mu_:.4f} ± {model.mu_se_:.4f}")
+print(f"Volatility: {model.sigma_:.4f} ± {model.sigma_se_:.4f}")
+
+# Simulate future paths
+paths = model.sample(n_paths=1000, horizon=252)
+paths.plot(title="OU Process Simulation")
+```
+
+## Usage Examples
+
+### Ornstein-Uhlenbeck Process
+
+Mean-reverting process commonly used for interest rates and volatility modelling.
+
+```python
+from kestrel import OUProcess
+
+model = OUProcess()
+model.fit(data, dt=1/252, method='mle')  # or method='ar1'
+
+# Simulate from fitted model
+simulation = model.sample(n_paths=100, horizon=50)
+```
+
+### Geometric Brownian Motion
+
+Standard model for equity prices.
+
+```python
+from kestrel import GeometricBrownianMotion
+
+model = GeometricBrownianMotion()
+model.fit(price_data, dt=1/252)
+
+# Expected price and variance at horizon
+expected = model.expected_price(t=1.0, s0=100)
+variance = model.variance_price(t=1.0, s0=100)
+```
+
+### Cox-Ingersoll-Ross Process
+
+Ensures non-negativity; suitable for interest rate modelling.
+
+```python
+from kestrel import CIRProcess
+
+model = CIRProcess()
+model.fit(rate_data, dt=1/252, method='mle')
+
+# Check Feller condition for strict positivity
+if model.feller_condition_satisfied():
+    print("Process guaranteed to remain positive")
+```
+
+### Merton Jump Diffusion
+
+Captures sudden market movements via Poisson jumps.
+
+```python
+from kestrel import MertonProcess
+
+model = MertonProcess()
+model.fit(log_returns, dt=1/252)
+
+# Jump-adjusted expected return
+total_drift = model.expected_return()
+total_var = model.total_variance()
+```
+
+## API Reference
+
+### Base Interface
+
+All stochastic processes inherit from `StochasticProcess` and implement:
+
+| Method | Description |
+|--------|-------------|
+| `fit(data, dt, method)` | Estimate parameters from time-series |
+| `sample(n_paths, horizon, dt)` | Generate Monte Carlo paths |
+| `is_fitted` | Property indicating fit status |
+| `params` | Dictionary of estimated parameters |
+
+### Fitted Attributes
+
+After calling `fit()`, estimated parameters are available as attributes with trailing underscore:
+
+```python
+model.theta_      # Estimated parameter value
+model.theta_se_   # Standard error of estimate
+```
+
+## Dependencies
+
+- numpy
+- scipy
+- pandas
+- matplotlib
+
+## Testing
+
+```bash
+pytest tests/ -v
+```
+
+## Contributing
+
+Contributions are welcome. Please ensure:
+
+1. Code follows existing style conventions
+2. New features include appropriate tests
+3. Documentation is updated accordingly
+
+## License
+
+Released under the MIT License. See [LICENSE](LICENSE) for details.
+
+## Citation
+
+If Kestrel is used in academic research, citation is appreciated:
+
+```bibtex
+@software{stokestrel,
+  title = {Stokestrel: A Modern Stochastic Modelling Library},
+  author = {Kidd, April},
+  url = {https://github.com/april-webm/kestrel},
+  version = {0.1.0},
+  year = {2024}
+}
+```

stokestrel-0.1.0/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",
+]

stokestrel-0.1.0/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

stokestrel-0.1.0/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",
+]