traj_gen

class nomad.traj_gen.Agent(identifier, city, home=None, workplace=None, still_probs={'home': 0.9, 'park': 0.5, 'retail': 0.5, 'workplace': 0.9}, speeds={'home': 0.3826530612244898, 'park': 1.0204081632653061, 'retail': 0.8928571428571429, 'workplace': 0.3826530612244898}, destination_diary=None, trajectory=None, diary=None, sparsity_params=None, seed=0, x=None, y=None, location=None, datetime=None, timestamp=None)

Bases: object

Represents an agent in the city simulation.

identifier

Agent identifier.

Type:

str

city

City object containing buildings and movement topology.

Type:

City

home

Building ID for the agent’s home.

Type:

str

workplace

Building ID for the agent’s workplace.

Type:

str

home_centroid

Centroid of the agent’s home building.

Type:

shapely.geometry.Point

workplace_centroid

Centroid of the agent’s workplace building.

Type:

shapely.geometry.Point

still_probs

Dictionary containing probabilities of the agent staying still.

Type:

dict

speeds

Dictionary containing possible speeds of the agent.

Type:

dict

destination_diary

Planned destinations with columns [‘datetime’, ‘timestamp’, ‘duration’, ‘location’].

Type:

pandas.DataFrame

trajectory

Full simulated trajectory.

Type:

pandas.DataFrame or None

sparse_traj

Sampled sparse trajectory.

Type:

pandas.DataFrame or None

diary

Travel diary produced from trajectory generation.

Type:

pandas.DataFrame

sparsity_params

Sparse trajectory sampling parameters and metadata.

Type:

dict

last_ping

Most recent known agent state.

Type:

pandas.Series or None

dt

Time step duration.

Type:

float

generate_dest_diary(end_time, epr_time_res=15, stay_probs={'home': 0.9821428571428571, 'park': 0.75, 'retail': 0.5, 'workplace': 0.9642857142857143}, rho=0.4, gamma=0.3, seed=0, verbose=False)

Generate the destination diary (exploration + preferential return).

Parameters:

• end_time (pd.Timestamp) – Generate until this timestamp (inclusive).

• epr_time_res (int) – Time-step in minutes for each diary entry.

• stay_probs (dict) – Probability of staying put, keyed by building type.

• rho (float) – Exploration parameter; lower values bias toward exploration.

• gamma (float) – Preferential return parameter; controls decay by visit count.

• seed (int) – RNG seed.

Notes

• Requires city.grav to be precomputed via city.compute_gravity(…)

generate_trajectory(destination_diary=None, end_time=None, epr_time_res=15, dt=1, seed=0, step_seed=None, verbose=False, **kwargs)

Generate a trajectory for an agent.

Parameters:

• destination_diary (pandas.DataFrame, optional (default=None)) – DataFrame containing ‘location’ and ‘datetime’ columns (required), and optionally ‘timestamp’ and ‘duration’. If ‘timestamp’ is missing, it will be derived from ‘datetime’.

• end_time (pd.Timestamp, optional) – The end time to generate the trajectory until. Required if destination_diary is empty.

• epr_time_res (int, optional) – The granularity of destination durations in epr generation (minutes).

• dt (float, optional) – Time step duration for trajectory simulation (minutes).

• seed (int, optional) – Random seed for reproducibility.

• step_seed (int, optional) – Random seed for trajectory steps. If None, uses seed.

• verbose (bool, optional) – Whether to print verbose warnings.

• kwargs (dict, optional) – Additional keyword arguments for setting initial position. Can include ‘x’, ‘y’, ‘location’, ‘datetime’, ‘timestamp’. If ‘x’ and ‘y’ are provided, used directly. Otherwise, if ‘location’ is provided, uses that building’s centroid. If neither, uses agent’s home.

Return type:

None (updates self.trajectory)

plot_traj(ax, color='black', alpha=1, doors=True, address=True, heatmap=False)

Plots the trajectory of the agent on the given axis.

Parameters:

• ax (matplotlib.axes.Axes) – The axis on which to plot the trajectory.

