UrbanSim

https://udst.github.io/urbansim/
Admin
UrbanSim is a platform for building statistical models of cities and regions to forecast long-range...
Tokens:63,709
Snippets:431
Trust Score:9.7
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install UrbanSim from Source

Source: https://udst.github.io/urbansim/_sources/gettingstarted.rst.txt

Steps to clone the repository and install the library directly from the source code.

```python
git clone -b branch-name https://github.com/udst/urbansim.git
cd urbansim
pip install .
```

--------------------------------

### Install UrbanSim

Source: https://udst.github.io/urbansim/_sources/gettingstarted.rst.txt

Commands to install the UrbanSim library using standard package managers.

```python
pip install urbansim
```

```python
conda install urbansim --channel conda-forge
```

--------------------------------

### GET /

Source: https://udst.github.io/urbansim/_modules/urbansim/maps/dframe_explorer.html

Serves the main dframe_explorer HTML interface.

```APIDOC
## GET /

### Description
Returns the main HTML page for the dframe_explorer application, rendered with the current configuration.

### Method
GET

### Endpoint
/
```

--------------------------------

### Start the dframe_explorer web service

Source: https://udst.github.io/urbansim/_modules/urbansim/maps/dframe_explorer.html

Initializes and runs the web service to serve data queries and map visualizations. Requires a dictionary of DataFrames and a path to a GeoJSON file.

```python
def start(views,
          center=[37.7792, -122.2191],
          zoom=11,
          shape_json='data/zones.json',
          geom_name='ZONE_ID',  # from JSON file
          join_name='zone_id',  # from data frames
          precision=8,
          port=8765,
          host='localhost',
          testing=False):
```

--------------------------------

### urbansim.maps.dframe_explorer.start

Source: https://udst.github.io/urbansim/maps/index.html

Starts the web service that serves Pandas queries and generates the HTML for the map. The service runs on the specified host and port, allowing users to interact with the data via a web browser.

```APIDOC
## urbansim.maps.dframe_explorer.start

### Description
Starts the web service which serves the Pandas queries and generates the HTML for the map. The service takes control of the thread and responds to queries from a web browser at the specified host and port.

### Parameters
- **views** (dict) - Required - A dictionary where keys are table names and values are DataFrames. Each DataFrame must contain the column specified by join_name.
- **center** (list) - Optional - A list of two floats representing the initial latitude and longitude of the map center. Default: [37.7792, -122.2191].
- **zoom** (int) - Optional - The initial zoom level of the map. Default: 11.
- **shape_json** (str) - Optional - The path to the geojson file containing the shapes to be displayed. Default: 'data/zones.json'.
- **geom_name** (str) - Optional - The field name from the JSON file containing the geometry ID. Default: 'ZONE_ID'.
- **join_name** (str) - Optional - The column name in the DataFrames that joins to geom_name in the shapes. Default: 'zone_id'.
- **precision** (int) - Optional - The precision of values shown in the map legend. Default: 8.
- **port** (int) - Optional - The port for the web service. Default: 8765.
- **host** (str) - Optional - The hostname for the web service. Default: 'localhost'.
- **testing** (bool) - Optional - Whether to print extra debug information. Default: False.
```

--------------------------------

### Pandas Aggregation Examples

Source: https://udst.github.io/urbansim/maps/index.html

Examples of the underlying Pandas operations performed by the web service based on user input.

```python
df.groupby('zone_id')['residential_units'].sum()
```

```python
households.groupby('zone_id').persons.sum()
```

```python
households.groupby('zone_id').persons.mean()
```

--------------------------------

### Control Table Format Example

Source: https://udst.github.io/urbansim/_sources/models/transrelo.rst.txt

Example of a control table used for relocation rates, where columns define filters for the model.

```text
    num_cars num_children_min num_children_max relocation_rate
           0              nan                2            0.08
           0                2                4            0.05
           0                4              nan            0.03
           1              nan                2            0.09
           1                2                4            0.04
           1                4              nan            0.05
```

--------------------------------

### Households aggregation examples

Source: https://udst.github.io/urbansim/_sources/maps/index.rst.txt

Examples of Pandas groupby operations performed on the households table to calculate population metrics.

```python
households.groupby('zone_id').persons.sum()
```

```python
households.groupby('zone_id').persons.mean()
```

--------------------------------

### GET /data/<filename>

Source: https://udst.github.io/urbansim/_modules/urbansim/maps/dframe_explorer.html

Serves static files from the data directory.

```APIDOC
## GET /data/<filename>

### Description
Retrieves a static file from the local data directory.

### Method
GET

### Endpoint
/data/<filename>

### Parameters
#### Path Parameters
- **filename** (string) - Required - The name of the file to retrieve.
```

--------------------------------

### Full module source code

Source: https://udst.github.io/urbansim/_modules/urbansim/maps/dframe_explorer.html

The complete implementation of the dframe_explorer module, including route definitions and the start function.

