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

dfpandas.DataFrame

filterslist 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_dfpandas.DataFrame

urbansim.models.util.columns_in_filters(filters)

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

Parameters

filterslist of str or str

List of the filters as passed passed to apply_filter_query.

Returns

columnslist 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

formulastr, iterable, or dict

Any formula construction supported by str_model_expression.

Returns

columnslist of str

urbansim.models.util.concat_indexes(indexes)

Concatenate a sequence of pandas Indexes.

Parameters

indexessequence 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

tablepandas.DataFrame

Table to filter.

filter_seriespandas.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.

ignoresequence of str, optional

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

Returns

filteredpandas.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

exprstr

Model expression to check.

Returns

has_constantbool

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

dfpandas.DataFrame

groupbyobject

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

exprstr, 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_constantbool, 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_expressionstr

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