Network-wrangler

Network Wrangler 2.1 Summary:
- supports groups of projects, or _plans_
- supports co-requisites, pre-requisites, and conflicts
- tighter and more flexible version-compatibility controls
- more enforced documentation

**1. Expand the Types to include project, plan, and seed.**
- _Projects_: code representations of changes to a `hwy` or `trn` network. Similar to projects in older versions of wrangler, with updates described below.
- _Plans_: collection of projects and/or other plans. Specified by a file called `planSpecs.csv` with two columns: the first indicates the `path/name` of the project, and the second indicates the Type.
- _Seed_: the baseline starting point for a network. They are similar to projects but are meant to be applied first.

**2. Upgrade 'project', 'plan', and 'seed' definition requirements to force more documentation**
Every 'project', 'plan', and 'seed' is expected to have an `__init__.py` file with functions to return standard information.
- `champVersion`: This now returns a tuple of the earliest and latest versions of CHAMP this project is compatible with. This is no longer stored in `champVersion.txt` for `hwy` projects.
- `wranglerVersion`: A new function that returns a tuple of the earliest and latest versions of NetworkWrangler the a project is compatible with
- `desc`: Returns a description of the project. This is no longer stored in `desc.txt` for hwy projects.
- `year`: Returns the opening year of a project, or the model year if the `modelyear` keyword argument is supplied.
- `networks`: A new function that returns a list of the network types that the project applies to. This is used by plans so projects listed in the plan are added to the correct networks.
- `prereqs`: Returns a list of projects which must be applied before this project.
- `coreqs`: Returns a list of projects which should be applied with this project (order doesn't matter though).
- `conflicts`: Returns a list of projects which are known to cause errors when applied with this project.
- `apply`, `applyFiles`, and `applyEdits`: Used the same as before, but we recommend using with a `modelyear` argument to specify the opening year of a project.

**3. Update `build_network.py` to support plans and enforce version requirements and corequisites, prerequisites, and conflicts - and checks for potential errors *in the begining***
- For each 'plan' in each network's project list, the script adds its projects, seeds, and other plans. These are all checked out prior to beginning to build any network.
- For each 'project' in each network's project list (including projects contained within plans), the script checks the project list for prereqs, coreqs, and conflicts, and prompts the user for review and approval before continuing.
- All projects (including projects contained within plans) are cloned and checked out prior to building any network. Only after checking out all projects and checking wranglerVersion, champVersion, prereqs, coreqs, and conflicts are networks built.

Released concurrently with SF-CHAMP 5

What's Changed

🚀 Features

- Adds script and notebook for creating your own example data from OSM

🏗️ Refactor

- Moves all roadway selection logic from the data models to selection classes

📘 Docs

- Pull network docs from network data models instead of writing anew
- Add in all relevant API docs to `api.md`
- Improve general formatting and comprehensiveness of docs

⏱️ Performance

- Upgrades performance of selection when selecting by a dictionary of attributes: https://github.com/wsp-sag/network_wrangler/commit/c630b00033696503ffdaca4a3aba3dcd56abaa1b

📎 Examples

- Minimizes example data size

🐞 Bugs

- Fix scenario `write()`/`load()` (389)
- Downgrades error to warning for deleting roadways with transit so can apply changes (390)
- Adds back all geojson files which were accidentally added to `.gitignore`
- Fixes notebooks in `/notebook` to use current API
- Minor typos in logging
- Minor bugs in tests
- Fix error in shape links gdf creation and add tests for it to not happen again

🧹 Chores

- Tighten mypy and ruff settings and fix all violations
- Deletes extraneous file `validation_failure_cases.csv`
- rm old project cards that don't match current network
- Updates API for project cards to be consistent with project card v3.3.3

**Full Changelog**: https://github.com/wsp-sag/network_wrangler/compare/v1.0-alpha.2...v1.0-beta.2

Pre-release for metcouncil to test their workflows:
1. Make roadway project cards from log files.ipynb
2. Make transit project cards from log files.ipynb
3. createV01_standardnetwork.ipynb
4. CreateVer02_baseyear.ipynb

Contains almost all functionality for wrangler v1.0.

Remaining issues:

- [ ] 1. update `gtfs.stops` data model to use dual-primary key stop_id/trip_id
- [ ] 2. add a js lock-like file for conda: `environment.yml`
- [ ] 3. complete documentation
- [ ] 4. update notebooks
- [ ] 5. update st paul example data to latest data model

What's Changed

* Implicit and fast validation
* Speed , stability and memory efficiency
* Support for multiple serialization formats
* Updated network variable names and explicit data models
* Add ability to edit transit route shape
* Improved error checking/logging/verboseness
* I/O and Mutation Speed
* Selection flexibility for transit based on any feature or by link or node
* More flexible and fast transition to geodataframes and visualization for (almost) any data part
* Easy data clipping to geographic bounds
* Scripts for actions you might want to execute from command line (i.e. data conversion/clipping/etc)

Housekeeping

1. Separation of causes prevents circular reference collisions, limits import bloat, and improves legibility/organization.
- Project card functionality in project card repo
- Separate modules for separate functionality
2. Reliability achieved through more testable code and expanding test coverage with more test cases and also anti-patterns
- Testable code
- Test coverage
3. Explicit data models that make complex data structures obvious and easy to validate
- Legible
- Self-documenting
- Flexible
- Validatable
4. Clean code principles that make code easier to test and maintain
- more functions that do a single thing...and do it well
- classes that are small - functions that access or manipulate them
5. Documentation
- consistent and detailed functional documentation
- consistent type hints
- usage for modules and classes
- overall documentation leverages the flexible and less bloated MkDocs package
6. Removes less-well-maintained dependencies
- Replaces Partridge with internal functionality

New Contributors
* lmz made their first contribution in https://github.com/wsp-sag/network_wrangler/pull/281

**Full Changelog**: https://github.com/wsp-sag/network_wrangler/compare/v0.2.0-alpha...v1.0-alpha.1

Adds feature to allow network manipulation via a hybrid project card (i.e. `my_project.wrangler` or `project.wr`) which is formatted with YAML front-matter surrounded by bounding lines (i.e. `---`) followed by python code which acts as on the RoadwayNetwork instance. Category field must be Calculated Roadway. Lines which bound the YAML component must be identical.

Example file:

----
Category: Calculated Roadway
Project: My awesome roadway project to make
----

self.links_df.loc[self.links_df['lanes'] == 4, 'lanes'] = 12