```python
from __future__ import print_function

from bottle import route, response, run, hook, static_file
from urbansim.utils import yamlio
import simplejson
import numpy as np
import pandas as pd
import os
from jinja2 import Environment


@hook('after_request')
def enable_cors():
    response.headers['Access-Control-Allow-Origin'] = '*'
    response.headers['Access-Control-Allow-Headers'] = \
        'Origin, Accept, Content-Type, X-Requested-With, X-CSRF-Token'


DFRAMES = {}
CONFIG = None


def get_schema():
    global DFRAMES
    return {name: list(DFRAMES[name].columns) for name in DFRAMES}


@route('/map_query/<table>/<filter>/<groupby>/<field:path>/<agg>', method="GET")
def map_query(table, filter, groupby, field, agg):
    global DFRAMES

    filter = ".query('%s')" % filter if filter != "empty" else ""

    df = DFRAMES[table]

    if field not in df.columns:
        print("Col not found, trying eval:", field)
        df["eval"] = df.eval(field)
        field = "eval"

    cmd = "df%s.groupby('%s')['%s'].%s" % \
          (filter, groupby, field, agg)
    print(cmd)
    results = eval(cmd)
    results[results == np.inf] = np.nan
    results = yamlio.series_to_yaml_safe(results.dropna())
    results = {int(k): results[k] for k in results}
    return results


@route('/map_query/<table>/<filter>/<groupby>/<field>/<agg>', method="OPTIONS")
def ans_options(table=None, filter=None, groupby=None, field=None, agg=None):
    return {}


@route('/')
def index():
    global CONFIG
    dir = os.path.dirname(__file__)
    index = open(os.path.join(dir, 'dframe_explorer.html')).read()
    return Environment().from_string(index).render(CONFIG)


@route('/data/<filename>')
def data_static(filename):
    return static_file(filename, root='./data')



[docs]def start(views,
          center=[37.7792, -122.2191],
          zoom=11,
          shape_json='data/zones.json',
          geom_name='ZONE_ID',  # from JSON file
          join_name='zone_id',  # from data frames
          precision=8,
          port=8765,
          host='localhost',
          testing=False):
    """
    Start the web service which serves the Pandas queries and generates the
    HTML for the map.  You will need to open a web browser and navigate to
    http://localhost:8765 (or the specified port)

    Parameters
    ----------
    views : Python dictionary
        This is the data that will be displayed in the maps.  Keys are strings
        (table names) and values are dataframes.  Each data frame should have a
        column with the name specified as join_name below
    center : a Python list with two floats
        The initial latitude and longitude of the center of the map
    zoom : int
        The initial zoom level of the map
    shape_json : str
        The path to the geojson file which contains that shapes that will be
        displayed
    geom_name : str
        The field name from the JSON file which contains the id of the geometry
    join_name : str
        The column name from the dataframes passed as views (must be in each
        view) which joins to geom_name in the shapes
    precision : int
        The precision of values to show in the legend on the map
    port : int
        The port for the web service to respond on
    host : str
        The hostname to run the web service from
    testing : bool
        Whether to print extra debug information

    Returns
    -------
    Does not return - takes over control of the thread and responds to
    queries from a web browser
    """

    global DFRAMES, CONFIG
    DFRAMES = {str(k): views[k] for k in views}

    root = "http://{}:{}/".format(host, port)

    config = {
        'center': str(center),
        'zoom': zoom,
        'shape_json': shape_json,
        'geom_name': geom_name,
        'join_name': join_name,
        'precision': precision,
        'root': root
    }

    for k in views:
        if join_name not in views[k].columns:
            raise Exception("Join name must be present on all dataframes - "
                            "'%s' not present on '%s'" % (join_name, k))

    config['schema'] = simplejson.dumps(get_schema())

    CONFIG = config

    if testing:
        return

    run(host=host, port=port, debug=True)
```

--------------------------------

### Pandas aggregation example

Source: https://udst.github.io/urbansim/_sources/maps/index.rst.txt

Example of a simple interactive Pandas statement generated by the web service.

```python
df.groupby('zone_id')['residential_units'].sum()
```

--------------------------------

### Define UrbanSim Regression Model in YAML

Source: https://udst.github.io/urbansim/_sources/examples.rst.txt

Example configuration for a regression model using YAML, mapping parameters directly to the RegressionModel API.

```yaml
name: rsh

model_type: regression

fit_filters:
- unit_lot_size > 0
- year_built > 1000
- year_built < 2020
- unit_sqft > 100
- unit_sqft < 20000

predict_filters:
- general_type == 'Residential'

model_expression: np.log1p(residential_sales_price) ~ I(year_built < 1940) + I(year_built
    > 2005) + np.log1p(unit_sqft) + np.log1p(unit_lot_size) + sum_residential_units
    + ave_lot_sqft + ave_unit_sqft + ave_income

ytransform: np.exp
```

--------------------------------

### Compute building feasibility with SqFtProForma

Source: https://udst.github.io/urbansim/_sources/developer/index.rst.txt

Initializes the pro forma, assigns prices per use to parcels, and computes feasibility for various building forms.

```python
pf = sqftproforma.SqFtProForma()

df = parcels.to_frame()

# add prices for each use
for use in pf.config.uses:
    df[use] = parcel_price_callback(use)

# convert from cost to yearly rent
if residential_to_yearly:
    df["residential"] *= pf.config.cap_rate

d = {}
for form in pf.config.forms:
    print "Computing feasibility for form %s" % form
    d[form] = pf.lookup(form, df[parcel_use_allowed_callback(form)])

far_predictions = pd.concat(d.values(), keys=d.keys(), axis=1)

sim.add_table("feasibility", far_predictions)
```

--------------------------------

### Initialize SqFtProForma

Source: https://udst.github.io/urbansim/_modules/urbansim/developer/sqftproforma.html

Initializes the pro forma object with a configuration instance and prepares lookup tables.

