Embedder

Gtfs2vec embedder.

This module contains embedder from gtfs2vec paper [1].

References

1. https://doi.org/10.1145/3486640.3491392

GTFS2VecEmbedder(
    hidden_size=48,
    embedding_size=64,
    skip_autoencoder=False,
)

Bases: Embedder

GTFS2Vec Embedder.

PARAMETER	DESCRIPTION
hidden_size	Hidden size in encoder and decoder. Defaults to 48. TYPE: int DEFAULT: 48
embedding_size	Embedding size. Defaults to 64. TYPE: int DEFAULT: 64
skip_autoencoder	Skip using autoencoder as part of embedding. TYPE: bool DEFAULT: False

Source code in srai/embedders/gtfs2vec/embedder.py

def __init__(
    self, hidden_size: int = 48, embedding_size: int = 64, skip_autoencoder: bool = False
) -> None:
    """
    Init GTFS2VecEmbedder.

    Args:
        hidden_size (int, optional): Hidden size in encoder and decoder. Defaults to 48.
        embedding_size (int, optional): Embedding size. Defaults to 64.
        skip_autoencoder (bool, optional): Skip using autoencoder as part of embedding.
        Defaults to False.
    """
    import_optional_dependencies(
        dependency_group="torch", modules=["torch", "pytorch_lightning"]
    )
    self._model: Optional[GTFS2VecModel] = None
    self._hidden_size = hidden_size
    self._embedding_size = embedding_size
    self._skip_autoencoder = skip_autoencoder
    self._is_fitted = False

transform(regions_gdf, features_gdf, joint_gdf)

Embed a given data.

PARAMETER	DESCRIPTION
regions_gdf	Region indexes and geometries. TYPE: GeoDataFrame
features_gdf	Feature indexes, geometries and feature values. TYPE: GeoDataFrame
joint_gdf	Joiner result with region-feature multi-index. TYPE: GeoDataFrame

RETURNS	DESCRIPTION
DataFrame	pd.DataFrame: Embedding and geometry index for each region in regions_gdf.

RAISES	DESCRIPTION
ValueError	If any of the gdfs index names is None.
ValueError	If joint_gdf.index is not of type pd.MultiIndex or doesn't have 2 levels.
ValueError	If index levels in gdfs don't overlap correctly.
ValueError	If number of features is incosistent with the model.
ModelNotFitException	If model is not fit.

Source code in srai/embedders/gtfs2vec/embedder.py

def transform(
    self,
    regions_gdf: gpd.GeoDataFrame,
    features_gdf: gpd.GeoDataFrame,
    joint_gdf: gpd.GeoDataFrame,
) -> pd.DataFrame:
    """
    Embed a given data.

    Args:
        regions_gdf (gpd.GeoDataFrame): Region indexes and geometries.
        features_gdf (gpd.GeoDataFrame): Feature indexes, geometries and feature values.
        joint_gdf (gpd.GeoDataFrame): Joiner result with region-feature multi-index.

    Returns:
        pd.DataFrame: Embedding and geometry index for each region in regions_gdf.

    Raises:
        ValueError: If any of the gdfs index names is None.
        ValueError: If joint_gdf.index is not of type pd.MultiIndex or doesn't have 2 levels.
        ValueError: If index levels in gdfs don't overlap correctly.
        ValueError: If number of features is incosistent with the model.
        ModelNotFitException: If model is not fit.
    """
    self._validate_indexes(regions_gdf, features_gdf, joint_gdf)
    features = self._prepare_features(regions_gdf, features_gdf, joint_gdf)

    if self._skip_autoencoder:
        return features
    return self._embed(features)

fit(regions_gdf, features_gdf, joint_gdf)

Fit model to a given data.

PARAMETER	DESCRIPTION
regions_gdf	Region indexes and geometries. TYPE: GeoDataFrame
features_gdf	Feature indexes, geometries and feature values. TYPE: GeoDataFrame
joint_gdf	Joiner result with region-feature multi-index. TYPE: GeoDataFrame

RAISES	DESCRIPTION
ValueError	If any of the gdfs index names is None.
ValueError	If joint_gdf.index is not of type pd.MultiIndex or doesn't have 2 levels.
ValueError	If index levels in gdfs don't overlap correctly.

