diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml index 3a9b3c5ab..6db583769 100644 --- 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 index 7421c20e0..2153bfdde 100644 --- 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 index 2e5323917..cd90b2050 100644 --- 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 deleted file mode 100644 index 67345d255..000000000 Binary files a/docs/source/examples/trip_distribution/just_matrices.omx and /dev/null differ diff --git a/docs/source/examples/trip_distribution/select_link_analysis.omx b/docs/source/examples/trip_distribution/select_link_analysis.omx deleted file mode 100644 index 2c97a0e39..000000000 Binary files a/docs/source/examples/trip_distribution/select_link_analysis.omx and /dev/null differ diff --git a/docs/source/modeling_with_aequilibrae/aequilibrae_project/project_database/data_model/transit_graph_configs.rst b/docs/source/modeling_with_aequilibrae/aequilibrae_project/project_database/data_model/transit_graph_configs.rst deleted file mode 100644 index 44332333e..000000000 --- a/docs/source/modeling_with_aequilibrae/aequilibrae_project/project_database/data_model/transit_graph_configs.rst +++ /dev/null @@ -1,29 +0,0 @@ -*transit_graph_configs* table structure ---------------------------------------- - -The *transit_graph_configs* table holds configuration parameters for a TransitGraph of a particular `period_id` -Attributes follow - -.. csv-table:: - :header: "Field", "Type", "NULL allowed", "Default Value" - :widths: 30, 20, 20, 20 - - period_id*,INTEGER,NO, - config,TEXT,YES, - - -(* - Primary key) - - - -The SQL statement for table and index creation is below. - - -:: - - - CREATE TABLE if not exists transit_graph_configs (period_id INTEGER UNIQUE NOT NULL PRIMARY KEY REFERENCES periods(period_id), - config TEXT); - - INSERT INTO 'attributes_documentation' (name_table, attribute, description) VALUES('transit_graph_configs','period_id', 'The period this config is associated with.'); - INSERT INTO 'attributes_documentation' (name_table, attribute, description) VALUES('transit_graph_configs','mode_id', 'JSON string containing the configuration parameters.'); diff --git a/docs/source/modeling_with_aequilibrae/aequilibrae_project/project_database/data_model/zones.rst b/docs/source/modeling_with_aequilibrae/aequilibrae_project/project_database/data_model/zones.rst deleted file mode 100644 index 34d6d0393..000000000 --- a/docs/source/modeling_with_aequilibrae/aequilibrae_project/project_database/data_model/zones.rst +++ /dev/null @@ -1,46 +0,0 @@ -*zones* table structure ------------------------ - -The *zones* table holds information on the Traffic Analysis Zones (TAZs) -in AequilibraE's model. - -The **zone_id** field identifies the zone. - -The **area** field corresponds to the area of the zone in **km2**. -TAZs' area is automatically updated by triggers. - -The **name** fields allows one to identity the zone using a name -or any other description. - -.. csv-table:: - :header: "Field", "Type", "NULL allowed", "Default Value" - :widths: 30, 20, 20, 20 - - ogc_fid*,INTEGER,YES, - zone_id,INTEGER,NO, - area,NUMERIC,YES, - name,TEXT,YES, - geometry,MULTIPOLYGON,NO,'' - - -(* - Primary key) - - - -The SQL statement for table and index creation is below. - - -:: - - - CREATE TABLE 'zones' (ogc_fid INTEGER PRIMARY KEY, - zone_id INTEGER UNIQUE NOT NULL, - area NUMERIC, - "name" TEXT); - - SELECT AddGeometryColumn( 'zones', 'geometry', 4326, 'MULTIPOLYGON', 'XY', 1); - CREATE UNIQUE INDEX idx_zone ON zones (zone_id); - SELECT CreateSpatialIndex( 'zones' , 'geometry' ); - INSERT INTO 'attributes_documentation' (name_table, attribute, description) VALUES('zones','zone_id', 'Unique node ID'); - INSERT INTO 'attributes_documentation' (name_table, attribute, description) VALUES('zones','area', 'Area of the zone in km2'); - INSERT INTO 'attributes_documentation' (name_table, attribute, description) VALUES('zones','name', 'Name of the zone, if any'); diff --git a/docs/source/modeling_with_aequilibrae/index.rst b/docs/source/modeling_with_aequilibrae/index.rst index 2b21d2a4d..f57d77dd3 100644 --- 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 \ No newline at end of file diff --git a/docs/source/modeling_with_aequilibrae/aequilibrae_project/parameter_file.rst b/docs/source/modeling_with_aequilibrae/parameter_file.rst similarity index 95% rename from docs/source/modeling_with_aequilibrae/aequilibrae_project/parameter_file.rst rename to docs/source/modeling_with_aequilibrae/parameter_file.rst index 82bd3b8e2..73b77669f 100644 --- a/docs/source/modeling_with_aequilibrae/aequilibrae_project/parameter_file.rst +++ b/docs/source/modeling_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 `_ . 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/docs/source/modeling_with_aequilibrae/aequilibrae_project/index.rst b/docs/source/modeling_with_aequilibrae/project.rst similarity index 90% rename from docs/source/modeling_with_aequilibrae/aequilibrae_project/index.rst rename to docs/source/modeling_with_aequilibrae/project.rst index 8d700aedc..d143d1721 100644 --- a/docs/source/modeling_with_aequilibrae/aequilibrae_project/index.rst +++ b/docs/source/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. \ No newline at end of file diff --git a/docs/source/modeling_with_aequilibrae/aequilibrae_project/project_database/about.rst b/docs/source/modeling_with_aequilibrae/project_database/about.rst similarity index 92% rename from docs/source/modeling_with_aequilibrae/aequilibrae_project/project_database/about.rst rename to docs/source/modeling_with_aequilibrae/project_database/about.rst index 5a2ee701e..9656f0e50 100644 --- a/docs/source/modeling_with_aequilibrae/aequilibrae_project/project_database/about.rst +++ b/docs/source/modeling_with_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 \ No newline at end of file diff --git a/docs/source/modeling_with_aequilibrae/aequilibrae_project/project_database/attributes_documentation.rst b/docs/source/modeling_with_aequilibrae/project_database/attributes_documentation.rst similarity index 84% rename from docs/source/modeling_with_aequilibrae/aequilibrae_project/project_database/attributes_documentation.rst rename to docs/source/modeling_with_aequilibrae/project_database/attributes_documentation.rst index 5ac56b796..8fb9327ff 100644 --- a/docs/source/modeling_with_aequilibrae/aequilibrae_project/project_database/attributes_documentation.rst +++ b/docs/source/modeling_with_aequilibrae/project_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 \ No newline at end of file diff --git a/docs/source/modeling_with_aequilibrae/aequilibrae_project/project_database/datamodel.rst.template b/docs/source/modeling_with_aequilibrae/project_database/datamodel.rst.template similarity index 98% rename from docs/source/modeling_with_aequilibrae/aequilibrae_project/project_database/datamodel.rst.template rename to docs/source/modeling_with_aequilibrae/project_database/datamodel.rst.template index 5cecdc360..b3980a814 100644 --- a/docs/source/modeling_with_aequilibrae/aequilibrae_project/project_database/datamodel.rst.template +++ b/docs/source/modeling_with_aequilibrae/project_database/datamodel.rst.template @@ -1,5 +1,3 @@ -:orphan: - .. _supply_data_model: SQL Data model diff --git a/docs/source/modeling_with_aequilibrae/aequilibrae_project/project_database/index.rst b/docs/source/modeling_with_aequilibrae/project_database/index.rst similarity index 57% rename from docs/source/modeling_with_aequilibrae/aequilibrae_project/project_database/index.rst rename to docs/source/modeling_with_aequilibrae/project_database/index.rst index c1036495a..6b64203b7 100644 --- a/docs/source/modeling_with_aequilibrae/aequilibrae_project/project_database/index.rst +++ b/docs/source/modeling_with_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 \ No newline at end of file + 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 \ No newline at end of file diff --git a/docs/source/modeling_with_aequilibrae/aequilibrae_project/project_database/link_types.rst b/docs/source/modeling_with_aequilibrae/project_database/link_types.rst similarity index 97% rename from docs/source/modeling_with_aequilibrae/aequilibrae_project/project_database/link_types.rst rename to docs/source/modeling_with_aequilibrae/project_database/link_types.rst index a86292f96..54c644421 100644 --- a/docs/source/modeling_with_aequilibrae/aequilibrae_project/project_database/link_types.rst +++ b/docs/source/modeling_with_aequilibrae/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 \ No newline at end of file diff --git a/docs/source/modeling_with_aequilibrae/aequilibrae_project/project_database/matrices.rst b/docs/source/modeling_with_aequilibrae/project_database/matrices.rst similarity index 85% rename from docs/source/modeling_with_aequilibrae/aequilibrae_project/project_database/matrices.rst rename to docs/source/modeling_with_aequilibrae/project_database/matrices.rst index 0a4b4f004..291b15748 100644 --- a/docs/source/modeling_with_aequilibrae/aequilibrae_project/project_database/matrices.rst +++ b/docs/source/modeling_with_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 \ No newline at end of file + :func:`aequilibrae.matrix.AequilibraeMatrix` \ No newline at end of file diff --git a/docs/source/modeling_with_aequilibrae/aequilibrae_project/project_database/modes.rst b/docs/source/modeling_with_aequilibrae/project_database/modes.rst similarity index 97% rename from docs/source/modeling_with_aequilibrae/aequilibrae_project/project_database/modes.rst rename to docs/source/modeling_with_aequilibrae/project_database/modes.rst index 1441a00a1..8ee7ffd43 100644 --- a/docs/source/modeling_with_aequilibrae/aequilibrae_project/project_database/modes.rst +++ b/docs/source/modeling_with_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 \ No newline at end of file diff --git a/docs/source/modeling_with_aequilibrae/aequilibrae_project/project_database/network.rst b/docs/source/modeling_with_aequilibrae/project_database/network.rst similarity index 95% rename from docs/source/modeling_with_aequilibrae/aequilibrae_project/project_database/network.rst rename to docs/source/modeling_with_aequilibrae/project_database/network.rst index d9cc69b84..94d4f4801 100644 --- a/docs/source/modeling_with_aequilibrae/aequilibrae_project/project_database/network.rst +++ b/docs/source/modeling_with_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 diff --git a/docs/source/modeling_with_aequilibrae/aequilibrae_project/project_database/network_geometry.rst b/docs/source/modeling_with_aequilibrae/project_database/network_geometry.rst similarity index 88% rename from docs/source/modeling_with_aequilibrae/aequilibrae_project/project_database/network_geometry.rst rename to docs/source/modeling_with_aequilibrae/project_database/network_geometry.rst index 8fe8f80fc..e1edf21aa 100644 --- a/docs/source/modeling_with_aequilibrae/aequilibrae_project/project_database/network_geometry.rst +++ b/docs/source/modeling_with_aequilibrae/project_database/network_geometry.rst @@ -69,6 +69,7 @@ can do to links and nodes, and you can use the table below to navigate between each of the changes to see how they are treated through triggers. .. table:: + :width: 60% :align: center +--------------------------------------+-----------------------------------+ @@ -151,26 +152,25 @@ Moving a node There are two possibilities for moving a node: Moving to an empty space, and moving on top of another node. -- If a node is moved to an empty space +- If a node is moved to an empty space - + all links originated/ending at that node will + have its shape altered to conform + to that new node position and keep the network connected. The alteration of the + link happens only by changing the Latitude and Longitude of the link extremity + associated with that node. - All links originated/ending at that node will have its shape altered to conform - to that new node position and keep the network connected. The alteration of the - link happens only by changing the Latitude and Longitude of the link extremity - associated with that node. - -- If a node is moved on top of another node - - All the links that connected to the node on the bottom have their extremities - switched to the node on top - The node on the bottom gets eliminated as a consequence of the behavior listed - on *Deleting a node* +- If a node is moved on top of another node - + All the links that connected to the node on the bottom have their extremities + switched to the node on top. + The node on the bottom gets eliminated as a consequence of the behavior listed + on *Deleting a node* Behavior regarding the fields related to modes and link types is discussed in their respective table descriptions. .. seealso:: - :ref:`Example - Editing network nodes ` + :ref:`Example - Editing network nodes ` Adding a data field +++++++++++++++++++ @@ -215,20 +215,17 @@ Moving a link extremity This change can happen in two different forms: -- The link extremity is moved to an empty space - - In this case, a new node needs to be created, according to the behavior - described in *Creating a node* . The information of node ID (A or B - node, depending on the extremity) needs to be updated according to the ID for - the new node created. - -- The link extremity is moved from one node to another - - The information of node ID (A or B node, depending on the extremity) needs to be - updated according to the ID for the node the link now terminates in. - - Behavior regarding the fields regarding modes and link types is discussed in - their respective table descriptions. +- The link extremity is moved to an empty space - + In this case, a new node needs to be created, according to the behavior + described in *Creating a node*. The information of node ID (A or B + node, depending on the extremity) needs to be updated according to the ID for + the new node created. + +- The link extremity is moved from one node to another - + The information of node ID (A or B node, depending on the extremity) needs to be + updated according to the ID for the node the link now terminates in. + Behavior regarding the fields regarding modes and link types is discussed in + their respective table descriptions. .. seealso:: diff --git a/docs/source/modeling_with_aequilibrae/aequilibrae_project/project_database/network_import_and_export.rst b/docs/source/modeling_with_aequilibrae/project_database/network_import_and_export.rst similarity index 97% rename from docs/source/modeling_with_aequilibrae/aequilibrae_project/project_database/network_import_and_export.rst rename to docs/source/modeling_with_aequilibrae/project_database/network_import_and_export.rst index e393151b9..5d227e0d4 100644 --- a/docs/source/modeling_with_aequilibrae/aequilibrae_project/project_database/network_import_and_export.rst +++ b/docs/source/modeling_with_aequilibrae/project_database/network_import_and_export.rst @@ -49,7 +49,7 @@ layers to the canvas, and selecting properties and clicking on *create spatial* *index* for each layer at a time. This action automatically saves the spatial indices to the sqlite database. -.. image:: ../../../images/qgis_creating_spatial_indices.png +.. image:: ../../images/qgis_creating_spatial_indices.png :align: center :alt: Adding Spatial indices with QGIS @@ -97,7 +97,7 @@ Before importing a network from a source in GMNS format, it is imperative to kno in which spatial reference its geometries (links and nodes) were created. If the SRID is different than 4326, it must be passed as an input using the argument 'srid'. -.. image:: ../../../images/plot_import_from_gmns.png +.. image:: ../../images/plot_import_from_gmns.png :align: center :alt: example :target: ../../../_auto_examples/plot_import_from_gmns.html @@ -141,7 +141,7 @@ Exporting AequilibraE model to GMNS format After loading an existing AequilibraE project, you can export it to GMNS format. -.. image:: ../../../images/plot_export_to_gmns.png +.. image:: ../../images/plot_export_to_gmns.png :align: center :alt: example :target: export_to_gmns diff --git a/docs/source/modeling_with_aequilibrae/aequilibrae_project/project_database/periods.rst b/docs/source/modeling_with_aequilibrae/project_database/periods.rst similarity index 74% rename from docs/source/modeling_with_aequilibrae/aequilibrae_project/project_database/periods.rst rename to docs/source/modeling_with_aequilibrae/project_database/periods.rst index 082ae8d8d..fe688c3cd 100644 --- a/docs/source/modeling_with_aequilibrae/aequilibrae_project/project_database/periods.rst +++ b/docs/source/modeling_with_aequilibrae/project_database/periods.rst @@ -6,6 +6,3 @@ Periods table .. seealso:: * :func:`aequilibrae.project.network.Periods` - -.. include:: data_model/periods.rst - diff --git a/docs/source/modeling_with_aequilibrae/aequilibrae_project/results_database.rst b/docs/source/modeling_with_aequilibrae/project_database/results.rst similarity index 92% rename from docs/source/modeling_with_aequilibrae/aequilibrae_project/results_database.rst rename to docs/source/modeling_with_aequilibrae/project_database/results.rst index 5d70b28f3..d1e933b5f 100644 --- a/docs/source/modeling_with_aequilibrae/aequilibrae_project/results_database.rst +++ b/docs/source/modeling_with_aequilibrae/project_database/results.rst @@ -17,5 +17,3 @@ As a simple table, it looks as follows: .. image:: ../../images/results_table.png :align: center :alt: results table structure - -.. include:: project_database/data_model/results.rst \ No newline at end of file diff --git a/docs/source/modeling_with_aequilibrae/aequilibrae_project/project_database/transit_graph.rst b/docs/source/modeling_with_aequilibrae/project_database/transit_graph.rst similarity index 84% rename from docs/source/modeling_with_aequilibrae/aequilibrae_project/project_database/transit_graph.rst rename to docs/source/modeling_with_aequilibrae/project_database/transit_graph.rst index ea87d5248..00ed9e744 100644 --- a/docs/source/modeling_with_aequilibrae/aequilibrae_project/project_database/transit_graph.rst +++ b/docs/source/modeling_with_aequilibrae/project_database/transit_graph.rst @@ -7,5 +7,3 @@ The 'transit_graph_configs' table holds information on the configuration paramet .. seealso:: * :func:`aequilibtae.transit.TransitGraphBuilder` - -.. include:: data_model/transit_graph_configs.rst \ No newline at end of file diff --git a/docs/source/modeling_with_aequilibrae/aequilibrae_project/project_database/zones.rst b/docs/source/modeling_with_aequilibrae/project_database/zones.rst similarity index 89% rename from docs/source/modeling_with_aequilibrae/aequilibrae_project/project_database/zones.rst rename to docs/source/modeling_with_aequilibrae/project_database/zones.rst index 5849c7d01..d6d24e7aa 100644 --- a/docs/source/modeling_with_aequilibrae/aequilibrae_project/project_database/zones.rst +++ b/docs/source/modeling_with_aequilibrae/project_database/zones.rst @@ -17,6 +17,4 @@ You can check :ref:`this example ` to learn how to add zones to yo .. seealso:: - :func:`aequilibrae.project.Zone` - -.. include:: data_model/zones.rst \ No newline at end of file + :func:`aequilibrae.project.Zone` \ No newline at end of file diff --git a/docs/source/modeling_with_aequilibrae/accessing_project_data.rst b/docs/source/modeling_with_aequilibrae/project_pieces/accessing_project_data.rst similarity index 99% rename from docs/source/modeling_with_aequilibrae/accessing_project_data.rst rename to docs/source/modeling_with_aequilibrae/project_pieces/accessing_project_data.rst index 6e9948b4a..32424063f 100644 --- a/docs/source/modeling_with_aequilibrae/accessing_project_data.rst +++ b/docs/source/modeling_with_aequilibrae/project_pieces/accessing_project_data.rst @@ -13,12 +13,15 @@ cover the main points regarding them. This method allows you to access the API resources to manipulate the 'links' table. Each item in the 'links' table is a ``Link`` object. +.. testsetup:: * + + >>> folder = getfixture("create_path") + .. code-block:: python >>> from shapely.geometry import LineString >>> from aequilibrae.utils.create_example import create_example - >>> folder = getfixture("create_path") >>> project = create_example(folder, "coquimbo") >>> project_links = project.network.links diff --git a/docs/source/modeling_with_aequilibrae/aequilibrae_matrix.rst b/docs/source/modeling_with_aequilibrae/project_pieces/aequilibrae_matrix.rst similarity index 99% rename from docs/source/modeling_with_aequilibrae/aequilibrae_matrix.rst rename to docs/source/modeling_with_aequilibrae/project_pieces/aequilibrae_matrix.rst index 703e89a1d..e55b1e5f5 100644 --- a/docs/source/modeling_with_aequilibrae/aequilibrae_matrix.rst +++ b/docs/source/modeling_with_aequilibrae/project_pieces/aequilibrae_matrix.rst @@ -18,7 +18,7 @@ There are three ways of creating an ``AequilibraeMatrix``: * from a trip list, which is nothing more than a CSV file containing the origins, destinations, and trip cores; * from an empty matrix. In this case, the data type must be one of the following NumPy data types: ``np.int32``, ``np.int64``, ``np.float32``, ``np.float64``. - + .. code-block:: python >>> import numpy as np diff --git a/docs/source/modeling_with_aequilibrae/project_pieces/index.rst b/docs/source/modeling_with_aequilibrae/project_pieces/index.rst new file mode 100644 index 000000000..33afb45b4 --- /dev/null +++ b/docs/source/modeling_with_aequilibrae/project_pieces/index.rst @@ -0,0 +1,11 @@ +Components of an AequilibraE Project +==================================== + +In this section, we present the main modules related to adding data to an AequilibraE project. + +.. toctree:: + :maxdepth: 1 + + project_components + accessing_project_data + aequilibrae_matrix \ No newline at end of file diff --git a/docs/source/modeling_with_aequilibrae/project_components.rst b/docs/source/modeling_with_aequilibrae/project_pieces/project_components.rst similarity index 99% rename from docs/source/modeling_with_aequilibrae/project_components.rst rename to docs/source/modeling_with_aequilibrae/project_pieces/project_components.rst index 5051c8347..b48aa61e8 100644 --- a/docs/source/modeling_with_aequilibrae/project_components.rst +++ b/docs/source/modeling_with_aequilibrae/project_pieces/project_components.rst @@ -1,7 +1,7 @@ .. _project_components: -Project Components -================== +Data Components +======================= In the :ref:`aeq_project_structure` section, we present the main file components and folders that consists an AequilibraE project. We also present in :ref:`aeq_project_database_tables` all tables @@ -25,7 +25,7 @@ object with similar name that corresponds to one object in the class. Thus ``pro enables the access to manipulate the 'links' table, and each item in the items table is a ``Link`` object. -.. image:: ../images/project_components_and_items.png +.. image:: ../../images/project_components_and_items.png :align: center :alt: basics on project components diff --git a/docs/source/modeling_with_aequilibrae/aequilibrae_project/transit_database/datamodel.rst.template b/docs/source/modeling_with_aequilibrae/transit_database/datamodel.rst.template similarity index 98% rename from docs/source/modeling_with_aequilibrae/aequilibrae_project/transit_database/datamodel.rst.template rename to docs/source/modeling_with_aequilibrae/transit_database/datamodel.rst.template index 2ebd72b2c..d732d4b0a 100644 --- a/docs/source/modeling_with_aequilibrae/aequilibrae_project/transit_database/datamodel.rst.template +++ b/docs/source/modeling_with_aequilibrae/transit_database/datamodel.rst.template @@ -1,5 +1,3 @@ -:orphan: - .. _transit_supply_data_model: SQL Data model diff --git a/docs/source/modeling_with_aequilibrae/aequilibrae_project/transit_database/index.rst b/docs/source/modeling_with_aequilibrae/transit_database/index.rst similarity index 59% rename from docs/source/modeling_with_aequilibrae/aequilibrae_project/transit_database/index.rst rename to docs/source/modeling_with_aequilibrae/transit_database/index.rst index 1b73cfaa4..fd28dccbd 100644 --- a/docs/source/modeling_with_aequilibrae/aequilibrae_project/transit_database/index.rst +++ b/docs/source/modeling_with_aequilibrae/transit_database/index.rst @@ -23,40 +23,8 @@ In the following sections, we'll dive deep into the tables existing in the publi Please notice that some tables are homonyms to the ones existing in the **project_database.sqlite**, but its contents are related to the public transport graph building and assignment processes. -.. include:: data_model/agencies.rst +.. toctree:: + :caption: Get to know the data structures in public transport database! + :maxdepth: 1 -.. include:: data_model/attributes_documentation.rst - -.. include:: data_model/fare_attributes.rst - -.. include:: data_model/fare_rules.rst - -.. include:: data_model/fare_zones.rst - -.. include:: data_model/link_types.rst - -.. include:: data_model/links.rst - -.. include:: data_model/modes.rst - -.. include:: data_model/node_types.rst - -.. include:: data_model/nodes.rst - -.. include:: data_model/pattern_mapping.rst - -.. include:: data_model/results.rst - -.. include:: data_model/route_links.rst - -.. include:: data_model/routes.rst - -.. include:: data_model/stop_connectors.rst - -.. include:: data_model/stops.rst - -.. include:: data_model/trigger_settings.rst - -.. include:: data_model/trips_schedule.rst - -.. include:: data_model/trips.rst + data_model/datamodel.rst \ No newline at end of file diff --git a/docs/table_documentation.py b/docs/table_documentation.py index 6d23c8310..c16dbef5d 100644 --- a/docs/table_documentation.py +++ b/docs/table_documentation.py @@ -30,13 +30,7 @@ def __init__(self, component: str, tgt_fldr: str): self.path = join( *Path(realpath(__file__)).parts[:-1], f"../aequilibrae/project/database_specification/{folder}/tables" ) - self.doc_path = str( - Path(realpath(__file__)).parent - / "source" - / "modeling_with_aequilibrae" - / "aequilibrae_project" - / tgt_fldr - ) + self.doc_path = str(Path(realpath(__file__)).parent / "source" / "modeling_with_aequilibrae" / tgt_fldr) Path(join(self.doc_path, self.stub)).mkdir(exist_ok=True, parents=True) @@ -51,11 +45,8 @@ def create(self): descr = self.conn.execute(f"pragma table_info({table_name})").fetchall() # Title of the page - title = f"*{table_name}* table structure" - txt = [title, "-" * len(title), ""] - - # intro = """A more technical view of the database structure, including the SQL queries used to create each table and the indices used are displayed below.\n""" - # txt.append(intro) + title = f'**{table_name.replace("_", " ")}** table structure' + txt = [title, "=" * len(title), ""] docstrings = self.__get_docstrings(table_name) sql_code = self.__get_sql_code(table_name) @@ -134,10 +125,7 @@ def readlines(filename): return [x.strip() for x in f.readlines()] -tables = [ - ("project_database", "project_database"), - ("transit_database", "transit_database"), -] +tables = [("project_database", "project_database"), ("transit_database", "transit_database")] for table, pth in tables: s = CreateTablesSRC(table, pth)