```python
def __init__(self, config=None):
    if config is None:
        config = SqFtProFormaConfig()
    config.check_is_reasonable()
    self.config = config
    self.config._convert_types()
    self._generate_lookup()
```

--------------------------------

### Initialize SqFtProFormaConfig

Source: https://udst.github.io/urbansim/_modules/urbansim/developer/sqftproforma.html

Defines the configuration class for square-foot-based pro forma analysis, requiring parameters for building uses, parking, and construction costs.

```python
from __future__ import division

import numpy as np
import pandas as pd
import logging


logger = logging.getLogger(__name__)



[docs]class SqFtProFormaConfig(object):
    """
    This class encapsulates the configuration options for the square
    foot based pro forma.

    Parameters
    ----------
    parcel_sizes : list
        A list of parcel sizes to test.  Interestingly, right now
        the parcel sizes cancel in this style of pro forma computation so
        you can set this to something reasonable for debugging purposes -
        e.g. [10000].  All sizes can be feet or meters as long as they are
        consistently used.
    fars : list
        A list of floor area ratios to use.  FAR is a multiple of
        the parcel size that is the total building bulk that is allowed by
        zoning on the site.  In this case, all of these ratios will be
        tested regardless of zoning and the zoning test will be performed
        later.
    uses : list
        A list of space uses to use within a building.  These are
        mixed into forms.  Generally speaking, you should only have uses
        for which you have an estimate (or observed) values for rents in
        the building.  By default, uses are retail, industrial, office,
        and residential.
    forms : dict
        A dictionary where keys are names for the form and values
        are also dictionaries where keys are uses and values are the
        proportion of that use used in this form.  The values of the
        dictionary should sum to 1.0.  For instance, a form called
        "residential" might have a dict of space allocations equal to
        {"residential": 1.0} while a form called "mixedresidential"
        might have a dictionary of space allocations equal to
        {"retail": .1, "residential" .9] which is 90% residential and
        10% retail.
    parking_rates : dict
        A dict of rates per thousand square feet where keys are the uses
        from the list specified in the attribute above.  The ratios
        are typically in the range 0.5 - 3.0 or similar.  So for
        instance, a key-value pair of "retail": 2.0 would be two parking
        spaces per 1,000 square feet of retail.  This is a per square
        foot pro forma, so the more typically parking ratio of spaces
        per residential unit must be converted to square feet for use in
        this pro forma.
    sqft_per_rate : float
        The number of square feet per unit for use in the
        parking_rates above.  By default this is set to 1,000 but can be
        overridden.
    parking_configs : list
        An expert parameter and is usually unchanged.  By default
        it is set to ['surface', 'deck', 'underground'] and very semantic
        differences in the computation are performed for each of these
        parking configurations.  Generally speaking it will break things
        to change this array, but an item can be removed if that parking
        configuration should not be tested.
    parking_sqft_d : dict
        A dictionary where keys are the three parking
        configurations listed above and values are square foot uses of
        parking spaces in that configuration.  This is to capture the
        fact that surface parking is usually more space intensive
        than deck or underground parking.
    parking_cost_d : dict
        The parking cost for each parking configuration.  Keys are the
        name of the three parking configurations listed above and values
        are dollars PER SQUARE FOOT for parking in that configuration.
        Used to capture the fact that underground and deck are far more
        expensive than surface parking.
    height_for_costs : list
        A list of "break points" as heights at which construction becomes
        more expensive.  Generally these are the heights at which
        construction materials change from wood, to concrete, to steel.
        Costs are also given as lists by use for each of these break
        points and are considered to be valid up to the break point.  A
        list would look something like [15, 55, 120, np.inf].
    costs : dict
        The keys are uses from the attribute above and the values are a
        list of floating point numbers of same length as the
        height_for_costs attribute.  A key-value pair of
        "residential": [160.0, 175.0, 200.0, 230.0] would say that the
        residential use if $160/sqft up to 15ft in total height for the
        building, $175/sqft up to 55ft, $200/sqft up to 120ft, and
        $230/sqft beyond.  A final value in the height_for_costs
        array of np.inf is typical.
    height_per_story : float
        The per-story height for the building used to turn an
        FAR into an actual height.
    max_retail_height : float
        The maximum height of retail buildings to consider.
```

--------------------------------

### Initialize Developer Class

Source: https://udst.github.io/urbansim/_modules/urbansim/developer/developer.html

The constructor accepts a feasibility dataframe or a dictionary of dataframes keyed by building form.

```python
from __future__ import print_function
from __future__ import division

import pandas as pd
import numpy as np



[docs]class Developer(object):
    """
    Pass the dataframe that is returned by feasibility here

    Can also be a dictionary where keys are building forms and values are
    the individual data frames returned by the proforma lookup routine.

    """

    def __init__(self, feasibility):
        if isinstance(feasibility, dict):
            feasibility = pd.concat(feasibility.values(), keys=feasibility.keys(), axis=1)
        self.feasibility = feasibility
```

--------------------------------

### Upgrade UrbanSim

Source: https://udst.github.io/urbansim/_sources/gettingstarted.rst.txt

Commands to update an existing UrbanSim installation to the latest version.

```python
pip install urbansim --upgrade
```

```python
conda update urbansim --channel conda-forge
```

--------------------------------

### Enable GPU Acceleration

Source: https://udst.github.io/urbansim/_modules/urbansim/urbanchoice/interaction.html

Initializes GPU support for the interaction module.

```python
def enable_gpu():
    global GPU
    GPU = 1
    pmat.initialize_gpu()
```

