DOCSEARCHbyAlgolia
Submit Docs

UrbanSim Documentation

repository·dev·Indexed 19 days ago

https://github.com/udst/urbansim

A platform and Python library for building statistical models of cities and regions to forecast real estate development and demographic patterns. It includes specialized modules like sqftproforma for computing building feasibility and a developer model for selecting buildings to meet demand. The framework utilizes the Orca library for managing simulation steps, computed columns, and data loading via decorators.

Tokens
9.8K
Snippets
25
Records
47
Agent score
68%

What's inside UrbanSim

  1. Overview of UrbanSim

    dev

    UrbanSim is a platform designed for building statistical models of cities and regions. It is used to forecast long-range patterns in real estate development, demographics, and related outcomes under various policy scenarios.

    The urbansim Python library serves as the core component of the platform, providing:

    • Tools for statistical estimation and simulation.
    • Domain-specific logic for housing markets, household relocation, and other urban processes.
    • Frameworks and utilities for assembling complete models.

  2. Overview of UrbanSim Core Models

    dev

    UrbanSim's core models are implemented as specialized classes designed to link pandas data structures with urban simulation operations. The primary model categories available are:

    • Statistical Models: Includes regression models for predicting numeric data and location choice models for matching choosers to their likely selections.
    • Supply and Demand Models: Used to adjust real estate prices based on supply and demand effects.
    • Transition and Relocation Models: Used for managing population dynamics, such as adding/removing members and choosing movers.

  3. Work with DataFrameWrapper objects

    dev

    When using @orca.column, the table object passed to the function is a DataFrameWrapper, not a standard Pandas DataFrame.

    Important Constraints:

    • You have access to Series objects by name (e.g., buildings.residential_units).
    • Standard Pandas DataFrame methods like .loc and .groupby are NOT available directly on the wrapper.

    Recommended Patterns:

    • Best (Fast): Use Series objects directly for operations: buildings.residential_units.groupby(buildings.zone_id).sum()
    • Avoid (Slow): Converting the whole wrapper to a DataFrame: buildings.to_frame().groupby("zone_id").residential_units.sum()
    • Alternative (Verbose): Convert only necessary columns: buildings.to_frame(['zone_id', 'residential_units']).groupby("zone_id").residential_units.sum()
    • Alternative (Primary attributes only): If using only primary attributes, use local_columns: buildings.to_frame(buildings.local_columns).groupby("zone_id").residential_units.sum()
    # Recommended
return buildings.residential_units.groupby(buildings.zone_id).sum()

# Avoid (Slow)
return buildings.to_frame().groupby("zone_id").residential_units.sum()

  4. How UrbanSim modeling works

    dev

    At a high level, UrbanSim operates as a sequence of models that are first estimated and then simulated over a specified number of years. The core logic follows this pattern:

    1. Estimation Phase: Models are estimated using provided configuration parameters.
    2. Simulation Phase: For each year in the simulation period, the models are executed in sequence to update the state of the urban system.

    Common model types include:

    • Residential/Non-residential Real Estate Models: Includes Hedonic Regression (prices/rents), Location Choice (where households/jobs go), and Transition models (generating new entities to match control totals).
    • Real Estate Development Models: Includes Development Project Location Choice and Pro Forma Developer models (which assess profitability against construction costs and planning policies).
    # Conceptual pseudocode of the UrbanSim simulation loop

for model in models:
    model.estimate(model_configuration_parameters)