Source code in srai/embedders/gtfs2vec/embedder.py

def fit(
    self,
    regions_gdf: gpd.GeoDataFrame,
    features_gdf: gpd.GeoDataFrame,
    joint_gdf: gpd.GeoDataFrame,
) -> None:
    """
    Fit model to a given data.

    Args:
        regions_gdf (gpd.GeoDataFrame): Region indexes and geometries.
        features_gdf (gpd.GeoDataFrame): Feature indexes, geometries and feature values.
        joint_gdf (gpd.GeoDataFrame): Joiner result with region-feature multi-index.

    Raises:
        ValueError: If any of the gdfs index names is None.
        ValueError: If joint_gdf.index is not of type pd.MultiIndex or doesn't have 2 levels.
        ValueError: If index levels in gdfs don't overlap correctly.
    """
    self._validate_indexes(regions_gdf, features_gdf, joint_gdf)
    features = self._prepare_features(regions_gdf, features_gdf, joint_gdf)

    if not self._skip_autoencoder:
        self._model = self._train_model_unsupervised(features)

fit_transform(regions_gdf, features_gdf, joint_gdf)

Fit model and transform a given data.

PARAMETER	DESCRIPTION
regions_gdf	Region indexes and geometries. TYPE: GeoDataFrame
features_gdf	Feature indexes, geometries and feature values. TYPE: GeoDataFrame
joint_gdf	Joiner result with region-feature multi-index. TYPE: GeoDataFrame

RETURNS	DESCRIPTION
DataFrame	pd.DataFrame: Embedding and geometry index for each region in regions_gdf.

RAISES	DESCRIPTION
ValueError	If any of the gdfs index names is None.
ValueError	If joint_gdf.index is not of type pd.MultiIndex or doesn't have 2 levels.
ValueError	If index levels in gdfs don't overlap correctly.

Source code in srai/embedders/gtfs2vec/embedder.py

def fit_transform(
    self,
    regions_gdf: gpd.GeoDataFrame,
    features_gdf: gpd.GeoDataFrame,
    joint_gdf: gpd.GeoDataFrame,
) -> pd.DataFrame:
    """
    Fit model and transform a given data.

    Args:
        regions_gdf (gpd.GeoDataFrame): Region indexes and geometries.
        features_gdf (gpd.GeoDataFrame): Feature indexes, geometries and feature values.
        joint_gdf (gpd.GeoDataFrame): Joiner result with region-feature multi-index.

    Returns:
        pd.DataFrame: Embedding and geometry index for each region in regions_gdf.

    Raises:
        ValueError: If any of the gdfs index names is None.
        ValueError: If joint_gdf.index is not of type pd.MultiIndex or doesn't have 2 levels.
        ValueError: If index levels in gdfs don't overlap correctly.
    """
    self._validate_indexes(regions_gdf, features_gdf, joint_gdf)
    features = self._prepare_features(regions_gdf, features_gdf, joint_gdf)

    if self._skip_autoencoder:
        return features
    else:
        self._model = self._train_model_unsupervised(features)
        return self._embed(features)

save(path)

Save the model to a directory.

PARAMETER	DESCRIPTION
path	Path to the directory. TYPE: Path

Source code in srai/embedders/gtfs2vec/embedder.py

def save(self, path: Union[Path, str]) -> None:
    """
    Save the model to a directory.

    Args:
        path (Path): Path to the directory.
    """
    embedder_config = {
        "hidden_size": self._hidden_size,
        "embedding_size": self._embedding_size,
        "skip_autoencoder": self._skip_autoencoder,
    }
    self._save(path, embedder_config)

load(path)

classmethod

Load the model from a directory.

PARAMETER	DESCRIPTION
path	Path to the directory. TYPE: Path

RETURNS	DESCRIPTION
Hex2VecEmbedder	The loaded embedder. TYPE: GTFS2VecEmbedder

Source code in srai/embedders/gtfs2vec/embedder.py

@classmethod
def load(cls, path: Union[Path, str]) -> "GTFS2VecEmbedder":
    """
    Load the model from a directory.

    Args:
        path (Path): Path to the directory.

    Returns:
        Hex2VecEmbedder: The loaded embedder.
    """
    return cls._load(path, GTFS2VecModel)