Refactoring and added new comments

Author: maggiofrancesco

.idea/workspace.xml

@@ -5,7 +5,7 @@
 
 
 def execute_sql(s):
-    con = psycopg2.connect('dbname=django_pugliaeventi user=postgres password=Frapama29')
+    con = psycopg2.connect('dbname=django_pugliaeventi user=postgres password=password')
     with con:
         cur = con.cursor()
         cur.execute(s)
@@ -58,6 +58,11 @@ def import_places():
 
 
 def import_sample_ratings():
+    """
+    Questo metodo effettua l'importazione nel db Django dei rating creati in maniera casuale preesistenti nel dataset
+    ratings_train.csv. Tuttavia, tali ratings non sono direttamente utilizzati in Django, per cui tale funzione al
+    momento risulta essere inutile.
+    """
     with open('data/ratings_train.csv') as f:
         i = 1
         for row in f.readlines():
@@ -187,7 +192,7 @@ def import_eventi():
 
 if __name__ == "__main__":
     import_places()
-    import_sample_ratings()
+    # import_sample_ratings() INUTILE
     import_comuni()
     import_distanze()
     import_eventi()

engine/export_data_to_django.py

@@ -215,18 +215,8 @@ def _parse_item_metadata(num_items, item_metadata_raw, item_tags_raw):
 
 def fetch_pugliaeventi(indicator_features=True, tag_features=False, min_rating=0.0):
     """
-    Fetch the `Movielens 100k dataset <http://grouplens.org/datasets/movielens/100k/>`_.
-
-    The dataset contains 100,000 interactions from 1000 users on 1700 movies,
-    and is exhaustively described in its
-    `README <http://files.grouplens.org/datasets/movielens/ml-100k-README.txt>`_.
-
     Parameters
     ----------
-
-    data_home: path, optional
-        Path to the directory in which the downloaded data should be placed.
-        Defaults to ``~/lightfm_data/``.
     indicator_features: bool, optional
         Use an [n_items, n_items] identity matrix for item features. When True with genre_features,
         indicator and genre features are concatenated into a single feature matrix of shape
@@ -237,8 +227,6 @@ def fetch_pugliaeventi(indicator_features=True, tag_features=False, min_rating=0
         [n_items, n_items + n_genres].
     min_rating: float, optional
         Minimum rating to include in the interaction matrix.
-    download_if_missing: bool, optional
-        Download the data if not present. Raises an IOError if False and data is missing.
 
     Notes
     -----
@@ -262,7 +250,7 @@ def fetch_pugliaeventi(indicator_features=True, tag_features=False, min_rating=0
 
     if not (indicator_features or tag_features):
         raise ValueError('At least one of item_indicator_features '
-                         'or genre_features must be True')
+                         'or tag_features must be True')
 
     # Load raw data
     (ratings_train, ratings_test, items, users, labels_item, labels_user) = _read_raw_data()

engine/lightfm_data_fetcher.py

@@ -1,5 +1,3 @@
-from lightfm.cross_validation import random_train_test_split
-
 from engine.lightfm_data_fetcher import fetch_pugliaeventi
 from engine.lightfm_data_fetcher import _build_interaction_matrix, _read_item_data, _parse_item_metadata
 from lightfm.evaluation import auc_score, precision_at_k, recall_at_k
@@ -9,10 +7,6 @@
 import pickle
 
 
-# Set the number of threads; you can increase this
-# if you have more physical cores available.
-
-
 NUM_THREADS = 2
 NUM_COMPONENTS = 30
 NUM_EPOCHS = 50
@@ -23,14 +17,19 @@
 
 
 def find_recommendations(user, model, data):
+    """
+    Ricerca di raccomandazioni utili per un utente specifico:
+    Il seguente metodo consente di ricercare raccomandazioni per un utente specifico. Il metodo predict del modello di
+    LightFM restituisce la lista degli ID dei luoghi, che successivamente viene ordinata in maniera decrescente (dal
+    luogo maggiormente raccomandato a quello meno raccomandato)
+    """
+
     # number of users and places in training data
     n_users, n_items = data['train'].shape
 
     # places the user already rated
     # known_positives = data['item_labels'][data['train'].tocsr()[user].indices]
 
-    # movies our model predicts they will like
-
     scores = model.predict(user,
                            np.arange(n_items),
                            item_features=data['item_features'])
@@ -57,6 +56,18 @@ def find_recommendations(user, model, data):
 
 
 def add_rating_to_model(max_user_id, max_item_id, user_id, item_id, rating):
+    """
+    Aggiunta di un nuovo rating al modello:
+    Il seguente metodo consente di aggiungere un nuovo rating al modello. In tal caso, considerato che l'utente esiste
+    già, non è necessario apprendere nuovamente il modello. Infatti, è sufficiente utilizzare il metodo fit_partial del
+    modello di LightFM per poter aggiungere il rating ad un utente esistente.
+    Il modello viene caricato in memoria utilizzando il checkpoint salvato in formato .pickle. Successivamente, viene
+    costruita una matrice delle interazioni il cui shape è pari a max_user_id x max_item_id e contiene la nuova
+    interazione che si vuole aggiungere al modello. Il metodo fit_partial viene chiamato passando la matrice delle
+    interazioni creata, le features degli item, il numero di epochs da applicare per l'apprendimento e il numero di
+    threads da impiegare.
+    """
+
     if os.path.isfile(os.path.join(script_dir, MODEL_CHECKPOINT_PATH)):
         with open(os.path.join(script_dir, MODEL_CHECKPOINT_PATH), 'rb') as fle:
             model = pickle.load(fle)
@@ -77,6 +88,17 @@ def add_rating_to_model(max_user_id, max_item_id, user_id, item_id, rating):
 
 
 def learn_model(force_model_creation=False):
+    """
+    Apprendimento del modello LightFM:
+    Il seguente metodo consente di caricare (se presente in formato .pickle) oppure apprendere il modello LightFM.
+    L'apprendimento del modello avviene con il metodo fit del modello di LightFM, passandogli il dataset contenente le
+    interazioni tra utenti e item (luoghi in questo caso), le features dei luoghi, il numero di epochs da applicare con
+    l'apprendimento e il numero di threads da impiegare.
+    In caso di apprendimento di un modello, i dati da impiegare vengono caricati utilizzando il metodo
+    fetch_pugliaeventi del modulo lightfm_data_featcher, in cui i dati vengono caricati dai file .csv presenti nel
+    folder engine/data e vengono strutturati in un formato utile per la creazione del modello in LightFM.
+    """
+
     data = fetch_pugliaeventi(min_rating=0.0, indicator_features=False, tag_features=True)
 
     if os.path.isfile(os.path.join(script_dir, MODEL_CHECKPOINT_PATH)) and not force_model_creation:

engine/lightfm_pugliaeventi.py

@@ -8,10 +8,6 @@
 import pickle
 
 
-# Set the number of threads; you can increase this
-# if you have more physical cores available.
-
-
 NUM_THREADS = 2
 NUM_COMPONENTS = 30
 NUM_EPOCHS = 50
@@ -31,7 +27,7 @@ def sample_recommendation(model, data, user_ids):
         # places they already rated
         known_positives = data['item_labels'][data['train'].tocsr()[user_id].indices]
 
-        # movies our model predicts they will like
+        # places our model predicts they will like
 
         scores = model.predict(user_id,
                                np.arange(n_items),

engine/lightfm_pugliaeventi_old.py

@@ -15,6 +15,7 @@
 """
 from django.conf.urls import url
 from django.contrib import admin
