Trips
PopulationGroupDayTrips
Group-level day plans for a given population can be generated using
the class PopulationGroupDayTrips.
- class mobility.trips.group_day_trips.BehaviorChangePhase(*, start_iteration: Annotated[int, Ge(ge=1)], scope: BehaviorChangeScope)
Behavior-change phase applied from
start_iterationonward.
- model_config = {'extra': 'forbid'}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class mobility.trips.group_day_trips.BehaviorChangeScope(*values)
Highest adaptation layer allowed during one behavior-change phase.
- class mobility.trips.group_day_trips.GroupDayTripsActivitySequenceParameters(*, k_activity_sequences: Annotated[int | None, Ge(ge=1)] = 3)
Settings used when sampling activity sequences.
- model_config = {'extra': 'forbid'}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class mobility.trips.group_day_trips.GroupDayTripsBehaviorChangeParameters(*, phases: list[BehaviorChangePhase] | None = None)
Per-iteration behavior-change policy.
- model_config = {'extra': 'forbid'}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- scope_at(iteration: int) BehaviorChangeScope
Return the active behavior-change scope for one iteration.
- validate_phases() GroupDayTripsBehaviorChangeParameters
Ensure phase definitions are sorted and non-overlapping.
- class mobility.trips.group_day_trips.GroupDayTripsDestinationSequenceParameters(*, alpha: Annotated[float, Ge(ge=0)] = 0.5, k_destination_sequences: Annotated[int, Ge(ge=1)] = 3, refresh_active_mode_alternatives: bool = False, dest_prob_cutoff: Annotated[float, Gt(gt=0.0), Le(le=1.0)] = 0.99, cost_uncertainty_sd: Annotated[float, Gt(gt=0)] = 1.0)
Settings used when sampling destination sequences.
- model_config = {'extra': 'forbid'}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class mobility.trips.group_day_trips.GroupDayTripsModeSequenceParameters(*, k_mode_sequences: Annotated[int, Ge(ge=1)] = 3, mode_sequence_search_parallel: bool = True, use_rust_mode_sequence_search: bool = False)
Settings used when searching mode sequences.
- model_config = {'extra': 'forbid'}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class mobility.trips.group_day_trips.GroupDayTripsOutputParameters(*, cache_iteration_events: bool = False)
Settings for optional cached outputs from the iteration loop.
- model_config = {'extra': 'forbid'}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class mobility.trips.group_day_trips.GroupDayTripsParameters(*, run: GroupDayTripsRunParameters = <factory>, periods: GroupDayTripsPeriodParameters = <factory>, outputs: GroupDayTripsOutputParameters = <factory>, behavior_change: GroupDayTripsBehaviorChangeParameters = <factory>, activity_sequences: GroupDayTripsActivitySequenceParameters = <factory>, destination_sequences: GroupDayTripsDestinationSequenceParameters = <factory>, mode_sequences: GroupDayTripsModeSequenceParameters = <factory>, plan_update: GroupDayTripsPlanUpdateParameters = <factory>)
Root settings for the grouped day-trips model.
- model_config = {'extra': 'forbid'}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- with_replication(replication: int) GroupDayTripsParameters
Return validated single-replication parameters for one replication.
- class mobility.trips.group_day_trips.GroupDayTripsPeriodParameters(*, simulate_weekend: bool = False, weekday_weight: Annotated[float, Gt(gt=0)] = 0.7142857142857143, weekend_weight: Annotated[float, Gt(gt=0)] = 0.2857142857142857, annual_weight: Annotated[float, Gt(gt=0)] = 365.0)
Day-type and reporting-period settings.
- model_config = {'extra': 'forbid'}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class mobility.trips.group_day_trips.GroupDayTripsPlanUpdateParameters(*, n_warmup_iterations: Annotated[int, Ge(ge=0)] = 1, max_inactive_age: Annotated[int, Ge(ge=0)] = 2, min_activity_time_constant: Annotated[float, Ge(ge=0)] = 1.0, update_plan_timings_from_modeled_travel_times: bool = False, use_destination_shadow_prices: bool = False, transition_distance_threshold: Annotated[float, Ge(ge=0)] = inf, enable_transition_distance_model: bool = False, transition_revision_probability: Annotated[float, Ge(ge=0.0), Le(le=1.0)] = 0.3, transition_logit_scale: Annotated[float, Ge(ge=0)] = 1.0, transition_utility_pruning_delta: Annotated[float, Ge(ge=0)] = 3.0, min_transition_utility_gain: Annotated[float, Ge(ge=0)] = 0.0, transition_distance_friction: Annotated[float, Ge(ge=0)] = 0.5, plan_embedding_dimension_weights: list[float] | None = None, plan_probability_pruning_retained_share: Annotated[float, Gt(gt=0.0), Le(le=1.0)] = 1.0, plan_probability_pruning_min_iteration: Annotated[int, Ge(ge=1)] = 2)
Settings used when updating day-to-day plans.
- model_config = {'extra': 'forbid'}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class mobility.trips.group_day_trips.GroupDayTripsResults(*, run: Callable, day_type: str, scenarios: str | list[str] | tuple[str, ...] | None, n_replications: int, scenario_manifest: Scenarios | None = None, replication: int | None = None, replications: list[int] | range | None = None)
Analysis entry point for one or more scenarios, one day type, and one or more runs.
- property first_run
Return the first concrete run in the result set.
- has_multiple_iterations(iterations: str | int | list[int] | range = 'last') bool
Return whether one result query contains several iterations.
- property is_weekday: bool
Return whether this result scope is for weekday runs.
- property last_iteration: int
Return the configured last model iteration.
- property run_contexts: list[ResultRun]
Return the concrete runs included in this result set.
- property scenario_titles: dict[str, str]
Return display titles for selected scenarios.
- selected_iterations(iterations: str | int | list[int] | range = 'last') list[int]
Return concrete iteration numbers for one result query.
- property survey_reference_plan_steps
Return the survey-weighted plan-step asset for this result scope.
- property surveys
Return the surveys used by this result scope.
- property transport_zones
Return the transport-zone asset used by this result scope.
- uses_last_iteration(iterations: str | int | list[int] | range = 'last') bool
Return whether a result query uses normal final run outputs.
- class mobility.trips.group_day_trips.GroupDayTripsRunParameters(*, n_iterations: Annotated[int, Ge(ge=1)] = 1, n_iter_per_cost_update: Annotated[int, Ge(ge=0)] = 3, seed: Annotated[int, Ge(ge=0)] = 0, n_replications: Annotated[int, Ge(ge=1)] = 1, seeds: list[int] | None = None)
Run length, cost refresh, and stochastic replication settings.
- model_config = {'extra': 'forbid'}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- seed_for_replication(replication: int) int
Return the seed used by one stochastic replication.
- validate_replication_seeds() GroupDayTripsRunParameters
Validate single-run and multi-run seed settings.
- with_replication(replication: int) GroupDayTripsRunParameters
Return single-replication run parameters for one replication.
- class mobility.trips.group_day_trips.PopulationGroupDayTrips(population: Population, modes: list[TransportMode] | None = None, activities: list[Activity] | None = None, surveys: list[MobilitySurvey] | None = None, parameters: GroupDayTripsParameters | None = None, scenarios: Scenarios | None = None)
Top-level setup for grouped day-trip simulations.
This object stores the population, transport modes, activities, surveys, and grouped day-trip parameters. It creates concrete weekday and weekend runs on demand when a day type, scenario, and stochastic replication are selected. Model execution happens through the returned run, for example with population_trips.run(“weekday”).get(). If no scenario is given, the setup uses the package default scenario named “default”.
- remove()
Remove cached run outputs for this setup.
This removes all runs that can be inferred from the setup: the default scenario, scenarios found in parameter values, configured replications, enabled day types, and any runs already built in this Python session.
- results(day_type: str | DayType = DayType.WEEKDAY, *, scenarios: str | list[str] | tuple[str, ...] | None = None, replication: int | None = None, replications: list[int] | range | None = None) GroupDayTripsResults
Return result helpers for one day type, scenario set, and replication set.
Omitting scenarios selects the default scenario named “default”. Omitting replication and replications selects all stochastic replications declared in parameters.run.
- run(day_type: str | DayType, *, scenario: str | None = None, replication: int = 0) Run
Return one weekday or weekend run.
The run is built on first access, then reused if the same day_type, scenario, and replication are requested again. Omitting scenario selects the default scenario named “default”. Plain parameter values are shared by all scenarios. Scenario-varying ParameterValue objects must define the requested scenario.
- Args:
day_type: “weekday” or “weekend”. scenario: Scenario name to resolve scenario-varying values. If
omitted, “default” is used.
- replication: Stochastic replication index. Replication seeds are
taken from parameters.run.
- Returns:
Run: Concrete run for the selected day type and context.
Use Parameters to change the model configuration.
- class mobility.trips.group_day_trips.core.parameters.BehaviorChangePhase(*, start_iteration: Annotated[int, Ge(ge=1)], scope: BehaviorChangeScope)
Behavior-change phase applied from
start_iterationonward.
- model_config = {'extra': 'forbid'}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class mobility.trips.group_day_trips.core.parameters.BehaviorChangeScope(*values)
Highest adaptation layer allowed during one behavior-change phase.
- class mobility.trips.group_day_trips.core.parameters.GroupDayTripsActivitySequenceParameters(*, k_activity_sequences: Annotated[int | None, Ge(ge=1)] = 3)
Settings used when sampling activity sequences.
- model_config = {'extra': 'forbid'}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class mobility.trips.group_day_trips.core.parameters.GroupDayTripsBehaviorChangeParameters(*, phases: list[BehaviorChangePhase] | None = None)
Per-iteration behavior-change policy.
- model_config = {'extra': 'forbid'}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- scope_at(iteration: int) BehaviorChangeScope
Return the active behavior-change scope for one iteration.
- validate_phases() GroupDayTripsBehaviorChangeParameters
Ensure phase definitions are sorted and non-overlapping.
- class mobility.trips.group_day_trips.core.parameters.GroupDayTripsDestinationSequenceParameters(*, alpha: Annotated[float, Ge(ge=0)] = 0.5, k_destination_sequences: Annotated[int, Ge(ge=1)] = 3, refresh_active_mode_alternatives: bool = False, dest_prob_cutoff: Annotated[float, Gt(gt=0.0), Le(le=1.0)] = 0.99, cost_uncertainty_sd: Annotated[float, Gt(gt=0)] = 1.0)
Settings used when sampling destination sequences.
- model_config = {'extra': 'forbid'}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class mobility.trips.group_day_trips.core.parameters.GroupDayTripsModeSequenceParameters(*, k_mode_sequences: Annotated[int, Ge(ge=1)] = 3, mode_sequence_search_parallel: bool = True, use_rust_mode_sequence_search: bool = False)
Settings used when searching mode sequences.
- model_config = {'extra': 'forbid'}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class mobility.trips.group_day_trips.core.parameters.GroupDayTripsOutputParameters(*, cache_iteration_events: bool = False)
Settings for optional cached outputs from the iteration loop.
- model_config = {'extra': 'forbid'}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class mobility.trips.group_day_trips.core.parameters.GroupDayTripsParameters(*, run: GroupDayTripsRunParameters = <factory>, periods: GroupDayTripsPeriodParameters = <factory>, outputs: GroupDayTripsOutputParameters = <factory>, behavior_change: GroupDayTripsBehaviorChangeParameters = <factory>, activity_sequences: GroupDayTripsActivitySequenceParameters = <factory>, destination_sequences: GroupDayTripsDestinationSequenceParameters = <factory>, mode_sequences: GroupDayTripsModeSequenceParameters = <factory>, plan_update: GroupDayTripsPlanUpdateParameters = <factory>)
Root settings for the grouped day-trips model.
- model_config = {'extra': 'forbid'}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- with_replication(replication: int) GroupDayTripsParameters
Return validated single-replication parameters for one replication.
- class mobility.trips.group_day_trips.core.parameters.GroupDayTripsPeriodParameters(*, simulate_weekend: bool = False, weekday_weight: Annotated[float, Gt(gt=0)] = 0.7142857142857143, weekend_weight: Annotated[float, Gt(gt=0)] = 0.2857142857142857, annual_weight: Annotated[float, Gt(gt=0)] = 365.0)
Day-type and reporting-period settings.
- model_config = {'extra': 'forbid'}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class mobility.trips.group_day_trips.core.parameters.GroupDayTripsPlanUpdateParameters(*, n_warmup_iterations: Annotated[int, Ge(ge=0)] = 1, max_inactive_age: Annotated[int, Ge(ge=0)] = 2, min_activity_time_constant: Annotated[float, Ge(ge=0)] = 1.0, update_plan_timings_from_modeled_travel_times: bool = False, use_destination_shadow_prices: bool = False, transition_distance_threshold: Annotated[float, Ge(ge=0)] = inf, enable_transition_distance_model: bool = False, transition_revision_probability: Annotated[float, Ge(ge=0.0), Le(le=1.0)] = 0.3, transition_logit_scale: Annotated[float, Ge(ge=0)] = 1.0, transition_utility_pruning_delta: Annotated[float, Ge(ge=0)] = 3.0, min_transition_utility_gain: Annotated[float, Ge(ge=0)] = 0.0, transition_distance_friction: Annotated[float, Ge(ge=0)] = 0.5, plan_embedding_dimension_weights: list[float] | None = None, plan_probability_pruning_retained_share: Annotated[float, Gt(gt=0.0), Le(le=1.0)] = 1.0, plan_probability_pruning_min_iteration: Annotated[int, Ge(ge=1)] = 2)
Settings used when updating day-to-day plans.
- model_config = {'extra': 'forbid'}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class mobility.trips.group_day_trips.core.parameters.GroupDayTripsRunParameters(*, n_iterations: Annotated[int, Ge(ge=1)] = 1, n_iter_per_cost_update: Annotated[int, Ge(ge=0)] = 3, seed: Annotated[int, Ge(ge=0)] = 0, n_replications: Annotated[int, Ge(ge=1)] = 1, seeds: list[int] | None = None)
Run length, cost refresh, and stochastic replication settings.
- model_config = {'extra': 'forbid'}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- seed_for_replication(replication: int) int
Return the seed used by one stochastic replication.
- validate_replication_seeds() GroupDayTripsRunParameters
Validate single-run and multi-run seed settings.
- with_replication(replication: int) GroupDayTripsRunParameters
Return single-replication run parameters for one replication.
Helpers
PopulationGroupDayTrips produces results through RunResults and stores
transition events that can be analyzed with the evaluation helpers.
- class mobility.trips.group_day_trips.core.results.RunResults(*, inputs_hash, is_weekday: bool, transport_zones, demand_groups, plan_steps, opportunities, costs, population_weighted_plan_steps, transitions, surveys, modes, parameters, run, expected_calibration_plan_steps=None, observed_calibration_plan_steps=None, iteration_metrics: IterationMetricsHistory | None = None, expected_entropy_plan_steps=None, observed_entropy_plan_steps=None)
Run-scoped analysis root that exposes grouped metrics, transitions, and diagnostics.
- property period: str
Return the string period label expected by plotting methods.
IndividualYearTrips
Individual trips can be sampled using the class IndividualYearTrips.
Use .get() to access the generated dataframe.
- class mobility.trips.individual_year_trips.DefaultGWP(values: Dict[str, float]=<factory>)
- class mobility.trips.individual_year_trips.EMPMobilitySurvey(parameters: MobilitySurveyParameters | None = None)
A class for managing and processing mobility survey data for the EMP-2019 and ENTD-2008 surveys.
- Attributes:
source (str): The source of the mobility survey data (e.g., “EMP-2019” or “ENTD-2008”). cache_path (dict): A dictionary mapping data identifiers to their file paths in the cache.
- Methods:
get_cached_asset: Returns the cached asset data as a dictionary of pandas DataFrames. create_and_get_asset: Prepares mobility survey data from scratch, caches it, and returns it. download_survey_data: Downloads survey data zip files from specified URLs. prepare_survey_data: Prepares survey data by calling specific methods based on the source. prepare_survey_data_ENTD_2008: Processes and formats ENTD-2008 survey data. prepare_survey_data_EMP_2019: Processes and formats EMP-2019 survey data.
- create_and_get_asset() dict[str, DataFrame]
Prepares mobility survey data by downloading, processing, and caching it, then returns the cached data.
- Returns:
dict: A dictionary where keys are data identifiers and values are pandas DataFrames of the prepared and cached data.
- download_survey_data(dataset_path: Path) None
Downloads the survey data zip file from a specified URL and extracts it to a designated folder.
- Args:
source (str): The source identifier of the mobility survey data (e.g., “EMP-2019” or “ENTD-2008”).
- Returns:
None
- parse_survey_data(dataset_path: Path) None
Processes and formats the EMP-2019 mobility survey data, then saves the data to parquet files in the cache directory.
- Args:
data_folder_path (pathlib.Path): The path to the folder containing the extracted EMP-2019 survey data files.
- Returns:
None
- class mobility.trips.individual_year_trips.FileAsset(inputs: dict, cache_path: Path | dict[str, Path])
Abstract base class representing an Asset, with functionality for cache validation based on input hash comparison.
- Attributes:
inputs (Dict): A dictionary of inputs used to generate the Asset. cache_path (pathlib.Path): The file path for storing the Asset. hash_path (pathlib.Path): The file path for storing the hash of the inputs. inputs_hash (str): The hash of the inputs.
- Methods:
get_cached_asset: Abstract method to retrieve a cached Asset. create_and_get_asset: Abstract method to create and retrieve an Asset. get: Retrieves the cached Asset or creates a new one if needed. compute_inputs_hash: Computes a hash based on the inputs. is_update_needed: Checks if an update is needed based on the input hash. get_cached_hash: Retrieves the cached hash from the file system. update_hash: Updates the cached hash with a new hash value.
- assets_missing()
Check whether the cached output file(s) exist.
- Returns:
bool: True if any expected cache file is missing, False otherwise.
- get(*args, **kwargs) Any
Retrieve the asset, ensuring that all upstream dependencies are up to date.
This method first checks and rebuilds any ancestor FileAssets that are stale, then retrieves the current asset. If the asset itself is outdated or missing, it is rebuilt and its input hash is updated.
- Returns:
Any: The cached or newly created asset.
- get_cached_hash() str
Retrieves the cached hash of the Asset’s inputs from the file system.
- Returns:
The cached hash string if it exists, otherwise None.
- inputs_changed()
Check whether the asset’s input hash differs from the cached version.
- Returns:
bool: True if the cached hash does not match the current input hash.
- is_update_needed() bool
Determine whether the asset requires an update.
An update is needed if the recorded input hash differs from the current one or if the cached output file(s) are missing.
- Returns:
bool: True if the asset is outdated or missing, False otherwise.
- update_ancestors_if_needed()
Identify and rebuild stale ancestor FileAssets in dependency order.
Builds a directed acyclic graph (DAG) of upstream FileAssets and determines which ones require updates. Those assets, along with all their descendants, are rebuilt in topological order. Each rebuilt asset also has its input hash refreshed after creation.
- Raises:
RuntimeError: If a dependency cycle is detected among FileAssets.
- update_hash(new_hash: str) None
Updates the cached hash of the Asset’s inputs with a new hash.
- Args:
new_hash (str): The new hash string to be cached.
- class mobility.trips.individual_year_trips.IndividualYearTrips(population: FileAsset, surveys: Dict[str, MobilitySurvey] = None, filter_population: Callable[[DataFrame], DataFrame] = None, gwp: DefaultGWP = DefaultGWP(values={'1.10': 0.0, '1.11': 0.0, '1.12': 0.0, '1.13': 0.0, '2.20': 0.00017, '2.22': 0.0763, '2.23': 0.0763, '2.24': 0.191, '2.25': 0.191, '2.29': 0.191, '3.30': 0.218, '3.31': 0.218, '3.32': 0.218, '3.33': 0.218, '3.39': 0.218, '4.40': 0.218, '4.41': 0.218, '4.42': 0.113, '4.43': 0.113, '5.50': 0.113, '5.51': 0.113, '5.52': 0.0294, '5.53': 0.0294, '5.54': 0.0294, '5.55': 0.00428, '5.56': 0.00444, '5.57': 0.00978, '5.58': 0.0277, '5.59': 0.0294, '6.60': 0.00293, '6.61': 0.00293, '6.62': 0.00898, '6.63': 0.00898, '6.69': 0.00898, '7.70': 0.152, '8.80': 0.218, '9.90': 0.218}))
A class to model and generate trips based on a population asset and mobility survey data.
- Attributes:
population (Asset): The population for which trips will be generated. source (str): The source of the mobility survey data (default is “EMP-2019”). cache_path (pathlib.Path): Path to cache the generated trips data.
- Methods:
get_cached_asset: Returns the cached trips data as a pandas DataFrame. create_and_get_asset: Generates trips for the population and caches the data. prepare_survey_data: Prepares the necessary mobility survey data for trip generation. get_population_trips: Generates trips for each individual in the population. get_individual_trips: Samples trips for an individual based on their profile.
- create_and_get_asset() DataFrame
Generates trips for each individual in the population based on the mobility survey data, then caches the data.
- Returns:
pd.DataFrame: The generated trips for the population.
- get_cached_asset() DataFrame
Fetches the cached trips data.
- Returns:
pd.DataFrame: The cached trips data as a pandas DataFrame.
- get_individual_trips(csp, csp_household, urban_unit_category, n_pers, n_cars, country, df_days) DataFrame
Samples long distance trips and short distance trips from survey data (prepared with prepare_survey_data), for a specific person’s profile (CSP, urban unit category, number of persons and cars of the household).
Determines the number of cars using the repartition for this urban unit category, CSP and number of persons. If data is not sufficient for that triplet, only uses urban unit category and CSP.
Computes the number of travels (n_travels) during the n_years thanks to the travels_db. n_travels are sampled. The long_trips associated to these travels are added to the data.
Thanks to these travels, the number of professional and personal days of travel may be known. Local trips made at the travel destination are not included in the source data, so they are estimated: for each day at destination, local trips are produced (weekdays for professional travel, week-end days for personal). The urban unit category of the destination is used, but the same number or cars is kept.
- The number of days without travels is then deduced (using a 364 days year):
Week days without travel : 52*5 - number of days of professional travels Week-end days without travel : 52*2 - number of days of personal travels Doing that, we assume that all professonal trips are made during weekdays and all personal trips during week-ends.
This assumption is obviously incorrect, and can lead to negative values. This is a point to fix.
The number of days of immobility is computed using the number without travels and the probability of immobility. For the days with mobility, short trips are sampled (separately for week and week-end days).
- Args:
- csp (str):
The socio-professional category of the person (“1” to “8”, or “no_csp”).
- csp_household (str):
The socio-professional category of the household (“1” to “8”, or “no_csp”).
- n_pers (str) :
The number of persons of the household (“1”, “2” or “3+”)
- n_cars (str):
The number of cars of the household (“0”, “1”, or “2+”).
- urban_unit_category (str):
The urban unit category (“C”, “B”, “I”, “R”).
- source (str) :
The source of the travels and trips data (“ENTD-2008” or “EMP-2019”, the default).
- Returns:
pd.DataFrame: a dataframe with one row per sampled trip. Contains long trips (from travels), short trips made during the travels, and short trips.
- Columns:
- id (int):
The unique id of the trip.
- mode (str):
The mode used for the trip.
- previous_motive (str):
the motive of the previous trip.
- motive (str):
the motive for the trip.
- distance (float):
the distance travelled, in km.
- n_other_passengers (int):
the number of passengers accompanying the person.
- get_population_trips(population: DataFrame, transport_zones: GeoDataFrame, study_area: GeoDataFrame) DataFrame
Generates trips for the entire population by merging population data with transport zone data and then individually generating trips for each person.
- Args:
population (pd.DataFrame): The population data for which trips are to be generated. transport_zones (gpd.GeoDataFrame): Geographic data for transport zones.
- Returns:
pd.DataFrame: A DataFrame containing generated trips for the population.
- class mobility.trips.individual_year_trips.MobilitySurveyAggregator(population, surveys)
- mobility.trips.individual_year_trips.safe_sample(data_base, n_sample, weights='pondki', minimum_sample_size=10, **kwargs)
Samples the data base filtered by kwargs.
Handles the case where the sample size is lesser than minimum_sample_size by withdrawing the filters
- Args:
- data_base (pd.DataFrame):
The database to sample from. Must be indexed (or muli-indexed) by the keys of kwargs.
- n_sample (int):
The number of samples to draw.
- weights (str) :
The name of columns of data_base containing the weights for the sampling.
- minimum_sample_size (int) :
The minimum size of the database to draw from. If the kwargs make the database to small, relax the criteria from last to first.
- kwargs :
the criteria to filter the database
- Returns:
pd.DataFrame: a dataframe with n_sample rows.
- Example :
safe_sample(days_trip_db, 10, csp=”3”, n_cars=”2+”, weekday=True, city_category=’C’)
- mobility.trips.individual_year_trips.sample_travels(df, start_col, length_col, weight_col, k, burnin=10000, thinning=1000, num_samples=1, random_seed=None)
Weighted MCMC sampling of k non-overlapping travels via swap-move Metropolis-Hastings.
Parameters: - df: pandas DataFrame with travel records. - start_col: column name for integer start index (e.g., day-of-year). - length_col: column name for duration (number of nights). - weight_col: column name for the base survey weight of each travel. - k: desired sample size. - burnin: number of initial MCMC steps to discard. - thinning: number of steps between recorded samples. - num_samples: how many independent samples to collect. - random_seed: for reproducibility.
Returns: - List of num_samples lists of DataFrame indices.
The trip generation uses the safe_sample module to ensure we do not use non-representative data
(from a group below the minimal sample size).
- mobility.trips.individual_year_trips.safe_sample.safe_sample(data_base, n_sample, weights='pondki', minimum_sample_size=10, **kwargs)
Samples the data base filtered by kwargs.
Handles the case where the sample size is lesser than minimum_sample_size by withdrawing the filters
- Args:
- data_base (pd.DataFrame):
The database to sample from. Must be indexed (or muli-indexed) by the keys of kwargs.
- n_sample (int):
The number of samples to draw.
- weights (str) :
The name of columns of data_base containing the weights for the sampling.
- minimum_sample_size (int) :
The minimum size of the database to draw from. If the kwargs make the database to small, relax the criteria from last to first.
- kwargs :
the criteria to filter the database
- Returns:
pd.DataFrame: a dataframe with n_sample rows.
- Example :
safe_sample(days_trip_db, 10, csp=”3”, n_cars=”2+”, weekday=True, city_category=’C’)