Call for action - Help us improve our examples gallery

[Renata Imai]

Dear AequilibraE and QAequilibraE users,

We plan to add some extra examples in the Python package and QGIS plugin documentation. 

Are there any examples you would like to see in the documentation? Are we missing to present any features? What else would you like: YouTube tutorials, GIFs, more screenshots? 

Are the installation instructions clear? How can we improve them?

Let us know by replying to this message! It would be awesome to hear from you!

Cheers, Renata :)

[Justine Kojo]

Dear Renata,

Thank you for reaching out and seeking user feedback! I've been working on integrating local datasets into AequilibraE for transit assignment, and I have some specific suggestions that would greatly improve the documentation and user experience.

While the existing examples in the Python package documentation are valuable for understanding the fundamentals of AequilibraE, I've noticed a gap in examples that demonstrate how to create projects and perform analyses using local datasets.

For instance, the public transit traffic assignment examples (Public Transit Example) often utilize the pre-hosted datasets. It would be extremely beneficial to have examples that walk users through the process of:

• Creating a new AequilibraE project from scratch using the Python API.
• Integrating local network datasets such as the  using Sioux Falls data, from TNTP into that aequilibrae project.  This would include reading network data (links and nodes) from common formats (like CSV files or Pandas DataFrames), defining attributes, and handling geometry.
• Integrating local demand data into the project: Demonstrating how to read and format demand matrices from local sources into the project.
• Integrating geometry file into the project: Showing how to incorporate spatial data for nodes and links, potentially using libraries like Shapely and GeoPandas.

Many users, including myself, are looking to apply AequilibraE to real-world scenarios using data they have collected or obtained locally. Providing clear examples for this workflow would significantly lower the barrier to entry and make AequilibraE more accessible to a wider audience.

1. Examples Focused on Local Data Integration:

• Creating a Project from Scratch with Local Data: A clear, step-by-step example demonstrating how to create an AequilibraE project and populate it with data from common local formats like TNTP files. This should cover:
  • Creating a new project using the Python API.
  • Defining the coordinate reference system (CRS).
  • Creating nodes from a DataFrame with coordinates.
  • Creating links from a DataFrame referencing node IDs and including geometry creation (e.g., using Shapely).
  • Defining modes relevant to local data.
  • Optionally, loading basic zoning data from a DataFrame or shapefile.
• Handling Common Data Challenges: Examples that address potential issues encountered when using local data, such as:
  • Node IDs not matching between link and node tables.
  • Coordinate system transformations.
  • Dealing with missing or inconsistent data.
  • Mapping local data fields to AequilibraE's expected attributes (especially for links, nodes, and modes).

2. Comprehensive Documentation for Key Modules and Classes:

• aequilibrae.project.network Module: More detailed documentation on the Nodes and Links classes, including:
  • All available attributes for Node and Link objects with clear descriptions and data types.
  • Clear examples of how to set various attributes correctly.
  • Explanation of constraints, such as not being able to directly set link_id.
• aequilibrae.project.modes Module:
  • More examples on creating and managing modes, including how to define additional mode-specific parameters (if applicable).
• aequilibrae.project.zoning Module:
  • Examples of loading zoning data from shapefiles and DataFrames.
  • Explanation of how to create and manage zone centroids.
• aequilibrae.project.matrices Module:
  • Clear examples of creating and populating demand matrices from local data sources.

3. Enhanced Documentation Features:

• YouTube Tutorials: Short, focused video tutorials demonstrating key workflows like project creation, data loading, and basic network visualization would be extremely helpful for visual learners.

Thank you for your dedication to improving AequilibraE. Providing better documentation and examples focused on real-world data integration would significantly lower the barrier to entry for new users and make the library even more powerful.

Sincerely,

Justine Kojo

--
You received this message because you are subscribed to the Google Groups "AequilibraE" group.
To unsubscribe from this group and stop receiving emails from it, send an email to aequilibrae...@googlegroups.com.
To view this discussion visit https://groups.google.com/d/msgid/aequilibrae/578251f5-469a-4687-96ef-2f6f1c7d1dafn%40googlegroups.com.