--------------------------------

### Retrieve Model Columns

Source: https://udst.github.io/urbansim/_modules/urbansim/models/regression.html

Get a list of all columns used in the model filters and expression.

```python
[docs]
def columns_used(self):
    """
    Returns all the columns used in this model for filtering
    and in the model expression.

    """
    return list(tz.unique(tz.concatv(
        util.columns_in_filters(self.fit_filters),
        util.columns_in_filters(self.predict_filters),
        util.columns_in_formula(self.model_expression))))
```

--------------------------------

### Execute Developer Model and Merge Buildings

Source: https://udst.github.io/urbansim/_sources/developer/index.rst.txt

Initializes the developer model, computes target units, picks new buildings, and merges them into the existing buildings table.

```python
dev = developer.Developer(feasibility.to_frame())

target_units = dev.\
    compute_units_to_build(len(agents),
                           buildings[supply_fname].sum(),
                           target_vacancy)

new_buildings = dev.pick(forms,
                         target_units,
                         parcel_size,
                         ave_unit_size,
                         total_units,
                         max_parcel_size=max_parcel_size,
                         drop_after_build=True,
                         residential=residential,
                         bldg_sqft_per_job=bldg_sqft_per_job)

if year is not None:
    new_buildings["year_built"] = year

if form_to_btype_callback is not None:
    new_buildings["building_type_id"] = new_buildings["form"].\
        apply(form_to_btype_callback)

all_buildings = dev.merge(buildings.to_frame(buildings.local_columns),
                          new_buildings[buildings.local_columns])

sim.add_table("buildings", all_buildings)
```

--------------------------------

### Get Model Expression String

Source: https://udst.github.io/urbansim/_modules/urbansim/models/regression.html

Property that returns the model expression formatted for patsy/statsmodels.

```python
return util.str_model_expression(
    self.model_expression, add_constant=True)
```

--------------------------------

### Retrieve Configuration Path

Source: https://udst.github.io/urbansim/_modules/urbansim/utils/misc.html

Constructs a full path for a configuration file within the configs directory.

```python
def config(fname):
    """
    Return the config path for the file with the given filename.
    """
    return os.path.join(configs_dir(), fname)
```

--------------------------------

### DataFrameWrapper aggregation patterns

Source: https://udst.github.io/urbansim/_sources/examples.rst.txt

Examples of recommended and discouraged patterns when performing groupby operations on DataFrameWrapper objects.

```python
return buildings.residential_units.groupby(buildings.zone_id).sum()
```

```python
return buildings.groupby("zone_id").residential_units.sum()
```

```python
return buildings.to_frame().groupby("zone_id").residential_units.sum()
```

```python
return buildings.to_frame(['zone_id', 'residential_units']).groupby("zone_id").residential_units.sum()
```

--------------------------------

### Fit model from configuration

Source: https://udst.github.io/urbansim/_modules/urbansim/models/regression.html

Fits a model using a YAML configuration file and saves the results back to a configuration file.

```python
@classmethod
    def fit_from_cfg(cls, df, cfgname, debug=False, min_segment_size=None, outcfgname=None):
        """
        Parameters
        ----------
        df : DataFrame
            The dataframe which contains the columns to use for the estimation.
        cfgname : string
            The name of the yaml config file which describes the hedonic model.
        debug : boolean, optional (default False)
            Whether to generate debug information on the model.
        min_segment_size : int, optional
            Set attribute on the model.
        outcfgname : string, optional (default cfgname)
            The name of the output yaml config file where estimation results are written into.

        Returns
        -------
        hm : SegmentedRegressionModel which was used to fit
        """
        logger.debug('start: fit from configuration {}'.format(cfgname))
        hm = cls.from_yaml(str_or_buffer=cfgname)
        if min_segment_size:
            hm.min_segment_size = min_segment_size

        for k, v in hm.fit(df, debug=debug).items():
            print("REGRESSION RESULTS FOR SEGMENT %s\n" % str(k))
            print(v.summary())
        outcfgname = outcfgname or cfgname
        hm.to_yaml(str_or_buffer=outcfgname)
        logger.debug('finish: fit into configuration {}'.format(outcfgname))
        return hm
```

--------------------------------

### Fit Model from Configuration

Source: https://udst.github.io/urbansim/_modules/urbansim/models/dcm.html

Class method to initialize and fit a discrete choice model using a YAML configuration file.

```python
    @classmethod
    def fit_from_cfg(cls, choosers, chosen_fname, alternatives, cfgname, outcfgname=None):
        """
        Parameters
        ----------
        choosers : DataFrame
            A dataframe in which rows represent choosers.
        chosen_fname : string
            A string indicating the column in the choosers dataframe which
            gives which alternatives the choosers have chosen.
        alternatives : DataFrame
            A table of alternatives. It should include the choices
            from the choosers table as well as other alternatives from
            which to sample.  Values in choosers[chosen_fname] should index
            into the alternatives dataframe.
        cfgname : string
            The name of the yaml config file from which to read the discrete
            choice model.
        outcfgname : string, optional (default cfgname)
            The name of the output yaml config file where estimation results are written into.
```

--------------------------------

### GET /map_query/<table>/<filter>/<groupby>/<field>/<agg>

Source: https://udst.github.io/urbansim/_modules/urbansim/maps/dframe_explorer.html

Executes a query on a specified DataFrame table, grouping the results by a column and applying an aggregation function.

