Add Documentation

Anthex
1 parent 67724b67
Showing 2 changed files with 86 additions and 9 deletions Show diff stats
main.py
structure.py
@@ -32,6 +32,8 @@ def main(args):
         #### Distances ####
         print ("\ndistances : " + str(testSample.distances))
+        KNeighbors(dz,)
+
         #### Barycenter ####
         a = resolve_barycenter(neighborsCells, testSample.distances)
         print(a.toString())
@@ -40,6 +42,7 @@ def main(args):
         MM = MarkovModel(Tf)    
         MM.path([8,7,8,7,8,7,8,5,8,2,9,8,1,9,8,9,5,4,3,2,3,2,4,5,4,5,6,6,7,6,9,5,9,3,2,4,3,5,3,4,3,3,5,6,7,6,7,6,5,4,3,4,3,4])
+        print("\r\n")
         MM.printValues()
         print("\r\nPERCENTAGES : \r\n")
         MM.printPercentages()
@@ -4,6 +4,12 @@ from math import floor
 class RSSVector():
     distances = []
     def __init__(self, n1, n2, n3, n4):
+        '''
+        :param n1: AP1 RSSI
+        :param n2: AP2 RSSI
+        :param n3: AP3 RSSI
+        :param n4: AP4 RSSI
+        '''
         self.n1 = n1
         self.n2 = n2
         self.n3 = n3
@@ -46,6 +52,10 @@ class Location():
         return "(" + str(self.x) + " ; " + str(self.y) + " ; " + str(self.z) + ")"
     def getPositionInArray(self, arraySize=3):
+        '''
+        Returns the unique ID of a fingerprint given its location
+        :param arraySize: (Optional) dimension of the array
+        '''
         temp = Location(self.x, self.y)
         temp /= 2
         temp -= Location(1,1)
@@ -53,6 +63,11 @@ class Location():
     @staticmethod
     def fromID(id, arraySize=3):
+        '''
+        Returns the Location of a fingerprint of known ID
+        :param: ID to resolve
+        :param arraySize: (Optional) dimension of the array
+        '''
         id -= 1
         y=id % 3
         x=floor((id - y) / 3)
@@ -64,16 +79,27 @@ class Location():
 class Cell():
     def __init__(self, v_, loc):
+        '''
+        :param v_: RSSI vector of the fingerprint
+        :param loc: Location of the fingerprint
+        '''
         self.v = v_
         self.location = loc
 class MarkovValue():
     def __init__(self, nb=0, percentage=0.0):
+        '''
+        :param nb: Counter of incoming/outgoing movements
+        :param percentage: probability of being the next movement [0.0 , 1.0]
+        '''
         self.nb = nb
         self.percentage = percentage # Probability of Markov model (100% <=> 1.0)
 class MarkovModel():
     def __init__(self,cells):
+        '''
+        :param cells: an array containing all the cells of the model
+        '''
         self.MarkovValues = [] #table of the coefficients of the Markov Model
         self.cells = cells
         self.previousCell = 0
@@ -84,20 +110,36 @@ class MarkovModel():
         self.MarkovValues[10][0].nb = 1 #initial position sigma increment  
     def moveToCellID(self, nextCell):
+        '''
+        Registers a movement from the current cell to a specified location by its ID
+        :param nextCell: The ID of the new location
+        '''
         self.MarkovValues[nextCell][self.previousCell].nb += 1     
         self.MarkovValues[10][nextCell].nb += 1
         self.refreshPercentage(self.previousCell)
         self.previousCell = nextCell
     def moveToCell(self, nextCell):
+        '''
+        Registers a movement from the current cell to another based on the Location of its fingerprint
+        :param nextCell: The location of the new cell
+        '''
         self.moveToCellID(nextCell.location.getPositionInArray()+1)
     def refreshPercentage(self, col):
+        '''
+        Refreshes the probabilities of a column after a counter is changed
+        Needed after every change to the nb field
+        :param col: the # of the column to refresh
+        '''
         if  self.MarkovValues[10][col].nb:
             for k in range(0,10):
                     self.MarkovValues[k][col].percentage = self.MarkovValues[k][col].nb / self.MarkovValues[10][col].nb
     def printValues(self):
