Skip to content

Commit

Permalink
[docs] : Add autobuilt documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
LegrandNico committed Aug 22, 2022
1 parent 1392168 commit cba04fa
Show file tree
Hide file tree
Showing 98 changed files with 472 additions and 56 deletions.
36 changes: 36 additions & 0 deletions .github/workflows/docs.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
name: Build and Deploy

on:
push:
branches:
- ecg
pull_request:
branches:
- ecg
permissions:
contents: write

jobs:
build-and-deploy:
runs-on: ubuntu-latest
steps:
- name: Checkout 🛎️
uses: actions/checkout@v3

- name: Set up Python 3.9
uses: actions/setup-python@v1
with:
python-version: 3.9

- name: Build
run: |
pip install git+https://github.com/embodied-computation-group/systole.git@dev
pip install .
pip install -r requirements-docs.txt
sphinx-build -b html docs/source docs/build/html
- name: Deploy 🚀
uses: JamesIves/github-pages-deploy-action@v4
with:
folder: docs/build/html
BRANCH: gh-pages
100 changes: 44 additions & 56 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,80 +2,56 @@

---

# The multilevel, generalized and nodalized Hierarchical Gaussian Filter for predictive coding
# HGF.py

This repository implements the generalized and nodalized Hierarchical Gaussian Filter in Python and [JAX](https://jax.readthedocs.io/en/latest/jax.html). This refactoring offers two advantages:
1. it offers significant performance improvement as compared to pure Python code.
2. it makes the model function itself differentiable in a way that optimization can be performed using e.g MCMC sampling and the model can be embedded as a log probability function in Hierarchical Bayesian models e.g using [Numpyro](https://num.pyro.ai/en/latest/index.html#introductory-tutorials).
The multilevel, generalized and nodalized Hierarchical Gaussian Filter for predictive coding

> **Note:** This branch is a fork of the generalized and nodalized HGF repository and is mainly developed by Nicolas Legrand from the ECG lab (Aarhus University). It is still largely experimental.
**HGF.py** is a Python library that implements the generalized and nodalized Hierarchical Gaussian Filter in Python. It uses [JAX](https://jax.readthedocs.io/en/latest/jax.html) and [Numba](http://numba.pydata.org/) as backend for compilation. Parameters probability distribution can be estimated using MCMC sampling using [PyMC](https://www.pymc.io/welcome.html).

---

# Tutorials
## Getting started

> Under construction
### Installation

| Notebook | Colab | nbViewer |
| --- | ---| --- |
| Binary HGF | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/ilabcode/ghgf/raw/ecg/notebooks/1-Binary%20HGF.ipynb) | [![View the notebook](https://img.shields.io/badge/render-nbviewer-orange.svg)](https://nbviewer.jupyter.org/github/ilabcode/ghgf/raw/ecg/notebooks/1-Binary%20HGF.ipynb)
| Continuous HGF | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/ilabcode/ghgf/raw/ecg/notebooks/2-Continuous%20HGF.ipynb) | [![View the notebook](https://img.shields.io/badge/render-nbviewer-orange.svg)](https://nbviewer.jupyter.org/github/ilabcode/ghgf/raw/ecg/notebooks/2-Continuous%20HGF.ipynb)
| Hierarchical HGF | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/ilabcode/ghgf/raw/ecg/notebooks/3-HierarchicalHGF.ipynb) | [![View the notebook](https://img.shields.io/badge/render-nbviewer-orange.svg)](https://nbviewer.jupyter.org/github/ilabcode/ghgf/raw/ecg/notebooks/3-HierarchicalHGF.ipynb)

# Getting started
## Pure Python code
The latest release of **HGF.py** can be installed from PyPI using pip:

Example of surprise minimization on a continuous input using the pure Python implementation.
`pip install ghgf`

```python
import os
from numpy import loadtxt
from ghgf.hgf import StandardHGF
### Example

# Load time series
timeserie = loadtxt("./test/data/usdchf.dat")

stdhgf = StandardHGF(
n_levels=2,
model_type="GRW",
initial_mu={"1": 1.04, "2": 1.0},
initial_pi={"1": 1e4, "2": 1e1},
omega={"1": -13.0, "2": -2.0},
rho={"1": 0.0, "2": 0.0},
kappas={"1": 1.0},
)
```
`
Continuous Hierarchical Gaussian Filter
... Initializing a 2 levels perceptual HGF using a GRW model.
`

```python
%timeit
stdhgf.input(timeserie)
```
`
6.81 ms ± 22.6 µs per loop (mean ± std. dev. of 7 runs, 100 loops each)
`
Fitting a continuous 3 levels HGF model on time series.

## JAX backend

```python
from numpy import loadtxt
from ghgf.model import HGF
from ghgf import load_data
import jax.numpy as jnp

data = jnp.array([timeserie, jnp.arange(1, len(timeserie) + 1, dtype=float)]).T

jaxhgf = HGF(
n_levels=2,
model_type="GRW",
initial_mu={"1": 1.04, "2": 1.0},
initial_pi={"1": 1e4, "2": 1e1},
omega={"1": -13.0, "2": -2.0},
# Load time series example data
timeserie = load_data("continuous")

# Format input data and add a time vector
data = jnp.array(
[
timeserie,
jnp.arange(1, len(timeserie) + 1, dtype=float)
]
).T

# This is where we define all the model parameters - You can control the value of
# different variables at different levels using the corresponding dictionary.
hgf_model = HGF(
n_levels=3,
initial_mu={"1": 1.04, "2": 1.0, "3": 1.0},
initial_pi={"1": 1e4, "2": 1e1, "3": 1.0},
omega={"1": -13.0, "2": -2.0, "3": -2.0},
rho={"1": 0.0, "2": 0.0},
kappas={"1": 1.0},
kappas={"1": 1.0, "2": 1.0},
)

```

`
Fitting the continuous Hierarchical Gaussian Filter (JAX) with 2 levels.
`
Expand All @@ -102,3 +78,15 @@ Plot the beliefs trajectories.
jaxhgf.plot_trajectories()
```
![png](./docs/images/trajectories.png)

## Tutorials

> Under construction
| Notebook | Colab | nbViewer |
| --- | ---| --- |
| Binary HGF | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/ilabcode/ghgf/raw/ecg/notebooks/1-Binary%20HGF.ipynb) | [![View the notebook](https://img.shields.io/badge/render-nbviewer-orange.svg)](https://nbviewer.jupyter.org/github/ilabcode/ghgf/raw/ecg/notebooks/1-Binary%20HGF.ipynb)
| Continuous HGF | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/ilabcode/ghgf/raw/ecg/notebooks/2-Continuous%20HGF.ipynb) | [![View the notebook](https://img.shields.io/badge/render-nbviewer-orange.svg)](https://nbviewer.jupyter.org/github/ilabcode/ghgf/raw/ecg/notebooks/2-Continuous%20HGF.ipynb)
| Hierarchical HGF | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/ilabcode/ghgf/raw/ecg/notebooks/3-HierarchicalHGF.ipynb) | [![View the notebook](https://img.shields.io/badge/render-nbviewer-orange.svg)](https://nbviewer.jupyter.org/github/ilabcode/ghgf/raw/ecg/notebooks/3-HierarchicalHGF.ipynb)

##
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes
File renamed without changes
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
Loading

0 comments on commit cba04fa

Please sign in to comment.