add_travel_matrix
site.SiteProblem.add_travel_matrix(
travel_matrix_df,
source_col,
skip_cols=None,
unit=None,
from_unit=None,
to_unit=None,
allow_missing=False,
treat_as_missing=None,
)Add a travel cost matrix to the problem and handle unit conversions.
This method integrates a matrix (typically time or distance) representing the travel cost between demand locations and candidate sites. It can automatically scale numeric columns if time unit conversion is required (e.g., converting seconds to minutes).
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| travel_matrix_df | pandas.DataFrame or geopandas.GeoDataFrame or str | The dataset containing travel costs, or a local or web path to its location. Usually structured as an origin-destination matrix or a long-format table. | required |
| source_col | str | The column name in travel_matrix_df that identifies the origin points (should correspond to IDs in the demand or site data). |
required |
| skip_cols | list of str | A list of column names to ignore during data loading. | None |
| unit | str | A label for the units used in the matrix (e.g., “miles”, “km”). Used if no conversion is performed. | None |
| from_unit | (seconds, minutes, hours) | The current time unit of the numeric values in the dataframe. | "seconds" |
| to_unit | (seconds, minutes, hours) | The target time unit for the numeric values in the dataframe. | "seconds" |
| allow_missing | bool | Whether to allow missing (NaN) travel costs – a demand location with no feasible journey to a given site (e.g. no public transport route within a permissive search radius). By default a missing value raises ValueError, since an unnoticed NaN usually means an ID mismatch or a botched generation run. Once allow_missing=True, min_cost/weighted_average/etc. skip unreachable rows rather than propagating NaN into every metric, and separate regions_unreachable/demand_unreachable metrics report how many/how much was excluded. solve() does not yet support optimising over a matrix with missing values – see its own error for the current workaround. |
False |
| treat_as_missing | scalar or callable | An existing missing-data sentinel already baked into travel_matrix_df (e.g. 9999), converted to a proper missing value before anything else runs. A scalar is matched by equality; a callable is applied to every cost cell and should return True for values that mean “missing” (e.g. lambda v: v >= 9000). Implies data containing missing values, so also pass allow_missing=True unless the conversion is expected to find nothing. |
None |
Returns
| Name | Type | Description |
|---|---|---|
| None |
Raises
| Name | Type | Description |
|---|---|---|
| ValueError | If the source_col is missing from the provided dataframe, or if the matrix contains missing (NaN) travel costs and allow_missing was not set. |
|
| KeyError | If the from_unit to to_unit combination is not supported by the internal conversion dictionary. |
Notes
If both from_unit and to_unit are provided, the method identifies all numeric columns in the dataframe and applies the appropriate multiplication factor. Supported conversions are limited to time-based units (seconds, minutes, hours).
The resulting data is stored in self.travel_matrix, and the resolved unit label is stored in self._travel_matrix_unit.