change project structure

AequilibraE · Sep 16, 2024 · 10b11b7 · 10b11b7
1 parent 12c22cb
commit 10b11b7
Show file tree

Hide file tree

Showing 31 changed files with 112 additions and 260 deletions.
diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml
@@ -46,9 +46,7 @@ jobs:
     - name: Test docstrings
       run: |
         python -m pytest --doctest-modules aequilibrae/log.py aequilibrae/parameters.py aequilibrae/paths/vdf.py
-        python -m pytest docs/source/modeling_with_aequilibrae/project_components.rst --doctest-glob=*.rst
-        python -m pytest docs/source/modeling_with_aequilibrae/accessing_project_data.rst --doctest-glob=*.rst
-        python -m pytest docs/source/modeling_with_aequilibrae/aequilibrae_matrix.rst --doctest-glob=*.rst
+        python -m pytest docs/source/modeling_with_aequilibrae/project_pieces --doctest-glob=*.rst
 
     - name: Build documentation
       run: |

diff --git a/.gitignore b/.gitignore
@@ -5,8 +5,8 @@ _templates
 docs/source/sg_execution_times.rst
 docs/source/_auto_examples
 docs/source/api/generated
-docs/source/modeling_with_aequilibrae/aequilibrae_project/project_database/data_model
-docs/source/modeling_with_aequilibrae/aequilibrae_project/transit_database/data_model
+docs/source/modeling_with_aequilibrae/project_database/data_model
+docs/source/modeling_with_aequilibrae/transit_database/data_model
 
 # User-specific stuff:
 .idea/**/workspace.xml

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -177,12 +177,7 @@
 
 # -- Options for Texinfo output ----------------------------------------------
 
-autodoc_default_options = {
-    "members": True,
-    "inherited-members": True,
-    "undoc-members": True,
-    'autosummary': True
-}
+autodoc_default_options = {"members": True, "inherited-members": True, "undoc-members": True, "autosummary": True}
 
 autodoc_member_order = "groupwise"
 autoclass_content = "class"  # classes should include both the class' and the __init__ method's docstring

diff --git a/docs/source/examples/trip_distribution/just_matrices.omx b/docs/source/examples/trip_distribution/just_matrices.omx
diff --git a/docs/source/examples/trip_distribution/select_link_analysis.omx b/docs/source/examples/trip_distribution/select_link_analysis.omx
diff --git a/...ibrae/aequilibrae_project/project_database/data_model/transit_graph_configs.rst b/...ibrae/aequilibrae_project/project_database/data_model/transit_graph_configs.rst
diff --git a/...ling_with_aequilibrae/aequilibrae_project/project_database/data_model/zones.rst b/...ling_with_aequilibrae/aequilibrae_project/project_database/data_model/zones.rst
diff --git a/docs/source/modeling_with_aequilibrae/index.rst b/docs/source/modeling_with_aequilibrae/index.rst
@@ -18,7 +18,11 @@ a start guide to a complete view into AequilibraE's data structure.
     :maxdepth: 1
     :caption: A guide to AequilibraE
 
-    aequilibrae_project/index
+    project
+    project_database/index
+    parameter_file
+    transit_database/index
+    project_pieces/index
     static_traffic_assignment/index
     transit_assignment/index
     route_choice/index
diff --git a/...ae/aequilibrae_project/parameter_file.rst → ...eling_with_aequilibrae/parameter_file.rst b/...ae/aequilibrae_project/parameter_file.rst → ...eling_with_aequilibrae/parameter_file.rst
@@ -14,7 +14,7 @@ The assignment section of the parameter file is the smallest one, and it
 contains only the convergence criteria for assignment in terms of the maximum number
 of iterations and target Relative Gap.
 
-.. image:: ../../images/parameters_assignment_example.png
+.. image:: ../images/parameters_assignment_example.png
     :align: center
     :scale: 80 %
     :alt: Assignment example
@@ -32,7 +32,7 @@ contains only the parameters for number of maximum iterations, convergence level
 and maximum trip length to be applied in Iterative Proportional Fitting and
 synthetic gravity models, as shown below.
 
-.. image:: ../../images/parameters_distribution_example.png
+.. image:: ../images/parameters_distribution_example.png
     :align: center
     :scale: 80 %
     :alt: Distribution example
@@ -66,7 +66,7 @@ The data types available are those that exist within the
 `SQLite specification <https://www.sqlite.org/datatype3.html>`_ . We recommend limiting yourself
 to the use of **integer**, **numeric** and **varchar**.
 
-.. image:: ../../images/parameters_links_example.png
+.. image:: ../images/parameters_links_example.png
     :align: center
     :scale: 80 %
     :alt: Link example
@@ -91,7 +91,7 @@ forward/backward values tagged). For this reason, one can use the parameter 'osm
 to define what to do with numeric tag values that have not been tagged for both directions.
 the allowed values for this parameter are **copy** and **divide**, as shown below.
 
