LibAdalina examples#

We provide a set of examples to show how to use the libadalina-core and libadalina-analytics libraries. These examples are implemented as Jupyter notebooks and cover various aspects of using the library, from basic usage to more advanced analytics features.

To run these example notebooks, you need to have Python 3.10 installed along with the following packages:

  • notebook

  • libadalina-core

  • libadalina-analytics

We provide two ways to run the examples:

  • using a Docker image that contains all the required dependencies

  • installing the required packages in a Python 3.10 environment on Linux

We also provide examples that run only on the Amelia platform, since they require the ameliadp_sql_toolkit library. These examples don’t need any configuration as long as the notebook kernel runs on Python 3.10, but they require to upload the sample datasets to the Amelia database.

Docker image#

We provide a Docker image that contains all the required dependencies to run the examples. This is the fastest way to start using the examples.

The image is built on top of the official python:3.10-slim image and includes:

  • Jupyter notebook

  • libadalina-analytics

  • all the dependencies required to run the examples

You can run the image from Docker Hub using the following command:

docker run -p "8888:8888" dexterux/adalina-examples:latest

which should start the Jupyter notebook server and print the URL to access the notebooks, e.g.

[C 2025-09-10 14:52:22.048 ServerApp] 
    
    To access the server, open this file in a browser:
        file:///root/.local/share/jupyter/runtime/jpserver-1-open.html
    Or copy and paste one of these URLs:
        http://7e416aaa80ca:8888/tree?token=7617376e3bb26ddb69078159a7c9e8418f67a9ee6f49acff
        http://127.0.0.1:8888/tree?token=7617376e3bb26ddb69078159a7c9e8418f67a9ee6f49acff

The Dockerfile used to build the image and all the notebooks with the examples are also available at the example repository page. Datasets used in the examples can also be downloaded at the samples repository page.

Note

The repository containing the datasets is a LFS (Large File Storage) repository, which means that you need to have Git LFS installed to clone it.

Run on Linux#

Install Miniconda and create a Python environment#

Download and install Miniconda for your Linux distribution.

To verify that Miniconda is installed, run the following command to print the installed version:

conda -V

which should print something like:

conda 25.7.0

Note

Although it is possible to skip the installation of Miniconda and use an existing Python 10 environment, we recommend using Miniconda or an equivalent solution to get a clean and isolated environment.

Create a new Python 10 environment using the following command:

conda create -n libadalina python=3.10 -y

Conda may require to accept the terms of service for the Anaconda repository. Follow the instructions printed by conda to accept the terms of service

conda tos accept --override-channels --channel https://repo.anaconda.com/pkgs/main
conda tos accept --override-channels --channel https://repo.anaconda.com/pkgs/r
conda tos accept --override-channels --channel https://repo.anaconda.com/pkgs/msys2

and then re-run the command to create the environment.

You can now active the new environment using the following command:

conda activate libadalina

Install libadalina#

First, install the notebook package

pip install notebook

Then install both the libadalina-core and libadalina-analytics packages using pip.

If you downloaded the source archives containing the libraries, you should extract them in two folders named libadalina_core and libadalina_analytics.
You can install them using pip as follows:

cd libadalina_core
pip install .
cd ../libadalina_analytics
pip install .

Otherwise, you can install the libraries directly from the PyPI repository using the following command:

pip install libadalina-core libadalina-analytics

Note

libadalina-core is a dependency of libadalina-analytics, so if you install libadalina-analytics using pip, libadalina-core will be installed automatically.

Run the examples#

You can run the examples by extracting the example archive or by cloning the example repository using git:

git clone --recurse-submodules https://gitlab.com/adalina_unimi/libadalina-examples.git

Note

The samples datasets repository is an LFS (Large File Storage) repository, so if you download the archive using git you need to have git-lfs installed.

You should now have a directory named libadalina-examples that contains three folders:

  • standalone: contains the examples that can run on a personal computer and use local datasets.

  • samples: contains the sample datasets used in the standalone examples.

  • amelia: contains the examples that can run only on Amelia, since they read the datasets using the ameliadp_sql_toolkit library and connect to the Amelia database; these examples can be run on Amelia after uploading the samples datasets to the Amelia database.

Enter the folder libadalina-examples, set the environment variable with the path of the sample datasets, and start the Jupyter notebook server:

cd libadalina-examples
export SAMPLES_DIR="$PWD/samples"
python -m notebook --ServerApp.root_dir=./standalone

The Jupyter notebook server should start and open a browser window with the Jupyter interface at http://localhost:8888/.