Calculates the Jaccard similarity between two trajectories or sub-trajectories, returning intersection counts and Jaccard index bounds.
Syntax
record ST_JaccardSimilarity(trajectory tr1, trajectory tr2, double tol_dist,
text unit default '{}', interval tol_time default NULL,
timestamp ts default '-infinity', timestamp te default 'infinity');Parameters
| Parameter | Description |
|---|---|
tr1 | The first trajectory. |
tr2 | The second trajectory. |
tol_dist | The maximum allowed distance between a matched pair of trajectory points. Unit: meters. |
unit | A JSON string that controls how distances are calculated. Default: '{}'. See the unit fields table below. |
tol_time | The maximum allowed time difference between a matched pair of trajectory points. If set to NULL or a negative value, the function matches points based on distance only and ignores time. Default: NULL. |
ts | The start of the time range for the calculation. The default value is -infinity. If you specify this parameter, this function calculates only the sub-trajectories between the specified start time and end time. |
te | The end of the time range for the calculation. The default value is infinity. If you specify this parameter, this function calculates only the sub-trajectories between the specified start time and end time. |
unit parameter fields
| Field | Type | Default | Description |
|---|---|---|---|
Projection | string | None | The coordinate system to use for re-projection. Valid values: auto (dynamically selects Lambert Azimuthal or UTM based on the trajectory's longitude and latitude; distances are in meters), srid (re-projects based on the specified spatial reference identifier (SRID)). If not set, the function uses the original coordinate system. |
Unit | string | null | The unit for measuring distance. Valid values: null (computes Euclidean distance directly from coordinates, no unit conversion), M (computes distance using the spatial reference unit of the trajectories, typically meters). |
useSpheroid | bool | true | Specifies whether to use an ellipsoid model when Unit is M. true: uses an ellipsoid for accurate distances. false: uses a sphere model for approximate distances. |
Return value
The function returns a record with the following fields:
| Field | Type | Description |
|---|---|---|
nleaf1 | int | The number of trajectory points in tr1 that have a matching point in tr2. |
nleaf2 | int | The number of trajectory points in tr2 that have a matching point in tr1. This value can differ from nleaf1. For example, if tr1 passes the same point in tr2 twice, nleaf1 is 1 and nleaf2 is 2. |
inter1 | int | The number of trajectory points in tr1 whose distance to tr2 meets both the distance tolerance and time tolerance. |
inter2 | int | The number of trajectory points in tr2 whose distance to tr1 meets both the distance tolerance and time tolerance. |
jaccard_lower | double | The lower bound of the Jaccard similarity. Calculated as min(inter1, inter2) / (nleaf1 + nleaf2 - min(inter1, inter2)). |
jaccard_upper | double | The upper bound of the Jaccard similarity. Calculated as max(inter1, inter2) / (nleaf1 + nleaf2 - max(inter1, inter2)). |
Description
The Jaccard index measures the similarity of two sets as the size of their intersection divided by the size of their union. For trajectory data, ST_JaccardSimilarity extends this definition by counting, in both directions, how many trajectory points from one trajectory fall within the specified distance (and optionally time) tolerance of the other. Because the intersection count is asymmetric — tr1-to-tr2 and tr2-to-tr1 can differ — the function returns both a lower bound (jaccard_lower) and an upper bound (jaccard_upper).
Example
The following example calculates the Jaccard similarity between two trajectories over a three-day time window, using a 100-meter distance tolerance and a 20-second time tolerance.
WITH traj AS (
SELECT
ST_makeTrajectory(
'STPOINT'::leaftype,
'SRID=4326;LINESTRING(114.49211 37.97921,114.49211 37.97921,114.49211 37.97921,114.49211 37.97921)'::geometry,
ARRAY[
to_timestamp(1590287775) AT TIME ZONE 'UTC',
to_timestamp(1590287778) AT TIME ZONE 'UTC',
to_timestamp(1590302169) AT TIME ZONE 'UTC',
to_timestamp(1590302171) AT TIME ZONE 'UTC'
],
'{}'
) a,
ST_makeTrajectory(
'STPOINT'::leaftype,
'SRID=4326;LINESTRING(114.49211 37.97921,114.49211 37.97921,114.49211 37.97921,114.49211 37.97921,114.49145 37.97781,114.49145 37.97781,114.49145 37.97781,114.49145 37.97781,114.49145 37.97781,114.49145 37.97781,114.49145 37.97781,114.49145 37.97781,114.49145 37.97781,114.49145 37.97781,114.49211 37.97921,114.49211 37.97921,114.49211 37.97921,114.49211 37.97921,114.49211 37.97921,114.49211 37.97921)'::geometry,
ARRAY[
to_timestamp(1590287765) AT TIME ZONE 'UTC',
to_timestamp(1590287771) AT TIME ZONE 'UTC',
to_timestamp(1590287778) AT TIME ZONE 'UTC',
to_timestamp(1590287780) AT TIME ZONE 'UTC',
to_timestamp(1590295992) AT TIME ZONE 'UTC',
to_timestamp(1590295997) AT TIME ZONE 'UTC',
to_timestamp(1590296013) AT TIME ZONE 'UTC',
to_timestamp(1590296018) AT TIME ZONE 'UTC',
to_timestamp(1590296025) AT TIME ZONE 'UTC',
to_timestamp(1590296032) AT TIME ZONE 'UTC',
to_timestamp(1590296055) AT TIME ZONE 'UTC',
to_timestamp(1590296073) AT TIME ZONE 'UTC',
to_timestamp(1590296081) AT TIME ZONE 'UTC',
to_timestamp(1590296081) AT TIME ZONE 'UTC',
to_timestamp(1590302169) AT TIME ZONE 'UTC',
to_timestamp(1590302174) AT TIME ZONE 'UTC',
to_timestamp(1590302176) AT TIME ZONE 'UTC',
to_timestamp(1590302176) AT TIME ZONE 'UTC',
to_timestamp(1590302172) AT TIME ZONE 'UTC',
to_timestamp(1590302176) AT TIME ZONE 'UTC'
],
'{}'
) b
)
SELECT ST_JaccardSimilarity(
a, b,
100,
'{"unit":"M"}',
'20 second',
'2020-05-23'::timestamptz AT TIME ZONE 'UTC',
'2020-05-26'::timestamptz AT TIME ZONE 'UTC'
)
FROM traj;Output:
st_jaccardsimilarity
-----------------------------------
(4,20,4,10,0.2,0.714285714285714)
(1 row)The result maps to the return fields as follows:
| Field | Value | Meaning |
|---|---|---|
nleaf1 | 4 | tr1 has 4 points with a match in tr2 |
nleaf2 | 20 | tr2 has 20 points with a match in tr1 |
inter1 | 4 | 4 points in tr1 meet both distance and time tolerances |
inter2 | 10 | 10 points in tr2 meet both distance and time tolerances |
jaccard_lower | 0.2 | 4 / (4 + 20 - 4) |
jaccard_upper | ~0.714 | 10 / (4 + 20 - 10) |