champpy.Parameterizer

The Parameterizer class is the factory class to calculate the model parameters ModelParams required as input for the mobility model MobModel. The Parameterizer uses cleaned reference mobility profiles MobProfiles and user parameters UserParamsParameterizer as inputs.

Basic workflow:

1. Initialize the parameterizer Parameterizer with user parameters UserParamsParameterizer.

2. Call calculate_params() to calculate the model parameters ModelParams using the cleaned reference mobility profiles MobProfiles as input.

3. The calculated ModelParams instance can be further used for MobModel.

The model parameters ModelParams have the following structure:

ModelParams
├── df    # Dataframe holding the model parameters
└── info  # Meta information about the parameters

Besided the Parameterizer, existing parameters can be loaded using the ModelParamsLoader class.

class champpy.Parameterizer(user_params)

Class to determine the paramerters for the mobility model.

The Parameterizer is a factory class to calculate the parameters for the mobility model based on cleaned mobility data and user-defined parameters. The main method is calc_params(), which takes cleaned mobility data as input and returns the calculated parameters as ModelParams.

Parameters:

user_params (UserParamsParameterizer) – User paramerters for the parameterization

calc_params(ref_profiles)

Calculate parameters for the mobility model.

Main method to calculate parameters for the mobility model based on cleaned mobility data and user-defined parameters. The function performs the following steps for each cluster and weekday combination:

• Calculate percentage of clusters based on number of days per cluster

• Extend reference data to include weekday and day index

• Reindex locations to consecutive integers starting from 1 (keep 0 as is)

• Calculate transition matrices for each cluster and weekday combination

• Fit Beta distributions for speed parameters binned by trip duration

Parameters:

ref_profiles (MobProfiles) – Cleaned mobility data to be used as reference for the parameterization. Must be cleaned using MobProfilesCleaner before input.

Returns:

Calculated parameters and metadata stored in ModelParams dataclass.

Return type:

ModelParams

class champpy.UserParamsParameterizer(description, vehicle_type, temp_res=0.25, typeday=<factory>, speed_dist_edges_duration=<factory>)

User parameters for the parameterization of the mobility model.

This data class encapsulates all user-configurable parameters required by the Parameterizer to calculate mobility model parameters from reference data.

Examples

user_params = UserParamsParameterizer(
    description="Passenger cars weekday/weekend",
    vehicle_type="passenger car",
    temp_res=0.25,
    typeday=TypeDays(groups=[[0, 1, 2, 3, 4], [5, 6]])
)

description: str

Description of the parameter set.

Example: "Parameters for passenger cars based on example1 data"

speed_dist_edges_duration: list

Speed distribution bin edges by trip duration in hours.

Default: [0, 0.5, 1, 10] (bins: 0-30min, 30min-1h, 1h-10h)

temp_res: float = 0.25

Temporal resolution in hours.

Default: 0.25 (15-minute resolution)

typeday: TypeDays

Group weekdays using types of days (TypeDays).

Default: TypeDays(groups=[[0], [1], [2], [3], [4], [5], [6]]) (each day of the week separate)

Example: TypeDays(groups=[[0, 1, 2, 3, 4], [5, 6]]) (for weekdays/weekends)

vehicle_type: str

Type of vehicle the parameters apply to.

Example: "passenger car", "light commercial vehicle"

class champpy.ModelParams(df, info)

Calculated parameters used in the mobility model.

This dataclass combines the calculated parameter DataFrame with metadata information about the parameter set. This class is generated with Parameterizer and can be loaded with ParamsLoader.

df: DataFrame

DataFrame with calculated parameters.

The DataFrame is construced with the panderad schema ParamsSchema and contains the following columns:

Column	Type	Description
id_params	int	Unique identifier for the parameter set
id_cluster	int	Cluster identifier (≥1)
percentage	float	Percentage of this cluster (0-100)
speed_max	float	Maximum speed for normalization (≥0)
weekdays	list	List of weekday integers (0=Monday, 6=Sunday)
transition_matrix	ndarray	3D array with transition probabilities (timesteps, locations, locations)
speed_dist_param1	list	Beta distribution alpha parameters by duration bin
speed_dist_param2	list	Beta distribution beta parameters by duration bin
speed_dist_edges_duration	list	Duration bin edges in hours

info: ParamsInfo

Information about the parameter set.

class champpy.ParamsInfo(id_params, description, vehicle_type, temp_res, annual_km, locations, share_of_time_at_locations, number_typedays, number_clusters, labels_locations, labels_clusters, created_user=<factory>, created_dt=<factory>)

Metadata information for a mobility model parameter set.

This dataclass stores descriptive information and metadata about calculated mobility model parameters, such as temporal resolution, vehicle type, and clustering details.

annual_km: float

Annual kilometers driven as reference value.

created_dt: Timestamp

now).

Type:

Timestamp when the parameter set was created (default

created_user: str

current user).

Type:

Username who created the parameter set (default

description: str

Description of the parameter set.

id_params: int

Unique identifier for the parameter set.

labels_clusters: list[str]

Human-readable labels for each cluster.

labels_locations: list[str]

Human-readable labels for each location.

locations: list[int]

List of location IDs occurring in the mobility data.

number_clusters: int

Number of vehicle clusters in the parameterization.

number_typedays: int

Number of typedays used in the parameterization (1-7).

share_of_time_at_locations: list[float]

Share of time (0-1) vehicles spend at each location.

temp_res: float

Temporal resolution of the mobility data in hours.

vehicle_type: str

Type of vehicle the parameters apply to (e.g., "passenger car").