for i in range(NUMYEARSINSIMULATION):
    for model in models:
        model.simulate(model_configuration_parameters)

  5. How DataFrame Explorer performs aggregations

    dev

    The DataFrame Explorer performs on-the-fly Pandas aggregations on disaggregate data. It translates your UI selections into interactive Pandas statements and then joins the resulting series to shapes to create a Leaflet-based web map.

    Example Workflow: If you have a households table with a zone_id and you select the persons attribute with a sum aggregation, the service executes:

    households.groupby('zone_id')['persons'].sum()

    If you change the aggregation to mean, it executes:

    households.groupby('zone_id')['persons'].mean()

  6. Specify scenario inputs in UrbanSim

    dev

    UrbanSim is a scenario planning tool used to investigate how different policies or assumptions affect urban development. You can specify scenarios by adjusting the following types of inputs:

    • Control Totals: Use a simple Excel-based format to specify demographic shifts of households and sector shifts of employment. These control transition models and the addition of new households/jobs.
    • Zoning Changes: Test scenario-specific density limits such as max_far and max_dua. These are passed to pro formas (e.g., SqFtProForma.lookup) during feasibility testing. You can also use utility functions to upzone specific parcels based on policy.
    • Fees and Subsidies: Adjust the feasibility of buildings by modifying fees or subsidies. This can include collecting fees from profitable buildings to transfer to less profitable ones (e.g., affordable housing policies).
    • Developer Assumptions: Test variables like interest rates, the impact of mixed-use buildings, density bonuses for amenities, and parking requirements.

  7. How Transition and Relocation models work

    dev

    Transition Models

    Transition models add (via copying) or remove rows from a table based on prescribed rates or totals.

    A TransitionModel is composed of two parts:

    1. The main interface: urbansim.models.transition.TransitionModel.
    2. A transitioner: The logic that performs the actual transition.

    Available built-in transitioners include:

    • GrowthRateTransition
    • TabularGrowthRateTransition
    • TabularTotalsTransition

    You can also implement a custom transitioner. A transitioner must be a callable that accepts a pandas.DataFrame and a year number, and returns a tuple containing:

    • The new data table
    • Indexes of rows added
    • Indexes of rows copied
    • Indexes of rows removed

    Relocation Models

    Relocation models are used to select specific 'movers' from a table based on prescribed rates.

  8. How to use statistical models in UrbanSim

    dev

    UrbanSim provides two types of statistical models: regressions and discrete choice models. Both follow a consistent three-stage lifecycle:

    1. Create: Instantiate a configured model. This is where you define the model (via expressions) and apply filters to restrict the data used for fitting and prediction.
    2. Fit: Train the model by supplying base year data.
    3. Predict: Generate predictions based on new data.

    Model Types:

    • Regressions: Predict numeric values.
    • Discrete Choice Models: Predict choices (location choice) and only require a right-hand side formula as they do not predict new numeric values.

  9. How UrbanSim models are constructed

    dev

    Operational UrbanSim models are built by estimating and validating a system of interconnected components based on detailed regional data.

    UrbanSim is part of the Urban Data Science Toolkit (UDST) and typically integrates with several other specialized libraries:

    • Orca: For task orchestration.
    • Synthpop: For population synthesis.
    • Pandana: For network analysis.

  10. Understand Supply and Demand Accounting in UrbanSim

    dev
    The urbansim.models.supplydemand module provides models designed to account for supply and demand effects that standard real estate price regression models often miss. These models work in tandem with location choice models to estimate supply and demand dynamics and adjust real estate prices to compensate for market mismatches.

  11. Understand the Real Estate Development Models

    dev

    The real estate development functionality is split into two distinct modules designed for vectorized Python performance, allowing for millions of pro forma calculations simultaneously:

    1. sqftproforma module: Computes real estate feasibility for a set of parcels based on allowed uses, prices, and building costs. It determines if a building 'form' is profitable but does not perform the actual construction or addition of buildings to a set.
    2. developer model module: Decides how much to build and selects from the set of feasible buildings to meet demand. It is primarily used in urban forecasting to add new buildings to the existing building stock.

    Note that feasibility is computed on a square foot basis. The developer model is responsible for translating these square foot calculations into specific unit mixes and sizes.

  12. How Orca orchestration works in UrbanSim

    dev

    UrbanSim uses Orca, a pipeline orchestration framework, to manage data and simulation steps. Orca allows you to register tables from various sources (databases, text files, shapefiles), define relationships between them, and maintain automatically synced calculated columns.

    Orca uses a pattern of decorators and injection:

    1. Decorators: Use @orca.table, @orca.column, or @orca.step to register specific pieces of functionality with the simulation engine.
    2. Injection: Once registered, objects are passed to functions automatically by name. For example, if you register a table named 'parcels', any function that includes parcels as an argument will automatically receive that table object.

    This allows you to build complex models by writing small, focused Python functions that implement specific logic.