Module Reference

Computing Objects

class traccess.access.AccessComputer(supply: Supply, cost: Cost, demand: Demand | None = None)

Compute access to opportunity metrics.

The access computer uses supplied datasets on supply, cost, and optionally demand to compute popular access to opportunity measures.

Parameters:

• supply (Supply) – The supply or destination set to compute access to

• cost (Cost) – A matrix of cost values (travel time, other cost, etc)

• demand (Demand, optional) – The demand for destinations, used for competitive measures

property cost: Cost

Access or set the cost object

cost_to_closest(cost_column: str, supply_columns: list[str], n=1) → Access

Compute the cost to the nth closest destination.

This function is generic over any kind of numeric travel cost, such as distance, time and money.

Parameters:

• cost_column (str) – The column in the Cost object that contains the travel cost

• supply_columns (list[str]) – The columns in the Supply data to compute access to

• n (int, optional) – The nth closest to compute, by default 1

Returns:

An Access data object with an id_column matching the origin zone.

Return type:

Access

cumulative_cutoff(cost_columns: list[str], cutoffs: list[float], supply_columns: list[str] | None = None) → Access

Compute the total number of opportunities within a specified travel cost cutoff.

Parameters:

• cost_columns (list[str]) – A list of cost columns to apply cutoffs to. Can be a single string for a single column.

• cutoffs (list[float]) – A list of cutoff values corresponding to each cost column. Can be a single value for a single cutoff column. Must be the same length as cost_columns.

• supply_columns (list[str]) – An optional list of supply columns to use and return. If None, all supply columns are used. By default, None.

Returns:

An Access data object with an id_column matching the origin zone.

Return type:

Access

Raises:

ValueError – If the supplied column list and cutoff lists are not the same length.

property supply

Access or set the supply object

class traccess.access.EquityComputer(access: Access, demographic: Demographic)

Compute distributive equity metrics across population demographics

An EquityComputer allows for the combination of access measures and demographic data to compute various metrics of distributive equity or transportation justice.

Parameters:

• access (Access) – An Access object which contains data on access to opportunities.

• demographic (Demographic) – A Demographic data object which contains data on demographics and populations

fgt_poverty(access_column: str, poverty_line: float, alpha: float, is_dual=False) → Series

Compute a Foster-Greer-Thorbecke (FGT) index for all demographics.

FGT measures consider the average amount of poverty in a given population by comparing the distance of each individual from the poverty line, raised to some exponent alpha. Common values of alpha are 0, 1, and 2.

When alpha = 0, the function returns the poverty rate

When alpha = 1, the function returns the poverty gap index

When alpha = 2, the function returns the poverty gap weighted by the poverty gap.

Parameters:

• access_column (str) – The access to opportunity column to compare the measure against

• poverty_line (float) – The poverty line to compare the access measure against

• alpha (float) – The alpha parameter, or the extent which to weight those further below the poverty line

• is_dual (bool, optional) – Whether the measure is a dual measure, where lower values are better, by default False

Returns:

A series with an index for each demographic column, containing the specified measure.

Return type:

pandas.Series

in_poverty(access_column: str, poverty_line: float, is_dual=False) → Series

Compute the number of individuals in poverty in any given demographic.

Parameters:

• access_column (str) – The access column to compare the poverty line to

• poverty_line (float) – The poverty line

• is_dual (bool, optional) – Whether the measure is a dual measure, where lower values are better, by default False

Returns:

A series with each row consisting of a demogrphic group, containing the number of that group in poverty.

Return type:

pandas.Series

poverty_index(access_column: str, poverty_line: float, is_dual=False) → Series

Compute the poverty index at each location.

This method computes the poverty index for each location, which is the difference between the poverty line and the supplied access value, divided by the poverty line.

Values above the poverty line are returned as null values.

Parameters:

• access_column (str) – The column to compare the poverty line to

• poverty_line (float) – The poverty line value for access

• is_dual (bool, optional) – Whether the measure is a dual measure, where lower values are better, by default False

Returns:

A pandas Series containing the poverty index for each location

