Starting Out

Installation

If you are managing multiple python versions, we suggest using virtualenv or conda virtual environments.

Example using a conda environment (recommended) and using the package manager pip to install Lasso from the source on GitHub.

conda config --add channels conda-forge
conda create python=3.7 rtree geopandas -n <my_lasso_environment>
conda activate <my_lasso_environment>
pip install git+https://github.com/wsp-sag/Lasso@master

Lasso will install network_wrangler from the PyPi repository because it is included in Lasso’s requirements.txt.

Bleeding Edge

If you want to install a more up-to-date or development version of network wrangler and lasso , you can do so by installing it from the develop branch of

conda config --add channels conda-forge
conda create python=3.7 rtree geopandas -n <my_lasso_environment>
conda activate <my_lasso_environment>
pip install git+https://github.com/wsp-sag/network_wrangler@develop
pip install git+https://github.com/wsp-sag/Lasso@develop

From Clone

If you are going to be working on Lasso locally, you might want to clone it to your local machine and install it from the clone. The -e will install it in editable mode.

if you plan to do development on both network wrangler and lasso locally, consider installing network wrangler from a clone as well!

conda config --add channels conda-forge
conda create python=3.7 rtree geopandas osmnx -n <my_lasso_environment>
conda activate <my_lasso_environment>
git clone https://github.com/wsp-sag/Lasso
git clone https://github.com/wsp-sag/network_wrangler
cd network_wrangler
pip install -e .
cd ..
cd Lasso
pip install -e .

Notes:

The -e installs it in editable mode.
If you are not part of the project team and want to contribute code bxack to the project, please fork before you clone and then add the original repository to your upstream origin list per these directions on github.
if you wanted to install from a specific tag/version number or branch, replace @master with @<branchname> or @tag
If you want to make use of frequent developer updates for network wrangler as well, you can also install it from clone by copying the instructions for cloning and installing Lasso for Network Wrangler

If you are going to be doing Lasso development, we also recommend:

a good IDE such as Atom, VS Code, Sublime Text, etc. with Python syntax highlighting turned on.
GitHub Desktop to locally update your clones

Brief Intro

Lasso is a ‘wrapper’ around the Network Wrangler utility.

Both Lasso and NetworkWrangler are built around the following data schemas:

[roadway network], which is based on a mashup of Open Street Map and Shared Streets. In Network Wrangler these are read in from three json files reprsenting: links, shapes, and nodes. Data fields that change by time of day or by user category are represented as nested fields such that any field can be defined for an ad-hoc time-of-day span or user category.
[transit network], which is based on a frequency-based implementation of the csv-based GTFS; and
[project card], which is novel to Network Wrangler and stores information about network changes as a result of projects in yml.

In addition, Lasso utilizes the following data schemas:

[MetCouncil Model Roadway Network Schema], which adds data fields to the roadway network schema that MetCouncil uses in their travel model including breaking out data fields by time period.
[MetCouncil Model Transit Network Schema], which uses the Cube PublicTransport format, and
[Cube Log Files], which document changes to the roadway network done in the Cube GUI. Lasso translates these to project cards in order to be used by NetworkWrangler.
[Cube public transport line files], which define a set of transit lines in the cube software.

Components

Network Wrangler has the following atomic parts:

RoadwayNetwork object, which represents the roadway network data as GeoDataFrames;
TransitNetwork object, which represents the transit network data as DataFrames;
ProjectCard object, which represents the data of the project card. Project cards identify the infrastructure that is changing (a selection) and defines the changes; or contains information about a new facility to be constructed or a new service to be run.;
Scenario object, which consist of at least a RoadwayNetwork, and TransitNetwork. Scenarios can be based on or tiered from other scenarios. Scenarios can query and add ProjectCards to describe a set of changes that should be made to the network.

In addition, Lasso has the following atomic parts:

Project object, creates project cards from one of the following: a base and a build transit network in cube format, a base and build highway network, or a base highway network and a Cube log file.
ModelRoadwayNetwork object is a subclass of RoadwayNetwork and contains MetCouncil-specific methods to define and create MetCouncil-specific variables and export the network to a format that can be read by Cube.
StandardTransit, an object for holding a standard transit feed as a Partridge object and contains methods to manipulate and translate the GTFS data to MetCouncil’s Cube Line files.
CubeTransit, an object for storing information about transit defined in Cube public transport line files . Has the capability to parse cube line file properties and shapes into python dictionaries and compare line files and represent changes as Project Card dictionaries.
Parameters, A class representing all the parameters defining the networks including time of day, categories, etc. Parameters can be set at runtime by initializing a parameters instance with a keyword argument setting the attribute. Parameters that are not explicitly set will use default parameters listed in this class.

RoadwayNetwork

Reads, writes, queries and and manipulates roadway network data, which is mainly stored in the GeoDataFrames links_df, nodes_df, and shapes_df.