```APIDOC
## GET /map_query/<table>/<filter>/<groupby>/<field>/<agg>

### Description
Performs a groupby aggregation on a DataFrame identified by the table name. The filter parameter allows for subsetting the data, and the result is returned as a JSON object.

### Method
GET

### Endpoint
/map_query/<table>/<filter>/<groupby>/<field>/<agg>

### Parameters
#### Path Parameters
- **table** (string) - Required - The name of the DataFrame to query.
- **filter** (string) - Required - A query string to filter the DataFrame (use "empty" for no filter).
- **groupby** (string) - Required - The column name to group by.
- **field** (string) - Required - The field to aggregate.
- **agg** (string) - Required - The aggregation function to apply (e.g., sum, mean).
```

--------------------------------

### Transition method implementation

Source: https://udst.github.io/urbansim/_modules/urbansim/models/transition.html

Executes the transition process on a DataFrame and updates any provided linked tables.

```python
[docs]    def transition(self, data, year, linked_tables=None):
        """
        Add or remove rows from a table based on population targets.

        Parameters
        ----------
        data : pandas.DataFrame
            Rows will be removed from or added to this table.
        year : int
            Year number that will be passed to `transitioner`.
        linked_tables : dict of tuple, optional
            Dictionary of (table, 'column name') pairs. The column name
            should match the index of `data`. Indexes in `data` that
            are copied or removed will also be copied and removed in
            linked tables. They dictionary keys are used in the
            returned `updated_links`.

        Returns
        -------
        updated : pandas.DataFrame
            Table with rows removed or added.
        added : pandas.Series
            Indexes of new rows in `updated`.
        updated_links : dict of pandas.DataFrame

        """
        logger.debug('start: transition')
        linked_tables = linked_tables or {}
        updated_links = {}

        with log_start_finish('add/remove rows', logger):
            updated, added, copied, removed = self.transitioner(data, year)

        for table_name, (table, col) in linked_tables.items():
            logger.debug('updating linked table {}'.format(table_name))
            updated_links[table_name] = \
                _update_linked_table(table, col, added, copied, removed)

        logger.debug('finish: transition')
        return updated, added, updated_links
```

--------------------------------

### Calculate Parking and Building Costs

Source: https://udst.github.io/urbansim/_modules/urbansim/developer/sqftproforma.html

Logic for adjusting building bulk based on parking configuration and calculating associated costs and stories.

```python
# need to converge in on exactly how much far is available for
                # deck pkg
                if parking_config == 'deck':
                    building_bulk /= (1.0 + np.sum(uses_distrib * c.parking_rates) *
                                      c.parking_sqft_d[parking_config] /
                                      c.sqft_per_rate)

                df['building_sqft'] = building_bulk

                parkingstalls = building_bulk * \
                    np.sum(uses_distrib * c.parking_rates) / c.sqft_per_rate
                parking_cost = (c.parking_cost_d[parking_config] *
                                parkingstalls *
                                c.parking_sqft_d[parking_config])

                df['spaces'] = parkingstalls

                if parking_config == 'underground':
                    df['park_sqft'] = parkingstalls * \
                        c.parking_sqft_d[parking_config]
                    stories = building_bulk / c.tiled_parcel_sizes
                if parking_config == 'deck':
                    df['park_sqft'] = parkingstalls * \
                        c.parking_sqft_d[parking_config]
                    stories = ((building_bulk + parkingstalls *
                                c.parking_sqft_d[parking_config]) /
                               c.tiled_parcel_sizes)
                if parking_config == 'surface':
                    stories = building_bulk / \
                        (c.tiled_parcel_sizes - parkingstalls *
                         c.parking_sqft_d[parking_config])
                    df['park_sqft'] = 0
                    # not all fars support surface parking
                    stories[stories < 0.0] = np.nan
                    # I think we can assume that stories over 3
                    # do not work with surface parking
                    stories[stories > 5.0] = np.nan

                df['total_built_sqft'] = df.building_sqft + df.park_sqft
                df['parking_sqft_ratio'] = df.park_sqft / df.total_built_sqft
                stories /= c.parcel_coverage
                df['stories'] = np.ceil(stories)
                df['height'] = df.stories * c.height_per_story
                df['build_cost_sqft'] = self._building_cost(uses_distrib, stories)

                df['build_cost'] = df.build_cost_sqft * df.building_sqft
                df['park_cost'] = parking_cost
                df['cost'] = df.build_cost + df.park_cost

                df['ave_cost_sqft'] = (df.cost / df.total_built_sqft) * c.profit_factor

                if name == 'retail':
                    df['ave_cost_sqft'][c.fars > c.max_retail_height] = np.nan
                if name == 'industrial':
                    df['ave_cost_sqft'][c.fars > c.max_industrial_height] = np.nan

                df_d[(name, parking_config)] = df

        self.dev_d = df_d
```

--------------------------------

### Initialize SqftProForma Defaults

Source: https://udst.github.io/urbansim/_modules/urbansim/developer/sqftproforma.html

The constructor initializes the class by calling the _reset_defaults method to set up standard development parameters.

```python
def __init__(self):
    self._reset_defaults()
```

--------------------------------

### Add rows to a DataFrame

Source: https://udst.github.io/urbansim/_modules/urbansim/models/transition.html

Adds a specified number of rows to a DataFrame by sampling existing rows. New rows are assigned new index values starting from the provided starting_index.

