Add DOCSTRING to some classes

main_package/classes/abstract_importer.py

@@ -2,6 +2,12 @@ from abc import ABC, abstractmethod
 
 
 class AbstractImporter(ABC):
+    """
+    Interfaccia che espone i metodi necessari all'importing delle trajectories e della struttura della CTBN
+
+    :files_path: il path in cui sono presenti i/il file da importare
+
+    """
 
     def __init__(self, files_path):
         self.files_path = files_path
@@ -9,8 +15,22 @@ class AbstractImporter(ABC):
 
     @abstractmethod
     def import_trajectories(self, raw_data):
+        """
+        Costruisce le traj partendo dal dataset raw_data
+        Parameters:
+            raw_data: il dataset da cui estrarre le traj
+        Returns:
+            void
+        """
         pass
 
     @abstractmethod
     def import_structure(self, raw_data):
+        """
+        Costruisce la struttura della rete partendo dal dataset raw_data
+        Parameters:
+            raw_data: il dataset da cui estrarre la struttura
+        Returns:
+            void
+        """
         pass

main_package/classes/amalgamated_cims.py

@@ -3,8 +3,12 @@ import numpy as np
 
 
 class AmalgamatedCims:
-
-    def __init__(self, states_number,list_of_keys, list_of_vars_order):
+    """
+    Aggrega un insieme di oggetti SetOfCims indicizzandoli a partire dal node_id della variabile:
+    {X:SetofCimsX, Y:SetOfCimsY.......}
+    """
+    # list_of_vars_orders contiene tutte le liste con i parent ordinati secondo il valore indx
+    def __init__(self, states_number, list_of_keys, list_of_vars_order):
         self.sets_of_cims = {}
         self.init_cims_structure(list_of_keys, states_number, list_of_vars_order)
         self.states_per_variable = states_number
@@ -15,8 +19,6 @@ class AmalgamatedCims:
         for indx, key in enumerate(keys):
             self.sets_of_cims[key] = socim.SetOfCims(key, list_of_vars_order[indx], nodes_val)
 
-
-
     def get_set_of_cims(self, node_id):
         return self.sets_of_cims[node_id]
 

main_package/classes/json_importer.py

@@ -2,11 +2,24 @@ import os
 import glob
 import pandas as pd
 import json
-import numpy as np
 from abstract_importer import AbstractImporter
 
 
 class JsonImporter(AbstractImporter):
+    """
+    Implementa l'interfaccia AbstractImporter e aggiunge i metodi necessari a costruire le trajectories e la struttura della rete
+    del dataset in formato json con la seguente struttura:
+    [] 0
+        |_ dyn.cims
+        |_ dyn.str
+        |_ samples
+        |_ variabels
+
+    :df_samples_list: lista di dataframe, ogni dataframe contiene una traj
+    :df_structure: dataframe contenente la struttura della rete
+    :df_variables: dataframe contenente le infromazioni sulle variabili della rete
+
+    """
 
     def __init__(self, files_path):
         self.df_samples_list = []
@@ -30,6 +43,15 @@ class JsonImporter(AbstractImporter):
         self.df_variables = self.one_level_normalizing(raw_data, 0, 'variables')
 
     def read_json_file(self):
+        """
+        Legge 'tutti' i file .json presenti nel path self.filepath
+
+        Parameters:
+              void
+        Returns:
+              :data: il contenuto del file json
+
+        """
         try:
             read_files = glob.glob(os.path.join(self.files_path, "*.json"))
             for file_name in read_files:
@@ -39,14 +61,43 @@ class JsonImporter(AbstractImporter):
         except ValueError as err:
             print(err.args)
 
-    def one_level_normalizing(self, raw_data, indx, variables_key):
-        return pd.json_normalize(raw_data[indx][variables_key])
+    def one_level_normalizing(self, raw_data, indx, key):
+        """
+        Estrae i dati innestati di un livello, presenti nel dataset raw_data,
+        presenti nel json array all'indice indx nel json object key
+
+        Parameters:
+            :raw_data: il dataset json completo
+            :indx: l'indice del json array da cui estrarre i dati
+            :key: il json object da cui estrarre i dati
+        Returns:
+            Il dataframe contenente i dati normalizzati
+
+        """
+        return pd.json_normalize(raw_data[indx][key])
 
     def normalize_trajectories(self, raw_data, indx, trajectories_key):
+        """
+        Estrae le traiettorie presenti in rawdata nel json array all'indice indx, nel json object trajectories_key.
+        Aggiunge le traj estratte nella lista di dataframe self.df_samples_list
+
+        Parameters:
+            void
+        Returns:
+            void
+        """
         for sample_indx, sample in enumerate(raw_data[indx][trajectories_key]):
             self.df_samples_list.append(pd.json_normalize(raw_data[indx][trajectories_key][sample_indx]))
 
     def build_list_of_samples_array(self, data_frame):
+        """
+        Costruisce una lista contenente le colonne presenti nel dataframe data_frame convertendole in numpy_array
+        Parameters:
+            :data_frame: il dataframe da cui estrarre e convertire le colonne
+        Returns:
+            :columns_list: la lista contenente le colonne convertite in numpyarray
+
+        """
         columns_list = []
         for column in data_frame:
             columns_list.append(data_frame[column].to_numpy())
@@ -54,7 +105,7 @@ class JsonImporter(AbstractImporter):
 
     def clear_data_frames(self):
         """
-        Rimuove tutti i valori contenuti nei data_frames presenti in df_list
+        Rimuove tutti i valori contenuti nei data_frames presenti in df_samples_list
         Parameters:
             void
         Returns:

main_package/classes/network_graph.py

@@ -1,15 +1,16 @@
 
-import sample_path as sp
 import networkx as nx
-import os
+
 
 
 class NetworkGraph():
     """