net = RoadwayNetwork.read(
        link_filename=MY_LINK_FILE,
        node_filename=MY_NODE_FILE,
        shape_filename=MY_SHAPE_FILE,
        shape_foreign_key ='shape_id',
        
    )
my_selection = {
    "link": [{"name": ["I 35E"]}],
    "A": {"osm_node_id": "961117623"},  # start searching for segments at A
    "B": {"osm_node_id": "2564047368"},
}
net.select_roadway_features(my_selection)

my_change = [
    {
        'property': 'lanes',
        'existing': 1,
        'set': 2,
     },
     {
        'property': 'drive_access',
        'set': 0,
      },
]

my_net.apply_roadway_feature_change(
    my_net.select_roadway_features(my_selection),
    my_change
)

ml_net = net.create_managed_lane_network(in_place=False)

ml_net.is_network_connected(mode="drive"))

_, disconnected_nodes = ml_net.assess_connectivity(
  mode="walk",
  ignore_end_nodes=True
)
ml_net.write(filename=my_out_prefix, path=my_dir)

TransitNetwork

ProjectCard

Scenario

Manages sets of project cards and tiering from a base scenario/set of networks.

my_base_scenario = {
    "road_net": RoadwayNetwork.read(
        link_filename=STPAUL_LINK_FILE,
        node_filename=STPAUL_NODE_FILE,
        shape_filename=STPAUL_SHAPE_FILE,
        fast=True,
        shape_foreign_key ='shape_id',
    ),
    "transit_net": TransitNetwork.read(STPAUL_DIR),
}

card_filenames = [
    "3_multiple_roadway_attribute_change.yml",
    "multiple_changes.yml",
    "4_simple_managed_lane.yml",
]

project_card_directory = os.path.join(STPAUL_DIR, "project_cards")

project_cards_list = [
    ProjectCard.read(os.path.join(project_card_directory, filename), validate=False)
    for filename in card_filenames
]

my_scenario = Scenario.create_scenario(
  base_scenario=my_base_scenario,
  project_cards_list=project_cards_list,
)
my_scenario.check_scenario_requisites()

my_scenario.apply_all_projects()

my_scenario.scenario_summary()

Project

Creates project cards by comparing two MetCouncil Model Transit Network files or by reading a cube log file and a base network;

test_project = Project.create_project(
  base_transit_source=os.path.join(CUBE_DIR, "transit.LIN"),
  build_transit_source=os.path.join(CUBE_DIR, "transit_route_shape_change"),
  )

test_project.evaluate_changes()

test_project.write_project_card(
  os.path.join(SCRATCH_DIR, "t_transit_shape_test.yml")
  )

ModelRoadwayNetwork

A subclass of network_wrangler’s RoadwayNetwork class which additional understanding about how to translate and write the network out to the MetCouncil Roadway Network schema.

net = ModelRoadwayNetwork.read(
      link_filename=STPAUL_LINK_FILE,
      node_filename=STPAUL_NODE_FILE,
      shape_filename=STPAUL_SHAPE_FILE,
      fast=True,
      shape_foreign_key ='shape_id',
  )

net.write_roadway_as_fixedwidth()

StandardTransit

Translates the standard GTFS data to MetCouncil’s Cube Line files.

cube_transit_net = StandardTransit.read_gtfs(BASE_TRANSIT_DIR)
cube_transit_net.write_as_cube_lin(os.path.join(WRITE_DIR, "outfile.lin"))

CubeTransit

Used by the project class and has the capability to:

Parse cube line file properties and shapes into python dictionaries
Compare line files and represent changes as Project Card dictionaries

tn = CubeTransit.create_from_cube(CUBE_DIR)
transit_change_list = tn.evaluate_differences(base_transit_network)

Parameters

Holds information about default parameters but can also be initialized to override those parameters at object instantiation using a dictionary.

# read parameters from a yaml configuration  file
# could also provide as a key/value pair
with open(config_file) as f:
      my_config = yaml.safe_load(f)

# provide parameters at instantiation of ModelRoadwayNetwork
model_road_net = ModelRoadwayNetwork.from_RoadwayNetwork(
            my_scenario.road_net, parameters=my_config.get("my_parameters", {})
        )
# network written with direction from the parameters given
model_road_net.write_roadway_as_shp()

Typical Workflow

Workflows in Lasso and Network Wrangler typically accomplish one of two goals:

Create Project Cards to document network changes as a result of either transit or roadway projects.
Create Model Network Files for a scenario as represented by a series of Project Cards layered on top of a base network.

Project Cards from Transit LIN Files

Project Cards from Cube LOG Files

Model Network Files for a Scenario

Running Quickstart Jupyter Notebooks

To learn basic lasso functionality, please refer to the following jupyter notebooks in the /notebooks directory:

Lasso Project Card Creation Quickstart.ipynb
Lasso Scenario Creation Quickstart.ipynb

Jupyter notebooks can be started by activating the lasso conda environment and typing jupyter notebook:

conda activate <my_lasso_environment>
jupyter notebook