```python
def add_rows(data, nrows, starting_index=None, accounting_column=None):
    """
    Add rows to data table according to a given nrows.
    New rows will have their IDs set to NaN.

    Parameters
    ----------
    data : pandas.DataFrame
    nrows : int
        Number of rows to add.
    starting_index : int, optional
        The starting index from which to calculate indexes for the new
        rows. If not given the max + 1 of the index of `data` will be used.
    accounting_column: string, optional
        Name of column with accounting totals/quanties to apply towards the control. If not provided
        then row counts will be used for accounting.

    Returns
    -------
    updated : pandas.DataFrame
        Table with rows added. New rows will have their index values
        set to NaN.
    added : pandas.Index
        New indexes of the rows that were added.
    copied : pandas.Index
        Indexes of rows that were copied. A row copied multiple times
        will have multiple entries.

    """
    logger.debug('start: adding {} rows in transition model'.format(nrows))
    if nrows == 0:
        return data, _empty_index(), _empty_index()

    if not starting_index:
        starting_index = data.index.values.max() + 1

    new_rows = sample_rows(nrows, data, accounting_column=accounting_column)
    copied_index = new_rows.index
    added_index = pd.Index(np.arange(
        starting_index, starting_index + len(new_rows.index), dtype=np.int))
    new_rows.index = added_index

    logger.debug(
        'finish: added {} rows in transition model'.format(len(new_rows)))
    return pd.concat([data, new_rows]), added_index, copied_index
```

--------------------------------

### pick

Source: https://udst.github.io/urbansim/developer/index.html

Chooses buildings from the list that are feasible to build to match specified demand.

```APIDOC
## pick(form, target_units, parcel_size, ave_unit_size, current_units, max_parcel_size=200000, min_unit_size=400, drop_after_build=True, residential=True, bldg_sqft_per_job=400.0, profit_to_prob_func=None)

### Description
Choose the buildings from the list that are feasible to build in order to match the specified demand.

### Parameters
- **form** (string or list) - Required - Building forms from the pro forma specification
- **target_units** (int) - Required - The number of units or job spaces to build
- **parcel_size** (series) - Required - The size of the parcels
- **ave_unit_size** (series) - Required - The average residential unit size around each parcel
- **current_units** (series) - Required - The current number of units on the parcel
- **max_parcel_size** (float) - Optional - Parcels larger than this size will not be considered
- **min_unit_size** (float) - Optional - Minimum unit size threshold
- **drop_after_build** (bool) - Optional - Whether to drop parcels after development
- **residential** (bool) - Optional - If false, fills job_spaces instead of residential_units
- **profit_to_prob_func** (function) - Optional - Function to return selection probabilities

### Returns
- **new_buildings** (dataframe) - DataFrame of buildings to add
```

--------------------------------

### Initialize and use RelocationModel

Source: https://udst.github.io/urbansim/_modules/urbansim/models/relocation.html

Encapsulates relocation logic within a class to manage rates and identify movers from a population.

```python
class RelocationModel(object):
    """
    Find movers within a population according to a table of
    relocation rates.

    Parameters
    ----------
    rates : pandas.DataFrame
        Table of relocation rates. Index is unused.

        Other columns describe filters on the `choosers`
        table so that different segments can have different relocation
        rates. Columns that ends with '_max' will be used to create
        a "less than" filters, columns that end with '_min' will be
        used to create "greater than or equal to" filters.
        A column with no suffix will be used to make an 'equal to' filter.

        An example `rates` structure:

        age_of_head_max  age_of_head_min
                    nan               65
                     65               40

        In this example the `choosers` table would need to have an
        'age_of_head' column on which to filter.

        nan should be used to flag filters that do not apply
        in a given row.
    rate_column : object, optional
        Name of column in `rates` table that contains relocation rates.
        If not given 'probability_of_relocating' is used.

    """
    def __init__(self, rates, rate_column=None):
        self.relocation_rates = rates
        self.rate_column = rate_column or 'probability_of_relocating'

    def find_movers(self, choosers):
        """
        Select movers from among a table of `choosers` according to the
        stored relocation rates.

        Parameters
        ----------
        choosers : pandas.DataFrame
            Table of agents from which to find movers.

        Returns
        -------
        movers : pandas.Index
            Suitable for indexing `choosers` by index.

        """
        return find_movers(choosers, self.relocation_rates, self.rate_column)
```

--------------------------------

### Select Buildings for Development

Source: https://udst.github.io/urbansim/_modules/urbansim/developer/developer.html

Placeholder method signature for selecting feasible buildings to meet demand.

```python
    [docs]    def pick(self, form, target_units, parcel_size, ave_unit_size,
             current_units, max_parcel_size=200000, min_unit_size=400,
             drop_after_build=True, residential=True, bldg_sqft_per_job=400.0,
             profit_to_prob_func=None):
        """
        Choose the buildings from the list that are feasible to build in
        order to match the specified demand.

```

--------------------------------

### Manage Directory Paths

Source: https://udst.github.io/urbansim/_modules/urbansim/utils/misc.html

Functions to retrieve or create specific directories based on the DATA_HOME environment variable.

