Transition and Relocation Models

Introduction

Transition models are used to add (via copying) or remove rows from a table based on prescribed rates or totals. Relocation models are used to select movers from a table, also based on prescribed rates.

Control Table Formatting

The tables of rates and totals used in transition and relocation models have a particular format that allows them to specify different values for different segments of the table. Below is an example table:

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

Each column except the relocation_rate column describes a filter on the table to which the rates will be applied. The column names are inspected to determine the type of the filter and the table column to which the filter applies.

Column names that end with _min indicate a “greater than or equal to” filter. For example, the second row of the above table will have a filter like num_children >= 2.

Column names that end with _max indicate a “less than” filter. For example, the second row of the above table will have a filter like num_children < 4. Notice that the maximum is not inclusive.

Column names that do not end in _min or _max indicate an “equal to” filter. In the above table the first, second, and third rows will have a filter like num_cars == 0.

nan values indicate filters that do not apply in a given row.

Transition Model Notes

Transition models have two components. The main interface is the TransitionModel, but it is configured by providing a “transitioner”. Transitioners can make transitions based on different inputs like growth rates and control totals. Available transitioners are:

Or you could write and provide your own transitioner. Transitioners are expected to be callable and take arguments of a DataFrame with the data to transition and a year number. They should return a new data table, the indexes of rows added, the indexes of rows copied, and the indexes of rows removed.

API

Transition API

GrowthRateTransition(growth_rate[, …])

Transition given tables using a simple growth rate.

TabularGrowthRateTransition(growth_rates, …)

Growth rate based transitions where the rates are stored in a table indexed by year with optional segmentation.

TabularTotalsTransition(targets, totals_column)

Transition data via control totals in pandas DataFrame with optional segmentation.

TransitionModel(transitioner)

Models things moving into or out of a region.

Relocation API

RelocationModel(rates[, rate_column])

Find movers within a population according to a table of relocation rates.

Transition API Docs

Use the TransitionModel class with the different transitioners to add or remove agents based on growth rates or target totals.

class urbansim.models.transition.GrowthRateTransition(growth_rate, accounting_column=None)[source]

Transition given tables using a simple growth rate.

Parameters
growth_ratefloat
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.

transition(self, data, year)[source]

Add or remove rows to/from a table according to the prescribed growth rate for this model.

Parameters
datapandas.DataFrame

Rows will be removed from or added to this table.

yearNone, optional

Here for compatibility with other transition models, but ignored.

Returns
updatedpandas.DataFrame

Table with rows removed or added.

addedpandas.Index

New indexes of the rows that were added.

copiedpandas.Index

Indexes of rows that were copied. A row copied multiple times will have multiple entries.

removedpandas.Index

Index of rows that were removed.

class urbansim.models.transition.TabularGrowthRateTransition(growth_rates, rates_column, accounting_column=None)[source]

Growth rate based transitions where the rates are stored in a table indexed by year with optional segmentation.

Parameters
growth_ratespandas.DataFrame
rates_columnstr

Name of the column in growth_rates that contains the rates.

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.

transition(self, data, year)[source]

Add or remove rows to/from a table according to the prescribed growth rate for this model and year.

Parameters
datapandas.DataFrame

Rows will be removed from or added to this table.

yearNone, optional

Here for compatibility with other transition models, but ignored.

Returns
updatedpandas.DataFrame

Table with rows removed or added.

addedpandas.Index

New indexes of the rows that were added.

copiedpandas.Index

Indexes of rows that were copied. A row copied multiple times will have multiple entries.

removedpandas.Index

Index of rows that were removed.

class urbansim.models.transition.TabularTotalsTransition(targets, totals_column, accounting_column=None)[source]

Transition data via control totals in pandas DataFrame with optional segmentation.

Parameters
targetspandas.DataFrame
totals_columnstr

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.

transition(self, data, year)[source]

Add or remove rows to/from a table according to the prescribed totals for this model and year.

Parameters
datapandas.DataFrame

Rows will be removed from or added to this table.

yearNone, optional

Here for compatibility with other transition models, but ignored.

Returns
updatedpandas.DataFrame

Table with rows removed or added.

addedpandas.Index

New indexes of the rows that were added.

copiedpandas.Index

Indexes of rows that were copied. A row copied multiple times will have multiple entries.

removedpandas.Index

Index of rows that were removed.

class urbansim.models.transition.TransitionModel(transitioner)[source]

Models things moving into or out of a region.

Parameters
transitionercallable

A callable that takes a data table and a year number and returns and new data table, the indexes of rows added, the indexes of rows copied, and the indexes of rows removed.

transition(self, data, year, linked_tables=None)[source]

Add or remove rows from a table based on population targets.

Parameters
datapandas.DataFrame

Rows will be removed from or added to this table.

yearint

Year number that will be passed to transitioner.

linked_tablesdict 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
updatedpandas.DataFrame

Table with rows removed or added.

addedpandas.Series

Indexes of new rows in updated.

updated_linksdict of pandas.DataFrame
urbansim.models.transition.add_or_remove_rows(data, nrows, starting_index=None, accounting_column=None)[source]

Add or remove rows to/from a table. Rows are added for positive nrows and removed for negative nrows.

Parameters
dataDataFrame
nrowsfloat

Number of rows to add or remove.

starting_indexint, optional

The starting index from which to calculate indexes for new rows. If not given the max + 1 of the index of data will be used. (Not applicable if rows are being removed.)

Returns
updatedpandas.DataFrame

Table with random rows removed.

addedpandas.Index

New indexes of the rows that were added.

copiedpandas.Index

Indexes of rows that were copied. A row copied multiple times will have multiple entries.

removedpandas.Index

Index of rows that were removed.

urbansim.models.transition.add_rows(data, nrows, starting_index=None, accounting_column=None)[source]

Add rows to data table according to a given nrows. New rows will have their IDs set to NaN.

Parameters
datapandas.DataFrame
nrowsint

Number of rows to add.

starting_indexint, 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
updatedpandas.DataFrame

Table with rows added. New rows will have their index values set to NaN.

addedpandas.Index

New indexes of the rows that were added.

copiedpandas.Index

Indexes of rows that were copied. A row copied multiple times will have multiple entries.

urbansim.models.transition.remove_rows(data, nrows, accounting_column=None)[source]

Remove a random nrows number of rows from a table.

Parameters
dataDataFrame
nrowsfloat

Number of rows to remove.

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
updatedpandas.DataFrame

Table with random rows removed.

removedpandas.Index

Indexes of the rows removed from the table.

Relocation API Docs

Use the RelocationModel class to choose movers based on relocation rates.

class urbansim.models.relocation.RelocationModel(rates, rate_column=None)[source]

Find movers within a population according to a table of relocation rates.

Parameters
ratespandas.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_columnobject, optional

Name of column in rates table that contains relocation rates. If not given ‘probability_of_relocating’ is used.

find_movers(self, choosers)[source]

Select movers from among a table of choosers according to the stored relocation rates.

Parameters
chooserspandas.DataFrame

Table of agents from which to find movers.

Returns
moverspandas.Index

Suitable for indexing choosers by index.

urbansim.models.relocation.find_movers(choosers, rates, rate_column)[source]

Returns an array of the indexes of the choosers that are slated to move.

Parameters
chooserspandas.DataFrame

Table of agents from which to find movers.

ratespandas.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_columnobject

Name of column in rates table that has relocation rates.

Returns
moverspandas.Index

Suitable for indexing choosers by index.