path components and other classes

aequilibrae/distribution/synthetic_gravity_model.py

@@ -47,7 +47,7 @@ def __getattr__(self, key):
             return self.__dict__[key]
 
     def load(self, file_name):
-        """Loads model from disk. Extension is \*.mod"""
+        """Loads model from disk. Extension is \\*.mod"""
         try:
             with open(file_name, "r") as f:
                 model = yaml.safe_load(f)[self.model_type]
@@ -60,7 +60,7 @@ def load(self, file_name):
             raise ValueError("File provided is not a valid Synthetic Gravity Model - {}".format(err.__str__())) from err
 
     def save(self, file_name):
-        """Saves model to disk in yaml format. Extension is \*.mod"""
+        """Saves model to disk in yaml format. Extension is \\*.mod"""
         file_name = str(file_name)
         if file_name[-4:].upper() != ".MOD":
             file_name += ".mod"

docs/source/_latex/index.rst

@@ -7,6 +7,7 @@ AequilibraE
    :hidden:
    :maxdepth: 1
 
+   ../useful_links/installation
    ../aequilibrae_project
    ../distribution_procedures
    ../network_manipulation

docs/source/conf.py

@@ -166,7 +166,7 @@
 # (source start file, target name, title, author, documentclass [howto, manual, or own class]).
 latex_documents = [("_latex/index", "aequilibrae.tex", html_title, author, "manual")]
 
-latex_appendices = ["useful_links/installation"]
+# latex_appendices = ["useful_links/installation"]
 
 latex_engine = 'xelatex'
 

docs/source/distribution_procedures/classes.rst

@@ -10,7 +10,7 @@ AequilibraE's distribution module comprises three different classes: ``GravityAp
 This class, as its own name explains, applies a synthetic gravity model, using one of the available
 deterrence funcions: ``EXPO``, ``POWER``, or ``GAMMA``. It requires some parameters, such as:
 
-* Synthetic gravity model (which is an instance of `aequilibrae.distribution.SyntheticGravityModel`)
+* Synthetic gravity model (which is an instance of ``SyntheticGravityModel``)
 * Impedance matrix (``AequilibraeMatrix``);
 * Vector (``Pandas.DataFrame``) with data for row and column totals;
 * Row and column fields, which are the names of the fields that contain the data for row and column
@@ -24,6 +24,8 @@ documentation.
 
 .. seealso::
 
+    * :func:`aequilibrae.distribution.SyntheticGravityModel`
+        Function documentation
     * :func:`aequilibrae.distribution.GravityApplication`
         Function documentation
 

docs/source/network_manipulation.rst

@@ -1,7 +1,10 @@
 Network Manipulation
 ====================
 
-In this section, we talk about 
+In this section, we discuss how can we import and export data to/from an AequilibraE project.
+Besides, important concepts on geometry manipulation are presented. Finally, some examples that
+involve project creation, edition of links and nodes, and identification of disconnected links
+for network clean up are presented.
 
 .. toctree::
    :caption: Network Manipulation

docs/source/path_computation.rst

@@ -9,14 +9,32 @@ This use case supports the development of a number of computationally intensive
 map-matching GPS data and simulation of Demand Responsive Transport (DRT, e.g. Uber) operators,
 for example.
 
+Some basic usages of the AequilibraE path module consist on:
+
 #. **Path computation**: computes the path between two arbritrary nodes.
 
 #. **Network skimming**: can compute either the distance, the travel time, or your own cost matrix
    between a series of nodes.
 
+Regarding computing paths through a network, part of its complexity comes from the fact that 
+transportation models usually house networks for multiple transport modes, so the loads (links)
+available for a passenger car may be different than those available for a heavy truck, as it happens 
+in practice.
+
+For this reason, all path computation in AequilibraE happens through ``Graph`` objects. While users 
+can operate models by simply selecting the mode they want AequilibraE to create graphs for, ``Graph`` 
+objects can also be manipulated in memory or even created from networks that are 
+:ref:`NOT housed inside an AequilibraE model <plot_assignment_without_model>`.
+
+AequilibraE's graphs are the backbone of path computation, skimming and traffic assignment. 
+Besides handling the selection of links available to each mode in an AequilibraE model, graphs 
+also handle the existence of bi-directional links with direction-specific characteristics 
+(e.g. speed limit, congestion levels, tolls, etc.). For this reason, the next section is
+entirely dedicated to this object.
+
 .. seealso::
 
-    * :func:`aequilibrae.paths.results`
+    * :func:`aequilibrae.paths.results.PathResults`
         Class documentation
     * :ref:`example_usage_path_computation` 
         Usage example
@@ -27,4 +45,5 @@ for example.
     :caption: Path Computation
     :maxdepth: 1
 
+    path_computation/aequilibrae_graph
     path_computation/_auto_examples/index

docs/source/project_components/aequilibrae_graph.rst → docs/source/path_computation/aequilibrae_graph.rst

@@ -1,13 +1,7 @@
 .. _aequilibrae-graphs:
 
 AequilibraE Graphs
-~~~~~~~~~~~~~~~~~~
-
-As mentioned above, AequilibraE's graphs are the backbone of path computation,
-skimming and Traffic Assignment. Besides handling the selection of links available to
-each mode in an AequilibraE model, graphs also handle the existence of bi-directional
-links with direction-specific characteristics (e.g. speed limit, congestion levels, tolls,
-etc.).
+==================
 
 The Graph object is rather complex, but the difference between the graph and the physical 
 links are the availability of two class member variables consisting of Pandas DataFrames: the
@@ -23,7 +17,7 @@ links are the availability of two class member variables consisting of Pandas Da
     >>> g.graph # doctest: +SKIP
 
 Directionality
-^^^^^^^^^^^^^^
+--------------
 
 Links in the Network table (the Pandas representation of the project's *Links* table) are
 potentially bi-directional, and the directions allowed for traversal are dictated by the
@@ -39,7 +33,7 @@ the graph used to set computations (e.g. field to minimize during path-finding,
 etc.) will be **free_flow_travel_time**.
 
 Graphs from a model
-^^^^^^^^^^^^^^^^^^^
+-------------------
 
 Building graphs directly from an AequilibraE model is the easiest option for beginners
 or when using AequilibraE in anger, as much of the setup is done by default.
@@ -52,7 +46,7 @@ or when using AequilibraE in anger, as much of the setup is done by default.
     >>> graph = project.network.graphs['c'] # we grab the graph for cars
 
 Manipulating graphs in memory
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+-----------------------------
 
 As mentioned before, the AequilibraE Graph can be manipulated in memory, with all its
 components available for editing. One of the simple tools available directly in the
@@ -86,7 +80,8 @@ changes to be made in the network DataFrame. For example:
     >>> graph.network.loc[graph.network.link_type == "motorway", "speed_ba"] = 100
 
 Skimming settings
-^^^^^^^^^^^^^^^^^
+-----------------
+
 Skimming the field of a graph when computing shortest path or performing
 traffic assignment must be done by setting the skimming fields in the
 Graph object, and there are no limits (other than memory) to the number
@@ -97,7 +92,7 @@ of fields that can be skimmed.
     >>> graph.set_skimming(["distance", "travel_time"])
 
 Setting centroids
-^^^^^^^^^^^^^^^^^
+-----------------
 
 Like other elements of the AequilibraE Graph, the user can also manipulate the
 set of nodes interpreted by the software as centroids in the Graph itself.