Transport zones
Use TransportZones to define the area that will be covered by your model.
Module providing transport zones for the desired study area in France and Switzerland.
- class mobility.spatial.transport_zones.TransportZones(local_admin_unit_id: str | List[str] | None = None, level_of_detail: Literal[0, 1] | None = None, radius: float | None = None, inner_radius: float | None = None, inner_local_admin_unit_id: List[str] | None = None, backend: Literal['r', 'python'] | None = None, backend_workers: int | None = None, min_buildings_per_zone: int | None = None, cutout_geometries: gpd.GeoDataFrame = None, parameters: 'TransportZonesParameters' | None = None)
A FileAsset class for the management of transport zones.
This class is responsible for creating, caching, and retrieving transport zones based on specified criteria such as city ID, method, and radius.
The transport zone is based on either a list of local admin units ids or one local admin unit id and a radius within which all local admin unit ids should be included.
It uses either the reference R backend or the experimental Python backend to create the transport zones.
Parameters
- local_admin_unit_idUnion[str, List[str]]
- The geographical code of the centre local admin unit, or of all the local admin units to include. Examples:
“fr-09122” (Foix) “ch-6621” (Genève) [“fr-09122”, “fr-09121””, “fr-09130””, “fr-09273”, “fr-09329”] (set of adjacent communes)
- level_of_detailLiteral[0, 1], default=0
If 0, uses the communal level. If 1, creates intra-communal transport zones to enable more precision in calculations. If there are more than 20 000 m² of building within the commune, one sub-zone is created for every 20 000 m². These buildings are then grouped using k-medoids to ensure consistent clusters. We use Voronoi constellations around the clusters centers to finally create these sub-communal transport zones.
- radiusfloat, default=40.0
Local admin units within this radius (in km) of the center admin unit will be included.
- backend{“r”, “python”}, default=”r”
Backend used to create transport zones. The Python backend follows the same building clustering and Voronoi method, but its results are not exactly identical to the R backend.
Methods
- get_cached_asset()
Retrieve cached transport zones with the given inputs.
- create_and_get_asset()
Create and retrieve transport zones with the given inputs.
- create_and_get_asset() GeoDataFrame
Create and retrieve transport zones with the given inputs.
It uses the selected transport zone backend to do so.
Returns
- transport_zonesgeopandas.geodataframe.GeoDataFrame
Transport zones for the given local admin unit(s), radius, and level of detail.
- create_transport_zones_with_python(study_area_fp, osm_buildings_fp)
Create raw transport zones with the experimental Python backend.
- create_transport_zones_with_r(study_area_fp, osm_buildings_fp)
Create raw transport zones with the reference R backend.
- get_cached_asset() GeoDataFrame
Retrieve cached transport zones with the given inputs.
Returns
- transport_zonesgeopandas.geodataframe.GeoDataFrame
Transport zones for the given local admin unit(s), radius, and level of detail.
- get_study_area_countries() list[str]
Return the country codes present in the study area.
- class mobility.spatial.transport_zones.TransportZonesParameters(*, local_admin_unit_id: str | list[str], radius: Annotated[float, Ge(ge=5.0), Le(le=100.0)] = 40.0, level_of_detail: Literal[0, 1] = 0, backend: Literal['r', 'python'] = 'r', backend_workers: Annotated[int | None, Ge(ge=1)] = None, min_buildings_per_zone: Annotated[int, Ge(ge=1)] = 20, inner_radius: float | None = None, inner_local_admin_unit_id: list[str] | None = None)
- model_config = {'extra': 'forbid'}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
The TransportZones will call the StudyArea class to manage data in the area.
- class mobility.spatial.study_area.StudyArea(local_admin_unit_id: str | List[str] | None = None, radius: float | None = None, cutout_geometries: gpd.GeoDataFrame = None, parameters: 'StudyAreaParameters' | None = None)
A FileAsset class that manages study areas.
Works for either a set of local admin units, or for a center commune + a radius (by default 40 km).
The inputs are LocalAdminUnits, the local admin unit id and the radius: if the LocalAdminUnits asset, the list of local admin units or the centre commune+radius did not change, the class will reuse the existing asset.
- Attributes:
local_admin_unit_id (str or list of str): The geographical code of the centre commune, or of all the local admin units to include. radius (float): Local admin units within this radius (in km) of the center commune will be included. Only used when local_admin_unit_id contains a single geographical code. Default is 40.
- Methods:
get_cached_asset: Retrieve a cached transport zones GeoDataFrame. create_and_get_asset: Create and retrieve transport zones based on the current inputs. filter_within_radius: Filter local admin units within a specified radius. ids_to_countries: create_study_area_boundary:
- create_and_get_asset() GeoDataFrame
Creates study area based on the current inputs and retrieves it.
- Returns:
gpd.GeoDataFrame: The newly created transport zones.
- create_study_area_boundary(study_area: GeoDataFrame)
Creates a combined boundary polygon for all transport zones and saves it as a GeoJSON file.
This method merges the geometries of all provided transport zones into a single polygon, which represents the combined boundary of these zones. It then saves this boundary as a GeoJSON file to be used in subsequent operations.
- Args:
study_area (gpd.GeoDataFrame): A GeoDataFrame containing the geometries of the study area.
- Returns:
Returns nothing but saves the GeoJSON in the project folder as “study_area_boundary.geojson”
- filter_within_radius(local_admin_units: GeoDataFrame, local_admin_unit_id: str, radius: int) GeoDataFrame
Filters local admin units within a specified radius from a given city. It selects local admin units within the specified radius from the centroid of the target local admin unit.
- Args:
local_admin_units (gpd.GeoDataFrame): The GeoDataFrame containing city data. local_admin_unit_id (str): The geographic code of the target city. radius (int): The radius in kilometers around the target city.
- Returns:
gpd.GeoDataFrame: A GeoDataFrame of cities filtered within the specified radius.
- get_cached_asset() GeoDataFrame
Retrieves the study area from the cache.
- Returns:
gpd.GeoDataFrame: The cached study area.
StudyArea will itself call the LocalAdminUnits class to grab data from the local admin units.
- class mobility.spatial.local_admin_units.LocalAdminUnits
FileAsset class preparing local admin units in France and Switzerland.
Use .get() method to get its content (under Parquet format).
In France, uses adminexpress base from IGN, stored on https://cartes.gouv.fr/. For Paris, Lyon and Marseille, each ‘arrondissement’ is considered a distinct admin unit.
In Switzerland, uses swisstopo data stored on geo.admin.ch
Data from both countries is merged and stored in Parquet format under coordinates system EPSG:3035.