get_trajectory_fun: Fit continuous trajectory interpolating curves from AVL data

In transittraj: Reconstruct and Visualize Transit Vehicle Trajectories

Fit continuous trajectory interpolating curves from AVL data

Description

This function fits a continuous vehicle trajectory to cleaned AVL points (see vignette("articles/data-workflow-la")). This function operates as a "function factory", returning a function (closure) which takes a timestamp and returns each trip's position. A separate curve is fit for each trip, and stored in a special trajectory object class. The default interpolating method is a velocity-informed piecewise cubic interpolating polynomial, but linear interpolation and other spline-based techniques are also supported. See Details for a discussion.

Usage

get_trajectory_fun(
  distance_df,
  interp_method = "monoH.FC",
  use_speeds = TRUE,
  find_inverse_function = TRUE,
  inv_tol = 0.01,
  return_group_function = TRUE
)

Arguments

distance_df	A dataframe of linearized AVL data. Must include trip_id_performed, event_timestamp, and distance. If use_speed = TRUE, must also include speed.
interp_method	Optional. The type of interpolation function to be fit. Either "linear", or a spline method from stats::splinefun(). Default is "monoH.FC".
use_speeds	Optional. A boolean, should curves be constrained by observed AVL speeds? Should only be used with interp_method = "monoH.FC", but monoH.FC does not require speeds. Default is TRUE.
find_inverse_function	Optional. A boolean, should the numeric inverse function (time ~ distance) be calculated? Default is TRUE.
inv_tol	Optional. A numeric in the units of input distance, the tolerance used when calculating the numeric inverse function. Default is 0.01.
return_group_function	Optional. A boolean, should the returned trajectory object be grouped into a single function? If FALSE, will return a list (indexed by trip_id_performed) of single trajectory objects. Default is TRUE.

Details

Interpolating Methods

The goal of this function is to fit a continuous function representing a vehicle's distance traveled as a function of time, for each trip. This function supports to types of interpolating curves:

• Linear interpolation, for interp_method = "linear". This will fit a simple linear function, ignorant to recorded speed values.

• Spline interpolation, for interp_method set to any method supported by stats::splinefun() (i.e., "fmm", "natural", "periodic", "monoH.FC", or "hyman".) Only interp_method = "monoH.FC" supports use of recorded speed values.

By default, interp_method = "monoH.FC" and use_speeds = TRUE. This will yield a continuous, differentiable, and invertible trajectory. If the input distance and speed values satisfy Fritsch-Carlson, the interpolating function is guaranteed to be montonic. See make_monotonic(). This is equivalent to the velocity-informed monotonic peicewise cubic Hermite interpolating polynomials with monotonic enforcement (VCHIP-ME) technique proposed by Robbennolt et al. (2026), and is our recommended approach.

Note that use_speeds = TRUE requires interp_method = "monoH.FC", but interp_method = "monoH.FC" does not require use_speeds = TRUE. In the latter scenario, a "velocity-ignorant' Fritsch-Carlson interpolating function can be created (Huang et al., 2023). If input distance values are monotonic, this curve is guaranteed to be monotonic.

Inverse Functions

Often times, we are concerned not with the position of a vehicle at a particular time, but the time at which a vehicle crosses a specific point in space. This can be accomplished by computing an inverse trajectory function. If find_inverse_function = TRUE (the default), a numeric inverse to the fit trajectory function will be found, with a tolerance controlled by inv_tol.

Because the inverse function is numerical, it can be found for any type of interpolating curve (linear or spline). However, the input data must be strictly monotonic for the trajectory curve to be invertible. If find_inverse_function = TRUE, this will be verified before proceeding (see validate_monotonicity()).

The Trajectory Object

A trajectory function does not exist by itself; rather, it requires the context about the trip it describes, as well as its inverse function. As such, get_trajectory_fun() returns an AVL trajectory object. If return_group_function = TRUE (the default), the function will return a single object containing:

• A vector of trip_id_performeds present in distance_df.

• A list of fit trajectory functions (closures), one per trip, indexed by their trip_id_performed.

• A list of fit inverse trajectory functions (closures), one per trip, indexed by their trip_id_performed.

• Information about how the trajectory and inverse trajectory functions were fit, including interp_method, use_speeds, and inv_tol.

• A vector each for the minimum distances, maximum distances, minimum times, and maximum times of each trip. These inform the domain and range of the trajectory function and its inverse, preventing extrapolation beyond the time or distance range actually served by a trip.

• The agency's timezone (see OlsonNames()), as extracted from the event_timestamp column.

Alternatively, if return_group_function = FALSE, a separate trajectory object will be returned for each trip, as a list of objects indexed by their trip_id_performed.

More information about the trajectory object classes and how to use them is available at vignette("articles/intro-trajectories-la").

Value

If return_group_function = TRUE, a grouped trajectory object. If FALSE, a list of single trajectory objects, indexed by their trip_id_performed.

References

Robbennolt, Jake, Sirajum Munira, and Stephen D. Boyles. 2026. “A Comparative Study of Spline-Based Trajectory Reconstruction Methods Across Varying Automatic Vehicle Location Data Densities.” Paper presented at 2026 Transportation Research Board Annual Meeting, January 11. http://arxiv.org/abs/2509.00119.

Huang, Yuzhu, Awad Abdelhalim, Anson Stewart, Jinhua Zhao, and Haris Koutsopoulos. 2023. “Reconstructing Transit Vehicle Trajectory Using High-Resolution GPS Data.” 2023 IEEE 26th International Conference on Intelligent Transportation Systems (ITSC), September 24, 5247–53. https://doi.org/10.1109/ITSC57777.2023.10422524.

Examples

# Get input data
lineE_mono <- new_transittraj_data("make_monotonic")

# Run function: grouped trajectory object
lineE_traj_grouped <- get_trajectory_fun(distance_df = lineE_mono)
summary(lineE_traj_grouped)

# Run function: list of single trajectory objects
lineE_traj_singles <- get_trajectory_fun(distance_df = lineE_mono,
                                         return_group_function = FALSE)
length(lineE_traj_singles)
summary(lineE_traj_singles[[2]])

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