Calculates the Jaccard index for two trajectories or sub-trajectories within an optional time range.
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 | Type | Default | Description |
|---|---|---|---|
tr1 | trajectory | — | The first trajectory. |
tr2 | trajectory | — | The second trajectory. |
tol_dist | double | — | The maximum allowed distance between a pair of trajectory points. Unit: meters. |
unit | text | '{}' | A JSON string that controls how distances are calculated. See unit fields. |
tol_time | interval | NULL | The maximum allowed time difference between a pair of trajectory points. If set to NULL or a negative value, the function calculates the Jaccard index based on distance only. |
ts | timestamp | '-infinity' | The start of the time range. When specified together with te, the function calculates the Jaccard index for sub-trajectories within the range. |
te | timestamp | 'infinity' | The end of the time range. When specified together with ts, the function calculates the Jaccard index for sub-trajectories within the range. |
unit fields
| Field | Type | Default | Description |
|---|---|---|---|
Projection | string | None | The coordinate system to re-project the trajectories into before calculating distances. Valid values: auto (dynamically selects Lambert Azimuthal and UTM based on the longitude and latitude of the trajectories; unit is meters), srid (re-projects based on the spatial reference identifier (SRID) you specify). If not set, the function uses the original coordinate system. |
Unit | string | null | The unit for distance measurement. Valid values: null (Euclidean distance based on coordinates), M (distance in the unit of the spatial reference, typically meters). |
useSpheroid | bool | true | Specifies whether to use an ellipsoid for distance calculation. Only applies when Unit is M. Valid values: true (ellipsoid; returns accurate distances), false (sphere; returns approximate distances). |
Response parameters
| Parameter | Type | Description |
|---|---|---|
nleaf1 | int | The number of trajectory points in tr1 that intersect with tr2. |
nleaf2 | int | The number of trajectory points in tr2 that intersect with tr1. This value can differ from nleaf1. For example, if tr1 passes the same point on 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 ratio of their intersection size to their union size. For trajectories, this function extends that definition: it counts the trajectory points where tr1 intersects tr2 and where tr2 intersects tr1, then computes lower and upper bounds for the Jaccard similarity using the formulas above.
Because the intersection counts may differ depending on the direction of comparison (tr1→tr2 vs. tr2→tr1), the function returns both a lower bound (jaccard_lower) and an upper bound (jaccard_upper).
Example
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 output maps to the response parameters in order: (nleaf1, nleaf2, inter1, inter2, jaccard_lower, jaccard_upper).