# LibAdalina examples

We provide a set of examples to show how to use the [_libadalina-core_](https://gitlab.com/amelia_unimi/libadalinacore) 
and [_libadalina-analytics_](https://gitlab.com/adalina_unimi/libadalinaanalytics) libraries. 
These examples are implemented as [Jupyter notebooks](https://jupyter.org/) 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](https://www.docker.com/) 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:

```bash
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.

```plaintext
[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](https://gitlab.com/adalina_unimi/libadalina-examples).
Datasets used in the examples can also be downloaded at the [samples repository page](https://gitlab.com/adalina_unimi/libadalina-samples).

> **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](https://www.anaconda.com/docs/getting-started/miniconda/main) for your Linux distribution.

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

```bash
conda -V
```

which should print something like:

```plaintext
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:

```bash
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 

```bash
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:

```bash
conda activate libadalina
```

### Install libadalina

First, install the notebook package

```bash
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:

```bash
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:

```bash
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`:

```bash
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](https://git-lfs.com/) 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:

```bash
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/](http://localhost:8888/).