plot_trajectory: Plot vehicle trajectories or AVL data

In transittraj: Reconstruct and Visualize Transit Vehicle Trajectories

Plot vehicle trajectories or AVL data

Description

This function uses the input trajectory object or TIDES AVL data to draw a trajectory plot (i.e., linear distance versus time) for each trip. This function allows for the plotting of spatial features and labels for these features. A ggplot2 object is returned, which can be further modified and customized as desired.

Usage

plot_trajectory(
  trajectory = NULL,
  distance_df = NULL,
  plot_trips = NULL,
  timestep = 5,
  distance_lims = NULL,
  center_trajectories = FALSE,
  feature_distances = NULL,
  convert_to_timezone = TRUE,
  traj_color = "coral",
  traj_type = "solid",
  traj_width = 1,
  traj_alpha = 1,
  traj_legend = NULL,
  feature_color = "grey30",
  feature_type = "dashed",
  feature_width = 0.8,
  feature_alpha = 0.8,
  feature_legend = NULL,
  label_field = NULL,
  label_size = 3,
  label_alpha = 0.6,
  label_pos = "left"
)

Arguments

trajectory	Optional. A trajectory object, either a single trajectory or grouped trajectory. If provided, distance_df must not be provided. Default is NULL.
distance_df	Optional. A dataframe of time and distance points. Must include at least event_timestamp, distance, and trip_id_performed. If provided, trajectory must not be provided. Default is NULL.
plot_trips	Optional. A vector of trip_id_performeds to plot. Default is NULL, which will plot all trips provided in the trajectory or distance_df.
timestep	Optional. If trajectory is provided, the time interval, in seconds, between interpolated observations to plot. Default is 5.
distance_lims	Optional. A vector with ⁠(minimum, maximum)⁠ distance values to plot.
center_trajectories	Optional. A boolean, should all trajectories be centered to start at the same time (0 seconds)? Default is FALSE.
feature_distances	Optional. A dataframe with at least numeric distance for features. Default is NULL.
convert_to_timezone	Optional. Should numeric epoch times be converted back to readable hour-minute-second time values, using the agency timezone? Default is TRUE.
traj_color	Optional. A color string, or a dataframe mapping an attribute in distance_df or trip_id_performed in trajectory to a color. Must contain column color. Default is "coral".
traj_type	Optional. A string specifying the ggplot2 linetype, or a dataframe mapping an attribute in distance_df or trip_id_performed in trajectory to a linetype. Must contain column linetype. Default is "solid".
traj_width	Optional. A numeric, the width of the trajectory line. Default is 1.
traj_alpha	Optional. A numeric, the opacity of the trajectory line. Default is 1.
traj_legend	Optional. A boolean, should a legend be shown for trajectory formatting? Default is NULL, where a legend will only appear if the linetype or color format is mapped to.
feature_color	Optional. A color string, or a dataframe mapping an attribute in feature_distances to a color. Must contain column color. Default is grey30.
feature_type	Optional. A string specifying the ggplot2 linetype, or a dataframe mapping an attribute in feature_distances to a linetype. Must contain column linetype. Default is "dashed".
feature_width	Optional. A numeric, the width of the feature line. Default is 0.8.
feature_alpha	Optional. A numeric, the opacity of the feature point. Default is 1.
feature_legend	Optional. A boolean, should a legend be shown for feature formatting? Default is NULL, where a legend will only appear if the linetype or color format is mapped to.
label_field	Optional. A string specifying the column in feature_distances with which to label the feature lines. Default is NULL, where no labels will be plotted.
label_size	Optional. The font size of the feature labels. Default is 3.
label_alpha	Optional. The opacity of the feature labels. Default is 0.6.
label_pos	Optional. A string specifying the label position on the graph. Must be either "left" or "right". Default is "left".

Details

Input Trajectory Data

There are two ways to provide data to this function:

• A single or grouped trajectory object. This will use the direct trajectory function at a resolution controlled by timestep. This is simplest, and looks best when zooming in using distance_lims. The only attribute that can be mapped to if using a trajectory is trip_id_performed.

• A distance_df of TIDES AVL data. This will use the distance and time point pairs for plotting, and draw linearly between them. This will look similar to a plot using trajectory when zoomed out. It is most useful if you want to map formatting to attributes other than trip_id_performed, such as a vehicle or operator ID. If starting with a trajectory, but the additional control over formatting is desired, consider using predict() to generate distance and time points to plot, then joining the desired attributes to the trip_id_performed column.

Note that only one of trajectory and distance_df can be used. If both (or neither) are provided, an error will be thrown.

Features and Labels

Often it is useful to plot the features of a route, such as its stops/stations or the traffic signals it passes through. Use feature_distances to provide information about spatial features to plot. Each row in feature_distances should include at least a distance column. Each of these rows will be plotted as a horizontal line across the graph.

These features can also be labeled. Set label_name to a character string corresponding to a field in feature_distances to generate labels with this field as their text. The color of the label will automatically match that of the feature they describe. The label placement is controlled by label_pos, which can be set to "left" or "right".

Formatting Options

Once a layer is created on a ggplot2 object, it is difficult to change its formatting. As such, this function attempts to provide as much flexibility in formatting its layers as possible. The resulting plot includes three layers:

• Vehicle trajectories, controlled by traj_color, traj_type, and traj_width, and traj_alpha.

• Features, controlled by feature_color, feature_type, feature_width, and feature_alpha.

• Labels, controlled by label_size, label_alpha, and label_pos.

All of these formats can be controlled by inputting a single string or numeric. The following attributes can also be modified using a dataframe, mapping them to attributes of the layer:

• traj_type and feature_type: A dataframe with one column named linetype, and another column sharing a name with a column in distance_df or feature_distances (or, if using trajectory, a column named trip_id_performed). The values in linetype should be valid ggplot2 linetypes, and the values in the mapping column should match the values in feature or trip column.

• traj_color and feature_color: A dataframe with one column named color, and another column sharing a name with a column in distance_df or feature_distances (or, if using trajectory, a column named trip_id_performed). The values in color should be valid color strings, and the values in the mapping column should match the values in feature or trip column.

Note that if inputting trajectory, instead of distance_df, traj_color and traj_type can only be mapped to trip_id_performed. If using distance_df, they may be mapped to any column in distance_df (e.g., vehicle or operator IDs).

Value

A ggplot2 object.

Examples

# Get input data
lineE_traj <- new_transittraj_data("get_trajectory_fun")

# Set my parameters
my_features <- data.frame(name = c("Metro Center"),
                          distance = c(24556))
my_dist_range <- c(24000, 25000)

# Run function
plot_trajectory(trajectory = lineE_traj,
                feature_distances = my_features,
                label_field = "name",
                label_alpha = 0.8,
                distance_lims = my_dist_range,
                traj_color = "indianred3",
                center_trajectories = TRUE,
                timestep = 1)

transittraj documentation built on Nov. 2, 2026, 1:10 a.m.