Examples and tutorials

In this section, you can read about some example models, supplied by some Jupyter notebook tutorials, to better understand and explore the package. In the menu, you can find the links for all the notebooks. The tutorials include the models explained in this page, a tutorial on the different samplers and a plotting tutorial.

Toy model

This is a simple Gaussian distribution with known parameters $N(1,1)$. This has been thought for tutorial purposes only, so that estimated parameters can be compared to the true ones. The chosen loss function is the MSM loss and all five built-in samplers are employed.

Here you can find the tutorial.

Simple shock model

This is a simple example of a stock price suddenly increasing due to a shock.

$$P(t) = \begin{cases} p_1, \quad t < \tau \\ p_2, \quad t \geq \tau \end{cases}$$

The model parameters are $p_1$, $p_2$ and $\tau$.

The model is fit on Slack Technologies stock price data, meant to quantify the shock after the spread of rumors about Salesforce wanting to acquire Slack (check here for the news). The loss function used is the quadratic one and the samplers are Halton, random forest and best batch.

Here you can find the tutorial.

SIR

This is an agent-based SIR model, whose parameters $\beta$ and $\gamma$ must be estimated.

In this model, each agent has a probability of being infected by having a contact with another agent and a probability of recovering. Such probabilities are modeled by the SIR parameters, while the contact network is modeled by a random graph generated by a Watts-Strogatz model.

As you will notice, in this tutorial, the model simulation is not implemented directly in Python but an external simulator is called and run on a docker container. For more information on how to use this option, check the simulator interface page.

The chosen loss function is the quadratic loss and the chosen samplers are Halton, random forest and best batch samplers.

The tutorial is divided in two parts: in the first one we will generate synthetic data feed it to black-it, in order to retrieve the parameters that were used to generate the synthetic time series.

In the second part, we will extend the simple SIR model, introducing a structural break in the $\beta$ parameter. This break is meant to model a lockdown or any event changing the infection rate. The calibration must retrieve the infection rates before ($\beta_1$) and after ($\beta_2$) the structural break, the recovery rate $\gamma$, and the moment $t$ in which the break happened. In this second part the model is fit on Italian lockdown data in 2020, slightly modified for didactic purposes.

Here you can find the tutorial.

Boltzmann wealth model

This is a simple agent-based model where every agent gives one unit of wealth to a random agent if a certain criterion is met (i.e. the ratio of the agents' wealth must be above a chosen threshold).

Here you can find the tutorial where the model is calibrated on the Italian Gini index in 2017.