• color (str, optional) – The color of the trajectory.

• alpha (float, optional) – The transparency of the trajectory.

• doors (bool, optional) – Whether to plot doors of buildings.

• address (bool, optional) – Whether to plot the address of buildings.

• heatmap (bool, optional) – Whether to plot a heatmap of time spent in each building.

reset_trajectory(trajectory=True, sparse=True, last_ping=True, diary=True)

Resets the agent’s trajectories and diaries to the initial state. Keeps the agent’s identifier, home, and workplace. This method is useful for reinitializing the agent after a simulation run.

sample_trajectory(seed=0, ha=0.75, pareto_prior=True, replace_sparse_traj=False, flush_traj_cache=False, debug_mode=False)

Samples a sparse trajectory using a hierarchical inhomogeneous Poisson process.

Parameters:

• seed (int) – Random seed for reproducibility.

• ha (float) – Horizontal accuracy

• replace_sparse_traj (bool) – if True, replaces existing sparse_traj field with the new sparsified trajectory rather than appending.

• flush_traj_cache (bool) – If True, discards the dense trajectory except for its final ping.

• debug_mode (bool) – If True, validates that dense and sparse trajectories are sorted chronologically.

Returns:

Start and end times for bursts that produced at least one ping.

Return type:

pandas.DataFrame

set_beta_params(beta_params=None, *, beta_start=None, beta_durations=None, beta_ping=None)

Set the parameters used to sample sparse trajectories.

Parameters:

• beta_params (dict, optional) – Parameter dictionary containing ‘beta_start’, ‘beta_durations’, and ‘beta_ping’. Additional values are retained. If provided, this dictionary takes precedence over the explicit parameters.

• beta_start (float or None) – The rate parameter governing burst starts. Use 0 together with beta_durations=np.inf for one full-trajectory burst. A value of 0 is stored as None.

• beta_durations (float or None) – The rate parameter governing burst durations. Use np.inf together with beta_start=0 for one full-trajectory burst. A value of np.inf is stored as None.

• beta_ping (float) – The rate parameter governing ping sampling.

class nomad.traj_gen.Population(city, dt=1)

Bases: object

A class to represent a population of agents within a city. Contains methods to initialize agents and randomize their attributes and trajectories.

roster

A dictionary to store agents with their identifiers as keys.

Type:

dict

city

The city in which the population resides.

Type:

City

dt

The time step duration for the agents.

Type:

float

add_agent:

Adds an agent to the population.

generate_agents:

Generates N agents with randomized attributes.

save_pop:

Saves trajectories, homes, and diaries as Parquet files to S3.

sample_step:

Generates (x, y) pings from a destination diary.

traj_from_dest_diary:

Simulates a trajectory and updates the agent’s travel diary.

generate_dest_diary:

Generates a destination diary using exploration and preferential return.

generate_trajectory:

Generates a trajectory for an agent.

plot_population:

Plots the population on a given axis.

add_agent(agent, verbose=True)

Adds an agent to the population. If the agent identifier already exists in the population, it will be replaced.

Parameters:

• agent (Agent) – The agent to be added to the population.

• verbose (bool, optional) – If True, prints a message if the agent identifier already exists in the population.

static gen_params_target_f(f, beta_start=None, beta_ping=None, beta_durations=None, *, beta_start_probs=None, beta_ping_probs=None, beta_durations_probs=None, seed=None, rng=None)

Sample burst parameters targeting expected ping frequency f, modeled as beta_durations / (beta_start * beta_ping).

Provide exactly two of beta_start, beta_ping, and beta_durations. The missing parameter is derived from f.

static gen_params_target_q(q, beta_start=None, beta_ping=None, beta_durations=None, *, beta_start_probs=None, beta_ping_probs=None, beta_durations_probs=None, seed=None, rng=None)

Sample burst parameters targeting coverage q, modeled as beta_durations / beta_start.

beta_ping must be provided. Provide exactly one of beta_start and beta_durations; the other is derived from the sampled q.

