add_travel_matrix

site.SiteProblem.add_travel_matrix(
    travel_matrix_df,
    source_col,
    skip_cols=None,
    unit=None,
    from_unit=None,
    to_unit=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"

Returns

Name	Type	Description
	None

Raises

Name	Type	Description
	ValueError	If the source_col is missing from the provided dataframe.
	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.