[MRG] Add UNHaP experiments and documentation

README.md

@@ -1,17 +1,29 @@
 # FaDIn: Fast Discretized Inference For Hawkes Processes with General Parametric Kernels
+# UNHaP: Unmixing Noise from Hawkes Processes
 
 ![build](https://img.shields.io/github/actions/workflow/status/GuillaumeStaermanML/FaDIn/unit_tests.yml?event=push&style=for-the-badge)
 ![python version](https://img.shields.io/badge/python-3.7_|_3.8_|_3.9_|_3.10_|_3.11-blue?style=for-the-badge)
 ![license](https://img.shields.io/github/license/GuillaumeStaermanML/FaDIn?style=for-the-badge)
 ![code style](https://img.shields.io/badge/code_style-black-black?style=for-the-badge)
 
-This Package implements FaDIn.
+This package implements FaDIn and UNHaP. FaDIn and UNHaP are solvers for inference of Hawkes Processes with finite-support kernels on simulated or real data, with the following features:
+- Computation time is low compared to other methods.
+- Compatible in an univariate setting as well as a multivariate setting.
+- Classical kernels (exponential truncated gaussian, raised cosine) are implemented. The user can add their own kernel for inference. 
+- Masking: if only a few Hawkes Parameters need to be inferred, the user can mask the other parameters.
+- Smart initialization of parameters before optimization: the user can choose between `random` (purely random), `moment_matching_max` (moment matching with maximum mode) and `moment_matching_mean` (moment matching with mean mode).
 
-## Installation
 
-**To install this package, make sure you have an up-to-date version of** `pip`.
+[FaDIn](https://proceedings.mlr.press/v202/staerman23a/staerman23a.pdf) does classical Hawkes inference with gradient descent.
+[UNHaP](https://raw.githubusercontent.com/mlresearch/v258/main/assets/loison25a/loison25a.pdf) does Hawkes inference where the Hawkes Process is marked and mixed with a noisy Poisson process.
 
 
+## Installation
+
+**To install this package, make sure you have an up-to-date version of** `pip`.
+```bash
+python3 -m pip install --upgrade pip
+```
 ### From PyPI (coming soon)
 
 In a dedicated Python env, run:
@@ -41,6 +53,12 @@ pip install -e ".[dev]"
 pre-commit install
 ```
 
+## Short examples
+A few illustrative examples are provided in the `examples` folder of this repository:
+- `plot_univariate_fadin`: simulate an univariate unmarked Hawkes process, infer Hawkes Process parameters using FaDIn, and plot inferred kernel.
+- `plot_multivariate_fadin`: same as `plot_univariate_fadin` but in the multivariate case.
+- `plot_unhap`: simulate an univariate marked Hawkes process and a marked Poisson process, infer Hawkes Process parameters using UNHaP, ald plot inferred kernels.
+
 ## Citing this work
 
 If this package was useful to you, please cite it in your work:
@@ -54,4 +72,12 @@ If this package was useful to you, please cite it in your work:
   year={2023},
   organization={PMLR}
 }
+
+@improceedings{loison2025unhap,
+title={UNHaP: Unmixing Noise from Hawkes Process},
+author={Loison, Virginie and Staerman, Guillaume and Moreau, Thomas},
+booktitle={International Conference on Artificial Intelligence and Statistics},
+pages={1342--1350},
+year={2025}
+}
 ```

examples/plot_unhap.py

@@ -45,7 +45,7 @@
 # %% Create the simulating function
 
 
-def simulate_data(baseline, baseline_noise, alpha, end_time, seed=0):
+def simulate_marked_data(baseline, baseline_noise, alpha, end_time, seed=0):
     n_dim = len(baseline)
 
     marks_kernel = identity
@@ -102,15 +102,15 @@ def simulate_data(baseline, baseline_noise, alpha, end_time, seed=0):
         np.zeros(marked_events[i].shape[0] + noisy_events_[i].shape[0])
         for i in range(n_dim)
     ]
-    labels[0][-marked_events[0].shape[0] :] = 1.0
+    labels[0][-marked_events[0].shape[0]:] = 1.0
     true_rho = [labels[i][events[i][:, 0].argsort()] for i in range(n_dim)]
     # put the mark to one to test the impact of the marks
     # events_cat[0][:, 1] = 1.
 
     return events_cat, noisy_marks, true_rho
 
 
-ev, noisy_marks, true_rho = simulate_data(
+ev, noisy_marks, true_rho = simulate_marked_data(
     baseline, baseline_noise.item(), alpha, end_time, seed=0
 )
 # %% Apply UNHAP
@@ -119,14 +119,14 @@ def simulate_data(baseline, baseline_noise, alpha, end_time, seed=0):
     n_dim=1,
     kernel="truncated_gaussian",
     kernel_length=1.0,
+    init='moment_matching_mean',
     delta=delta,
     optim="RMSprop",
     params_optim={"lr": 1e-3},
     max_iter=max_iter,
     batch_rho=batch_rho,
     density_hawkes="linear",
     density_noise="uniform",
-    moment_matching=True,
 )
 solver.fit(ev, end_time)