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, seed=0, x=None, y=None, location=None, datetime=None, timestamp=None)

Bases: object

Represents an agent in the city simulation.

still_probs

Dictionary containing probabilities of the agent staying still.

Type:

dict

speeds

Dictionary containing possible speeds of the agent.

Type:

dict

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(beta_start=None, beta_durations=None, beta_ping=5, seed=0, ha=0.75, pareto_prior=True, dt=None, output_bursts=False, deduplicate=True, replace_sparse_traj=False, cache_traj=False)

Samples a sparse trajectory using a hierarchical non-homogeneous Poisson process.

Parameters:

• beta_start (float) – The rate parameter governing the Poisson Process controlling the start of the trajectory.

• beta_durations (float) – The rate parameter governing the Exponential controlling for the durations of the trajectory.

• beta_ping (float) – The rate parameter governing the Poisson Process controlling which pings are sampled.

• seed (int) – Random seed for reproducibility.

• ha (float) – Horizontal accuracy

• output_bursts (bool) – If True, outputs the latent variables on when bursts start and end.

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

• cache_traj (bool) – if True, empties the Agent’s trajectory DataFrame.

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.

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.

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.allowed_buildings(local_ts)

Finds allowed buildings for the timestamp

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=5, seed=None, return_bursts=False, tz=None)

Generate absolute ping timestamps (seconds) within [t0, t_end].

If return_bursts is True, also returns a list of (start_time, end_time) for bursts that produced at least one ping. If tz is provided, start/end are timezone-aware pandas Timestamps; otherwise they are Unix seconds (int).

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.sample_bursts_gaps(traj, beta_start=None, beta_durations=None, beta_ping=5, ha=0.75, pareto_prior=True, seed=None, output_bursts=False, deduplicate=True)

Sample from simulated trajectory, drawn using hierarchical Poisson processes.

Parameters:

• traj (numpy array) – simulated trajectory from simulate_traj

• beta_start (float) – scale parameter (mean) of Exponential distribution modeling burst inter-arrival times where 1/beta_start is the rate of events (bursts) per minute.

• beta_durations (float) – scale parameter (mean) of Exponential distribution modeling burst durations. if beta_start and beta_durations are None, a single burst covering the whole trajectory is used.

• beta_ping (float) – scale parameter (mean) of Exponential distribution modeling ping inter-arrival times within a burst, where 1/beta_ping is the rate of events (pings) per minute.

• ha (float) – Mean horizontal-accuracy radius in 15 m blocks. The actual per-ping accuracy is random: ha >= 8 m / 15 m and follows a Pareto distribution with that mean. For each ping the spatial noise (epsilon_x, epsilon_y) is drawn i.i.d. from N(0, sigma^2), with sigma = HA / 1.515 so that abs(epsilon) <= HA with 68 percent probability.

• seed (int) – The seed for random number generation.

• output_bursts (bool) – If True, outputs the latent variables on when bursts start and end.

• deduplicate (bool) – If True, sampled times are also discretized to be in ticks

nomad.traj_gen.thin_traj_by_times(traj, ping_times, *, deduplicate=True)

Apply ping_times to a dense traj via searchsorted thinning.