-.. image:: ../../images/parameters_links_osm_behaviour.png
+.. image:: ../images/parameters_links_osm_behaviour.png
     :align: center
     :scale: 80 %
     :alt: OSM behaviour examples
@@ -132,7 +132,7 @@ GMNS
 The **GMNS** group of parameters has four specifications: **critical_dist**, **link**,
 **node**, and **use_definition**.
 
-.. image:: ../../images/parameter_yaml_files_gmns.png
+.. image:: ../images/parameter_yaml_files_gmns.png
     :align: center
     :alt: GMNS parameter group
 
@@ -154,7 +154,7 @@ number of threads used in multi-threaded processes, logging and temp folders
 and whether we should be saving information to a log file at all, as exemplified
 below.
 
-.. image:: ../../images/parameters_system_example.png
+.. image:: ../images/parameters_system_example.png
     :align: center
     :scale: 80 %
     :alt: System example
@@ -180,7 +180,7 @@ The OSM section of the parameter file is relevant only when one plans to
 download a substantial amount of data from an Overpass API, in which case it is
 recommended to deploy a local Overpass server.
 
-.. image:: ../../images/parameters_osm_example.png
+.. image:: ../images/parameters_osm_example.png
     :align: center
     :scale: 80 %
     :alt: OSM example

diff --git a/...aequilibrae/aequilibrae_project/index.rst → ...rce/modeling_with_aequilibrae/project.rst b/...aequilibrae/aequilibrae_project/index.rst → ...rce/modeling_with_aequilibrae/project.rst
@@ -27,31 +27,6 @@ please refer to :ref:`dependencies`. For QGIS users this is not a concern, while
 for Windows users this dependency is automatically handled under the hood, but
 the details are also discussed in the aforementioned dependencies section.
 
-Package components: A conceptual view
--------------------------------------
-
-As all the components of an AequilibraE model are based on open-source software and
-open-data standards, modeling with AequilibraE is a little different from
-modeling with commercial packages, as the user can read and manipulate model
-components outside the software modeling environments (Python and QGIS).
-
-Thus, using/manipulating each one of an AequilibraE model components can be done
-in different ways depending on the tool you use for such.
-
-It is then important to highlight that AequilibraE, as a software, is divided in
-three very distinctive layers.  The first, which is responsible for tables
-consistent with each other (including links and nodes, modes and link_types),
-are embedded in the data layer in the form of geo-spatial database triggers. The
-second is the Python API, which provides all of AequilibraE's core algorithms
-and data manipulation facilities. The third is the GUI implemented in QGIS,
-which provides a user-friendly interface to access the model, visualize results
-and run procedures.
-
-These software layers are *stacked* and depend on each other, which means that any
-network editing done in SQLite, Python or QGIS will go through the SpatiaLite triggers,
-while any procedure such as traffic assignment done in QGIS is nothing more than an
-API call to the corresponding Python method.
-
 .. _aeq_project_structure:
 
 Project structure
@@ -61,7 +36,7 @@ Since version 0.7, the AequilibraE project consists of a main folder, where a
 series of files and sub folders exist, and the current project organization
 is as follows:
 
-.. image:: ../../images/project_structure.png
+.. image:: ../images/project_structure.png
     :scale: 25 %
     :align: center
     :alt: AequilibraE project structure
@@ -100,21 +75,27 @@ also created *on-the-fly* when the user imports a GTFS source into an Aequilibra
 model, but there is still no support for manually or programmatically adding routes
 to a route system as of yet.
 
-The following sections presents the structure and contents for all databases in the project.
+Package components: A conceptual view
+-------------------------------------
 
-.. toctree::
-    :maxdepth: 1
-    :caption: Get to know the project components 
+As all the components of an AequilibraE model are based on open-source software and
+open-data standards, modeling with AequilibraE is a little different from
+modeling with commercial packages, as the user can read and manipulate model
+components outside the software modeling environments (Python and QGIS).
 
-    ../project_components
-    ../accessing_project_data
-    ../aequilibrae_matrix
+Thus, using/manipulating each one of an AequilibraE model components can be done
+in different ways depending on the tool you use for such.
 
-.. toctree::
-    :maxdepth: 1
-    :caption: Or dive deep into project structure! 
+It is then important to highlight that AequilibraE, as a software, is divided in
+three very distinctive layers.  The first, which is responsible for tables
+consistent with each other (including links and nodes, modes and link_types),
+are embedded in the data layer in the form of geo-spatial database triggers. The
+second is the Python API, which provides all of AequilibraE's core algorithms
+and data manipulation facilities. The third is the GUI implemented in QGIS,
+which provides a user-friendly interface to access the model, visualize results
+and run procedures.
 
-    project_database/index
-    parameter_file
-    results_database
-    transit_database/index
+These software layers are *stacked* and depend on each other, which means that any
+network editing done in SQLite, Python or QGIS will go through the SpatiaLite triggers,
+while any procedure such as traffic assignment done in QGIS is nothing more than an
+API call to the corresponding Python method.
diff --git a/...librae_project/project_database/about.rst → ...th_aequilibrae/project_database/about.rst b/...librae_project/project_database/about.rst → ...th_aequilibrae/project_database/about.rst
@@ -19,7 +19,7 @@ We strongly recommend not to edit the information on **projection** and
 the software to produce valuable information to the user with regards to
 opportunities for version upgrades.
 