Return type:

pandas.Series

weighted_average(access_column: str) → Series

Compute the population group-weighted average access for all groups.

Parameters:

access_column (str) – The access value to weight

Returns:

A series with a row for demographic group, with the weighted average access.

Return type:

pandas.Series

weighted_quantile(access_column: str, quantile=0.5, is_dual=False) → Series

Compute a population-weighted quantile for all demographics.

Population-weighted quantiles are not interpolated, meaning that the values returned by this function are the highest value in the dataset not exceeding the quantile value.

Parameters:

• access_column (str) – The column to compute the quantile over

• quantile (float, optional) – The quantile to use, by default 0.5

• is_dual (bool, optional) – Whether the measure is a dual measure, where lower values are better, by default False

Returns:

A series containing each demographic group and the access value of that quantile.

Return type:

pandas.Series

Data Objects

class traccess.data.AbstractDataSet(dataframe: DataFrame, id_column='id')

Bases: ABC

An abstract data set

Parameters:

• dataframe (pandas.DataFrame) – The dataframe containing the data

• id_column (str, optional) – The column which should be used as a unique ID, by default “id”

classmethod from_csv(csv_filepath, id_column='id', **kwargs)

Create a Supply object from a csv file

Parameters:

• csv_filepath (str or path) – The filepath of the CSV to parse

• id_column (str, optional) – The column used as the reference id, by default “id”

Returns:

A supply object containing opportunities or land use data

Return type:

Supply

normalize(columns=None, min=0.0, max=1.0)

Normalize one or more columns between a range

This method scales a column based on its minimum and maximum values.

Parameters:

• columns (list, optional) – The list of columns to normalise. If None, all columns are used, by default None

• min (float, optional) – The minimum of the scaled range, by default 0

• max (float, optional) – The maximum of the scaled range, by default 1

class traccess.data.AbstractMatrix(dataframe: DataFrame, from_id='from_id', to_id='to_id')

Bases: ABC

A representation of a matrix object.

Parameters:

• dataframe (pandas.DataFrame) – The dataframe for the matrix object

• from_id (str, optional) – The first reference id (the origin), by default “from_id”

• to_id (str, optional) – The second reference id (the destination), by default “to_id”

property columns: list

The list of columns in the dataset

property data: DataFrame

The object’s dataframe

classmethod from_csv(csv_filepath, from_id='from_id', to_id='to_id', **kwargs)

Load data and create an object from a CSV file

Parameters:

• csv_filepath (str) – The filepath of the CSV file to load

• from_id (str, optional) – The column name of the origin, by default “from_id”

• to_id (str, optional) – The column name of the destination, by default “to_id”

Returns:

A matrix dataset.

Return type:

AbstractMatrix

classmethod from_parquet(parquet_filepath, from_id='from_id', to_id='to_id', **kwargs)

Load data and create an object from a Parquet file

Parameters:

• csv_filepath (str) – The filepath of the Parquet file to load

• from_id (str, optional) – The column name of the origin, by default “from_id”

• to_id (str, optional) – The column name of the destination, by default “to_id”

Returns:

A matrix dataset.

Return type:

AbstractMatrix

class traccess.data.Access(dataframe: DataFrame, id_column='id')

Bases: AbstractDataSet

classmethod from_csv(csv_filepath, id_column='id', **kwargs)

Create a Supply object from a csv file

Parameters:

• csv_filepath (str or path) – The filepath of the CSV to parse

• id_column (str, optional) – The column used as the reference id, by default “id”

Returns:

A supply object containing opportunities or land use data

Return type:

Supply

normalize(columns=None, min=0.0, max=1.0)

Normalize one or more columns between a range

This method scales a column based on its minimum and maximum values.

Parameters:

• columns (list, optional) – The list of columns to normalise. If None, all columns are used, by default None

• min (float, optional) – The minimum of the scaled range, by default 0

• max (float, optional) – The maximum of the scaled range, by default 1

class traccess.data.Cost(dataframe: DataFrame, from_id='from_id', to_id='to_id')