```python
def _mkifnotexists(folder):
    d = os.path.join(os.getenv('DATA_HOME', "."), folder)
    if not os.path.exists(d):
        os.makedirs(d)
    return d

def data_dir():
    """
    Return the directory for the input data.
    """
    return _mkifnotexists("data")

def configs_dir():
    """
    Return the directory for the model configuration files.
    """
    return _mkifnotexists("configs")

def runs_dir():
    """
    Return the directory for the run output.
    """
    return _mkifnotexists("runs")

def models_dir():
    """
    Return the directory for the model configuration files (used by the
    website).
    """
    return _mkifnotexists("configs")

def charts_dir():
    """
    Return the directory for the chart configuration files (used by the
    website).
    """
    return _mkifnotexists("web/charts")

def maps_dir():
    """
    Return the directory for the map configuration files (used by the
    website).
    """
    return _mkifnotexists("web/maps")

def simulations_dir():
    """
    Return the directory for the simulation configuration files (used by the
    website).
    """
    return _mkifnotexists("web/simulations")

def reports_dir():
    """
    Return the directory for the report configuration files (used by the
    website).
    """
    return _mkifnotexists("web/reports")

def edits_dir():
    """
    Return the directory for the editable files (used by the
    website).
    """
    return _mkifnotexists("")
```

--------------------------------

### Initialize DiscreteChoiceModel from YAML

Source: https://udst.github.io/urbansim/_modules/urbansim/models/dcm.html

Creates a model instance by parsing a YAML configuration string or file buffer.

```python
@classmethod
def from_yaml(cls, yaml_str=None, str_or_buffer=None):
    """
    Create a DiscreteChoiceModel instance from a saved YAML configuration.
    Arguments are mutally exclusive.

    Parameters
    ----------
    yaml_str : str, optional
        A YAML string from which to load model.
    str_or_buffer : str or file like, optional
        File name or buffer from which to load YAML.

    Returns
    -------
    MNLDiscreteChoiceModel

    """
    cfg = yamlio.yaml_to_dict(yaml_str, str_or_buffer)

    model = cls(
        cfg['model_expression'],
        cfg['sample_size'],
        probability_mode=cfg.get('probability_mode', 'full_product'),
        choice_mode=cfg.get('choice_mode', 'individual'),
        choosers_fit_filters=cfg.get('choosers_fit_filters', None),
        choosers_predict_filters=cfg.get('choosers_predict_filters', None),
        alts_fit_filters=cfg.get('alts_fit_filters', None),
        alts_predict_filters=cfg.get('alts_predict_filters', None),
        interaction_predict_filters=cfg.get(
            'interaction_predict_filters', None),
        estimation_sample_size=cfg.get('estimation_sample_size', None),
        prediction_sample_size=cfg.get('prediction_sample_size', None),
        choice_column=cfg.get('choice_column', None),
        name=cfg.get('name', None)
    )

    if cfg.get('log_likelihoods', None):
        model.log_likelihoods = cfg['log_likelihoods']
    if cfg.get('fit_parameters', None):
        model.fit_parameters = pd.DataFrame(cfg['fit_parameters'])

    logger.debug('loaded LCM model {} from YAML'.format(model.name))
    return model
```

--------------------------------

### Initialize MNLDiscreteChoiceModelGroup

Source: https://udst.github.io/urbansim/_modules/urbansim/models/dcm.html

Initializes a group of discrete choice models for different chooser segments.

```python
def __init__(self, segmentation_col, remove_alts=False, name=None):
    self.segmentation_col = segmentation_col
    self.remove_alts = remove_alts
    self.name = name if name is not None else 'MNLDiscreteChoiceModelGroup'
    self.models = {}
```

--------------------------------

### Fit and Predict from Configuration

Source: https://udst.github.io/urbansim/_modules/urbansim/models/regression.html

Methods for fitting a regression model from a YAML configuration file and performing predictions using the same configuration.

```python
@classmethod
def fit_from_cfg(cls, df, cfgname, debug=False, outcfgname=None):
    """
    Parameters
    ----------
    df : DataFrame
        The dataframe which contains the columns to use for the estimation.
    cfgname : string
        The name of the yaml config file which describes the hedonic model.
    debug : boolean, optional (default False)
        Whether to generate debug information on the model.
    outcfgname : string, optional (default cfgname)
        The name of the output yaml config file where estimation results are written into.

    Returns
    -------
    RegressionModel which was used to fit
    """
    logger.debug('start: fit from configuration {}'.format(cfgname))
    hm = cls.from_yaml(str_or_buffer=cfgname)
    ret = hm.fit(df, debug=debug)
    print(ret.summary())
    outcfgname = outcfgname or cfgname
    hm.to_yaml(str_or_buffer=outcfgname)
    logger.debug('finish: fit into configuration {}'.format(outcfgname))
    return hm
```

```python
@classmethod
def predict_from_cfg(cls, df, cfgname):
    """
    Parameters
    ----------
    df : DataFrame
        The dataframe which contains the columns to use for the estimation.
    cfgname : string
        The name of the yaml config file which describes the hedonic model.

    Returns
    -------
    predicted : pandas.Series
        Predicted data in a pandas Series. Will have the index of `data`
        after applying filters and minus any groups that do not have
        models.
    hm : RegressionModel which was used to predict
    """
    logger.debug('start: predict from configuration {}'.format(cfgname))
    hm = cls.from_yaml(str_or_buffer=cfgname)

    price_or_rent = hm.predict(df)
    print(price_or_rent.describe())

    logger.debug('start: predict from configuration {}'.format(cfgname))
    return price_or_rent, hm
```

--------------------------------

### Persist models using YAML

Source: https://udst.github.io/urbansim/_sources/models/statistical.rst.txt

Use .from_yaml and .to_yaml to load and save model configurations and parameters. This allows for estimating models in one environment and applying them in another.

