...

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.

...

iterateOver can be used in more advanced cases.

Iterate Over a Metadata Field:

Specify a metadata field, in order to generate associations.

eg.  "iterateOver": "json.twitter_entities.user_mentions"

Metadata field nesting is also supported using dot notation, in which case they are looped over to generate calls with _value/_iterator/_index

This is the same as iterating over a metadata array to obtain entities using Manual entities.

For more information concerning metadata fields and support for nested fields, see section Manual entities.

See detailed example below

Iterate Over a Single Entity Type:

A less common scenario is when you want to iterate over a single entity type.  You can do this by using "dummy."

eg "entity1/dummy" or "entity2,dummy"

See detailed example below

Multiplicative:

Create one association for every combination of entities of specified types.  Also referred to as combinatorial association.

eg. "iterateOver": "entity1/entity2/geo_index",

See detailed example below

Associative:

Create one association for every pair (/set) of entities of specified types.  Also referred to as lock-step or additive association.

eg. "iterateOver": "entity1,entity2"

See detailed example below

creationCriteriaScripts

Association fields generated from the entity loop are placed in "_iterator". For example, for "iterateOver": "entity1/entity2/geo_index", an _iterator object with the following fields is available in the Javascript: "_iterator.entity1_index", "_iterator.entity2_index", "_iterator.geo_index".

These fields can be usefully used together with "creationCriteriaScript" scriptlets to filter out unwanted associations, eg when looping over entity1 and entity2 with the same entity type, the following script would ensure the association didn't involve the same entity:

"creationCriteriaScript": "$SCRIPT( return _iterator.entity1_index != _iterator.entity2_index; )", "iterateOver": "entity1/entity2", "entity1": "EmailAddress", "entity2": "EmailAddress", //etc

The creationCriteriaScript runs before the association is generated (so can be safely used to remove items that would return errors).

See detailed example  below

Examples

Basic Association

In the basic association example, the code specifies an entity from the document metadata.  The association specifies the relationship between the type of offense and the date and time at which it was reported.

...

IN PROGRESS

iterateOver

iterateOver can be used in more advanced cases.

Iterate Over a Metadata Field:

Specify a metadata field, in order to generate associations.

eg.  "iterateOver": "json.twitter_entities.user_mentions"

Metadata field nesting is also supported using dot notation, in which case they are looped over to generate calls with _value/_iterator/_index

This is the same as iterating over a metadata array to obtain entities using Manual entities.

For more information concerning metadata fields and support for nested fields, see section Manual entities.

See detailed example below

Iterate Over a Single Entity Type:

A less common scenario is when you want to iterate over a single entity type.  You can do this by using "dummy."

eg "entity1/dummy" or "entity2,dummy"

See detailed example below

Multiplicative:

Create one association for every combination of entities of specified types.  Also referred to as combinatorial association.

eg. "iterateOver": "entity1/entity2/geo_index",

See detailed example below

Associative:

Create one association for every pair (/set) of entities of specified types.  Also referred to as lock-step or additive association.

eg. "iterateOver": "entity1,entity2"

See detailed example below

...

creationCriteriaScripts

Association fields generated from the entity loop are placed in "_iterator". For example, for "iterateOver": "entity1/entity2/geo_index", an _iterator object with the following fields is available in the Javascript: "_iterator.entity1_index", "_iterator.entity2_index", "_iterator.geo_index".

These fields can be usefully used together with "creationCriteriaScript" scriptlets to filter out unwanted associations, eg when looping over entity1 and entity2 with the same entity type, the following script would ensure the association didn't involve the same entity:

"creationCriteriaScript": "$SCRIPT( return _iterator.entity1_index != _iterator.entity2_index; )", "iterateOver": "entity1/entity2", "entity1": "EmailAddress", "entity2": "EmailAddress", //etc

The creationCriteriaScript runs before the association is generated (so can be safely used to remove items that would return errors).

See detailed example  below

Examples

Basic Association

In the basic association example, the code specifies an entity from the document metadata.  The association specifies the relationship between the type of offense and the date and time at which it was reported.

  {
            "associations": [
   "geotag": {             {
                    "entity1": "$metadata.offense,$metadata.method",
                    "geotag": {},
                    "time_start": "$metadata.reportdatetime",
                    "verb": "reported",
                    "verb_category": "crime"
                }
            ]
        }

...

    "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"
        }
    ],

Anchor
single single