Bases: AbstractMatrix

property columns: list

The list of columns in the dataset

property data: DataFrame

The object’s dataframe

classmethod from_csv(csv_filepath, from_id='from_id', to_id='to_id', **kwargs)

Load data and create an object from a CSV file

Parameters:

• csv_filepath (str) – The filepath of the CSV file to load

• from_id (str, optional) – The column name of the origin, by default “from_id”

• to_id (str, optional) – The column name of the destination, by default “to_id”

Returns:

A matrix dataset.

Return type:

AbstractMatrix

classmethod from_parquet(parquet_filepath, from_id='from_id', to_id='to_id', **kwargs)

Load data and create an object from a Parquet file

Parameters:

• csv_filepath (str) – The filepath of the Parquet file to load

• from_id (str, optional) – The column name of the origin, by default “from_id”

• to_id (str, optional) – The column name of the destination, by default “to_id”

Returns:

A matrix dataset.

Return type:

AbstractMatrix

median(use_to_id=False) → DataFrame

Compute the median cost values across all origins or destinations.

This function is a shorthand for Cost.quantile(quantile=0.5)

Parameters:

use_to_id (bool, optional) – If true, group by the destination column instead of the origin, by default False

Returns:

A dataframe with an index for each id and a median value

Return type:

pandas.DataFrame

quantile(quantile: float, use_to_id=False) → DataFrame

Compute the quantile cost values across all origins or destinations

Parameters:

• quantile (float) – The quantile to compute (0 to 1)

• use_to_id (bool, optional) – If true, group by the destination column instead of the origin, by default False

Returns:

A dataframe with an index for each id and the quantile value

Return type:

pandas.DataFrame

class traccess.data.Demand(dataframe: DataFrame, id_column='id')

Bases: AbstractDataSet

classmethod from_csv(csv_filepath, id_column='id', **kwargs)

Create a Supply object from a csv file

Parameters:

• csv_filepath (str or path) – The filepath of the CSV to parse

• id_column (str, optional) – The column used as the reference id, by default “id”

Returns:

A supply object containing opportunities or land use data

Return type:

Supply

normalize(columns=None, min=0.0, max=1.0)

Normalize one or more columns between a range

This method scales a column based on its minimum and maximum values.

Parameters:

• columns (list, optional) – The list of columns to normalise. If None, all columns are used, by default None

• min (float, optional) – The minimum of the scaled range, by default 0

• max (float, optional) – The maximum of the scaled range, by default 1

class traccess.data.Demographic(dataframe: DataFrame, id_column='id')

Bases: AbstractDataSet

classmethod from_csv(csv_filepath, id_column='id', **kwargs)

Create a Supply object from a csv file

Parameters:

• csv_filepath (str or path) – The filepath of the CSV to parse

• id_column (str, optional) – The column used as the reference id, by default “id”

Returns:

A supply object containing opportunities or land use data

Return type:

Supply

normalize(columns=None, min=0.0, max=1.0)

Normalize one or more columns between a range

This method scales a column based on its minimum and maximum values.

Parameters:

• columns (list, optional) – The list of columns to normalise. If None, all columns are used, by default None

• min (float, optional) – The minimum of the scaled range, by default 0

• max (float, optional) – The maximum of the scaled range, by default 1

class traccess.data.Supply(dataframe: DataFrame, id_column='id')

Bases: AbstractDataSet

classmethod from_csv(csv_filepath, id_column='id', **kwargs)

Create a Supply object from a csv file

Parameters:

• csv_filepath (str or path) – The filepath of the CSV to parse

• id_column (str, optional) – The column used as the reference id, by default “id”

Returns:

A supply object containing opportunities or land use data

Return type:

Supply

normalize(columns=None, min=0.0, max=1.0)

Normalize one or more columns between a range

This method scales a column based on its minimum and maximum values.

Parameters:

• columns (list, optional) – The list of columns to normalise. If None, all columns are used, by default None

• min (float, optional) – The minimum of the scaled range, by default 0

• max (float, optional) – The maximum of the scaled range, by default 1