```python
model = RegressionModel.from_yaml('my_model.yaml')

model.fit(data)

model.to_yaml('my_model.yaml')
```

--------------------------------

### MNLDiscreteChoiceModel Initialization

Source: https://udst.github.io/urbansim/_modules/urbansim/models/dcm.html

Initializes a multinomial logit discrete choice model with specific probability and choice modes, and optional filters for estimation and prediction.

```python
def __init__(
        self, model_expression, sample_size,
        probability_mode='full_product', choice_mode='individual',
        choosers_fit_filters=None, choosers_predict_filters=None,
        alts_fit_filters=None, alts_predict_filters=None,
        interaction_predict_filters=None,
        estimation_sample_size=None,
        prediction_sample_size=None,
        choice_column=None, name=None):
    self._check_prob_choice_mode_compat(probability_mode, choice_mode)
    self._check_prob_mode_interaction_compat(
        probability_mode, interaction_predict_filters)
```

--------------------------------

### Calculate Development Feasibility

Source: https://udst.github.io/urbansim/_modules/urbansim/developer/sqftproforma.html

Calculates the most profitable development configuration by iterating through parking configurations and selecting the maximum profit.

```python
df = pd.concat(self._lookup_parking_cfg(form, parking_config, df, only_built,
                                                pass_through)
                       for parking_config in self.config.parking_configs)

        if len(df) == 0:
            return pd.DataFrame()

        max_profit_ind = df.pivot(
            columns="parking_config",
            values="max_profit").idxmax(axis=1).to_frame("parking_config")

        df.set_index(["parking_config"], append=True, inplace=True)
        max_profit_ind.set_index(["parking_config"], append=True, inplace=True)

        # get the max_profit idx
        return df.loc[max_profit_ind.index].reset_index(1)
```

--------------------------------

### RegressionModel Initialization

Source: https://udst.github.io/urbansim/_modules/urbansim/models/regression.html

Constructor for the RegressionModel class, setting up filters, model expressions, and optional transformations.

```python
def __init__(self, fit_filters, predict_filters, model_expression,
             ytransform=None, name=None):
    self.fit_filters = fit_filters
    self.predict_filters = predict_filters
    self.model_expression = model_expression
    self.ytransform = ytransform
    self.name = name or 'RegressionModel'
    self.model_fit = None
    self.fit_parameters = None
    self.est_data = None
```

--------------------------------

### Implement TabularTotalsTransition

Source: https://udst.github.io/urbansim/_modules/urbansim/models/transition.html

Transition data using control totals from a pandas DataFrame, with optional segmentation and accounting columns.

```python
class TabularTotalsTransition(TabularGrowthRateTransition):
    """
    Transition data via control totals in pandas DataFrame with
    optional segmentation.

    Parameters
    ----------
    targets : pandas.DataFrame
    totals_column : str
        Name of the column in `targets` that contains the control totals.
    accounting_column: string, optional
        Name of column with accounting totals/quanties to apply towards the control. If not provided
        then row counts will be used for accounting.
    """
    def __init__(self, targets, totals_column, accounting_column=None):
        self.targets = targets
        self.totals_column = totals_column
        self.accounting_column = accounting_column

    @property
    def _config_table(self):
        """
        Table that has transition configuration.

        """
        return self.targets

    @property
    def _config_column(self):
        """
        Non-filter column in config table.

        """
        return self.totals_column

    def _calc_nrows(self, len_data, target_pop):
        """
        Calculate the number of rows to add to or remove from some data.

        Parameters
        ----------
        len_data : int
            The current number of rows in the data table.
        target_pop : int
            Target population.

        """
        return target_pop - len_data


    def transition(self, data, year):
        """
        Add or remove rows to/from a table according to the prescribed
        totals for this model and year.

        Parameters
        ----------
        data : pandas.DataFrame
            Rows will be removed from or added to this table.
        year : None, optional
            Here for compatibility with other transition models,
            but ignored.

        Returns
        -------
        updated : pandas.DataFrame
            Table with rows removed or added.
        added : pandas.Index
            New indexes of the rows that were added.
        copied : pandas.Index
            Indexes of rows that were copied. A row copied multiple times
            will have multiple entries.
        removed : pandas.Index
            Index of rows that were removed.

        """
        with log_start_finish('tabular totals transition', logger):
            return super(TabularTotalsTransition, self).transition(data, year)
```

--------------------------------

### Calculate Units to Build

Source: https://udst.github.io/urbansim/_modules/urbansim/developer/developer.html

Computes the number of units required to reach a target vacancy rate based on current agent and unit counts.

```python
    [docs]    @staticmethod
    def compute_units_to_build(num_agents, num_units, target_vacancy):
        """
        Compute number of units to build to match target vacancy.

        Parameters
        ----------
        num_agents : int
            number of agents that need units in the region
        num_units : int
            number of units in buildings
        target_vacancy : float (0-1.0)
            target vacancy rate

        Returns
        -------
        number_of_units : int
            the number of units that need to be built
        """
        print("Number of agents: {:,}".format(num_agents))
        print("Number of agent spaces: {:,}".format(int(num_units)))
        assert target_vacancy < 1.0
        target_units = int(max(num_agents / (1 - target_vacancy) - num_units, 0))
        print("Current vacancy = {:.2f}"
              .format(1 - num_agents / float(num_units)))
        print("Target vacancy = {:.2f}, target of new units = {:,}"
              .format(target_vacancy, target_units))
        return target_units
```
Tokens:
Raw