Overview
This toolkit element enables the generation of one of more types of association between existing entities based on the document or content metadata. The expressions default to replacement strings, or $SCRIPT(...) can be used to return a string using javascript.
Format
{
"display": string,
"associations": [
{
"iterateOver" : "string", // OPTIONAL: If specified as a list of entity types, steps over entities with matching types (again, lock step or combinatorially)
// Can also specify a metadata field (nesting supported using dot notation), in which case they are looped over to generate calls with _value/_iterator/_index
"entity1" : "string", // OPTIONAL: String/script: In "iterateOver"/type cases, the disambiguated name of the entity type; otherwise using entity1_index is preferred.
"entity1_index" : "string", // OPTIONAL: String/script: should return the 'disambiguated_name/type' string, must resolve to an entity or is discarded
"entity2" : "string", // OPTIONAL: String/script: In "iterateOver"/type cases, the disambiguated name of the entity type; otherwise using entity1_index is preferred.
"entity2_index" : "string", // OPTIONAL: String/script: should return the 'disambiguated_name/type' string, must resolve to an entity or is discarded
"verb" : "string", // MANDATORY: String/script
"verb_category" : "string", // MANDATORY: String/script
"assoc_type" : "string", // MANDATORY: Must specify/return one of "Fact", "Event", "Summary" and be overridden (eg converted to summary if there is only 1 index)
// (if left blank, the Structured Analysis Handler will auto-generate this field reasonably accurately based on the contents)
"time_start" : "string", // OPTIONAL: String/script: Must specify/return a time in ISO date format ("yyyy-MM-dd'T'HH:mm:ss") or Javascript time format
"time_end" : "string", // OPTIONAL: String/script: Must specify/return a time in ISO date format ("yyyy-MM-dd'T'HH:mm:ss") or Javascript time format
"geo_index" : "string", // OPTIONAL: String/script: The entity index corresponding to the "geotag" below (or the Type in "iterateOver" cases)
"geotag" : { // OPTIONAL: Format is identical to the docGeo format specified above
"lat": "string", "lon": "string,
"city": "string", "stateProvince": "string, "country": "string", "countryCode": "string
},
//(note the ontology_type for associations is always "point" - use geo_index to specify larger areas)
"creationCriteriaScript" : "string", // // OPTIONAL: script: If populated, runs a user script function and if return value is false doesn't create the object
}
]
}
Description
Associations can be "something that happens or is regarded as happening; an occurrence, especially one of some importance", "the outcome, issue, or result of anything", or "something that occurs in a certain place during a particular interval of time" (Definitions found here: http://dictionary.reference.com/browse/event). Within Infinit.e events are typically a combination of entities assembled in the form of Noun - Verb - Noun, e.g. "a car crashed into a building", "the plane flew to San Diego". In addition to the Noun - Verb - Noun form events can include geographic information (i.e., where an event happened) as well as a start and/or end time for an event.
Examples
Basic Association
In the example, the associations code block has been configured to act on the entity that represents the username of the Twitter user. It also takes into account a secondary entity representing the hashtag of the user's tweet. It acts on the document metadata values that have been provided.
The expected output will report what the tweets were about for the usernames.
{ "assoc_type": "Event",
"entity1_index": "$SCRIPT( return _doc.metadata.json[0].actor.preferredUsername + '/twitterhandle';)",
"entity2_index": "$SCRIPT( return _iterator.text + '/hashtag'; )",
"iterateOver": "json.twitter_entities.hashtags",
"verb": "tweets_about",
"verb_category": "tweets_about"
},
},
Output
In the sample output, an association has been created based on the two entities that were configured in the associations block.
{
"associations": [
{
"assoc_type": "Event",
"entity1": "focalcrm",
"entity1_index": "focalcrm/twitterhandle",
"entity2": "crm",
"entity2_index": "crm/hashtag",
"verb": "tweets_about",
"verb_category": "tweets_about"
},
Multiplicative Associations
Multiplicative association are associations that are created by "multiplying" a combination of entities, locations, and times together to determine the number of associations to extract from the source data.
Multiplicative Associations are specified by specifying which entity types to use to populate the entity1, entity2, geo_index, time_start, and time_end fields of the events created. The iterateOver field is used to specify the order in which the entity types to use are multiplied to determine the total number of associations to create.
In the associations block, two entities are specified for association using $SCRIPT. In order to obtain the association, it will iterateOver the returned metadata which represents the Message-To field of the email message.
The specified scripts return metadata values for the associations.
{ "associations": [
{
"assoc_type": "Event",
"entity1": "$SCRIPT( return _doc.metadata._FILE_METADATA_[0].metadata.Author[0];)",
"entity2": "$SCRIPT(return _value;)",
"iterateOver": "email_meta.Message-To",
"time_start": "$SCRIPT( return _doc.publishedDate;)",
"verb": "emailed",
"verb_category": "emailed/communicated"
}
Output
In the sample output the association displays the sender and receiver of the email message.
], "associations": [
{
"entity1": "cara.semperger@enron.com",
"entity1_index": "cara.semperger@enron.com/account",
"verb": "emailed",
"verb_category": "emailed/communicated",
"entity2": "will.smith@enron.com",
"entity2_index": "will.smith@enron.com/account",
"time_start": "2001-07-09T14:33:32",
"assoc_type": "Event"
}
],
Footnotes:
Legacy documentation:
Legacy documentation:
- StructuredAnalysis object (under "Associations")