The Spatiotemporal Join joins records in one DataFrame to records in another DataFrame based on spatial, temporal, or attribute relationships, or a combination of those relationships. For example, if two records occur within one hour of each other, they will be joined.
Records in time-enabled DataFrames can be represented in one of the following two ways:
- Instant—A single moment in time.
- Interval—A duration of time with a start and end time.
Temporal relationships are based on ISO19108 - Temporal Schema.
Target and join DataFrame
A temporal join matches records from the target DataFrame to the join DataFrame based on the record's placement or occurrence in time.
The following legend applies to all examples in this topic:
- Target DataFrame time—Green
- Join DataFrame time—Blue
Time types and supported relationships
The following table lists the supported temporal relationships for a temporal join between time types (for example, joining time intervals to time instants):
| Instant and instant | Instant and interval | Interval and instant | Interval and interval | |
|---|---|---|---|---|
| Equals | ||||
| During | ||||
| Contains | ||||
| Finishes | ||||
| Finished by | ||||
| Meets | ||||
| Met by | ||||
| Overlaps | ||||
| Overlapped by | ||||
| Starts | ||||
| Started by | ||||
| Intersects | ||||
| Near | ||||
| Near before | ||||
| Near after |
Equals
Two times are considered equal if their instants or intervals are identical. The times of both the target and join DataFrame must be of the same type to be considered equal—both instant or both interval times.
During
When a target time occurs between the start and end of the join time interval, the target time is during the join time. This is the opposite of the Contains temporal relationship operator. During is supported when the join time is an interval.
Contains
When a join record time occurs between the start and end of the target time interval, the target time contains the join time. This is the opposite of the During temporal relationship operator. Contains is supported when the target record is an interval.
Finishes
When a target time ends at the same time as a join time, and the target time started after the join time, the target time finishes the join time. This is the complement of the Finished by temporal relationship operator and the opposite of the Starts temporal relationship operator. Finishes is supported when the join record is an interval.
Finished by
When a join record time ends at the same time as a target time, and the join time started after the target time, the target time is finished by the join time. This is the complement of the Finishes temporal relationship operator and the opposite of the Started by temporal relationship operator. Finished by is supported when the target record is an interval.
Meets
When a target time interval end is equal to the join time interval start, the target time meets the join time. This is the complement of the Met by temporal relationship operator. Meets is supported when the join and target times are intervals.
Met by
When a target time interval start is equal to the join time interval end, the target time is met by the join time. This is the complement of the Meets temporal relationship operator. Met by is supported when the join and target times are intervals.
Overlaps
When a target time interval starts and ends before the start and end of the join time interval, the target time overlaps the join time. This is the complement of the Overlapped by temporal relationship operator. Overlaps is supported when the join and target times are intervals.
Overlapped by
When a target time interval starts and ends after the start and end time of the join time interval, the target time is overlapped by the join time. This is the complement of the Overlaps temporal relationship. Overlapped by is supported when the join and target times are intervals.
Starts
When a target time starts at the same time as the join time interval start and ends before the join time interval ends, the target time starts the join time. This is the complement of the Started by temporal relationship operator and the opposite of the Finishes temporal relationship operator. Starts is supported when the join time is an interval.
Started by
When a target interval time starts at the same time as the join time and ends after the join time, the target time is started by the join time. This is the complement of the Starts temporal relationship operator and the opposite of the Finished by temporal relationship operator. Started by is supported when the target time is an interval.
Intersects
When any part of a target time occurs at the same time as the join time, the target time intersects the join time. The Intersects operator is a combination of all the other types of temporal relationships.
Near
When a target time is within a specified range of time from the join time, the target time is near the join time. Using a user-specified temporal distance (for example, 1 month), an Intersects relationship operator is applied with the temporal distance added to both ends of the join time.
Near before
When a target time is within a specified range of time and occurs before the join time, the target time is near before the join time. Using a user-specified temporal distance (for example, 1 month), an Intersects relationship operator is applied with the temporal distance added to the beginning of the join time.
Near after
When a target time is within a specified range of time and occurs after the join time, the target time is near after the join time. Using a user-specified temporal distance (for example, 1 month), an Intersects relationship operator is applied with the temporal distance added to the end of the join time.
What's next?
Learn more about temporal relationships:
- Use the analysis tool Spatiotemporal Join to analyze relationships between your data
- Enable time on a DataFrame