+from django.shortcuts import render
 from django.urls import include, path
 
 from recommender_webapp import views
@@ -36,7 +37,7 @@
     path('ratings/<int:place_id>/<int:mood>/<int:companionship>/', views.add_rating_config, name='add_rating_conf'),
 
     # place it at whatever base url you like
-    url(r'^ajax_select/', include(ajax_select_urls)),
-    #url(r'.*', lambda request: render(request, '404.html'), name='404')
+    url(r'^ajax_select/', include(ajax_select_urls))
+    # url(r'.*', lambda request: render(request, '404.html'), name='404')
 
 ]

pugliaeventi/urls.py

@@ -6,25 +6,26 @@
 from recommender_webapp.models import Mood, Rating
 
 
-"""
-Pagina principale:
-La view, prima di procedere con la visualizzazione della pagina principale, verifica il numero di rating effettuati
-dall'utente. In questa prima versione, il rating consiste nell'aggiunta di un luogo al proprio profilo, senza un rate
-numerico. Dato che LightFM implementa un modello implicito, non è necessario un rate numerico. Se il numero di rating
-è inferiore al numero di rating necessari per la configurazione del profilo, significa che l'utente non ha ancora
-concluso la procedura di configurazione. In tal caso, l'utente viene reindirizzato alla pagina della configurazione
-del profilo. In caso contrario, si procede con la visualizzazione della pagina principale.
-La pagina principale consente di visualizzare i posti raccomandati in base al mood (angry, joyful, sad), alla 
-companionship (withFriends oppure alone), alla distanza in KM e alla presenza di eventi. Questi sono i filtri presenti
-nel form. Per ricevere le raccomandazioni viene utilizzato il metodo find_recommendations del modulo lightfm_manager.
-L'ID utente utilizzato da LightFM, e quindi passato al metodo find_recommendations, è una stringa che si costituisce
-delle seguenti componenti: (ID utente in Django incrementato di 100) + ID mood + ID companionship. Ad esempio, se l'id
-utente in django è 4, l'ID mood è 2 e l'ID companionship è 1 allora la stringa rappresentante l'utente è: 10421. L'id
-utente di django viene sommato a 100 in quanto gli utenti da 1 a 100 sono già presenti nel dataset di LightFM (vedi
-data/users.csv e ratings_train.csv)
-"""
 @csrf_protect
 def index(request):