iterateOver a single entity type

In some cases you will only want to iterate over a single entity type, rather than two or three, which is more common.  For these cases you can use "dummy" for iterateOver.

...

The association specification uses the multiplicative format to create events using the following math to determine the total number of associations: Entity1 (Person Perpetrator) * Entity2 (Victim Type) * Geo_index (Location) = Total Number of Associations. _index (Location) = Total Number of Associations.

            {
                "creationCriteriaScript": "$FUNC( isOrganizationSpecified(); )",
                "entity1": "Organization",
                "entity2": "VictimType",
                "iterateOver": "entity1/entity2",
                "time_start": "$SCRIPT( return _doc.metadata.incidentdate[0]; )",
                "verb": "attacked",
                "verb_category": "assault/attack"
            },

On the following set of entities:

    "entities":  [
     {    {
            "creationCriteriaScriptactual_name": "$FUNC( isOrganizationSpecified(); )","Taliban",
            "dimension": "Who",
            "entity1disambiguated_name": "OrganizationTaliban",
            "doccount": 0,
            "entity2frequency": "VictimType",
    1,
            "iterateOverindex": "entity1taliban/entity2organization",
  
             "time_startrelevance": "$SCRIPT( return _doc.metadata.incidentdate[0]; )",
   
            "verbtotalfrequency": "attacked"-1,
                "verb_category"type": "assault/attack"
   Organization"
        },

On the following set of entities:

    "entities":
[         {
            "actual_name": "Talibanname": "Targeted, Civilian, Adult from Afghanistan",
            "dimension": "Who",
            "disambiguated_name": "TalibanTargeted, Civilian, Adult from Afghanistan",
            "doccount": 0,
            "frequency": 1,
            "index": "taliban/organizationtargeted, civilian, adult from afghanistan/victimtype",
            "relevance": 0,
            "totalfrequency": -1,
            "type": "OrganizationVictimType"
        },

Sample Output:

{
    "associations": [
        {
            "actualassoc_nametype": "Targeted, Civilian, Adult from AfghanistanEvent",
            "dimensionentity1": "Whotaliban",
            "disambiguatedentity1_nameindex": "Targeted, Civilian, Adult from Afghanistantaliban/organization",
            "doccountentity2": 0"targeted, civilian, adult           "frequency": 1from afghanistan",
            "entity2_index": "targeted, civilian, adult from afghanistan/victimtype",
            "relevancetime_start": 0"2009-07-01T00:00:00",
            "totalfrequencyverb": -1"attacked",
            "typeverb_category": "VictimType"assault/attack"
           },

...

}

Anchor
associative associative

Associative

Additive associations cover the less common case where (eg) 2 entity types have the same number of elements and are ordered "in lock step". For example:

{
    "associations"entities": [
        	{
     "index": "alex/person",
	 "index": "craig/person", 
	  "assoc_typeindex": "Eventbaltimore/city", 
	 "index": "washington dc/city", 
      "entity1	}
]

In this case the additive association specification:

{
	"iterateOver": "talibanentity1,entity2", // note "," instead of        "/"
	"entity1_index": "taliban/organizationPerson",
            	"entity2": "City"targeted,
civilian, adult from afghanistan",
	"verb_category": "lives in",
}

Would generate the 2 associations depicted in the sample output below

],
    "associations":  [
    "entity2_index": "targeted, civilian, adult from afghanistan/victimtype",{
            "time_startentity1": "2009-07-01T00:00:00Alex/person",
            "verb": "attackedlives in",
            "verb_category": "assault/attack"residence",
          }  

...

Additive associations cover the less common case where (eg) 2 entity types have the same number of elements and are ordered "in lock step". For example:

"entities": [
	{
 "entity2": "Baltimore/city",
            "indexassoc_type": "alex/person"Fact"
        },
		{
			"indexentity1": "craigCraig/person",
       	 "index": "baltimore/city",  	 "indexverb": "washingtonlives dc/cityin",
  	} ]

In this case the additive association specification:

{ 	"iterateOver": "entity1,entity2", // note "," instead of "/" 	"entity1verb_category": "Personresidence",
	
            "entity2": "CityWashington dc/city",
	"verb_category
            "assoc_type": "lives inFact",
		}

Would generate the 2 associations "alex/person lives in baltimore/city" and "craig/person lives in washintgon dc/city".

...

 ],

Anchor
creation creation

creationCriteriaScript

...