AequilibraE · pedrocamargo · Jun 16, 2024 · May 31, 2024 · Jun 2, 2024 · Jun 2, 2024
diff --git a/aequilibrae/reference_files/coquimbo.zip b/aequilibrae/reference_files/coquimbo.zip
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -77,7 +77,7 @@
             "examples/trip_distribution",
             "examples/visualization",
             "examples/aequilibrae_without_a_model",
-            "examples/full_workflows",
+            "examples/assignment_workflows",
             "examples/other_applications",
         ]
     ),

diff --git a/...amples/full_workflows/plot_forecasting.py → .../assignment_workflows/plot_forecasting.py b/...amples/full_workflows/plot_forecasting.py → .../assignment_workflows/plot_forecasting.py
diff --git a/...rkflows/plot_public_transit_assignment.py → ...rkflows/plot_public_transit_assignment.py b/...rkflows/plot_public_transit_assignment.py → ...rkflows/plot_public_transit_assignment.py
diff --git a/...es/trip_distribution/plot_route_choice.py → ...assignment_workflows/plot_route_choice.py b/...es/trip_distribution/plot_route_choice.py → ...assignment_workflows/plot_route_choice.py
@@ -37,6 +37,19 @@
 # %%
 import numpy as np
 
+# %%
+# Model parameters
+# ~~~~~~~~~~~~~~~~
+# We'll set the parameters for our route choice model. These are the parameters that will be used to calculate the
+# utility of each path. In our example, the utility is equal to *theta* * distance
+# And the path overlap factor (PSL) is equal to *beta*.
+
+# Distance factor
+theta=0.011
+
+# PSL parameter
+beta = 1.1
+
 # %%
 # Let's build all graphs
 project.network.build_graphs()
@@ -51,7 +64,8 @@
 project.network.graphs.keys()
 
 # let's say we want to minimize the distance
-graph.set_graph("distance")
+graph.network = graph.network.assign(utility=graph.network.distance * theta)
+graph.set_graph("utility")
 
 # But let's say we only want a skim matrix for nodes 28-40, and 49-60 (inclusive), these happen to be a selection of
 # western centroids.
@@ -109,8 +123,8 @@
 #
 # It is highly recommended to set either `max_routes` or `max_depth` to prevent runaway results.
 
-# rc.set_choice_set_generation("link-penalisation", max_routes=5, penalty=1.1)
-rc.set_choice_set_generation("bfsle", max_routes=5, beta=1.1, theta=1.1)
+# rc.set_choice_set_generation("link-penalisation", max_routes=5, penalty=1.02)
+rc.set_choice_set_generation("bfsle", max_routes=5, beta=1.1)
 
 # %%
 # All parameters are optional, the defaults are:

diff --git a/docs/source/examples/assignment_workflows/readme.rst b/docs/source/examples/assignment_workflows/readme.rst
@@ -0,0 +1,2 @@
+Assignment Workflows
+--------------------
diff --git a/docs/source/examples/creating_models/plot_import_gtfs.py b/docs/source/examples/creating_models/plot_import_gtfs.py
@@ -45,7 +45,7 @@
 
 data = Transit(project)
 
-transit = data.new_gtfs_builder(agency="LISANCO", file_path=dest_path)
+transit = data.new_gtfs_builder(agency="Lisanco", file_path=dest_path)
 
 # %%
 # To load the data, we must choose one date. We're going to continue with 2016-04-13 but feel free 
@@ -66,9 +66,7 @@
 # Now we will plot one of the route's patterns we just imported
 conn = database_connection("transit")
 
-links = pd.read_sql(
-    "SELECT pattern_id, ST_AsText(geometry) geom FROM routes WHERE geom IS NOT NULL AND pattern_id == 10001003000;", 
-    con=conn)
+links = pd.read_sql("SELECT pattern_id, ST_AsText(geometry) geom FROM routes;", con=conn)
 
 stops = pd.read_sql("""SELECT stop_id, ST_X(geometry) X, ST_Y(geometry) Y FROM stops""", con=conn)
 
