Add YAML Configuration Documentation and Template

docs/design.md

@@ -193,7 +193,7 @@ For an interactive demonstration of what this means: `notebooks.Roadway Network
 | `errors.py` | User-facing errors. |
 | `logger.py` | Logging utilities and the WranglerLogger class. |
 | `models`| Pydantic and pandera data models and helper functions for them. |
-| `params.py` | Package-wide constants. |
+| `params.py` | Package-wide constants. **Not user-configurable.** Use `WranglerConfig` via YAML/TOML files for user-settable parameters. |
 | `roadway` | Classes and functions pertaining to read, write, analyzing and editing roadway networks. |
 | `scenario.py`| Scenario object class and helper functions. |
 | `time.py` | Time helper functions. |

docs/how_to.md

@@ -28,15 +28,107 @@
 
 ## Change Wrangler Configuration
 
-::: network_wrangler.configs.wrangler
-    options:
-        heading_level: 3
-    handlers:
-      python:
-        options:
-          show_root_toc_entry: false
+The easiest way to configure Network Wrangler parameters is using a YAML file. This is especially useful for users less familiar with Python, as you can simply point to a YAML file path rather than writing Python code.
+
+!!! warning "Configuration Best Practices"
+
+    **Always use YAML or TOML configuration files** for setting Wrangler parameters. Do not modify
+    `DefaultConfig` or other Python code to change configuration values. Using configuration files:
+
+    - Makes it easy to track and version control your settings
+    - Allows you to use different configurations for different projects
+    - Is more accessible for users less familiar with Python
+    - Prevents accidental global state changes
+    - Makes it clear which parameters you've customized
+
+### Step 1: Get the Configuration Template
+
+The configuration template contains all available parameters with default values and guidance on when to change them. All parameters are commented out by default, so you only uncomment what you need to customize.
+
+??? note "Configuration Template to Copy"
+    Click to expand and view the complete configuration template. You can copy this entire file to create your own `wrangler.config.yml`:
+
+    ```yaml
+    --8<-- "examples/wrangler.config.yml.template"
+    ```
+
+!!! tip "Configuration Template Details"
+    The template includes:
+    - **All available parameters** organized by category (ID Generation, Model Roadway, Edits, CPU)
+    - **Default values** shown in comments for easy reference
+    - **When to change** guidance explaining common use cases for each parameter
+    - **Examples** showing proper formatting and typical values
+
+    You only need to uncomment and modify parameters that differ from defaults. All other parameters will use their default values automatically.
+
+### Step 2: Customize Your Configuration
+
+Open your `wrangler.config.yml` file and uncomment only the parameters you want to change from their defaults. All other parameters will use their default values automatically.
+
+!!! example "Example: Customizing Configuration"
+
+    ```yaml
+    # Only uncomment what you need to customize
+    MODEL_ROADWAY:
+      # Change managed lane offset if using different lane widths
+      ML_OFFSET_METERS: -12  # 12-foot lanes instead of default 10-foot
+
+    EDITS:
+      # Use strict validation for production runs
+      EXISTING_VALUE_CONFLICT: error
+    ```
+
+### Step 3: Load Your Configuration
+
+!!! example "Loading Configuration from YAML File"
+    ```python
+    from network_wrangler.configs import load_wrangler_config
+
+    # Load configuration from YAML file
+    config = load_wrangler_config("wrangler.config.yml")
+    ```
+
+??? danger "Edit an Existing Configuration in Python"
+    You can also modify an existing configuration programmatically, including the default configuration:
+
+    ```python
+    from network_wrangler.configs import DefaultConfig
+
+    config = DefaultConfig()
+
+    config.MODEL_ROADWAY.ML_OFFSET_METERS = -12
+    config.EDITS.EXISTING_VALUE_CONFLICT = "error"
+    ```
+
+    **NOTE** this is less traceable than storing your configurations in config files and should be used with caution.
+
+### Step 4: Use Your Configuration
+
+When loading networks or creating scenarios, pass your configuration using the `config=` parameter. If you don't provide a `config=` parameter, Network Wrangler will use the default configuration values.
+
+!!! example "Using Configurations"
+    ```python
+    from network_wrangler.scenario import create_scenario, create_base_scenario
+    from network_wrangler import load_roadway_from_dir
+
+    base_scenario = create_base_scenario(
+        roadway={"dir": "path/to/roadway"},
+        config=config  # Without this, defaults will be used
+    )
+
+    my_scenario = create_scenario(
+        base_scenario=base_scenario,
+        config=config  # Without this, defaults will be used
+    )
+
+    # Use the configuration when loading networks
+    road_net = load_roadway_from_dir(
+        "path/to/roadway",
+        config=config  # Without this, defaults will be used
+    )
+    ```
 
-## Review changes beetween networks
+## Review changes between networks
 
 !!! example "Review Added Managed Lanes"
 

examples/stpaul/wrangler.config.yml

@@ -0,0 +1,64 @@
+# Wrangler Configuration File
+# This file allows you to configure Network Wrangler parameters without writing Python code.
+# You can use this file by passing its path to load_wrangler_config() or by referencing it
+# in a scenario configuration file.
+
+# ID Generation Parameters
+# These control how new IDs are generated for various network elements
+IDS:
+  # Method for creating shape_id for transit shapes
+  TRANSIT_SHAPE_ID_METHOD: scalar
+  # Scalar value to add to general purpose lane to create a shape_id for a transit shape
+  TRANSIT_SHAPE_ID_SCALAR: 1000000
+
+  # Method for creating shape_id for roadway shapes
+  ROAD_SHAPE_ID_METHOD: scalar
+  # Scalar value to add to general purpose lane to create a shape_id for a roadway shape
+  ROAD_SHAPE_ID_SCALAR: 1000
+
+  # Method for creating model_link_id for managed lane links
+  # Options: "range" or "scalar"
+  ML_LINK_ID_METHOD: scalar
+  # Range of model_link_ids to use when creating managed lane links (if using range method)
+  ML_LINK_ID_RANGE: [950000, 999999]
+  # Scalar value to add to general purpose lane to create model_link_id (if using scalar method)
+  ML_LINK_ID_SCALAR: 3000000
+
+  # Method for creating model_node_id for managed lane nodes
+  # Options: "range" or "scalar"
+  ML_NODE_ID_METHOD: range
+  # Range of model_node_ids to use when creating managed lane nodes (if using range method)
+  ML_NODE_ID_RANGE: [950000, 999999]
+  # Scalar value to add to general purpose lane node to create model_node_id (if using scalar method)
+  ML_NODE_ID_SCALAR: 15000
+
+# Model Roadway Parameters
+# These control how the model roadway network is created
+MODEL_ROADWAY:
+  # Offset in meters for managed lanes (negative values offset to the right)
+  ML_OFFSET_METERS: -10
+  # Additional fields to copy from general purpose lanes to managed lanes
+  ADDITIONAL_COPY_FROM_GP_TO_ML: []
+  # Additional fields to copy to access and egress links
+  ADDITIONAL_COPY_TO_ACCESS_EGRESS: []
+
+# Edit Handling Parameters
+# These control how conflicts and existing values are handled during edits
+EDITS:
+  # How to handle conflicts when 'existing' value in project card doesn't match network value
+  # Options: "warn", "error", or "skip"
+  EXISTING_VALUE_CONFLICT: warn
+  # How to handle conflicts with existing scoped values
+  # Options: "conflicting", "all", or "error"
+  OVERWRITE_SCOPED: conflicting
+
+# CPU Performance Parameters
+# These are used for performance estimation and do not change network outcomes
+CPU:
+  # Estimated read speed in seconds per MB for different file formats
+  EST_PD_READ_SPEED:
+    csv: 0.03
+    parquet: 0.005
+    geojson: 0.03
+    json: 0.15
+    txt: 0.04

examples/wrangler.config.yml.template

@@ -0,0 +1,185 @@
+# Network Wrangler Configuration Template
+# ======================================
+# 
+# This template contains all available configuration parameters with their default values.
+# To use this file:
+#   1. Copy this file to your project directory (e.g., `wrangler.config.yml`)
+#   2. Uncomment and modify only the parameters you want to change from defaults
+#   3. Reference this file when loading networks or creating scenarios
+#
+# All parameters are commented out by default. Uncomment only what you need to customize.
+# Default values are shown in comments for reference.
+
+# ==============================================================================
+# ID GENERATION PARAMETERS
+# ==============================================================================
+# These parameters control how Network Wrangler generates new IDs for various
+# network elements (shapes, managed lane links/nodes, etc.).
+#
+# When to customize:
+#   - If your network uses a specific ID numbering scheme
+#   - If you need to avoid ID conflicts with existing network elements
+#   - If you're integrating with external systems that require specific ID ranges
+
+IDS:
+  # Method for creating shape_id for transit shapes
+  # Options: "scalar" (only option currently)
+  # Default: "scalar"
+  # When to change: Rarely needed - scalar method is standard
+  # TRANSIT_SHAPE_ID_METHOD: scalar
+
+  # Scalar value to add to general purpose lane link_id to create a shape_id for transit shapes
+  # Default: 1000000
+  # When to change: If you need transit shape IDs in a different range to avoid conflicts
+  # TRANSIT_SHAPE_ID_SCALAR: 1000000
+
+  # Method for creating shape_id for roadway shapes
+  # Options: "scalar" (only option currently)
+  # Default: "scalar"
+  # When to change: Rarely needed - scalar method is standard
+  # ROAD_SHAPE_ID_METHOD: scalar
+
+  # Scalar value to add to general purpose lane link_id to create a shape_id for roadway shapes
+  # Default: 1000
+  # When to change: If you need roadway shape IDs in a different range to avoid conflicts
+  # ROAD_SHAPE_ID_SCALAR: 1000
+
+  # Method for creating model_link_id for managed lane links
+  # Options: "range" or "scalar"
+  # Default: "scalar"
+  # When to change:
+  #   - Use "range" if you want managed lane IDs in a specific reserved range (e.g., 950000-999999)
+  #   - Use "scalar" if you want IDs calculated by adding a value to the GP lane ID
+  # ML_LINK_ID_METHOD: scalar
+
+  # Range of model_link_ids to use when creating managed lane links (only used if ML_LINK_ID_METHOD is "range")
+  # Format: [min, max] as a list
+  # Default: [950000, 999999]
+  # When to change: If using range method and need a different reserved ID range
+  # ML_LINK_ID_RANGE: [950000, 999999]
+
+  # Scalar value to add to general purpose lane link_id to create model_link_id for managed lanes
+  # (only used if ML_LINK_ID_METHOD is "scalar")
+  # Default: 3000000
+  # When to change: If using scalar method and need a different offset to avoid ID conflicts
+  # ML_LINK_ID_SCALAR: 3000000
+
+  # Method for creating model_node_id for managed lane nodes
+  # Options: "range" or "scalar"
+  # Default: "range"
+  # When to change:
+  #   - Use "range" if you want managed lane node IDs in a specific reserved range (e.g., 950000-999999)
+  #   - Use "scalar" if you want IDs calculated by adding a value to the GP node ID
+  # ML_NODE_ID_METHOD: range
+
+  # Range of model_node_ids to use when creating managed lane nodes (only used if ML_NODE_ID_METHOD is "range")
+  # Format: [min, max] as a list
+  # Default: [950000, 999999]
+  # When to change: If using range method and need a different reserved ID range
+  # ML_NODE_ID_RANGE: [950000, 999999]
+
+  # Scalar value to add to general purpose lane node_id to create model_node_id for managed lanes
+  # (only used if ML_NODE_ID_METHOD is "scalar")
+  # Default: 15000
+  # When to change: If using scalar method and need a different offset to avoid ID conflicts
+  # ML_NODE_ID_SCALAR: 15000
+
+# ==============================================================================
+# MODEL ROADWAY PARAMETERS
+# ==============================================================================
+# These parameters control how the model roadway network is created from the
+# base roadway network, particularly for managed lanes.
+#
+# When to customize:
+#   - If your managed lanes need different geometric offsets
+#   - If you need to copy additional fields between GP and ML lanes
+#   - If you're working with specialized network data structures
+
+MODEL_ROADWAY:
+  # Offset in meters for managed lanes relative to general purpose lanes
+  # Negative values offset to the right (typical for US roadways)
+  # Positive values offset to the left
+  # Default: -10
+  # When to change:
+  #   - If your managed lanes are a different width (e.g., -12 for 12-foot lanes)
+  #   - If you're modeling left-side managed lanes (use positive value)
+  #   - If you need to match specific geometric standards
+  # ML_OFFSET_METERS: -10
+
+  # Additional fields to copy from general purpose lanes to managed lanes
+  # Format: list of field names as strings
+  # Default: [] (empty list)
+  # When to change:
+  #   - If you have custom fields on GP lanes that should also appear on ML lanes
+  #   - If you're preserving metadata or attributes during managed lane creation
+  # Example: ["custom_field", "another_field"]
+  # ADDITIONAL_COPY_FROM_GP_TO_ML: []
+
+  # Additional fields to copy to access and egress links
+  # Format: list of field names as strings
+  # Default: [] (empty list)
+  # When to change:
+  #   - If you have custom fields that should be propagated to access/egress links
+  #   - If you need to maintain specific attributes on connector links
+  # Example: ["custom_field", "another_field"]
+  # ADDITIONAL_COPY_TO_ACCESS_EGRESS: []
+
+# ==============================================================================
+# EDIT HANDLING PARAMETERS
+# ==============================================================================
+# These parameters control how Network Wrangler handles conflicts and existing
+# values when applying project cards and edits.
+#
+# When to customize:
+#   - If you need stricter validation (use "error" instead of "warn")
+#   - If you're doing bulk edits and want to overwrite all scoped values
+#   - If you want to skip conflicts silently during automated processing
+
+EDITS:
+  # How to handle conflicts when 'existing' value in project card doesn't match network value
+  # Options: "warn", "error", or "skip"
+  # Default: "warn"
+  # When to change:
+  #   - Use "error" for strict validation - will stop processing if values don't match
+  #   - Use "skip" for automated processing - will silently skip mismatched properties
+  #   - Use "warn" (default) for interactive work - will warn but continue processing
+  # Note: Can be overridden per-project in project card with `existing_value_conflict` field
+  # EXISTING_VALUE_CONFLICT: warn
+
+  # How to handle conflicts with existing scoped (time-based) property values
+  # Options: "conflicting", "all", or "error"
+  # Default: "conflicting"
+  # When to change:
+  #   - Use "all" if you want to completely replace all scoped values (useful for bulk updates)
+  #   - Use "error" for strict validation - will stop if any scope overlap exists
+  #   - Use "conflicting" (default) to only overwrite values where scopes partially overlap
+  # Note: Can be overridden per-project in project card with `overwrite_scoped` field
+  # OVERWRITE_SCOPED: conflicting
+
+# ==============================================================================
+# CPU PERFORMANCE PARAMETERS
+# ==============================================================================
+# These parameters are used for performance estimation and do NOT affect network
+# outcomes or results. They help Network Wrangler estimate processing times.
+#
+# When to customize:
+#   - If you're running on significantly faster/slower hardware
+#   - If you want more accurate time estimates for your specific system
+#   - Generally not needed unless you're doing performance analysis
+
+CPU:
+  # Estimated read speed in seconds per MB for different file formats
+  # These values are used for progress estimation only
+  # Format: dictionary with file format as key and seconds/MB as value
+  # Default values shown below
+  # When to change:
+  #   - If you have measured different read speeds on your system
+  #   - If you're using different storage (SSD vs HDD, network storage, etc.)
+  #   - Generally not necessary unless doing performance tuning
+  # EST_PD_READ_SPEED:
+  #   csv: 0.03
+  #   parquet: 0.005
+  #   geojson: 0.03
+  #   json: 0.15
+  #   txt: 0.04
+