Introduction¶

Module Documentation¶

class urbansim_defaults.utils.SimulationSummaryData(run_number, zone_indicator_file='runs/run{}_simulation_output.json', parcel_indicator_file='runs/run{}_parcel_output.csv')[source]¶

Keep track of zone-level and parcel-level output for use in the simulation explorer. Writes the correct format and filenames that the simulation explorer expects.

Parameters:

run_number : int The run number for this run zone_indicator_file : optional, str A template for the zone_indicator_filename - use {} notation and the run_number will be substituted. Should probably not be modified if using the simulation explorer. parcel_indicator_file : optional, str A template for the parcel_indicator_filename - use {} notation and the run_number will be substituted. Should probably not be modified if using the simulation explorer.

add_parcel_output(new_parcel_output)[source]¶

Add new parcel-level indicators to the parcel output.

Parameters:	new_parcel_output : DataFrame Adds a new set of parcel data for output exploration - this data is merged with previous data that has been added. This data is generally used to capture new developments that UrbanSim has predicted, thus it doesn’t override previous years’ indicators
Returns:	Nothing

add_zone_output(zones_df, name, year, round=2)[source]¶

Pass in a dataframe and this function will store the results in the simulation state to write out at the end (to describe how the simulation changes over time)

Parameters:	zones_df : DataFrame dataframe of indicators whose index is the zone_id and columns are indicators describing the simulation name : string The name of the dataframe to use to differentiate all the sources of the indicators year : int The year to associate with these indicators round : int The number of decimal places to round to in the output json
Returns:	Nothing

write_parcel_output(add_xy=None)[source]¶

Write the parcel-level output to a csv file

Parameters:

add_xy : dictionary (optional) Used to add x, y values to the output - an example dictionary is pasted below - the parameters should be fairly self explanatory. Note that from_epsg and to_epsg can be omitted in which case the coordinate system is not changed. NOTE: pyproj is required if changing coordinate systems: { "xy_table": "parcels", "foreign_key": "parcel_id", "x_col": "x", "y_col": "y", "from_epsg": 3740, "to_epsg": 4326 }

Returns:

Nothing

write_zone_output()[source]¶

Write the zone-level output to a file.

urbansim_defaults.utils.check_nas(df)[source]¶

Checks for nas and errors if they are found (also prints a report on how many nas are found in each column)

Parameters:	df : DataFrame DataFrame to check for nas
Returns:	Nothing

urbansim_defaults.utils.conditional_upzone(scenario, scenario_inputs, attr_name, upzone_name)[source]¶

Parameters:

scenario : str The name of the active scenario (set to “baseline” if no scenario zoning) scenario_inputs : dict Dictionary of scenario options - keys are scenario names and values are also dictionaries of key-value paris for scenario inputs. Right now “zoning_table_name” should be set to the table that contains the scenario based zoning for that scenario attr_name : str The name of the attribute in the baseline zoning table upzone_name : str The name of the attribute in the scenario zoning table

Returns:

The new zoning per parcel which is increased if the scenario based zoning is higher than the baseline zoning

urbansim_defaults.utils.enable_logging()[source]¶

A quick shortcut to enable logging at log level INFO

urbansim_defaults.utils.full_transition(agents, agent_controls, year, settings, location_fname)[source]¶

Run a transition model based on control totals specified in the usual UrbanSim way

Parameters:

agents : DataFrameWrapper Table to be transitioned agent_controls : DataFrameWrapper Table of control totals year : int The year, which will index into the controls settings : dict Contains the configuration for the transition model - is specified down to the yaml level with a “total_column” which specifies the control total and an “add_columns” param which specified which columns to add when calling to_frame (should be a list of the columns needed to do the transition location_fname : str The field name in the resulting dataframe to set to -1 (to unplace new agents)

Returns:

Nothing

urbansim_defaults.utils.hedonic_estimate(cfg, tbl, join_tbls)[source]¶

Estimate the hedonic model for the specified table

Parameters:	cfg : string The name of the yaml config file from which to read the hedonic model tbl : DataFrameWrapper A dataframe for which to estimate the hedonic join_tbls : list of strings A list of land use dataframes to give neighborhood info around the buildings - will be joined to the buildings using existing broadcasts

urbansim_defaults.utils.hedonic_simulate(cfg, tbl, join_tbls, out_fname)[source]¶

Simulate the hedonic model for the specified table

Parameters:

cfg : string The name of the yaml config file from which to read the hedonic model tbl : DataFrameWrapper A dataframe for which to estimate the hedonic join_tbls : list of strings A list of land use dataframes to give neighborhood info around the buildings - will be joined to the buildings using existing broadcasts out_fname : string The output field name (should be present in tbl) to which to write the resulting column to

urbansim_defaults.utils.lcm_estimate(cfg, choosers, chosen_fname, buildings, join_tbls)[source]¶

Estimate the location choices for the specified choosers

Parameters:

cfg : string The name of the yaml config file from which to read the location choice model choosers : DataFrameWrapper A dataframe of agents doing the choosing chosen_fname : str The name of the column (present in choosers) which contains the ids that identify the chosen alternatives buildings : DataFrameWrapper A dataframe of buildings which the choosers are locating in and which have a supply. join_tbls : list of strings A list of land use dataframes to give neighborhood info around the buildings - will be joined to the buildings using existing broadcasts

urbansim_defaults.utils.lcm_simulate(cfg, choosers, buildings, join_tbls, out_fname, supply_fname, vacant_fname, enable_supply_correction=None)[source]¶

Simulate the location choices for the specified choosers

Parameters:

cfg : string The name of the yaml config file from which to read the location choice model choosers : DataFrameWrapper A dataframe of agents doing the choosing buildings : DataFrameWrapper A dataframe of buildings which the choosers are locating in and which have a supply join_tbls : list of strings A list of land use dataframes to give neighborhood info around the buildings - will be joined to the buildings using existing broadcasts. out_fname : string The column name to write the simulated location to supply_fname : string The string in the buildings table that indicates the amount of available units there are for choosers, vacant or not vacant_fname : string The string in the buildings table that indicates the amount of vacant units there will be for choosers enable_supply_correction : Python dict Should contain keys “price_col” and “submarket_col” which are set to the column names in buildings which contain the column for prices and an identifier which segments buildings into submarkets

urbansim_defaults.utils.run_developer(forms, agents, buildings, supply_fname, parcel_size, ave_unit_size, total_units, feasibility, year=None, target_vacancy=0.1, form_to_btype_callback=None, add_more_columns_callback=None, max_parcel_size=2000000, residential=True, bldg_sqft_per_job=400.0, min_unit_size=400, remove_developed_buildings=True, unplace_agents=['households', 'jobs'])[source]¶

Run the developer model to pick and build buildings

Parameters:

forms : string or list of strings Passed directly dev.pick agents : DataFrame Wrapper Used to compute the current demand for units/floorspace in the area buildings : DataFrame Wrapper Used to compute the current supply of units/floorspace in the area supply_fname : string Identifies the column in buildings which indicates the supply of units/floorspace parcel_size : Series Passed directly to dev.pick ave_unit_size : Series Passed directly to dev.pick - average residential unit size total_units : Series Passed directly to dev.pick - total current residential_units / job_spaces feasibility : DataFrame Wrapper The output from feasibility above (the table called ‘feasibility’) year : int The year of the simulation - will be assigned to ‘year_built’ on the new buildings target_vacancy : float The target vacancy rate - used to determine how much to build form_to_btype_callback : function Will be used to convert the ‘forms’ in the pro forma to ‘building_type_id’ in the larger model add_more_columns_callback : function Takes a dataframe and returns a dataframe - is used to make custom modifications to the new buildings that get added max_parcel_size : float Passed directly to dev.pick - max parcel size to consider min_unit_size : float Passed directly to dev.pick - min unit size that is valid residential : boolean Passed directly to dev.pick - switches between adding/computing residential_units and job_spaces bldg_sqft_per_job : float Passed directly to dev.pick - specified the multiplier between floor spaces and job spaces for this form (does not vary by parcel as ave_unit_size does) remove_redeveloped_buildings : optional, boolean (default True) Remove all buildings on the parcels which are being developed on unplace_agents : optional For all tables in the list, will look for field building_id and set it to -1 for buildings which are removed - only executed if remove_developed_buildings is true

Returns:

Writes the result back to the buildings table and returns the new buildings with available debugging information on each new building

urbansim_defaults.utils.run_feasibility(parcels, parcel_price_callback, parcel_use_allowed_callback, residential_to_yearly=True, parcel_filter=None, config=None, pass_through=[])[source]¶

Execute development feasibility on all parcels

Parameters:

parcels : DataFrame Wrapper The data frame wrapper for the parcel data parcel_price_callback : function A callback which takes each use of the pro forma and returns a series with index as parcel_id and value as yearly_rent parcel_use_allowed_callback : function A callback which takes each form of the pro forma and returns a series with index as parcel_id and value and boolean whether the form is allowed on the parcel residential_to_yearly : boolean (default true) Whether to use the cap rate to convert the residential price from total sales price per sqft to rent per sqft parcel_filter : string A filter to apply to the parcels data frame to remove parcels from consideration - is typically used to remove parcels with buildings older than a certain date for historical preservation, but is generally useful config : SqFtProFormaConfig configuration object. Optional. Defaults to None pass_through : list of strings Will be passed to the feasibility lookup function - is used to pass variables from the parcel dataframe to the output dataframe, usually for debugging

Returns:

Adds a table called feasibility to the sim object (returns nothing)

urbansim_defaults.utils.simple_relocation(choosers, relocation_rate, fieldname)[source]¶

Run a simple rate based relocation model

Parameters:	tbl : DataFrameWrapper or DataFrame Table of agents that might relocate rate : float Rate of relocation location_fname : str The field name in the resulting dataframe to set to -1 (to unplace new agents)
Returns:	Nothing

urbansim_defaults.utils.simple_transition(tbl, rate, location_fname)[source]¶

Run a simple growth rate transition model on the table passed in

Parameters:	tbl : DataFrameWrapper Table to be transitioned rate : float Growth rate location_fname : str The field name in the resulting dataframe to set to -1 (to unplace new agents)
Returns:	Nothing

urbansim_defaults.utils.table_reprocess(cfg, df)[source]¶

Reprocesses a table with the given configuration, mainly by filling nas with the given configuration.

Parameters:

cfg : dict The configuration is specified as a nested dictionary, javascript style, and a simple config is given below. Most parameters should be fairly self-explanatory. “filter” filters the dataframe using the query command in Pandas. The “fill_nas” parameter is another dictionary which takes each column and specifies how to fill nas - options include “drop”, “zero”, “median”, “mode”, and “mean”. The “type” must also be specified since items like “median” usually return floats but the result is often desired to be an “int” - the type is thus specified to avoid ambiguity.: { "filter": "building_type_id >= 1 and building_type_id <= 14", "fill_nas": { "building_type_id": { "how": "drop", "type": "int" }, "residential_units": { "how": "zero", "type": "int" }, "year_built": { "how": "median", "type": "int" }, "building_type_id": { "how": "mode", "type": "int" } } } df : DataFrame to process

Returns:

New DataFrame which is reprocessed according the configuration

urbansim_defaults.utils.to_frame(tbl, join_tbls, cfg, additional_columns=[])[source]¶

Leverage all the built in functionality of the sim framework to join to the specified tables, only accessing the columns used in cfg (the model yaml configuration file), an any additionally passed columns (the sim framework is smart enough to figure out which table to grab the column off of)

Parameters:	tbl : DataFrameWrapper The table to join other tables to join_tbls : list of DataFrameWrappers or strs A list of tables to join to “tbl” cfg : str The filename of a yaml configuration file from which to parse the strings which are actually used by the model additional_columns : list of strs A list of additional columns to include
Returns:	A single DataFrame with the index from tbl and the columns used by cfg and any additional columns specified

urbansim_defaults.utils.yaml_to_class(cfg)[source]¶

Convert the name of a yaml file and get the Python class of the model associated with the configuratoin

Parameters:	cfg : str The name of the yaml configuration file
Returns:	Nothing

Index¶

Use this index Index to lookup methods by name.