-    Rappresenta un grafo dinamico con la seguente struttura:
+    Rappresenta il grafo che contiene i nodi e gli archi presenti nell'oggetto Structure graph_struct.
+    Ogni nodo contine la label node_id, al nodo è anche associato un id numerico progressivo indx che rappresenta la posizione
+    dei sui valori nella colonna indx della traj
 
-        :sample_path: le traiettorie/a da cui costruire il grafo
-        :graph: la struttura dinamica che definisce il grafo
+    :graph_struct: l'oggetto Structure da cui estrarre i dati per costruire il grafo graph
+    :graph: il grafo
 
     """
 
@@ -17,7 +18,6 @@ class NetworkGraph():
         self.graph_struct = graph_struct
         self.graph = nx.DiGraph()
 
-
     def init_graph(self):
         self.add_nodes(self.graph_struct.list_of_nodes())
         self.add_edges(self.graph_struct.list_of_edges())

main_package/classes/sample_path.py

@@ -8,12 +8,14 @@ import structure as st
 
 class SamplePath:
     """
-    Rappresenta l'aggregazione di una o più traiettorie.
-    Ha il compito dato di costruire tutte gli oggetti Trajectory a partire
-    dai dataset contenuti nella directory files_path.
+    Contiene l'aggregazione di una o più traiettorie e la struttura della rete.
+    Ha il compito dato di costruire tutte gli oggetti Trajectory e l'oggetto Structure
+    a partire dai dataframe contenuti in self.importer
+
 
     :importer: l'oggetto Importer che ha il compito di caricare i dataset
-    :trajectories: lista contenente le traiettorie create
+    :trajectories: lista di oggetti Trajectories
+    :structure: oggetto Structure
     """
 
     def __init__(self, files_path):

main_package/classes/set_of_cims.py

@@ -3,6 +3,14 @@ import conditional_intensity_matrix as cim
 
 
 class SetOfCims:
+    """
+    Rappresenta la struttura che aggrega tutte le CIM per la variabile di label node_id
+
+    :node_id: la label della varibile a cui fanno riferimento le CIM
+    :ordered_parent_set: il set dei parent della variabile node_id ordinata secondo la property indx
+    :value: il numero massimo di stati assumibili dalla variabile
+    :actual_cims: le CIM della varibile
+    """
 
     def __init__(self, node_id, ordered_parent_set, value_type):
         self.node_id = node_id
@@ -19,23 +27,18 @@ class SetOfCims:
 
     def update_state_transition(self, dict_of_indexes, element_indx_tuple):
         matrix_indx = self.indexes_converter(dict_of_indexes)
-        #print("Converted Indx SRT")
-        #print(matrix_indx)
         self.actual_cims[matrix_indx].update_state_transition_count(element_indx_tuple)
 
     def update_state_residence_time(self, which_matrix, which_element, time):
         matrix_indx = self.indexes_converter(which_matrix)
-        #print("Converted Indx")
-        #print(matrix_indx)
-        #print("Updating Time for variable ",self.node_id)
         self.actual_cims[matrix_indx].update_state_residence_time_for_state(which_element, time)
 
 
     def get_cims_number(self):
         return len(self.actual_cims)
 
-    def indexes_converter(self, dict_of_indexes): # Si aspetta oggetti del tipo {X:1, Y:1, Z:0}
-        #print(dict_of_indexes)
+    def indexes_converter(self, dict_of_indexes): # Si aspetta oggetti del tipo {X:1, Y:1, Z:0} dove
+                                                    # le keys sono i parent del nodo e i values sono i valori che assumono
         if not dict_of_indexes:
             return 0
         else:

main_package/classes/structure.py

@@ -1,6 +1,13 @@
 
 
 class Structure:
+    """
+    Contiene tutte il informazioni sulla struttura della rete (connessione dei nodi, valori assumibili dalle variabili)
+
+    :structure_frame: il dataframe contenente le connessioni dei nodi della rete
+    :variables_frame: il data_frame contenente i valori assumibili dalle variabili e si suppone il corretto ordinamento
+    rispetto alle colonne del dataset
+    """
 
     def __init__(self, structure, variables):
         self.structure_frame = structure
@@ -14,7 +21,7 @@ class Structure:
         return edges_list
 
     def list_of_nodes(self):
-        return self.variables_frame['Name']
+        return self.variables_frame['Name'] #TODO rimuovere dipendenza diretta dalla key 'Name'
 
     def get_node_id(self, node_indx):
         return self.variables_frame['Name'][node_indx]

main_package/classes/trajectory.py

@@ -6,6 +6,10 @@ class Trajectory():
     """ 
     Rappresenta una traiettoria come un numpy_array contenente n-ple (indx, T_k,S_i,.....,Sj)
     Offre i metodi utili alla computazione sulla struttura stessa.
+
+    Una Trajectory viene costruita a partire da una lista di numpyarray dove ogni elemento rappresenta una colonna
+    della traj
+
     :actual_trajectory: il numpy_array contenente la successione di n-ple (indx, T_k,S_i,.....,Sj)
 
     """
@@ -19,12 +23,3 @@ class Trajectory():
     def merge_columns(self, list_of_cols):
         return np.vstack(list_of_cols).T
 
-    """def get_states(self):
-        
-        Identifica gli stati visitati nella traiettoria.
-        Parameters:
-            void
-        Returns:
-            una lista contenente gli stati visitati nella traiettoria
-        
-        return self.actual_trajectory['State'].unique()"""