.. raw:: html

   <link rel="stylesheet" type="text/css" href="_static/custom.css">

Inference Methods & Examples
=============================

VBI provides multiple approaches for parameter inference, each with different strengths and use cases.

Inference Method Overview
-------------------------

.. list-table:: Inference Methods Comparison
   :header-rows: 1
   :class: color-caption

   * - **Method**
     - **Dependencies**
     - **Performance**
     - **Best For**
   * - **CDE (Conditional Density Estimation)**
     - NumPy + autograd
     - Fast, lightweight
     - Quick inference, limited resources
   * - **SBI (Simulation-Based Inference)**
     - PyTorch + sbi
     - State-of-the-art
     - Complex problems, research

CDE-Based Inference (Lightweight)
----------------------------------

**Conditional Density Estimation** using pure NumPy implementation - no PyTorch required.

**Key Features:**

- ✅ **Lightweight**: Only requires NumPy and autograd
- ✅ **Fast**: Efficient implementation for moderate-scale problems  
- ✅ **Transparent**: Clear mathematical foundation
- ✅ **Flexible**: Easy to customize and extend

Documentation & Tutorials
~~~~~~~~~~~~~~~~~~~~~~~~~~

**Quick Start:**

- :doc:`inference_cde_mdn_basic` - **Quick Start Guide** for MDN (5-minute read)

**Complete Reference:**

- :doc:`inference_cde_guide` - **Comprehensive API Documentation** for MDN and MAF (includes theory, usage, and best practices)

Example Notebooks
~~~~~~~~~~~~~~~~~

Complete examples demonstrating CDE inference on various brain models:

.. toctree::
   :maxdepth: 1

   examples/damp_oscillator_cde
   examples/jansen_rit_sde_numba_cde
   examples/vep_sde_numba_cde
   examples/vep_sde_numba_cde_84
   examples/mpr_sde_numba_cde
   examples/wilson_cowan_sde_numba_cde
   examples/ww_full_sde_numba_cde

**When to use CDE:**

- Limited computational resources
- Want to avoid heavy PyTorch dependency
- Need transparent, interpretable inference

.. - Working with moderate-dimensional problems (< 20 parameters)

SBI-Based Inference (Advanced)
-------------------------------

**Simulation-Based Inference** using PyTorch and the sbi library - state-of-the-art methods.

**Key Features:**

- 🚀 **State-of-the-art**: Latest neural density estimation techniques
- 🧠 **Scalable**: Handles high-dimensional problems efficiently

.. - 🔬 **Research-grade**: Used in cutting-edge neuroscience research
- 🔧 **Comprehensive**: Multiple inference algorithms (SNPE, SNLE, SNRE)

**Current Examples:**

*Note: Most simulation examples currently use SBI for inference. We're working on separating these into dedicated inference tutorials.*

**When to use SBI:**

- Working with high-dimensional parameter spaces (> 10 parameters)
- Need state-of-the-art performance
- Complex, multimodal posterior distributions

.. Choosing Your Inference Method
.. ------------------------------

.. **Decision Tree:**

.. 1. **Do you have PyTorch and sufficient computational resources?**
   
..    - **Yes** → Consider SBI methods
..    - **No** → Use CDE methods

.. 2. **How many parameters are you estimating?**
   
..    - **< 10 parameters** → CDE is often sufficient
..    - **> 10 parameters** → SBI recommended

.. 3. **What's your priority?**
   
..    - **Speed of setup** → CDE
..    - **State-of-the-art accuracy** → SBI
..    - **Interpretability** → CDE
..    - **Scalability** → SBI

Getting Started
---------------

**For CDE Inference:**

1. Start with :doc:`inference_cde_mdn_basic` - Quick start with MDN
2. Read :doc:`inference_cde_guide` - Comprehensive API guide for MDN and MAF
3. Try example notebooks:
   
   - :doc:`examples/damp_oscillator_cde` - Simple damped oscillator
   - :doc:`examples/jansen_rit_sde_numba_cde` - Jansen-Rit neural mass model
   - :doc:`examples/wilson_cowan_sde_numba_cde` - Wilson-Cowan model

4. Apply to your brain model of choice

**For SBI Inference:**

1. Install full VBI: ``pip install vbi[inference]``
2. Check existing simulation examples that include SBI
3. Adapt to your specific use case

Upcoming Examples
-----------------

We're working on expanding the inference examples:

- **CDE + Brain Models**: Direct application to Jansen-Rit, Wilson-Cowan models
- **SBI Tutorials**: Dedicated SBI workflow examples
- **Method Comparisons**: Side-by-side CDE vs SBI comparisons
- **Real Data Examples**: Using experimental neuroimaging data

Performance Guidelines
----------------------

**CDE Performance Tips:**

- Use appropriate number of mixture components (MDN) or layers (MAF)
- Monitor training convergence carefully
- Consider data preprocessing/normalization

**SBI Performance Tips:**

- Use GPU acceleration when available
- Tune simulation budget vs accuracy trade-off
- Consider sequential vs single-round inference

**Memory and Speed:**

- **CDE**: Lower memory usage, faster setup
- **SBI**: Higher memory usage, potentially faster inference for complex problems

Contributing
------------

We welcome contributions of new inference examples! See our `CONTRIBUTING.md` for guidelines on adding new tutorials and examples.