# BellmanFilterDFSV
[](https://www.python.org/downloads/)
[](https://jax.readthedocs.io/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/givani30/BellmanFilterDFSV/actions)
[](https://givani30.github.io/BellmanFilterDFSV/)
**High-performance JAX-based filtering for Dynamic Factor Stochastic Volatility (DFSV) models**
BellmanFilterDFSV is a Python package that provides efficient implementations of filtering algorithms for Dynamic Factor Stochastic Volatility models using JAX for automatic differentiation and JIT compilation.
## ๐ Key Features
- **Multiple Filtering Algorithms**: Bellman Information Filter (BIF), Bellman Filter, and Particle Filter
- **JAX-Powered Performance**: Automatic differentiation, JIT compilation, and vectorization
- **Numerical Stability**: Advanced techniques for robust parameter estimation
- **Clean API**: Intuitive interface for research and applications
- **Extensible Design**: Easy to adapt for other state-space models
- **Comprehensive Testing**: Full test suite with 76+ tests
## ๐ฆ Installation
### Basic Installation
```bash
pip install bellman-filter-dfsv
```
### With Optional Dependencies
```bash
# For data analysis and visualization
pip install bellman-filter-dfsv[analysis]
# For cloud computing and batch processing
pip install bellman-filter-dfsv[cloud]
# For notebook development
pip install bellman-filter-dfsv[notebooks]
# For econometric extensions
pip install bellman-filter-dfsv[econometrics]
# Everything
pip install bellman-filter-dfsv[all]
```
### Development Installation
```bash
git clone https://github.com/givani30/BellmanFilterDFSV.git
cd BellmanFilterDFSV
pip install -e .[dev,all]
```
Or using [uv](https://docs.astral.sh/uv/) (recommended):
```bash
git clone https://github.com/givani30/BellmanFilterDFSV.git
cd BellmanFilterDFSV
uv sync
uv run pytest # Run tests
```
## ๐ Quick Start
```python
import jax.numpy as jnp
from bellman_filter_dfsv.core.models import DFSVParamsDataclass, simulate_DFSV
from bellman_filter_dfsv.core.filters import DFSVBellmanInformationFilter
# Define model parameters
params = DFSVParamsDataclass(
N=3, # Number of observed series
K=1, # Number of factors
Lambda=jnp.array([[0.8], [0.7], [0.9]]),
phi_f=jnp.array([[0.7]]),
phi_h=jnp.array([0.95]),
sigma_f=jnp.array([1.0]),
sigma_h=jnp.array([0.1]),
sigma_eps=jnp.array([0.3, 0.25, 0.35]),
mu=jnp.array([-1.2])
)
# Simulate data
returns, factors, log_vols = simulate_DFSV(params, T=500, key=42)
# Create and run filter
bif = DFSVBellmanInformationFilter(N=3, K=1)
states, covs, loglik = bif.filter(params, returns)
print(f"Log-likelihood: {loglik:.2f}")
print(f"Filtered states shape: {states.shape}")
```
## ๐ Examples
The package includes several comprehensive examples:
- **Basic Simulation**: Simulate DFSV models and analyze properties
- **Filter Comparison**: Compare BIF, Bellman, and Particle filters
- **Parameter Estimation**: Maximum likelihood estimation with optimization
- **Real Data Application**: Apply to financial time series
```bash
# Run examples
python examples/01_dfsv_simulation.py
python examples/02_basic_filtering.py
python examples/03_parameter_optimization.py
```
## ๐๏ธ Architecture
### DFSV Model
The Dynamic Factor Stochastic Volatility model represents observed returns as:
```
y_t = ฮf_t + ฮต_t
```
Where:
- `y_t`: Observed returns (Nร1)
- `f_t`: Latent factors (Kร1)
- `ฮ`: Factor loading matrix (NรK)
- `ฮต_t`: Idiosyncratic errors with stochastic volatility
### Filtering Algorithms
1. **Bellman Information Filter (BIF)**: Information-form implementation for numerical stability
2. **Bellman Filter**: Traditional covariance-form implementation
3. **Particle Filter**: Bootstrap particle filter for non-linear/non-Gaussian cases
## ๐ Project Structure
```text
BellmanFilterDFSV/
โโโ src/bellman_filter_dfsv/ # Core package
โ โโโ core/ # Main functionality
โ โ โโโ filters/ # Filtering algorithms
โ โ โโโ models/ # DFSV model definitions
โ โ โโโ optimization/ # Parameter estimation
โ โโโ utils/ # Utility functions
โโโ examples/ # Usage examples
โโโ tests/ # Test suite
โโโ docs/ # Documentation
โโโ thesis_artifacts/ # Research materials
โโโ pyproject.toml # Package configuration
```
## ๐งช Testing
Run the comprehensive test suite:
```bash
# Run all tests
uv run pytest
# Run with coverage
uv run pytest --cov=bellman_filter_dfsv
# Run specific test
uv run pytest tests/test_unified_filters.py
```
## ๐ Documentation
**๐ [Full Documentation](https://givani30.github.io/BellmanFilterDFSV/)** - Complete API reference, tutorials, and examples
**Local Documentation Build:**
```bash
cd docs/
make html
# Open docs/build/html/index.html
```
## ๐ค Contributing
Contributions are welcome! Please see our [Contributing Guide](docs/source/contributing.rst) for details.
1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Submit a pull request
## ๐ License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## ๐ฌ Research
This package was developed as part of a quantitative finance thesis on Dynamic Factor Stochastic Volatility models.
**๐ [Complete Research Materials](https://github.com/givani30/BellmanFilterDFSV-ThesisResearch)**
All thesis research materials, simulation studies, and experimental code are available in the dedicated research repository. This includes:
- ๐ฏ Monte Carlo simulation studies
- ๐ Empirical analysis with real financial data
- ๐ฌ Experimental implementations and prototypes
- ๐ Complete thesis results and figures
- ๐ Research notes and development logs
See [THESIS_RESEARCH.md](THESIS_RESEARCH.md) for detailed information.
## ๐ Contact
- **Author**: Givani Boekestijn
- **Email**: givaniboek@hotmail.com
- **GitHub**: [@givani30](https://github.com/givani30)
---
**Citation**: If you use this package in your research, please cite:
```bibtex
@software{boekestijn2025bellman,
title={BellmanFilterDFSV: JAX Implementation of Bellman Filter for Dynamic Factor Stochastic Volatility Models},
author={Boekestijn, Givani},
year={2025},
url={https://github.com/givani30/BellmanFilterDFSV},
note={Research materials: https://github.com/givani30/BellmanFilterDFSV-ThesisResearch}
}
```
Raw data
{
"_id": null,
"home_page": null,
"name": "bellman-filter-dfsv",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "jax, filtering, stochastic-volatility, dynamic-factors, econometrics, finance",
"author": null,
"author_email": "Givani Boekestijn <givaniboek@hotmail.com>",
"download_url": "https://files.pythonhosted.org/packages/eb/e0/5ca875704119faf42c80e955d792b83c15cbb4bed76f3272d7dfe024bcfa/bellman_filter_dfsv-1.0.0.tar.gz",
"platform": null,
"description": "# BellmanFilterDFSV\n\n[](https://www.python.org/downloads/)\n[](https://jax.readthedocs.io/)\n[](https://opensource.org/licenses/MIT)\n[](https://github.com/givani30/BellmanFilterDFSV/actions)\n[](https://givani30.github.io/BellmanFilterDFSV/)\n\n**High-performance JAX-based filtering for Dynamic Factor Stochastic Volatility (DFSV) models**\n\nBellmanFilterDFSV is a Python package that provides efficient implementations of filtering algorithms for Dynamic Factor Stochastic Volatility models using JAX for automatic differentiation and JIT compilation.\n\n## \ud83d\ude80 Key Features\n\n- **Multiple Filtering Algorithms**: Bellman Information Filter (BIF), Bellman Filter, and Particle Filter\n- **JAX-Powered Performance**: Automatic differentiation, JIT compilation, and vectorization\n- **Numerical Stability**: Advanced techniques for robust parameter estimation\n- **Clean API**: Intuitive interface for research and applications\n- **Extensible Design**: Easy to adapt for other state-space models\n- **Comprehensive Testing**: Full test suite with 76+ tests\n\n## \ud83d\udce6 Installation\n\n### Basic Installation\n\n```bash\npip install bellman-filter-dfsv\n```\n\n### With Optional Dependencies\n\n```bash\n# For data analysis and visualization\npip install bellman-filter-dfsv[analysis]\n\n# For cloud computing and batch processing\npip install bellman-filter-dfsv[cloud]\n\n# For notebook development\npip install bellman-filter-dfsv[notebooks]\n\n# For econometric extensions\npip install bellman-filter-dfsv[econometrics]\n\n# Everything\npip install bellman-filter-dfsv[all]\n```\n\n### Development Installation\n\n```bash\ngit clone https://github.com/givani30/BellmanFilterDFSV.git\ncd BellmanFilterDFSV\npip install -e .[dev,all]\n```\n\nOr using [uv](https://docs.astral.sh/uv/) (recommended):\n\n```bash\ngit clone https://github.com/givani30/BellmanFilterDFSV.git\ncd BellmanFilterDFSV\nuv sync\nuv run pytest # Run tests\n```\n\n## \ud83d\ude80 Quick Start\n\n```python\nimport jax.numpy as jnp\nfrom bellman_filter_dfsv.core.models import DFSVParamsDataclass, simulate_DFSV\nfrom bellman_filter_dfsv.core.filters import DFSVBellmanInformationFilter\n\n# Define model parameters\nparams = DFSVParamsDataclass(\n N=3, # Number of observed series\n K=1, # Number of factors\n Lambda=jnp.array([[0.8], [0.7], [0.9]]),\n phi_f=jnp.array([[0.7]]),\n phi_h=jnp.array([0.95]),\n sigma_f=jnp.array([1.0]),\n sigma_h=jnp.array([0.1]),\n sigma_eps=jnp.array([0.3, 0.25, 0.35]),\n mu=jnp.array([-1.2])\n)\n\n# Simulate data\nreturns, factors, log_vols = simulate_DFSV(params, T=500, key=42)\n\n# Create and run filter\nbif = DFSVBellmanInformationFilter(N=3, K=1)\nstates, covs, loglik = bif.filter(params, returns)\n\nprint(f\"Log-likelihood: {loglik:.2f}\")\nprint(f\"Filtered states shape: {states.shape}\")\n```\n\n## \ud83d\udcca Examples\n\nThe package includes several comprehensive examples:\n\n- **Basic Simulation**: Simulate DFSV models and analyze properties\n- **Filter Comparison**: Compare BIF, Bellman, and Particle filters\n- **Parameter Estimation**: Maximum likelihood estimation with optimization\n- **Real Data Application**: Apply to financial time series\n\n```bash\n# Run examples\npython examples/01_dfsv_simulation.py\npython examples/02_basic_filtering.py\npython examples/03_parameter_optimization.py\n```\n\n## \ud83c\udfd7\ufe0f Architecture\n\n### DFSV Model\n\nThe Dynamic Factor Stochastic Volatility model represents observed returns as:\n\n```\ny_t = \u039bf_t + \u03b5_t\n```\n\nWhere:\n- `y_t`: Observed returns (N\u00d71)\n- `f_t`: Latent factors (K\u00d71)\n- `\u039b`: Factor loading matrix (N\u00d7K)\n- `\u03b5_t`: Idiosyncratic errors with stochastic volatility\n\n### Filtering Algorithms\n\n1. **Bellman Information Filter (BIF)**: Information-form implementation for numerical stability\n2. **Bellman Filter**: Traditional covariance-form implementation\n3. **Particle Filter**: Bootstrap particle filter for non-linear/non-Gaussian cases\n\n## \ud83d\udcc1 Project Structure\n\n```text\nBellmanFilterDFSV/\n\u251c\u2500\u2500 src/bellman_filter_dfsv/ # Core package\n\u2502 \u251c\u2500\u2500 core/ # Main functionality\n\u2502 \u2502 \u251c\u2500\u2500 filters/ # Filtering algorithms\n\u2502 \u2502 \u251c\u2500\u2500 models/ # DFSV model definitions\n\u2502 \u2502 \u2514\u2500\u2500 optimization/ # Parameter estimation\n\u2502 \u2514\u2500\u2500 utils/ # Utility functions\n\u251c\u2500\u2500 examples/ # Usage examples\n\u251c\u2500\u2500 tests/ # Test suite\n\u251c\u2500\u2500 docs/ # Documentation\n\u251c\u2500\u2500 thesis_artifacts/ # Research materials\n\u2514\u2500\u2500 pyproject.toml # Package configuration\n```\n\n## \ud83e\uddea Testing\n\nRun the comprehensive test suite:\n\n```bash\n# Run all tests\nuv run pytest\n\n# Run with coverage\nuv run pytest --cov=bellman_filter_dfsv\n\n# Run specific test\nuv run pytest tests/test_unified_filters.py\n```\n\n## \ud83d\udcda Documentation\n\n**\ud83d\udcd6 [Full Documentation](https://givani30.github.io/BellmanFilterDFSV/)** - Complete API reference, tutorials, and examples\n\n**Local Documentation Build:**\n\n```bash\ncd docs/\nmake html\n# Open docs/build/html/index.html\n```\n\n## \ud83e\udd1d Contributing\n\nContributions are welcome! Please see our [Contributing Guide](docs/source/contributing.rst) for details.\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes with tests\n4. Submit a pull request\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## \ud83d\udd2c Research\n\nThis package was developed as part of a quantitative finance thesis on Dynamic Factor Stochastic Volatility models.\n\n**\ud83d\udcda [Complete Research Materials](https://github.com/givani30/BellmanFilterDFSV-ThesisResearch)**\n\nAll thesis research materials, simulation studies, and experimental code are available in the dedicated research repository. This includes:\n\n- \ud83c\udfaf Monte Carlo simulation studies\n- \ud83d\udcca Empirical analysis with real financial data\n- \ud83d\udd2c Experimental implementations and prototypes\n- \ud83d\udcc8 Complete thesis results and figures\n- \ud83d\udcdd Research notes and development logs\n\nSee [THESIS_RESEARCH.md](THESIS_RESEARCH.md) for detailed information.\n\n## \ud83d\udcde Contact\n\n- **Author**: Givani Boekestijn\n- **Email**: givaniboek@hotmail.com\n- **GitHub**: [@givani30](https://github.com/givani30)\n\n---\n\n**Citation**: If you use this package in your research, please cite:\n\n```bibtex\n@software{boekestijn2025bellman,\n title={BellmanFilterDFSV: JAX Implementation of Bellman Filter for Dynamic Factor Stochastic Volatility Models},\n author={Boekestijn, Givani},\n year={2025},\n url={https://github.com/givani30/BellmanFilterDFSV},\n note={Research materials: https://github.com/givani30/BellmanFilterDFSV-ThesisResearch}\n}\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "High-performance JAX-based filtering for Dynamic Factor Stochastic Volatility (DFSV) models",
"version": "1.0.0",
"project_urls": null,
"split_keywords": [
"jax",
" filtering",
" stochastic-volatility",
" dynamic-factors",
" econometrics",
" finance"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "0fdba2f07e31212de04a7b6671e5b63a713705fc1779081ad8e14aad434712d5",
"md5": "120786377e870a6facfe24ceaf09572a",
"sha256": "c86c35a4d8ed4500218c88bec86ef759863d9a1f50a2faeedb0b375abc6adaf2"
},
"downloads": -1,
"filename": "bellman_filter_dfsv-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "120786377e870a6facfe24ceaf09572a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 93305,
"upload_time": "2025-08-12T01:10:36",
"upload_time_iso_8601": "2025-08-12T01:10:36.477031Z",
"url": "https://files.pythonhosted.org/packages/0f/db/a2f07e31212de04a7b6671e5b63a713705fc1779081ad8e14aad434712d5/bellman_filter_dfsv-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "ebe05ca875704119faf42c80e955d792b83c15cbb4bed76f3272d7dfe024bcfa",
"md5": "c3b50f01e2a571fe5015c16fcac197e9",
"sha256": "11fc01b99cd7807c008e73f8057ea0f4ab130f3cf11021a07945e0292189b6a5"
},
"downloads": -1,
"filename": "bellman_filter_dfsv-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "c3b50f01e2a571fe5015c16fcac197e9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 116018,
"upload_time": "2025-08-12T01:10:38",
"upload_time_iso_8601": "2025-08-12T01:10:38.464099Z",
"url": "https://files.pythonhosted.org/packages/eb/e0/5ca875704119faf42c80e955d792b83c15cbb4bed76f3272d7dfe024bcfa/bellman_filter_dfsv-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-12 01:10:38",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "bellman-filter-dfsv"
}
JSON