@@ -78,23 +76,30 @@
 
 layers = [gtfs_links, gtfs_stops]
 
+# %%
+pattern_colors = ["#146DB3", "#EB9719"]
+
+# %%
 for i, row in links.iterrows():
     points = row.geom.replace("MULTILINESTRING", "").replace("(", "").replace(")", "").split(", ")
     points = "[[" + "],[".join([p.replace(" ", ", ") for p in points]) + "]]"
     points = [[x[1], x[0]] for x in eval(points)]
 
-    _ = folium.vector_layers.PolyLine(points, popup=f"<b>link_id: {row.pattern_id}</b>", color="red", weight=2).add_to(
-        gtfs_links
-    )
+    _ = folium.vector_layers.PolyLine(
+        points, 
+        popup=f"<b>pattern_id: {row.pattern_id}</b>", 
+        color=pattern_colors[i], 
+        weight=5,
+    ).add_to(gtfs_links)
 
 for i, row in stops.iterrows():
     point = (row.Y, row.X)
 
     _ = folium.vector_layers.CircleMarker(
         point,
-        popup=f"<b>link_id: {row.stop_id}</b>",
+        popup=f"<b>stop_id: {row.stop_id}</b>",
         color="black",
-        radius=3,
+        radius=2,
         fill=True,
         fillColor="black",
         fillOpacity=1.0,
@@ -104,7 +109,7 @@
 # Let's create the map!
 
 # %%
-map_osm = folium.Map(location=[-29.9633719, -71.3242825], zoom_start=13)
+map_osm = folium.Map(location=[-29.93, -71.29], zoom_start=13)
 
 # add all layers
 for layer in layers:

diff --git a/docs/source/examples/full_workflows/readme.rst b/docs/source/examples/full_workflows/readme.rst
diff --git a/docs/source/images/plot_import_gtfs.png b/docs/source/images/plot_import_gtfs.png
diff --git a/docs/source/modeling_with_aequilibrae.rst b/docs/source/modeling_with_aequilibrae.rst
@@ -19,8 +19,9 @@ a start guide to a complete view into AequilibraE's data structure.
     :maxdepth: 1
 
     modeling_with_aequilibrae/project
-    modeling_with_aequilibrae/modeling_concepts
-    modeling_with_aequilibrae/project_database
     modeling_with_aequilibrae/parameter_file
+    modeling_with_aequilibrae/project_database
     modeling_with_aequilibrae/public_transport
+    modeling_with_aequilibrae/static_traffic_assignment
     modeling_with_aequilibrae/transit_assignment
+    modeling_with_aequilibrae/route_choice
diff --git a/docs/source/modeling_with_aequilibrae/route_choice.rst b/docs/source/modeling_with_aequilibrae/route_choice.rst
@@ -0,0 +1,11 @@
+.. _route_choice:
+
+Route Choice
+============
+
+
+.. toctree::
+    :maxdepth: 1
+
+    transit_assignment/hyperpath_routing.rst
+    transit_assignment/transit_graph.rst
diff --git a/docs/source/modeling_with_aequilibrae/route_choice/choice_set_generation.rst b/docs/source/modeling_with_aequilibrae/route_choice/choice_set_generation.rst
@@ -0,0 +1,25 @@
+Choice set generation algorithms
+================================
+
+XXXXXXXXXXXXXX
+
+Imports
+-------
+
+.. code:: python
+
+   from aequilibrae.paths.route_choice_set import RouteChoiceSet
+   rc = RouteChoiceSet(graph)  # Builds 1:n compressed id -> network ids map, can take a minute
+
+
+
+
+References
+----------
+
+.. [1] Rieser-Schüssler, N., Balmer, M., & Axhausen, K. W. (2012). Route choice sets for very high-resolution data.
+       Transportmetrica A: Transport Science, 9(9), 825–845.
+       https://doi.org/10.1080/18128602.2012.671383
+
+.. [2] Moss, J., P. V. de Camargo, C. de Freitas, and R. Imai. High-Performance Route Choice Set Generation on
+       Large Networks. Presented at the ATRF, Melbourne, 2024.
diff --git a/docs/source/modeling_with_aequilibrae/route_choice/route_choice_model.rst b/docs/source/modeling_with_aequilibrae/route_choice/route_choice_model.rst
@@ -0,0 +1,48 @@
+Route choice models
+===================
+
+XXXXXXXXXXXXXX
+
+Imports
+-------
+
+.. code:: python
+
+   from aequilibrae.paths.route_choice_set import RouteChoiceSet
+   from aequilibrae import Project
+
+   proj = Project()
+   proj.load('path/to/project/folder')
+
+   proj.network.build_graphs()
+   graph = proj.network.graphs['c']
+
+   graph.prepare_graph(centroids=[list_of_all_nodes_which_are_origin_or_destination_in_the_observed_dataset])
+
+   # Measure that will be used to compute paths
+   graph.set_graph('free_flow_time')
+
+   nodes = [(1, 50), (2, 100), (3, 150)]  # List of tuples with (origin, destination) nodes
+   max_routes = 10  # Maximum number of routes to be computed for each OD pair
+   penalty = 1.01  # Penalty to be applied to links used in paths.
+   cores = 60  # Number of cores to be used in the computation
+   psl = True  # If True, the path size logit will be used to compute probabilities already
+   bfsle=True # Should we use BFSLE? If False, defaults to Link Penalization
+   # This is only useful if you are already using an utility measure to compute paths
+
+   rc = RouteChoiceSet(graph)  # Builds data structures -> can take a minute
+   rc.batched(nodes, max_routes=max_routes, cores=cores, bfsle=bfsle, penalty=penalty, path_size_logit=psl)
+
+   results = rc.get_results().to_pandas()
+   results.to_parquet(Path(r"/my_choice_set.parquet")
+
+
+
+References
+----------
+
+.. [1] Ramming, M. S. Network Knowledge and Route Choice. Massachusetts Institute of Technology, 2002.
+
+.. [2] Zill, J. C., and P. V. de Camargo. State-Wide Route Choice Models.
+       Presented at the ATRF, Melbourne, Australia, 2024.
+
diff --git a/...ng_with_aequilibrae/modeling_concepts.rst → ...aequilibrae/static_traffic_assignment.rst b/...ng_with_aequilibrae/modeling_concepts.rst → ...aequilibrae/static_traffic_assignment.rst
@@ -1,14 +1,14 @@
-.. _modeling_concepts:
+.. _static_traffic_assignment:
 
-Modeling Concepts
-=================
+Static Traffic Assignment
+=========================
 
-Modeling with AequilibraE is not dissimilar than modeling with traditional commercial packages,
+Performing static traffic assignment with AequilibraE is not dissimilar than doing so with traditional commercial packages,
 as we strive to make it as easy as possible for seasoned modelers to migrate their models and
 workflows to AequilibraE.
 
 Although modeling with AequilibraE should feel somewhat familiar to seasoned modelers, especially
-those used to programming, the mechanics of some of AequilibraE procedures might be foreign to
+those used to programming, the mechanics of traffic assignment in AequilibraE might be foreign to
 some users, so this section of the documentation will include discussions of the mechanics
 of some of these procedures and some light discussion on its motivation.
 
@@ -20,6 +20,6 @@ we detail how these concepts are translated into the AequilibraE tools and recom
 .. toctree::
     :maxdepth: 1
 
-    modeling_concepts/multi_class_equilibrium
-    modeling_concepts/assignment_mechanics
+    static_traffic_assignment/multi_class_equilibrium
+    static_traffic_assignment/assignment_mechanics
 
diff --git a/...odeling_concepts/assignment_mechanics.rst → ...affic_assignment/assignment_mechanics.rst b/...odeling_concepts/assignment_mechanics.rst → ...affic_assignment/assignment_mechanics.rst
diff --git a/...ling_concepts/multi_class_equilibrium.rst → ...ic_assignment/multi_class_equilibrium.rst b/...ling_concepts/multi_class_equilibrium.rst → ...ic_assignment/multi_class_equilibrium.rst