+    """
+    Pagina principale:
+    La view, prima di procedere con la visualizzazione della pagina principale, verifica il numero di rating effettuati
+    dall'utente. In questa prima versione, il rating consiste nell'aggiunta di un luogo al proprio profilo, senza un rate
+    numerico. Dato che LightFM implementa un modello implicito, non è necessario un rate numerico. Se il numero di rating
+    è inferiore al numero di rating necessari per la configurazione del profilo, significa che l'utente non ha ancora
+    concluso la procedura di configurazione. In tal caso, l'utente viene reindirizzato alla pagina della configurazione
+    del profilo. In caso contrario, si procede con la visualizzazione della pagina principale.
+    La pagina principale consente di visualizzare i posti raccomandati in base al mood (angry, joyful, sad), alla
+    companionship (withFriends oppure alone), alla distanza in KM e alla presenza di eventi. Questi sono i filtri presenti
+    nel form. Per ricevere le raccomandazioni viene utilizzato il metodo find_recommendations del modulo lightfm_manager.
+    L'ID utente utilizzato da LightFM, e quindi passato al metodo find_recommendations, è una stringa che si costituisce
+    delle seguenti componenti: (ID utente in Django incrementato di 100) + ID mood + ID companionship. Ad esempio, se l'id
+    utente in django è 4, l'ID mood è 2 e l'ID companionship è 1 allora la stringa rappresentante l'utente è: 10421. L'id
+    utente di django viene sommato a 100 in quanto gli utenti da 1 a 100 sono già presenti nel dataset di LightFM (vedi
+    data/users.csv e ratings_train.csv)
+    """
+
     context = {}
     recommended_places = []
     # places_dict = data_loader.data_in_memory['places_dict']

pugliaeventi/views.py

@@ -7,6 +7,14 @@
 
 
 def add_user(user_id, user_location,  user_contexts, data):
+    """
+    Aggiunta di un nuovo utente al sistema di raccomandazione:
+    Quando un nuovo utente si registra al sistema e completa la procedura di configurazione del profilo, oltre che
+    memorizzare l'utente e i rating nel database Django, è necessario  memorizzare le informazioni anche nel dataset di
+    LightFM (users.csv e ratings_train.csv). Successivamente è INDISPENSABILE apprendere nuovamente il modello. A tal
+    scopo viene utilizzato il metodo learn_model del modulo lightfm_pugliaeventi.
+    """
+
     lightfm_user_id = constant.DJANGO_USER_ID_BASE_START_LIGHTFM + user_id
     for user_context in user_contexts:
         contextual_lightfm_user_id = str(lightfm_user_id) + str(user_context.get('mood').value) + str(user_context.get('companionship').value)
@@ -29,6 +37,20 @@ def add_user(user_id, user_location,  user_contexts, data):
 
 
 def add_rating(contextual_lightfm_user_id, place_id, rating):
+    """
+    Aggiunta di un nuovo rating al sistema di raccomandazione:
+    Quando un utente aggiunge un nuovo luogo al suo profilo (lo seleziona come valido in un determinato contesto),
+    oltre che memorizzare il rating nel database Django, è necessario memorizzare le informazioni anche nel dataset di
+    LightFM (ratings_train.csv).
+    Diversamente dal caso precedente, in questo caso l'utente già esiste ed è presente nel modello LightFM. In tal caso,
+    per aggiungere un rating per un utente specifico non è necessario apprendere nuovamente il modello. La funzione
+    fit_partial del modello di LightFM consente di aggiungere al modello preesistente il rating per l'utente
+    specificato. Tutto questo processo viene implementato all'interno del metodo add_rating_to_model del modulo
+    lightfm_pugliaeventi. A tal metodo è necessario passare (oltre che ID utente, ID luogo e rating) l'attuale ID
+    massimo utente e l'attuale ID massimo item (sono necessari in quanto LightFM costruisce una matrice di shape
+    max_user_id x max_item_id).
+    """
+
     # Add rating to ratings.csv
     with open(r'engine/data/ratings_train.csv', 'a') as f:
         writer = csv.writer(f)
@@ -51,6 +73,18 @@ def add_rating(contextual_lightfm_user_id, place_id, rating):
 
 
 def find_recommendations(user, user_location, distance, any_events):
+    """
+    Ricerca di raccomandazioni utili per un utente specifico:
+    Il seguente metodo consente di ricercare raccomandazioni per un utente specifico ed implementa anche operazioni di
+    post-filtering sui risultati restituiti da LightFM. Mediante il metodo find_recommendations del modulo
+    lightfm_pugliaeventi vengono recuperati gli id dei luoghi raccomandati. LightFM restituisce un lista in cui gli ID
+    dei luoghi sono ordinati per rilevanza e di tale lista vengono prelevati solamente i primi 300 (costante
+    NUM_RECOMMENDATIONS_FROM_LIGHTFM). A partire da ciascun ID, vengono prelevati gli oggetti Place dal DB Django.
+    Successivamente, se l'utente ha selezionato la voce "any_events", significa che è interessato a luoghi in cui ci
+    sono degli eventi in programma. Inoltre, se l'utente ha specificato un range di KM, è necessario procedere ad un
+    ulteriore filtraggio dei luoghi in base alla distanza dalla location dell'utente.
+    """
+
     recommended_places = []
     user = int(user) - 1   # LightFM uses a zero-based indexing
     model, data = lightfm_pugliaeventi.learn_model()