IBM Streams 4.2

Operator Hangout

SPL standard and specialized toolkits > com.ibm.streams.geospatial 3.0.2 > com.ibm.streams.geospatial > Hangout

Primitive operator image not displayed. Problem loading file: ../../image/tk$com.ibm.streams.geospatial/op$com.ibm.streams.geospatial$Hangout.svg

The Hangout operator is used to detect a basic pattern about a moving entity's location called a hangout. The input for this operator is a stream of data describing the location of one or more entities over time. For a given entity, it is said to be hanging out or in a hangout if it has been dwelling in the same region for a period of time. This operator uses Geohashes to identify regions where hangouts occur. The size of each Geohash region is controlled by the sampleLatitude and the cellSize parameters.

The Hangout operator will report that a Hangout is ongoing if two conditions are met: First, the latitude and longitude of each consecutively reported location during that period generate the same Geohash, and second, that the period of time in question is at least minimumDwellTime seconds in duration.

This operator has one input port, port 0, known as the entity stream, which receives information about an entity's location at a given time. Each input tuple must specify the current location of the entity as latitude and longitude coordinates, as well as the timestamp at which the location was observed. There is one output port, which produces a tuple for every incoming tuple on the entity stream. The output will indicate if the entity is hanging out, and if so, it will also provide the Geohash of the region where it is hanging out, and the duration of the hangout.

For more information on Geohashes, see the Geohashes section in the main page of the documentation for this toolkit.

Behavior in a consistent region

  • The Hangout operator is not supported in a consistent region.
  • The operator does not support checkpoint and reset. If the application fails, the operator might produce incorrect results.
Example

Summary

Ports
This operator has 1 input port and 1 output port.
Windowing
This operator does not accept any windowing configurations.
Parameters
This operator supports 10 parameters.

Required: minimumDwellTime

Optional: cellSize, geohashBitDepth, id, latitude, longitude, precision, sampleLatitude, timeStamp, timeout

Metrics
This operator reports 3 metrics.

Properties

Implementation
C++
Threading
Always - Operator always provides a single threaded execution context.

Input Ports

Ports (0)

The Hangout operator has one input port, port 0, which is also referred to as the entity stream. This port receives time based data that is used to detect hangouts.

Properties

Output Ports

Assignments
This operator allows any SPL expression of the correct type to be assigned to output attributes. Attributes not assigned in the output clause will be automatically assigned from the attributes of the input ports that have the same name and type. If there is no such input attribute, an error is reported at compile-time.
Output Functions
HangoutOutputFunctions
boolean IsInHangout()

Returns true if the entity is currently in a hangout, i.e. if it has passed the minimum dwell time threshold in the same geographic area identified by a Geohash.

uint64 HangoutDuration()

If the entity is currently in a hangout, returns the duration, in seconds, of the hangout. This is the total amount of time the entity has spent in the region. If the entity is not hanging out, this function returns 0.

rstring HangoutGeohashBase32()

If the entity is currently in a hangout, returns the Geohash of the hangout in base 32, which is the more common, alphanumeric Geohash format. If the entity is currently not in a hangout, returns an empty string.

rstring HangoutGeohashBinary()

If the entity is currently in a hangout, returns the Geohash of the hangout as a binary string. If the entity is currently not in a hangout, returns an empty string.

<any T> T AsIs(T)

No op

Ports (0)

This operator has one mandatory output port, Output Port 0, which produces data describing any ongoing hangouts as a response to incoming data from the entity stream.

Properties

Parameters

Required: minimumDwellTime

Optional: cellSize, geohashBitDepth, id, latitude, longitude, precision, sampleLatitude, timeStamp, timeout

cellSize

This value is in meters and specifies the dimensions of each geohash cell, such that for a given cellSize M, each geohash cell will be a rectangle that covers a geographical area of size M meters x M meters. The operator will report a Hangout for any entity whose location for at least minimumDwellTime seconds is within the same geohash cell. Note that this is an approximation and there might be some variation between the desired cell size and the dimensions of the generated geohash cells. This parameter must be used in conjunction with the sampleLatitude parameter to indicate the general geographical area where Hangout detection will be performed. Must be specified at compile or submission time.

Properties

geohashBitDepth

Parameter indicating the number of bits used to determine the size of each Geohash region. The higher the number of bits, the smaller the size of each Geohash region. Using the sampleLatitude and cellSize parameters is recommended instead. This parameter must be specified at compile or submission time.

Properties

id

Attribute containing an identifier that represents a unique entity being tracked by this operator. If not specified, it is assumed that the input stream contains an attribute named id.

Properties

latitude

Specifies the given entity's latitude. If this parameter is not specified, it is assumed that the input stream contains an attribute named latitude.

Properties

longitude

Specifies the given entity's longitude. If this parameter is not specified, it is assumed that the input stream contains an attribute named longitude.

Properties

minimumDwellTime

Parameter specifying the minimum time, in seconds, an entity must spend within the same Geohash region before a hangout will be reported. This parameter must be specified at compile or submission time.

Properties

precision

This optional parameter specifies the distance, in meters, by which the computed boundaries of each Geohash region will be extended on all sides. For example, assume that an entity's previously reported latitude and longitude coordinates placed it within Geohash g1, and the value of the precision parameter is set to 50.0. If the entity's currently reported location places it up to 50.0 meters in any direction from the boundary of the Geohash g1, the entity will still be said to be within Geohash g1. Thus, a non-zero value for this parameter will cause a hangout to be detected in situations where an entity's location oscillates in and around one neighbouring Geohash. The value specified is in meters. This parameter, if used, must be specified at compile or submission time. If this parameter is not used, the default value is zero.

Properties

sampleLatitude

Parameter specifying the latitude, in degrees, of the area where Hangout detection will be performed. This parameter must be used alongside the cellSize parameter and must be specified at compile or submission time. The absolute value of the sampleLatitude must be no greater than 90.

Properties

timeStamp

This attribute contains the timestamp at which the entity was reported to be in the location specified by latitude and longitude above. The timeStamp attribute is expected to be in milliseconds relative to the Epoch (00:00:00 UTC, January 1, 1970). If not specified, it is assumed that the input stream has an attribute named timeStamp.

Properties

timeout

This optional parameter specifies how often, in seconds, a check should be made to delete data for stale entities. An entity is considered stale if an update to its location has not been received on the entity stream in the last timeout seconds. All ongoing hangouts for which no data has been received within timeout seconds will be marked as expired and the entity will no longer be considered to be hanging out. This parameter, if used, must be specified at compile time or submission time. If this parameter is not used, the default value is zero, which disables such checks.

Properties

Metrics

nCurrentHangouts - Counter

The number of entities that are currently in a hangout.

nCurrentlyMoving - Counter

The number of entities that are not currently in a hangout.

nTimedOutEntities - Counter

The number of entities that have not received an update in the last timeout seconds.

Libraries

Geospatial toolkit helper library
Library Name: geospatialToolkit
Library Path: ../../impl/lib
Include Path: ../../impl/include/toolkit
ST library
Library Name: st
Library Path: ../../impl/lib
Include Path: ../../impl/include/st
PROJ4 library
Library Name: proj
Library Path: ../../impl/lib/external/proj4
Include Path: ../../impl/include/external