-.. image:: ../../../images/about_table_example.png
+.. image:: ../../images/about_table_example.png
     :alt: About table structure
     :align: center
 
@@ -28,5 +28,3 @@ An API for editing the contents of this database is available from the API docum
 .. seealso::
 
     :func:`aequilibrae.project.About`
-
-.. include:: data_model/about.rst
diff --git a/...ect_database/attributes_documentation.rst → ...ect_database/attributes_documentation.rst b/...ect_database/attributes_documentation.rst → ...ect_database/attributes_documentation.rst
@@ -12,12 +12,10 @@ itself.
 
 As a simple table, it looks as follows:
 
-.. image:: ../../../images/attributes_documentation.png
+.. image:: ../../images/attributes_documentation.png
     :align: center
     :alt: attributes documentation table 
 
 .. seealso::
 
     :func:`aequilibrae.project.FieldEditor`
-
-.. include:: data_model/attributes_documentation.rst
diff --git a/...t/project_database/datamodel.rst.template → ...e/project_database/datamodel.rst.template b/...t/project_database/datamodel.rst.template → ...e/project_database/datamodel.rst.template
@@ -1,5 +1,3 @@
-:orphan:
-
 .. _supply_data_model:
 
 SQL Data model

diff --git a/...librae_project/project_database/index.rst → ...th_aequilibrae/project_database/index.rst b/...librae_project/project_database/index.rst → ...th_aequilibrae/project_database/index.rst
@@ -10,12 +10,21 @@ an AequilibraE model you intend to use in anger.
 .. toctree::
    :maxdepth: 1
 
-   about
    network
-   modes
    link_types
-   matrices
+   modes
    zones
-   attributes_documentation
+   matrices
+   results
    periods
-   transit_graph
+   transit_graph
+   about
+   attributes_documentation
+
+A more technical view of the database structure, including the SQL queries used to create each table and the indices used for each table are also available.
+
+.. toctree::
+   :caption: Get to know the data structures in the project database!
+   :maxdepth: 1
+
+   data_model/datamodel.rst
diff --git a/...e_project/project_database/link_types.rst → ...quilibrae/project_database/link_types.rst b/...e_project/project_database/link_types.rst → ...quilibrae/project_database/link_types.rst
@@ -33,7 +33,7 @@ Adding new link types to a project
 Adding link types to a project can be done through the Python API or directly into
 the 'link_types' table, which could look like the following.
 
-.. image:: ../../../images/link_types_table.png
+.. image:: ../../images/link_types_table.png
     :align: center
     :alt: Link_types table structure
 
@@ -121,5 +121,3 @@ required.
 .. seealso::
 
     :func:`aequilibrae.project.network.LinkTypes`
-
-.. include:: data_model/link_types.rst
diff --git a/...rae_project/project_database/matrices.rst → ...aequilibrae/project_database/matrices.rst b/...rae_project/project_database/matrices.rst → ...aequilibrae/project_database/matrices.rst
@@ -11,7 +11,7 @@ This index, which looks like below, has two main columns. The first one is the
 AequilibraE to find the file, and **name**, which is the name by which the user
 should refer to the matrix in order to access it through the API.
 
-.. image:: ../../../images/matrices_table.png
+.. image:: ../../images/matrices_table.png
     :align: center
     :alt: Matrices table structure
 
@@ -22,6 +22,4 @@ types (AEM and OMX) without prejudice to functionality.
 
     :func:`aequilibrae.project.Matrices`
 
-    :func:`aequilibrae.matrix.AequilibraeMatrix`
-
-.. include:: data_model/matrices.rst
+    :func:`aequilibrae.matrix.AequilibraeMatrix`
diff --git a/...librae_project/project_database/modes.rst → ...th_aequilibrae/project_database/modes.rst b/...librae_project/project_database/modes.rst → ...th_aequilibrae/project_database/modes.rst
@@ -16,7 +16,7 @@ As described in the SQL data model, all AequilibraE models are created with 4
 standard modes, which can be added to or removed by the user, and would look like
 the following.
 
-.. image:: ../../../images/modes_table.png
+.. image:: ../../images/modes_table.png
     :align: center
     :alt: Modes table structure
 
@@ -98,5 +98,3 @@ required.
 .. seealso::
 
     :func:`aequilibrae.project.network.Modes`
-
-.. include:: data_model/modes.rst
diff --git a/...brae_project/project_database/network.rst → ..._aequilibrae/project_database/network.rst b/...brae_project/project_database/network.rst → ..._aequilibrae/project_database/network.rst
@@ -33,7 +33,3 @@ other changes to the layers or preventing the changes.
 
    network_import_and_export.rst
    network_geometry.rst
-
-.. include:: data_model/links.rst
-
-.. include:: data_model/nodes.rst