generate_agents(N, seed=0, name_count=2, agent_homes=None, agent_workplaces=None, datetimes=None)

Generates N agents, with randomized attributes.

reproject_to_mercator(sparse_traj=True, full_traj=False, diaries=False, poi_data=None)

Reproject all agent trajectories from city block coordinates to Web Mercator. Uses the city’s stored transformation parameters (block_side_length, web_mercator_origin_x/y).

Parameters:

• sparse_traj (bool, default True) – Whether to reproject sparse trajectories

• full_traj (bool, default False) – Whether to reproject full trajectories

• diaries (bool, default False) – Whether to reproject diaries (must have x, y columns)

• poi_data (pd.DataFrame, optional) – DataFrame with building coordinates (building_id, x, y) to join with diaries. If not provided, derived from city’s buildings_gdf using door coordinates.

static sample_from_intervals(beta_start, beta_ping, beta_durations, *, beta_start_probs=None, beta_ping_probs=None, beta_durations_probs=None, seed=None, rng=None)

Sample random trajectory parameters from specified ranges.

Each beta parameter may be a scalar, a (low, high) tuple sampled uniformly, a list of exact values sampled uniformly, or a dict with {"values": [...], "probs": [...]}.

save_pop(traj_cols=None, sparse_path=None, full_path=None, homes_path=None, diaries_path=None, dest_diaries_path=None, partition_cols=None, mixed_timezone_behavior='naive', filesystem=None, fmt='parquet', **kwargs)

Save trajectories, homes, and diaries to local or S3 destinations.

Parameters:

• traj_cols (dict, optional) – Column mapping used to normalize trajectory data before writing.

• sparse_path (str or Path, optional) – Destination path for sparse trajectories.

• full_path (str or Path, optional) – Destination path for full (ground truth) trajectories.

• homes_path (str or Path, optional) – Destination path for the homes table.

• diaries_path (str or Path, optional) – Destination path for diaries.

• dest_diaries_path (str or Path, optional) – Destination path for destination diaries.

• partition_cols (list of str, optional) – Column names used to partition written datasets.

• mixed_timezone_behavior (str, optional) – Behavior passed to nomad.io.base.from_df for mixed timezone columns.

• filesystem (pyarrow.fs.FileSystem or None) – Optional filesystem object (e.g., s3fs.S3FileSystem). If None, inferred automatically.

• fmt (str, optional) – File format to write.

• **kwargs (dict, optional) – Additional static columns to include in the homes table. Each key-value pair represents a column name and its values. Values must be a list/array of length N (number of agents) or a single value to be repeated for all agents.

nomad.traj_gen.condense_destinations(destination_diary, *, time_cols=None)

Modifies a destination diary, joining consecutive entries for the same location into a single entry with the total duration.

Parameters:

• destination_diary (pandas.DataFrame) – Diary containing the destinations of the user.

• time_cols (dict, optional (keyword-only)) – Optional mapping for non-canonical column names. Expected keys: {‘datetime’: <col_name>, ‘timestamp’: <col_name>}. Defaults are ‘datetime’ and ‘timestamp’.

Returns:

Updated destination diary with canonical columns ‘datetime’ and ‘timestamp’.

Return type:

pandas.DataFrame

nomad.traj_gen.generate_ping_times(t0, t_end, *, beta_start=None, beta_durations=None, beta_ping=None, seed=None, tz=None)

Generate ping timestamps and burst information within [t0, t_end].

nomad.traj_gen.parse_agent_attr(attr, N, name)

Parse agent attribute (homes/workplaces/datetimes) into a callable that returns the i-th value.

Parameters:

• attr (str, list, pd.Timestamp, or None) – The attribute value. Can be: - None: returns None for all indices - str or pd.Timestamp: returns the same value for all indices - list: must have length N, returns the i-th element

• N (int) – Expected number of agents

• name (str) – Name of the attribute for error messages

Returns:

A function that takes an index i and returns the corresponding attribute value

Return type:

callable

nomad.traj_gen.thin_traj_by_times(traj, ping_times)

Apply ping_times to a dense traj via searchsorted thinning.