scgraph 2.1.2__tar.gz → 2.3.0__tar.gz

{scgraph-2.1.2/scgraph.egg-info → scgraph-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: scgraph
-Version: 2.1.2
+Version: 2.3.0
 Summary: Determine an approximate route between two points on earth.
 Author-email: Connor Makowski <conmak@mit.edu>
 Project-URL: Homepage, https://github.com/connor-makowski/scgraph
@@ -9,7 +9,7 @@ Project-URL: Documentation, https://connor-makowski.github.io/scgraph/core.html
 Classifier: Programming Language :: Python :: 3
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
-Requires-Python: >=3.6
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 
@@ -57,7 +57,9 @@ Low Level: https://connor-makowski.github.io/scgraph/scgraph/core.html
 
 ## Setup
 
-Make sure you have Python 3.6.x (or higher) installed on your system. You can download it [here](https://www.python.org/downloads/).
+Make sure you have Python 3.10.x (or higher) installed on your system. You can download it [here](https://www.python.org/downloads/).
+
+Support for python3.6-3.9 is available up to version 2.2.0
 
 ## Installation
 
@@ -67,7 +69,10 @@ pip install scgraph
 
 ## Use with Google Colab
 
-See the example [here](https://colab.research.google.com/github/connor-makowski/scgraph/blob/main/example.ipynb) 
+- [Getting Started](https://colab.research.google.com/github/connor-makowski/scgraph/blob/main/examples/getting_started.ipynb) 
+- [Creating A Multi Path Geojson](https://colab.research.google.com/github/connor-makowski/scgraph/blob/main/examples/multi_path_geojson.ipynb)
+- [Modifying A Geograph](https://colab.research.google.com/github/connor-makowski/scgraph/blob/main/examples/geograph_modifications.ipynb)
+
 
 # Getting Started
 
@@ -101,7 +106,7 @@ In the above example, the `output` variable is a dictionary with three keys: `le
             - `ft` (feet)
 - `coordinate_path`: A list of lists [`latitude`,`longitude`] that make up the shortest path
 
-For more examples including viewing the output on a map, see the [example notebook](https://colab.research.google.com/github/connor-makowski/scgraph/blob/main/example.ipynb).
+For more examples including viewing the output on a map, see the [example notebook](https://colab.research.google.com/github/connor-makowski/scgraph/blob/main/examples/getting_started.ipynb).
 
 ## Included GeoGraphs
 
@@ -165,15 +170,17 @@ output = marnet_geograph.get_shortest_path(
 get_line_path(output, filename='output.geojson')
 ```
 
+Modify an existing geograph: See the notebook [here](https://colab.research.google.com/github/connor-makowski/scgraph/blob/main/examples/geograph_modifications.ipynb)
+
 
 You can specify your own custom graphs for direct access to the solving algorithms. This requires the use of the low level `Graph` class
 
 ```py
 from scgraph import Graph
 
-# Define a graph
+# Define an arbitrary graph
 # See the graph definitions here: 
-# https://connor-makowski.github.io/scgraph/scgraph/core.html
+# https://connor-makowski.github.io/scgraph/scgraph/core.html#GeoGraph
 graph = [
     {1: 5, 2: 1},
     {0: 5, 2: 2, 3: 1},
@@ -198,25 +205,67 @@ from scgraph import GeoGraph
 
 # Define nodes
 # See the nodes definitions here: 
-# https://connor-makowski.github.io/scgraph/scgraph/core.html
+# https://connor-makowski.github.io/scgraph/scgraph/core.html#GeoGraph
 nodes = [
-    [0,0],
-    [0,1],
-    [1,0],
-    [1,1],
-    [1,2],
-    [2,1]
+    # London
+    [51.5074, -0.1278],
+    # Paris
+    [48.8566, 2.3522],
+    # Berlin
+    [52.5200, 13.4050],
+    # Rome
+    [41.9028, 12.4964],
+    # Madrid
+    [40.4168, -3.7038],
+    # Lisbon
+    [38.7223, -9.1393]
 ]
 # Define a graph
 # See the graph definitions here: 
-# https://connor-makowski.github.io/scgraph/scgraph/core.html
+# https://connor-makowski.github.io/scgraph/scgraph/core.html#GeoGraph
 graph = [
-    {1: 5, 2: 1},
-    {0: 5, 2: 2, 3: 1},
-    {0: 1, 1: 2, 3: 4, 4: 8},
-    {1: 1, 2: 4, 4: 3, 5: 6},
-    {2: 8, 3: 3},
-    {3: 6}
+    # From London
+    {
+        # To Paris
+        1: 311,
+    },
+    # From Paris
+    {
+        # To London
+        0: 311, 
+        # To Berlin
+        2: 878, 
+        # To Rome
+        3: 1439,
+        # To Madrid
+        4: 1053
+    },
+    # From Berlin
+    {
+        # To Paris 
+        1: 878,
+        # To Rome
+        3: 1181,
+    },
+    # From Rome
+    {
+        # To Paris
+        1: 1439,
+        # To Berlin
+        2: 1181,
+    },
+    # From Madrid
+    {
+        # To Paris
+        1: 1053,
+        # To Lisbon
+        5: 623
+    },
+    # From Lisbon
+    {
+        # To Madrid
+        4: 623
+    }
 ]
 
 # Create a GeoGraph object
@@ -229,23 +278,31 @@ my_geograph.validate_graph()
 my_geograph.validate_nodes()
 
 # Get the shortest path between two points
+# In this case, Birmingham England and Zaragoza Spain
+# Since Birmingham and Zaragoza are not in the graph,
+# the algorithm will add them into the graph.
+# See: https://connor-makowski.github.io/scgraph/scgraph/core.html#GeoGraph.get_shortest_path
+# Expected output would be to go from
+# Birmingham -> London -> Paris -> Madrid -> Zaragoza
+
 output = my_geograph.get_shortest_path(
-    origin_node = {'latitude': 0, 'longitude': 0},
-    destination_node = {'latitude': 2, 'longitude': 1}
+    # Birmingham England
+    origin_node = {'latitude': 52.4862, 'longitude': -1.8904},
+    # Zaragoza Spain
+    destination_node = {'latitude': 41.6488, 'longitude': -0.8891}
 )
-#=>
+print(output)
 # {
-#     "coordinate_path": [
-#         [0,0],
-#         [0,0],
-#         [1,0],
-#         [0,1],
-#         [1,1],
-#         [2,1],
-#         [2,1]
-#     ],
-#     "length": 10
+#     'length': 1799.4323, 
+#     'coordinate_path': [
+#         [52.4862, -1.8904], 
+#         [51.5074, -0.1278], 
+#         [48.8566, 2.3522], 
+#         [40.4168, -3.7038], 
+#         [41.6488, -0.8891]
+#     ]
 # }
+
 ```
 
 ## Attributions and Thanks

{scgraph-2.1.2 → scgraph-2.3.0}/README.md

@@ -42,7 +42,9 @@ Low Level: https://connor-makowski.github.io/scgraph/scgraph/core.html
 
 ## Setup
 
-Make sure you have Python 3.6.x (or higher) installed on your system. You can download it [here](https://www.python.org/downloads/).
+Make sure you have Python 3.10.x (or higher) installed on your system. You can download it [here](https://www.python.org/downloads/).
+
+Support for python3.6-3.9 is available up to version 2.2.0
 
 ## Installation
 
@@ -52,7 +54,10 @@ pip install scgraph
 
 ## Use with Google Colab
 
-See the example [here](https://colab.research.google.com/github/connor-makowski/scgraph/blob/main/example.ipynb) 
+- [Getting Started](https://colab.research.google.com/github/connor-makowski/scgraph/blob/main/examples/getting_started.ipynb) 
+- [Creating A Multi Path Geojson](https://colab.research.google.com/github/connor-makowski/scgraph/blob/main/examples/multi_path_geojson.ipynb)
+- [Modifying A Geograph](https://colab.research.google.com/github/connor-makowski/scgraph/blob/main/examples/geograph_modifications.ipynb)
+
 
 # Getting Started
 
@@ -86,7 +91,7 @@ In the above example, the `output` variable is a dictionary with three keys: `le
             - `ft` (feet)
 - `coordinate_path`: A list of lists [`latitude`,`longitude`] that make up the shortest path
 
-For more examples including viewing the output on a map, see the [example notebook](https://colab.research.google.com/github/connor-makowski/scgraph/blob/main/example.ipynb).
+For more examples including viewing the output on a map, see the [example notebook](https://colab.research.google.com/github/connor-makowski/scgraph/blob/main/examples/getting_started.ipynb).
 
 ## Included GeoGraphs
 
@@ -150,15 +155,17 @@ output = marnet_geograph.get_shortest_path(
 get_line_path(output, filename='output.geojson')
 ```
 
+Modify an existing geograph: See the notebook [here](https://colab.research.google.com/github/connor-makowski/scgraph/blob/main/examples/geograph_modifications.ipynb)
+
 
 You can specify your own custom graphs for direct access to the solving algorithms. This requires the use of the low level `Graph` class
 
 ```py
 from scgraph import Graph
 
-# Define a graph
+# Define an arbitrary graph
 # See the graph definitions here: 
-# https://connor-makowski.github.io/scgraph/scgraph/core.html
+# https://connor-makowski.github.io/scgraph/scgraph/core.html#GeoGraph
 graph = [
     {1: 5, 2: 1},
     {0: 5, 2: 2, 3: 1},
@@ -183,25 +190,67 @@ from scgraph import GeoGraph
 
 # Define nodes
 # See the nodes definitions here: 
-# https://connor-makowski.github.io/scgraph/scgraph/core.html
+# https://connor-makowski.github.io/scgraph/scgraph/core.html#GeoGraph
 nodes = [
-    [0,0],
-    [0,1],
-    [1,0],
-    [1,1],
-    [1,2],
-    [2,1]
+    # London
+    [51.5074, -0.1278],
+    # Paris
+    [48.8566, 2.3522],
+    # Berlin
+    [52.5200, 13.4050],
+    # Rome
+    [41.9028, 12.4964],
+    # Madrid
+    [40.4168, -3.7038],
+    # Lisbon
+    [38.7223, -9.1393]
 ]
 # Define a graph
 # See the graph definitions here: 
-# https://connor-makowski.github.io/scgraph/scgraph/core.html
+# https://connor-makowski.github.io/scgraph/scgraph/core.html#GeoGraph
 graph = [
-    {1: 5, 2: 1},
-    {0: 5, 2: 2, 3: 1},
-    {0: 1, 1: 2, 3: 4, 4: 8},
-    {1: 1, 2: 4, 4: 3, 5: 6},
-    {2: 8, 3: 3},
-    {3: 6}
+    # From London
+    {
+        # To Paris
+        1: 311,
+    },
+    # From Paris
+    {
+        # To London
+        0: 311, 
+        # To Berlin
+        2: 878, 
+        # To Rome
+        3: 1439,
+        # To Madrid
+        4: 1053
+    },
+    # From Berlin
+    {
+        # To Paris 
+        1: 878,
+        # To Rome
+        3: 1181,
+    },
+    # From Rome
+    {
+        # To Paris
+        1: 1439,
+        # To Berlin
+        2: 1181,
+    },
+    # From Madrid
+    {
+        # To Paris
+        1: 1053,
+        # To Lisbon
+        5: 623
+    },
+    # From Lisbon
+    {
+        # To Madrid
+        4: 623
+    }
 ]
 
 # Create a GeoGraph object
@@ -214,23 +263,31 @@ my_geograph.validate_graph()
 my_geograph.validate_nodes()
 
 # Get the shortest path between two points
+# In this case, Birmingham England and Zaragoza Spain
+# Since Birmingham and Zaragoza are not in the graph,
+# the algorithm will add them into the graph.
+# See: https://connor-makowski.github.io/scgraph/scgraph/core.html#GeoGraph.get_shortest_path
+# Expected output would be to go from
+# Birmingham -> London -> Paris -> Madrid -> Zaragoza
+
 output = my_geograph.get_shortest_path(
-    origin_node = {'latitude': 0, 'longitude': 0},
-    destination_node = {'latitude': 2, 'longitude': 1}
+    # Birmingham England
+    origin_node = {'latitude': 52.4862, 'longitude': -1.8904},
+    # Zaragoza Spain
+    destination_node = {'latitude': 41.6488, 'longitude': -0.8891}
 )
-#=>
+print(output)
 # {
-#     "coordinate_path": [
-#         [0,0],
-#         [0,0],
-#         [1,0],
-#         [0,1],
-#         [1,1],
-#         [2,1],
-#         [2,1]
-#     ],
-#     "length": 10
+#     'length': 1799.4323, 
+#     'coordinate_path': [
+#         [52.4862, -1.8904], 
+#         [51.5074, -0.1278], 
+#         [48.8566, 2.3522], 
+#         [40.4168, -3.7038], 
+#         [41.6488, -0.8891]
+#     ]
 # }
+
 ```
 
 ## Attributions and Thanks

{scgraph-2.1.2 → scgraph-2.3.0}/pyproject.toml

@@ -12,13 +12,13 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "scgraph"
-version = "2.1.2"
+version = "2.3.0"
 description = "Determine an approximate route between two points on earth."
 authors = [
     {name="Connor Makowski", email="conmak@mit.edu"}
 ]
 readme = "README.md"
-requires-python = ">=3.6"
+requires-python = ">=3.10"
 classifiers = [
     "Programming Language :: Python :: 3",
     'License :: OSI Approved :: MIT License',

{scgraph-2.1.2 → scgraph-2.3.0}/scgraph/core.py

@@ -1,4 +1,4 @@
-from .utils import haversine, hard_round, distance_converter
+from .utils import haversine, hard_round, distance_converter, get_line_path
 import json
 
 
@@ -16,11 +16,10 @@ class Graph:
 
         Required Arguments:
 
-        - `graph`
+        - `graph`:
             - Type: list of dictionaries
-            - What: A list of dictionaries where the indicies are origin node ids and the values are dictionaries of destination node indices and distances
-            - Note: All nodes must be included as origins in the graph regardless of if they have any connected destinations
-
+            - See: https://connor-makowski.github.io/scgraph/scgraph/core.html#GeoGraph
+        
         Optional Arguments:
 
         - `check_symmetry`
@@ -75,10 +74,9 @@ class Graph:
 
         Required Arguments:
 
-        - `graph`
+        - `graph`:
             - Type: list of dictionaries
-            - What: A list of dictionaries where the indicies are origin node ids and the values are dictionaries of destination node ids and distances
-            - Note: All nodes must be included as origins in the graph regardless of if they have any connected destinations
+            - See: https://connor-makowski.github.io/scgraph/scgraph/core.html#GeoGraph
 
         Optional Arguments:
 
@@ -121,9 +119,9 @@ class Graph:
 
         Required Arguments:
 
-        - `graph`
-            - Type: list[dict]
-            - What: A list of dictionaries where the indicies are origin node ids and the values are dictionaries of destination node ids and distances
+        - `graph`:
+            - Type: list of dictionaries
+            - See: https://connor-makowski.github.io/scgraph/scgraph/core.html#GeoGraph
         - `origin_id`
             - Type: int
             - What: The id of the origin node from the graph dictionary to start the shortest path from
@@ -167,9 +165,9 @@ class Graph:
 
         Required Arguments:
 
-        - `graph`
-            - Type: list[dict]
-            - What: A list of dictionaries where the indicies are origin node ids and the values are dictionaries of destination node ids and distances
+        - `graph`:
+            - Type: list of dictionaries
+            - See: https://connor-makowski.github.io/scgraph/scgraph/core.html#GeoGraph
         - `origin_id`
             - Type: int
             - What: The id of the origin node from the graph dictionary to start the shortest path from
@@ -242,9 +240,9 @@ class Graph:
 
         Required Arguments:
 
-        - `graph`
-            - Type: list[dict]
-            - What: A list of dictionaries where the indicies are origin node ids and the values are dictionaries of destination node ids and distances
+        - `graph`:
+            - Type: list of dictionaries
+            - See: https://connor-makowski.github.io/scgraph/scgraph/core.html#GeoGraph
         - `origin_id`
             - Type: int
             - What: The id of the origin node from the graph dictionary to start the shortest path from
@@ -298,7 +296,7 @@ class Graph:
 
 class GeoGraph:
     def __init__(
-        self, graph: list[dict], nodes: list[list[int, float]]
+        self, graph: list[dict], nodes: list[list[float|int]]
     ) -> None:
         """
         Function:
@@ -311,13 +309,74 @@ class GeoGraph:
             - Type: list of dictionaries
             - What: A list of dictionaries where the indicies are origin node ids and the values are dictionaries of destination node indices and distances
             - Note: All nodes must be included as origins in the graph regardless of if they have any connected destinations
+            - EG: 
+            ```
+                [
+                    # From London
+                    {
+                        # To Paris
+                        1: 311,
+                    },
+                    # From Paris
+                    {
+                        # To London
+                        0: 311, 
+                        # To Berlin
+                        2: 878, 
+                        # To Rome
+                        3: 1439,
+                        # To Madrid
+                        4: 1053
+                    },
+                    # From Berlin
+                    {
+                        # To Paris 
+                        1: 878,
+                        # To Rome
+                        3: 1181,
+                    },
+                    # From Rome
+                    {
+                        # To Paris
+                        1: 1439,
+                        # To Berlin
+                        2: 1181,
+                    },
+                    # From Madrid
+                    {
+                        # To Paris
+                        1: 1053,
+                        # To Lisbon
+                        5: 623
+                    },
+                    # From Lisbon
+                    {
+                        # To Madrid
+                        4: 623
+                    }
+                ]
+            ```
         - `nodes`
-            - Type: list of lists
+            - Type: list of lists of ints or floats
             - What: A list of lists where the values are coordinates (latitude then longitude)
             - Note: The length of the nodes list must be the same as that of the graph list
-
-        Optional Arguments:
-
+            - EG: 
+            ```
+                [
+                    # London
+                    [51.5074, 0.1278],
+                    # Paris
+                    [48.8566, 2.3522],
+                    # Berlin
+                    [52.5200, 13.4050],
+                    # Rome
+                    [41.9028, 12.4964],
+                    # Madrid
+                    [40.4168, 3.7038],
+                    # Lisbon
+                    [38.7223, 9.1393]
+                ]
+            ```
         """
         self.graph = graph
         self.nodes = nodes
@@ -397,17 +456,17 @@ class GeoGraph:
 
     def get_shortest_path(
         self,
-        origin_node: dict[int, float],
-        destination_node: dict[int, float],
+        origin_node: dict[float|int],
+        destination_node: dict[float|int],
         output_units: str = "km",
         algorithm_fn=Graph.dijkstra_makowski,
-        off_graph_circuity: [int, float] = 1,
+        off_graph_circuity: [float|int] = 1,
         node_addition_type: str = "quadrant",
-        node_addition_circuity: [int, float] = 4,
+        node_addition_circuity: [float|int] = 4,
         geograph_units: str = "km",
         output_coordinate_path: str = "list_of_lists",
         output_path: bool = False,
-        node_addition_lat_lon_bound: [int, float] = 5,
+        node_addition_lat_lon_bound: [float|int] = 5,
         node_addition_math: str = "euclidean",
         **kwargs,
     ) -> dict:
@@ -450,6 +509,7 @@ class GeoGraph:
                 - 'Graph.dijkstra_makowski': A modified dijkstra algorithm that uses a sparse distance matrix to identify the shortest path
                 - Any user defined algorithm that takes the arguments:
                     - `graph`: A dictionary of dictionaries where the keys are origin node ids and the values are dictionaries of destination node ids and distances
+                        - See: https://connor-makowski.github.io/scgraph/scgraph/core.html#GeoGraph
                     - `origin`: The id of the origin node from the graph dictionary to start the shortest path from
                     - `destination`: The id of the destination node from the graph dictionary to end the shortest path at
         - `off_graph_circuity`
@@ -582,9 +642,9 @@ class GeoGraph:
     def adujust_circuity_length(
         self,
         output: dict,
-        node_addition_circuity: [float, int],
-        off_graph_circuity: [float, int],
-    ) -> [float, int]:
+        node_addition_circuity: [float|int],
+        off_graph_circuity: [float|int],
+    ) -> [float|int]:
         """
         Function:
 
@@ -619,7 +679,7 @@ class GeoGraph:
                 4,
             )
 
-    def get_coordinate_path(self, path: list[int]) -> list[dict[int, float]]:
+    def get_coordinate_path(self, path: list[int]) -> list[dict[float|int]]:
         """
         Function:
 
@@ -663,11 +723,11 @@ class GeoGraph:
     def get_node_distances(
         self,
         node: list,
-        circuity: [int, float],
+        circuity: [float|int],
         node_addition_type: str,
         node_addition_math: str,
-        lat_lon_bound: [int, float],
-    ) -> dict[int, float]:
+        lat_lon_bound: [float|int],
+    ) -> dict[float|int]:
         """
         Function:
 
@@ -767,11 +827,11 @@ class GeoGraph:
 
     def add_node(
         self,
-        node: dict[int, float],
-        circuity: [int, float],
+        node: dict[float|int],
+        circuity: [float|int],
         node_addition_type: str = "quadrant",
         node_addition_math: str = "euclidean",
-        lat_lon_bound: [int, float] = 5,
+        lat_lon_bound: [float|int] = 5,
     ) -> int:
         """
         Function:
@@ -877,13 +937,13 @@ class GeoGraph:
 
         """
         features = []
-        for origin_idx, destinations in self.graph.items():
+        for origin_idx, destinations in enumerate(self.graph):
             for destination_idx, distance in destinations.items():
                 # Create an undirected graph for geojson purposes
                 if origin_idx > destination_idx:
                     continue
-                origin = self.nodes.get(origin_idx)
-                destination = self.nodes.get(destination_idx)
+                origin = self.nodes[origin_idx]
+                destination = self.nodes[destination_idx]
                 features.append(
                     {
                         "type": "Feature",
@@ -895,10 +955,10 @@ class GeoGraph:
                         "geometry": {
                             "type": "LineString",
                             "coordinates": [
-                                [origin["longitude"], origin["latitude"]],
+                                [origin[1], origin[0]],
                                 [
-                                    destination["longitude"],
-                                    destination["latitude"],
+                                    destination[1],
+                                    destination[0],
                                 ],
                             ],
                         },
@@ -908,3 +968,395 @@ class GeoGraph:
         out_dict = {"type": "FeatureCollection", "features": features}
         with open(filename, "w") as f:
             json.dump(out_dict, f)
+
+    def save_as_geograph(self, name: str) -> None:
+        """
+        Function:
+
+        - Save the current geograph as an importable python file
+
+        Required Arguments:
+
+        - `name`
+            - Type: str
+            - What: The name of the geograph and file
+            - EG: 'custom'
+                - Stored as: 'custom.py'
+                    - In your current directory
+                - Import as: 'from .custom import custom_geograph'
+        """
+        self.validate_nodes()
+        self.validate_graph(check_symmetry=True, check_connected=False)
+        out_string = f"""from scgraph.core import GeoGraph\ngraph={str(self.graph)}\nnodes={str(self.nodes)}\n{name}_geograph = GeoGraph(graph=graph, nodes=nodes)"""
+        with open(name + ".py", "w") as f:
+            f.write(out_string)
+
+    def mod_remove_arc(
+        self, origin_idx: int, destination_idx: int, undirected: bool = True
+    ) -> None:
+        """
+        Function:
+
+        - Remove an arc from the graph
+
+        Required Arguments:
+
+        - `origin_idx`
+            - Type: int
+            - What: The index of the origin node
+        - `destination_idx`
+            - Type: int
+            - What: The index of the destination node
+
+        Optional Arguments:
+
+        - `undirected`
+            - Type: bool
+            - What: Whether to remove the arc in both directions
+            - Default: True
+        """
+        assert origin_idx < len(self.graph), "Origin node does not exist"
+        assert destination_idx < len(
+            self.graph
+        ), "Destination node does not exist"
+        assert destination_idx in self.graph[origin_idx], "Arc does not exist"
+        del self.graph[origin_idx][destination_idx]
+        if undirected:
+            if origin_idx in self.graph[destination_idx]:
+                del self.graph[destination_idx][origin_idx]
+
+    def mod_add_node(
+        self, latitude: [float|int], longitude: [float|int]
+    ) -> int:
+        """
+        Function:
+
+        - Add a node to the graph
+
+        Required Arguments:
+
+        - `latitude`
+            - Type: int | float
+            - What: The latitude of the node
+        - `longitude`
+            - Type: int | float
+            - What: The longitude of the node
+
+        Returns:
+
+        - The index of the new node
+        """
+        self.nodes.append([latitude, longitude])
+        self.graph.append({})
+        return len(self.graph) - 1
+
+    def mod_add_arc(
+        self,
+        origin_idx: int,
+        destination_idx: int,
+        distance: [float|int] = 0,
+        use_haversine_distance=True,
+        undirected: bool = True,
+    ) -> None:
+        """
+        Function:
+
+        - Add an arc to the graph
+
+        Required Arguments:
+
+        - `origin_idx`
+            - Type: int
+            - What: The index of the origin node
+        - `destination_idx`
+            - Type: int
+            - What: The index of the destination node
+
+        Optional Arguments:
+
+        - `distance`
+            - Type: int | float
+            - What: The distance between the origin and destination nodes in terms of the graph distance (normally km)
+            - Default: 0
+        - `use_haversine_distance`
+            - Type: bool
+            - What: Whether to calculate the haversine distance (km) between the nodes when calculating the distance
+            - Default: True
+            - Note: If true, overrides the `distance` argument
+        - `undirected`
+            - Type: bool
+            - What: Whether to add the arc in both directions
+            - Default: True
+        """
+        assert origin_idx < len(self.graph), "Origin node does not exist"
+        assert destination_idx < len(
+            self.graph
+        ), "Destination node does not exist"
+        if use_haversine_distance:
+            distance = haversine(
+                self.nodes[origin_idx], self.nodes[destination_idx]
+            )
+        self.graph[origin_idx][destination_idx] = distance
+        if undirected:
+            self.graph[destination_idx][origin_idx] = distance
+
+
+def load_geojson_as_geograph(geojson_filename: str) -> GeoGraph:
+    """
+    Function:
+
+    - Create a CustomGeoGraph object loaded from a geojson file
+
+    Required Arguments:
+
+    - `geojson_filename`
+        - Type: str
+        - What: The filename of the geojson file to load
+        - Note: All arcs read in will be undirected
+        - Note: This geojson file must be formatted in a specific way
+            - The geojson file must be a FeatureCollection
+            - Each feature must be a LineString with two coordinate pairs
+                - The first coordinate pair must be the origin node
+                - The second coordinate pair must be the destination node
+                - The properties of the feature must include the distance between the origin and destination nodes
+                - The properties of the feature must include the origin and destination node idxs
+                - Origin and destination node idxs must be integers between 0 and n-1 where n is the number of nodes in the graph
+            - EG:
+            ```
+            {
+                "type": "FeatureCollection",
+                "features": [
+                    {
+                        "type": "Feature",
+                        "properties": {
+                            "origin_idx": 0,
+                            "destination_idx": 1,
+                            "distance": 10
+                        },
+                        "geometry": {
+                            "type": "LineString",
+                            "coordinates": [
+                                [121.47, 31.23],
+                                [121.48, 31.24]
+                            ]
+                        }
+                    }
+                ]
+            }
+            ```
+    """
+    with open(geojson_filename, "r") as f:
+        geojson_features = json.load(f).get("features", [])
+
+    nodes_dict = {}
+    graph_dict = {}
+    for feature in geojson_features:
+        properties = feature.get("properties", {})
+        origin_idx = properties.get("origin_idx")
+        destination_idx = properties.get("destination_idx")
+        distance = properties.get("distance")
+        geometry = feature.get("geometry", {})
+        coordinates = geometry.get("coordinates", [])
+
+        # Validations
+        assert (
+            feature.get("type") == "Feature"
+        ), "All features must be of type 'Feature'"
+        assert (
+            geometry.get("type") == "LineString"
+        ), "All geometries must be of type 'LineString'"
+        assert (
+            len(coordinates) == 2
+        ), "All LineStrings must have exactly 2 coordinates"
+        assert isinstance(
+            origin_idx, int
+        ), "All features must have an 'origin_idx' property that is an integer"
+        assert isinstance(
+            destination_idx, int
+        ), "All features must have a 'destination_idx' property that is an integer"
+        assert isinstance(
+            distance, (int, float)
+        ), "All features must have a 'distance' property that is a number"
+        assert (
+            origin_idx >= 0
+        ), "All origin_idxs must be greater than or equal to 0"
+        assert (
+            destination_idx >= 0
+        ), "All destination_idxs must be greater than or equal to 0"
+        assert distance >= 0, "All distances must be greater than or equal to 0"
+        origin = coordinates[0]
+        destination = coordinates[1]
+        assert isinstance(origin, list), "All coordinates must be lists"
+        assert isinstance(destination, list), "All coordinates must be lists"
+        assert len(origin) == 2, "All coordinates must have a length of 2"
+        assert len(destination) == 2, "All coordinates must have a length of 2"
+        assert all(
+            [isinstance(i, (int, float)) for i in origin]
+        ), "All coordinates must be numeric"
+        assert all(
+            [isinstance(i, (int, float)) for i in destination]
+        ), "All coordinates must be numeric"
+        # assert all([origin[0] >= -90, origin[0] <= 90, origin[1] >= -180, origin[1] <= 180]), "All coordinates must be valid latitudes and longitudes"
+        # assert all([destination[0] >= -90, destination[0] <= 90, destination[1] >= -180, destination[1] <= 180]), "All coordinates must be valid latitudes and longitudes"
+
+        # Update the data
+        nodes_dict[origin_idx] = origin
+        nodes_dict[destination_idx] = destination
+        graph_dict[origin_idx] = {
+            **graph_dict.get(origin_idx, {}),
+            destination_idx: distance,
+        }
+        graph_dict[destination_idx] = {
+            **graph_dict.get(destination_idx, {}),
+            origin_idx: distance,
+        }
+    assert len(nodes_dict) == len(
+        graph_dict
+    ), "All nodes must be included as origins in the graph dictionary"
+    nodes = [
+        [i[1][1], i[1][0]]
+        for i in sorted(nodes_dict.items(), key=lambda x: x[0])
+    ]
+    ordered_graph_tuple = sorted(graph_dict.items(), key=lambda x: x[0])
+    graph_map = {i[0]: idx for idx, i in enumerate(ordered_graph_tuple)}
+    graph = [
+        {graph_map[k]: v for k, v in i[1].items()} for i in ordered_graph_tuple
+    ]
+    return GeoGraph(graph=graph, nodes=nodes)
+
+
+def get_multi_path_geojson(
+    routes: list[dict],
+    filename: [str, None] = None,
+    show_progress: bool = False,
+) -> dict:
+    """
+    Creates a GeoJSON file with the shortest path between the origin and destination of each route.
+
+    Required Parameters:
+
+    - `routes`: list[dict]
+        - List of dictionaries with the following keys:
+            - geograph: GeoGraph
+                - Geograph object to use for the shortest path calculation.
+            - origin: dict[float|float]
+                - Origin coordinates
+                - EG: {"latitude":39.2904, "longitude":-76.6122}
+            - destination: dict[float|int]
+                - Destination coordinates
+                - EG: {"latitude":39.2904, "longitude":-76.6122}
+            - properties: dict
+                - Dictionary with the properties of the route
+                - Everything in this dictionary will be included in the output GeoJSON file as properties of the route.
+                - EG: {"id":"route_1", "name":"Route 1", "color":"#ff0000"}
+
+    Optional Parameters:
+
+    - `filename`: str | None
+        - Name of the output GeoJSON file.
+        - If None, the function will not save the file
+        - Default: None
+    - `show_progress`: bool
+        - Whether to show basic progress information
+        - Default: False
+
+    Returns
+
+    - `output`: dict
+        - Dictionary with the GeoJSON file content.
+    """
+    assert isinstance(routes, list), "Routes must be a list"
+    assert all(
+        [isinstance(i, dict) for i in routes]
+    ), "Routes must be a list of dictionaries"
+    assert all(
+        [isinstance(i.get("geograph"), GeoGraph) for i in routes]
+    ), "All routes must have a 'geograph' key with a GeoGraph object"
+    assert all(
+        [isinstance(i.get("origin"), dict) for i in routes]
+    ), "All routes must have an 'origin' key with a dictionary"
+    assert all(
+        [isinstance(i.get("destination"), dict) for i in routes]
+    ), "All routes must have a 'destination' key with a dictionary"
+    assert all(
+        [isinstance(i.get("properties"), dict) for i in routes]
+    ), "All routes must have a 'properties' key with a dictionary"
+    assert all(
+        [isinstance(i["origin"].get("latitude"), (int, float)) for i in routes]
+    ), "All origins must have a 'latitude' key with a number"
+    assert all(
+        [isinstance(i["origin"].get("longitude"), (int, float)) for i in routes]
+    ), "All origins must have a 'longitude' key with a number"
+    assert all(
+        [
+            isinstance(i["destination"].get("latitude"), (int, float))
+            for i in routes
+        ]
+    ), "All destinations must have a 'latitude' key with a number"
+    assert all(
+        [
+            isinstance(i["destination"].get("longitude"), (int, float))
+            for i in routes
+        ]
+    ), "All destinations must have a 'longitude' key with a number"
+    assert all(
+        [
+            (
+                i["origin"].get("latitude") >= -90
+                and i["origin"].get("latitude") <= 90
+            )
+            for i in routes
+        ]
+    ), "All origin latitudes must be between -90 and 90"
+    assert all(
+        [
+            (
+                i["origin"].get("longitude") >= -180
+                and i["origin"].get("longitude") <= 180
+            )
+            for i in routes
+        ]
+    ), "All origin longitudes must be between -180 and 180"
+    assert all(
+        [
+            (
+                i["destination"].get("latitude") >= -90
+                and i["destination"].get("latitude") <= 90
+            )
+            for i in routes
+        ]
+    ), "All destination latitudes must be between -90 and 90"
+    assert all(
+        [
+            (
+                i["destination"].get("longitude") >= -180
+                and i["destination"].get("longitude") <= 180
+            )
+            for i in routes
+        ]
+    ), "All destination longitudes must be between -180 and 180"
+
+    output = {"type": "FeatureCollection", "features": []}
+    len_routes = len(routes)
+    for idx, route in enumerate(routes):
+        shortest_path = route["geograph"].get_shortest_path(
+            route["origin"], route["destination"]
+        )
+        shortest_line_path = get_line_path(shortest_path)
+        output["features"].append(
+            {
+                "type": "Feature",
+                "properties": route["properties"],
+                "geometry": shortest_line_path,
+            }
+        )
+        if show_progress:
+            print(
+                f"[{'='*(int((idx+1)/len_routes*20))}>{' '*(20-int((idx+1)/len_routes*20))}] {idx+1}/{len_routes}",
+                end="\r",
+            )
+    if show_progress:
+        print()
+    if filename is not None:
+        json.dump(output, open(filename, "w"))
+    return output

{scgraph-2.1.2 → scgraph-2.3.0}/scgraph/utils.py

@@ -2,10 +2,10 @@ import math, json
 
 
 def haversine(
-    origin: list[float, int],
-    destination: list[float, int],
+    origin: list[float|int],
+    destination: list[float|int],
     units: str = "km",
-    circuity: [int, float] = 1,
+    circuity: [float|int] = 1,
 ):
     """
     Function:
@@ -16,10 +16,10 @@ def haversine(
 
     - `origin`:
         - Type: list of two floats | ints
-        - What: The origin point as a list of "longitude" and "latitude"
+        - What: The origin point as a list of "latitude" and "longitude"
     - `destination`:
         - Type: list of two floats | ints
-        - What: The destination point as a list of "longitude" and "latitude"
+        - What: The destination point as a list of "latitude" and "longitude"
 
     Optional Arguments:
 
@@ -69,7 +69,7 @@ def haversine(
         raise Exception()
 
 
-def hard_round(decimal_places: int, a: [int, float]):
+def hard_round(decimal_places: int, a: [float|int]):
     """
     Function:
 
@@ -90,7 +90,7 @@ def hard_round(decimal_places: int, a: [int, float]):
 
 
 def distance_converter(
-    distance: [int, float], input_units: str, output_units: str
+    distance: [float|int], input_units: str, output_units: str
 ):
     """
     Function:

{scgraph-2.1.2 → scgraph-2.3.0/scgraph.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: scgraph
-Version: 2.1.2
+Version: 2.3.0
 Summary: Determine an approximate route between two points on earth.
 Author-email: Connor Makowski <conmak@mit.edu>
 Project-URL: Homepage, https://github.com/connor-makowski/scgraph
@@ -9,7 +9,7 @@ Project-URL: Documentation, https://connor-makowski.github.io/scgraph/core.html
 Classifier: Programming Language :: Python :: 3
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
-Requires-Python: >=3.6
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 
@@ -57,7 +57,9 @@ Low Level: https://connor-makowski.github.io/scgraph/scgraph/core.html
 
 ## Setup
 
-Make sure you have Python 3.6.x (or higher) installed on your system. You can download it [here](https://www.python.org/downloads/).
+Make sure you have Python 3.10.x (or higher) installed on your system. You can download it [here](https://www.python.org/downloads/).
+
+Support for python3.6-3.9 is available up to version 2.2.0
 
 ## Installation
 
@@ -67,7 +69,10 @@ pip install scgraph
 
 ## Use with Google Colab
 
-See the example [here](https://colab.research.google.com/github/connor-makowski/scgraph/blob/main/example.ipynb) 
+- [Getting Started](https://colab.research.google.com/github/connor-makowski/scgraph/blob/main/examples/getting_started.ipynb) 
+- [Creating A Multi Path Geojson](https://colab.research.google.com/github/connor-makowski/scgraph/blob/main/examples/multi_path_geojson.ipynb)
+- [Modifying A Geograph](https://colab.research.google.com/github/connor-makowski/scgraph/blob/main/examples/geograph_modifications.ipynb)
+
 
 # Getting Started
 
@@ -101,7 +106,7 @@ In the above example, the `output` variable is a dictionary with three keys: `le
             - `ft` (feet)
 - `coordinate_path`: A list of lists [`latitude`,`longitude`] that make up the shortest path
 
-For more examples including viewing the output on a map, see the [example notebook](https://colab.research.google.com/github/connor-makowski/scgraph/blob/main/example.ipynb).
+For more examples including viewing the output on a map, see the [example notebook](https://colab.research.google.com/github/connor-makowski/scgraph/blob/main/examples/getting_started.ipynb).
 
 ## Included GeoGraphs
 
@@ -165,15 +170,17 @@ output = marnet_geograph.get_shortest_path(
 get_line_path(output, filename='output.geojson')
 ```
 
+Modify an existing geograph: See the notebook [here](https://colab.research.google.com/github/connor-makowski/scgraph/blob/main/examples/geograph_modifications.ipynb)
+
 
 You can specify your own custom graphs for direct access to the solving algorithms. This requires the use of the low level `Graph` class
 
 ```py
 from scgraph import Graph
 
-# Define a graph
+# Define an arbitrary graph
 # See the graph definitions here: 
-# https://connor-makowski.github.io/scgraph/scgraph/core.html
+# https://connor-makowski.github.io/scgraph/scgraph/core.html#GeoGraph
 graph = [
     {1: 5, 2: 1},
     {0: 5, 2: 2, 3: 1},
@@ -198,25 +205,67 @@ from scgraph import GeoGraph
 
 # Define nodes
 # See the nodes definitions here: 
-# https://connor-makowski.github.io/scgraph/scgraph/core.html
+# https://connor-makowski.github.io/scgraph/scgraph/core.html#GeoGraph
 nodes = [
-    [0,0],
-    [0,1],
-    [1,0],
-    [1,1],
-    [1,2],
-    [2,1]
+    # London
+    [51.5074, -0.1278],
+    # Paris
+    [48.8566, 2.3522],
+    # Berlin
+    [52.5200, 13.4050],
+    # Rome
+    [41.9028, 12.4964],
+    # Madrid
+    [40.4168, -3.7038],
+    # Lisbon
+    [38.7223, -9.1393]
 ]
 # Define a graph
 # See the graph definitions here: 
-# https://connor-makowski.github.io/scgraph/scgraph/core.html
+# https://connor-makowski.github.io/scgraph/scgraph/core.html#GeoGraph
 graph = [
-    {1: 5, 2: 1},
-    {0: 5, 2: 2, 3: 1},
-    {0: 1, 1: 2, 3: 4, 4: 8},
-    {1: 1, 2: 4, 4: 3, 5: 6},
-    {2: 8, 3: 3},
-    {3: 6}
+    # From London
+    {
+        # To Paris
+        1: 311,
+    },
+    # From Paris
+    {
+        # To London
+        0: 311, 
+        # To Berlin
+        2: 878, 
+        # To Rome
+        3: 1439,
+        # To Madrid
+        4: 1053
+    },
+    # From Berlin
+    {
+        # To Paris 
+        1: 878,
+        # To Rome
+        3: 1181,
+    },
+    # From Rome
+    {
+        # To Paris
+        1: 1439,
+        # To Berlin
+        2: 1181,
+    },
+    # From Madrid
+    {
+        # To Paris
+        1: 1053,
+        # To Lisbon
+        5: 623
+    },
+    # From Lisbon
+    {
+        # To Madrid
+        4: 623
+    }
 ]
 
 # Create a GeoGraph object
@@ -229,23 +278,31 @@ my_geograph.validate_graph()
 my_geograph.validate_nodes()
 
 # Get the shortest path between two points
+# In this case, Birmingham England and Zaragoza Spain
+# Since Birmingham and Zaragoza are not in the graph,
+# the algorithm will add them into the graph.
+# See: https://connor-makowski.github.io/scgraph/scgraph/core.html#GeoGraph.get_shortest_path
+# Expected output would be to go from
+# Birmingham -> London -> Paris -> Madrid -> Zaragoza
+
 output = my_geograph.get_shortest_path(
-    origin_node = {'latitude': 0, 'longitude': 0},
-    destination_node = {'latitude': 2, 'longitude': 1}
+    # Birmingham England
+    origin_node = {'latitude': 52.4862, 'longitude': -1.8904},
+    # Zaragoza Spain
+    destination_node = {'latitude': 41.6488, 'longitude': -0.8891}
 )
-#=>
+print(output)
 # {
-#     "coordinate_path": [
-#         [0,0],
-#         [0,0],
-#         [1,0],
-#         [0,1],
-#         [1,1],
-#         [2,1],
-#         [2,1]
-#     ],
-#     "length": 10
+#     'length': 1799.4323, 
+#     'coordinate_path': [
+#         [52.4862, -1.8904], 
+#         [51.5074, -0.1278], 
+#         [48.8566, 2.3522], 
+#         [40.4168, -3.7038], 
+#         [41.6488, -0.8891]
+#     ]
 # }
+
 ```
 
 ## Attributions and Thanks

{scgraph-2.1.2 → scgraph-2.3.0}/setup.cfg

@@ -1,6 +1,6 @@
 [metadata]
 name = scgraph
-version = 2.1.2
+version = 2.3.0
 description_file = README.md
 
 [options]