+        '''
+        Prints the counters of the Markov Model in a human-readable table form
+        '''
         print("\t? \t1 \t2 \t3\t4 \t5 \t6 \t7 \t8 \t9")
         print("---------------------------------------------------------------------------------", end='')
@@ -108,17 +150,23 @@ class MarkovModel():
             print(i, end='\t')
             for k in range (0,10):
+                if not self.MarkovValues[i][k].nb:
+                    print("\033[0;31;40m", end='')
+                else:
+                    print("\033[1;36;40m", end='')
                 print(self.MarkovValues[i][k].nb, end='\t')
+                print("\033[1;37;40m", end='')
         print("")
     def printPercentages(self):
+        '''
+        Prints the percentages of the Markov Model in a human-readable table form
+        '''
         print("\t? \t1 \t2 \t3\t4 \t5 \t6 \t7 \t8 \t9")
         print("---------------------------------------------------------------------------------", end='')
         for i in range (1, 10):
-            print("\r\n", end='')
-            
-            print(i, end='\t')
+            print("\r\n", i, end='\t')
             for k in range (0,10):
                 if not self.MarkovValues[i][k].percentage:
                     print("\033[0;31;40m", end='')
@@ -129,9 +177,21 @@ class MarkovModel():
         print("")
     def getMostLikely(self):
+        '''
+        Returns the ID of the most likely next location
+        Convert to coordinates using the Location.fromID() function
+        :return: ID of the most likely next location
+        '''
         return self.getMostLikelyFromCell(self.previousCell)
     def getMostLikelyFromCell(self, currentCell):
+        '''
+        Returns the ID of the most likely next location with a given previous cell ID
+        Typically called by getMostLikely() function
+        Convert to coordinates using the Location.fromID() function
+        :param currentCell: ID of the last cell 
+        :return: ID of the most likely next location
+        '''
         max=0
         max_id=0
         for k in range(1,10):
@@ -141,19 +201,33 @@ class MarkovModel():
         return max_id 
     def path(self, locationIDs):
+        '''
+        shorthand for defining multiple movements betweens cells
+        :param LocationIDs: Array containing the different cell IDs in order of movement
+        '''
         for loc in locationIDs:
             self.moveToCellID(loc)
 def newCell(n1, n2, n3, n4, l1, l2):
+    '''
+    Shorthand for Cell creation
+    :param n1: AP1 RSSI
+    :param n2: AP2 RSSI
+    :param n3: AP3 RSSI
+    :param n4: AP4 RSSI
+    :param L1: x coordinate of the fingerprinting location
+    :param L2: y coordinate of the fingerprinting location
+    :return: Cell with given characteristics
+    '''
     return Cell(RSSVector(n1,n2,n3,n4), Location(l1,l2))
 def KNeighbors(fingerprints, sample):  
     '''
     Returns the 4 closest cells to the given sample and fills sample distance data
-    :param Cell[3][3] fingerprints: 2D array of all the cells
-    :param RSSVector sample: Mobile terminal sample
-    :return Cell[4]: the 4 nearest cells
+    :param fingerprints: 2D array of all the cells
+    :param sample: Mobile terminal sample
+    :return: the 4 nearest cells
     '''
     distances, neighbours = [], []
     for row in fingerprints:
@@ -174,9 +248,9 @@ def KNeighbors(fingerprints, sample):
 def resolve_barycenter(nC, d):
     '''
     Returns the weighted barycenter of the 4 neighbouring cells
-    :param Cell[4] nC: (neighborCells) Array containing the 4 closest cells
-    :param distance[4] d: distances of the sample of the mobile terminal
-    :return Location: Estimated location of the mobile terminal (return None if error)
+    :param nC: (neighborCells) Array containing the 4 closest cells
+    :param d: distances of the sample of the mobile terminal
+    :return: Estimated location of the mobile terminal (return None if error)
     '''
     return None if len(nC) != 4 or len(d) != 4 else  \
           1 / (1+d[0]/d[1]+d[0]/d[2]+d[0]/d[3])*nC[0].location \