---
# System prepended metadata

title: Manuale utente

---

# Manuale utente

## Installazione
Eseguire il comando `$ make install` direttamente dal proprio terminale, assumendo che sull'host siano installati `python3` e `pip3`. <br>In questo caso verrà creato un ambiente virtuale in cui saranno installate le dipendenze del progetto. <br>Lo user dovrà poi attivare l'environment per mezzo del comando `$ source bioinfo_env/bin/activate` ed eseguire il programma portandosi nella root del progetto.
 


## Modalità d'uso

Per trainare / testare le reti è sufficiente eseguire lo script `main.py` con i relativi argomenti:
```
usage: main.py [-h] [--seed SEED] [--output_dir OUTPUT_DIR]
               [--path_source_data PATH_SOURCE_DATA]
               [--sequence_type {dna,protein}] [--train] [--validation]
               [--test] [--lr LR] [--num_epochs NUM_EPOCHS]
               [--batch_size BATCH_SIZE]
               [--network_parameters NETWORK_PARAMETERS]
               [--load_network LOAD_NETWORK] [--onehot_flag]
               [--early_stopping_on_loss]
               [--early_stopping_epoch EARLY_STOPPING_EPOCH]
               [--pretrained_model PRETRAINED_MODEL]

optional arguments:
  -h, --help            show this help message and exit
  --seed SEED           Value assigned to global seed for initializing
                        tensorflow module entirely.
  --output_dir OUTPUT_DIR
                        Directory path for storing all results gained from
                        running this analysis tool.
  --path_source_data PATH_SOURCE_DATA
                        Path that specifies the location of source datasets.
  --sequence_type {dna,protein,kmers}
                        Type of sequence to process in the model: "dna",
                        "protein" or "kmers"
  --train               Train model on whole training data and save it
  --validation          Perform Holdout-Validation for hyperparameter
                        selection
  --test                Test saved model, in the specified subdir, on test bin
  --lr LR               Learning rate coefficient
  --num_epochs NUM_EPOCHS
                        Number of epochs before halting the training
  --batch_size BATCH_SIZE
                        Number of sample for each training step
  --network_parameters NETWORK_PARAMETERS
                        File with neural network parameters, either json or
                        yaml format
  --load_network LOAD_NETWORK
                        Architecture's name. According to this a different
                        model is loaded
  --onehot_flag         If true, it encodes data by using one-hot encodin,
                        otherwise embedding representation is used
  --early_stopping_on_loss
                        If true, it perform early stopping during train based
                        on train loss of holdout phase
  --early_stopping_epoch EARLY_STOPPING_EPOCH
                        Number of epochs after holdout train stops for early
                        stopping
  --pretrained_model PRETRAINED_MODEL
                        Path where to find the weights of a pre-trained model
```

Nota che è possibile inoltre variare i singoli **hyperparameter** caratteristici di ogni architettura dal file di configurazione JSON nella directory `/models`.
La configurazione sarà quindi caricata da file per mezzo dell'opzione `--network parameters`.

---

## Esempi di utilizzo

- *ModelUnidirect DNA*

**1.a Esegui holdout validation sul modello \#1:**

`python3 main.py  --validation --sequence_type dna  --path_source_data ./data/bins_translated  --load_network ModelUnidirect --network_parameters models/ModelUnidirect.json --num_epochs 100 --batch_size 16 --lr 1e-4 --onehot_flag`

**1.b Esegui training phase e test phase su modello \#1:**
`python3 main.py --train --test --load_network ModelUnidirect --sequence_type dna --onehot_flag --num_epochs 100 --batch_size 16 --lr 1e-4 --network_parameters models/ModelUnidirect.json --early_stopping_on_loss --pretrained_model <directory of previosly validated model>`


**1.c Esegui test phase su modello \#1**
`python3 main.py --test  --load_network ModelUnidirect --sequence_type dna --onehot_flag --network_parameters models/ModelUnidirect.json  --early_stopping_on_loss  --pretrained_model pretrained_models/ModelUnidirect/my_model_weights.h5`

---

- *ModelBidirectDNA*

