Model Related Utilities

Introduction

These are utility functions used within UrbanSim’s model packages. They may be useful when implementing new models or adding custom behavior to UrbanSim.

API

apply_filter_query(df[, filters])	Use the DataFrame.query method to filter a table down to the desired rows.
filter_table(table, filter_series[, ignore])	Filter a table based on a set of restrictions given in Series of column name / filter parameter pairs.
concat_indexes(indexes)	Concatenate a sequence of pandas Indexes.
str_model_expression(expr[, add_constant])	We support specifying model expressions as strings, lists, or dicts; but for use with patsy and statsmodels we need a string.
has_constant_expr(expr)	Report whether a model expression has constant specific term.
columns_in_filters(filters)	Returns a list of the columns used in a set of query filters.
columns_in_formula(formula)	Returns the names of all the columns used in a patsy formula.

Utilities used within the urbansim.models package.

urbansim.models.util.apply_filter_query(df, filters=None)

Use the DataFrame.query method to filter a table down to the desired rows.

Parameters:

df : pandas.DataFrame

filters : list of str or str, optional

List of filters to apply. Will be joined together with ‘ and ‘ and passed to DataFrame.query. A string will be passed straight to DataFrame.query. If not supplied no filtering will be done.

Returns:

filtered_df : pandas.DataFrame

urbansim.models.util.columns_in_filters(filters)

Returns a list of the columns used in a set of query filters.

Parameters:

filters : list of str or str

List of the filters as passed passed to apply_filter_query.

Returns:

columns : list of str

List of all the strings mentioned in the filters.

urbansim.models.util.columns_in_formula(formula)

Returns the names of all the columns used in a patsy formula.

Parameters:

formula : str, iterable, or dict

Any formula construction supported by str_model_expression.

Returns:

columns : list of str

urbansim.models.util.concat_indexes(indexes)

Concatenate a sequence of pandas Indexes.

Parameters:indexes : sequence of pandas.Index Returns:pandas.Index

urbansim.models.util.filter_table(table, filter_series, ignore=None)

Filter a table based on a set of restrictions given in Series of column name / filter parameter pairs. The column names can have suffixes _min and _max to indicate “less than” and “greater than” constraints.

Parameters:

table : pandas.DataFrame

Table to filter.

filter_series : pandas.Series

Series of column name / value pairs of filter constraints. 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.

ignore : sequence of str, optional

List of column names that should not be used for filtering.

Returns:

filtered : pandas.DataFrame

urbansim.models.util.has_constant_expr(expr)

Report whether a model expression has constant specific term. That is, a term explicitly specying whether the model should or should not include a constant. (e.g. ‘+ 1’ or ‘- 1’.)

Parameters:

expr : str

Model expression to check.

Returns:

has_constant : bool

urbansim.models.util.sorted_groupby(df, groupby)

Perform a groupby on a DataFrame using a specific column and assuming that that column is sorted.

Parameters:

df : pandas.DataFrame

groupby : object

Column name on which to groupby. This column must be sorted.

Returns:

generator

Yields pairs of group_name, DataFrame.

urbansim.models.util.str_model_expression(expr, add_constant=True)

We support specifying model expressions as strings, lists, or dicts; but for use with patsy and statsmodels we need a string. This function will take any of those as input and return a string.

Parameters:

expr : str, iterable, or dict

A string will be returned unmodified except to add or remove a constant. An iterable sequence will be joined together with ‘ + ‘. A dictionary should have right_side and, optionally, left_side keys. The right_side can be a list or a string and will be handled as above. If left_side is present it will be joined with right_side with ‘ ~ ‘.

add_constant : bool, optional

Whether to add a ‘ + 1’ (if True) or ‘ - 1’ (if False) to the model. If the expression already has a ‘+ 1’ or ‘- 1’ this option will be ignored.

Returns:

model_expression : str

A string model expression suitable for use with statsmodels and patsy.