Added documentation

1 files changed, 64 insertions, 11 deletions

diff --git a/utils.py b/utils.py
index aeaf7ab..3709724 100644
--- a/utils.py
+++ b/utils.py
@@ -6,6 +6,16 @@ from sklearn.cluster import KMeans
 
 
 def cluster_and_optimize(df, centroids, end, time_diff=0.25, max_time=24, n=2):
+    """
+    Takes a dataframe of gps coordinates, a list of centroids, and an end point and returns a dataframe with a cluster
+    :param df: a dataframe of gps coordinates
+    :param centroids: a list of centroids
+    :param end: the end point of the trip
+    :param time_diff: the maximum time difference between the longest trip and the average trip
+    :param max_time: the maximum time of the trip
+    :param n: the number of routes to create
+    :return: a dataframe with a cluster column
+    """
     # Create a new column with normalized gps coordinates and centroids
     df['normalized_gps'], norm_centroids = __normalize_gps(df['gps'].values.tolist(), centroids)
 
@@ -33,7 +43,9 @@ def cluster_and_optimize(df, centroids, end, time_diff=0.25, max_time=24, n=2):
 
 def list_to_string(list_of_lists):
     """
-    Takes a list of lists of coordinates and returns a string of the coordinates
+    Takes a list of lists and returns a string of the list of lists
+    :param list_of_lists: a list of lists
+    :return: a string of the list of lists
     """
     string = ''
     for i in list_of_lists:
@@ -43,6 +55,13 @@ def list_to_string(list_of_lists):
 
 
 def create_json_df(coordinate_string, start, end):
+    """
+    Takes a string of coordinates and returns a dataframe of the coordinates in order of the waypoint index
+    :param coordinate_string: a string of coordinates
+    :param start: the start point of the trip
+    :param end: the end point of the trip
+    :return: a dataframe of the coordinates in order of the waypoint index
+    """
     coordinates = requests.get(
         'http://acetyl.net:5000/trip/v1/bike/' + start + coordinate_string + end + '?roundtrip=false&source=first&destination=last')
     coordinates = coordinates.json()
@@ -64,7 +83,13 @@ def create_json_df(coordinate_string, start, end):
 
 def get_trip_time(coordinate_string, num_waypoints, start, end, time_per_waypoint=90):
     """
-    Takes a list of lists of coordinates and returns the time of the trip in hours
+    Takes a string of coordinates and returns the trip time in hours
+    :param coordinate_string: a string of coordinates
+    :param num_waypoints: the number of waypoints
+    :param start: the start point of the trip
+    :param end: the end point of the trip
+    :param time_per_waypoint: the time per waypoint in seconds
+    :return: the trip time in hours
     """
     coordinates = requests.get(
         'http://acetyl.net:5000/trip/v1/bike/' + start + coordinate_string + end + '?roundtrip=false&source=first&destination=last')
@@ -78,10 +103,15 @@ def get_trip_time(coordinate_string, num_waypoints, start, end, time_per_waypoin
     return total_time_hours
 
 
-def __minimize_route_time_diff(routes, starts, end,
-                               time_diff, n):
+def __minimize_route_time_diff(routes, starts, end, time_diff, n):
     """
-    Takes two routes and a time difference and returns routes that have time differences less than the time difference
+    Takes a list of lists of coordinates, a list of start points, an end point, a time difference, and a number of routes
+    :param routes: the list of lists of coordinates
+    :param starts: the list of start points
+    :param end: the end point
+    :param time_diff: the time difference
+    :param n: the number of routes
+    :return: a list of lists of coordinates
     """
     times = []
 
@@ -114,8 +144,12 @@ def __minimize_route_time_diff(routes, starts, end,
 
 def __remove_longest_waypoints(route_coordinates, start, end, max_time):
     """
-    Takes a list of lists of coordinates and returns a list of lists of coordinates that is the same length as the
-    original list but has a trip time less than the max time
+    Takes a list of coordinates, a start point, an end point, and a maximum time and returns a list of coordinates
+    :param route_coordinates: the list of coordinates
+    :param start: the start point
+    :param end: the end point
+    :param max_time: the maximum time
+    :return: a list of coordinates
     """
     # Find the trip time for the route
     route_time = get_trip_time(list_to_string(route_coordinates), len(route_coordinates), start, end)
@@ -133,7 +167,11 @@ def __remove_longest_waypoints(route_coordinates, start, end, max_time):
 
 def __normalize_gps(coordinates, centroids):
     """
-    Takes a list of lists of coordinates and centroids and returns a list of lists of normalized coordinates and centroids
+    Takes a list of coordinates and a list of centroids and returns a list of normalized coordinates and a list of
+    normalized centroids
+    :param coordinates: the list of coordinates
+    :param centroids: the list of centroids
+    :return: the list of normalized coordinates and the list of normalized centroids
     """
 
     # Create a list of latitudes and longitudes
@@ -162,7 +200,11 @@ def __normalize_gps(coordinates, centroids):
 
 def __min_max_normalize(value, min_value, max_value):
     """
-    Takes a value, min value, and max value and returns the normalized value
+    Takes a value, a minimum value, and a maximum value and returns the normalized value
+    :param value: the value
+    :param min_value: the minimum value
+    :param max_value: the maximum value
+    :return: the normalized value
     """
     return (value - min_value) / (max_value - min_value)
 
@@ -170,6 +212,9 @@ def __min_max_normalize(value, min_value, max_value):
 def __find_closest_coordinate(coordinates, centroid):
     """
     Takes a list of coordinates and a centroid and returns the coordinate in the list that is closest to the centroid
+    :param coordinates: the list of coordinates
+    :param centroid: the centroid
+    :return: the coordinate in the list that is closest to the centroid
     """
     closest_coordinate = coordinates[0]
     closest_coordinate_distance = __distance(closest_coordinate, centroid)
@@ -184,7 +229,10 @@ def __find_closest_coordinate(coordinates, centroid):
 
 def __find_farthest_coordinate(coordinates, centroid):
     """
-    Takes a list of coordinates and a centroid and returns the coordinate in the list that is furthest from the centroid
+    Takes a list of coordinates and a centroid and returns the coordinate in the list that is farthest from the centroid
+    :param coordinates: the list of coordinates
+    :param centroid: the centroid
+    :return: the coordinate in the list that is farthest from the centroid
     """
     farthest_coordinate = coordinates[0]
     farthest_coordinate_distance = __distance(farthest_coordinate, centroid)
@@ -200,6 +248,8 @@ def __find_farthest_coordinate(coordinates, centroid):
 def __mean_center(coordinates):
     """
     Takes a list of coordinates and returns the mean center of the coordinates
+    :param coordinates: the list of coordinates
+    :return: the mean center of the coordinates
     """
     return [sum([i[0] for i in coordinates]) / len(coordinates), sum([i[1] for i in coordinates]) / len(coordinates)]
 
@@ -207,5 +257,8 @@ def __mean_center(coordinates):
 def __distance(coordinate1, coordinate2):
     """
     Takes two coordinates and returns the distance between them
+    :param coordinate1: the first coordinate
+    :param coordinate2: the second coordinate
+    :return: the distance between the two coordinates
     """
-    return ((coordinate1[0] - coordinate2[0]) ** 2 + (coordinate1[1] - coordinate2[1]) ** 2) ** 0.5
+    return ((coordinate1[0] - coordinate2[0]) ** 2 + (coordinate1[1] - coordinate2[1]) ** 2) ** 0.5
\ No newline at end of file