**2.a Esegui holdout validation sul modello \#2:**
`python3 main.py  --validation  --path_source_data ./data/bins_translated --load_network ModelBidirectDNA  --sequence_type dna  --onehot_flag  --num_epochs 100  --batch_size 20  --lr 5e-4  --network_parameters models/ModelBidirectDNA.json`

**2.b Esegui training phase e test phase su modello \#2:**
`python3 main.py  --train  --test  --load_network ModelBidirectDNA  --sequence_type dna  --onehot_flag  --num_epochs 100  --batch_size 20  --lr 5e-4  --network_parameters models/ModelBidirectDNA.json  --early_stopping_on_loss --pretrained_model <directory of previosly validated model>`

**2.c Esegui test phase su modello \#3**
`python3 main.py  --test  --load_network ModelBidirectDNA  --sequence_type dna --onehot_flag  --network_parameters models/ModelBidirectDNA.json  --early_stopping_on_loss  --pretrained_model pretrained_models/ModelBidirectDNA/my_model_weights.h5`

---

- *ModelOneHotProtein*

**3.a Esegui holdout validation sul modello \#3:**
`python3 main.py  --validation  --path_source_data ./data/bins_translated --network_parameters models/ModelOneHotProtein.json  --batch_size 32  --num_epochs 100  --lr 5e-4  --load_network ModelOneHotProtein  --sequence_type protein  --onehot_flag`

**3.b Esegui training phase e test phase su modello \#3:**
`python3 main.py  --train  --test  --load_network ModelOneHotProtein  --batch_size 32  --num_epochs 100  --lr 5e-4  --network_parameters models/ModelOneHotProtein.json  --sequence_type protein  --onehot_flag  --early_stopping_on_loss  --num_epochs 100 --pretrained_model <directory of previosly validated model>`
 
**3.c Esegui test phase su modello \#3**
`python3 main.py --test  --load_network ModelOneHotProtein  --network_parameters models/ModelOneHotProtein.json  --sequence_type protein  --onehot_flag  --pretrained_model pretrained_models/ModelOneHotProtein/my_model_weights.h5`

___

**4.a Esegui holdout validation sul modello \#4 (A e B)**
- *modello A*
`python3 main.py  --validation  --path_source_data ./data/bins_translated --sequence_type protein  --batch_size 32  --num_epochs 100  --lr 5e-4  --load_network ModelEmbeddingBidirect --network_parameters models/ModelEmbeddingBidirect.json`

- *modello B*
`python3 main.py  --validation  --sequence_type protein  --batch_size 20  --num_epochs 100  --lr 5e-4  --onehot_flag  --network_parameters models/ModelConvBidirect.json  --load_network ModelConvBidirect`

**4.b Esegui training phase e test phase su modello \#4 (A e B)**:
- *modello A*
`python3 main.py  --train  --test  --path_source_data ./data/bins_translated --load_network ModelEmbeddingBidirect  --network_parameters models/ModelEmbeddingBidirect.json  --sequence_type protein  --early_stopping_on_loss  --num_epochs 100  --lr 5e-4 --pretrained_model <directory of previosly validated model>`

- *modello B*
`python3 main.py  --train  --test  --path_source_data ./data/bins_translated --load_network ModelConvBidirect  --network_parameters models/ModelConvBidirect.json  --sequence_type protein  --onehot_flag  --early_stopping_on_loss  --num_epochs 100  --lr 5e-4 --pretrained_model <directory of previosly validated model>`

**4.c Esegui test phase su modello \#4 (A e B)**
- *modello A*
`python3 main.py  --test  --path_source_data ./data/bins_translated --load_network ModelEmbeddingBidirect  --network_parameters models/ModelEmbeddingBidirect.json  --sequence_type protein  --pretrained_model pretrained_models/ModelEmbeddingBidirect/my_model_weights.h5` 

- *modello B*
`python3 main.py  --test  --path_source_data ./data/bins_translated --load_network ModelConvBidirect  --network_parameters models/ModelConvBidirect.json  --sequence_type protein  --onehot_flag  --pretrained_model pretrained_models/ModelConvBidirect/my_model_weights.h5`
