How it Works (detailed)

Running a protocol

Making an API call to run a protocol is simple. You just need to compose a protocol_instance attribute, and make a HTTPS GET or POST query with the following syntax:

https://your-tag.cortex-url/q{...} //Where the {...} JSON object contains a protocol_instance attribute

Here's a generic example of a protocol_instance. The name attribute indicates the protocol you wish to run. For each argument you want to set, replace e.g. "aaa1" with that argument name. The protocol will fail if all mandatory arguments are not set.

{
  "protocol_instance": {
    "name":"pppp", //A valid protocol name
    "arguments":{
      "aaa1":1, //Note how arguments can be provided
      "aaa2": ["value_two", "value_three"], //as primitives (string, number, boolean)
      "aaa3":true, //or arrays of primitives
    ...
    }
  },
  "api_key":"kkkk", //Optional, if the tag.cortex server requires it
  "zip":? //Optional, defaults to false, specifies if results should be returned gzipped
}

Parsing protocol output

Parsing the response of an API call to run a protocol is straightforward, but there is a lot of information when many variable results are returned. The best way to understand the response is to make an API call and inspect the result yourself. For detailed information, see the section below. Here are the key high-level components:

{
  "protocol_instance": {...}, //This is the API call you made
  "protocol_definition": {...}, //This contains metadata about the protocol that was run
  "method": "mmmm", //The analysis method that was run
  "background_size": #, //The number of entities in the background
  "focus_size": #, //The number of entities in the focus
  "results": [ //Array containing statistics for each of the analysis_variables
    {
      "query_type":"tag-tag", //query_types include "tag-tag" and numeric-tag"
      "query_name": "...", //The statistical tests used, with version numbers
      "values": [ //The values array contains statistics and variable information
        "collection": {"name":"cccc"}, //The collection for the variable analyzed
        "variable": {"name":vvvv"}, //The variable analyzed
        "entities": [...] //Optional annotation for the entities associated with this variable
      ],
      "vizualization": [...] //Optional visualization recommendations from the protocol
    }
    ... //The number of results returned is controlled by the protocol
  ]
}

Here's an actual single result in the results array attribute from a protocol API call:

{
  "query_type": "tag-tag", //tag-tag is the result of a tag-comparison method with a categorical variable
  "query_name": "TagComparison: Hypergeometric v. 0.1.0 MannWhitney U test v. 0.1",
  "values": {
    "collection": {
      "name": "Movie title|Rating\u003d5" //Note how text is URL-encoded
    },
    "variable": {
      "name": "Pirates of the Caribbean: The Curse of the Black Pearl"
    },
    "score": "Infinity", //Ranges from 0 (numeric) to "Infinity" (a string, because JSON)
    "signed score": "Infinity", //Ranges from "-Infinity" to "Infinity" (with numeric values in-between)
    "greater_than_expected": true, //If this variable had a greater than expected value in the focus
    "k": 6393, //The intersection size of categorical variable and focus
    "m": 82549, //The categorical variable size
    "n": 10299, //The focus size for this variable (might differ between variables analyzed)
    "N": 192906, //The background size for this variable (might differ between variables analyzed)
    "k|n": 0.6207398776580251, //Using the / character is bad practice, so we use | instead
    "k|m": 0.07744491150710488,
    "n|N": 0.0533886970856272,
    "m|N": 0.4279234445792251,
    "expected-k": 4407.18355572144, //The expected value of k, given N, m and n
    "k-delta": 1985.81644427856, //The difference between k and expected-k
    "abs-k-delta": 1985.81644427856,
    "expected-k|m": 0.0533886970856272,
    "k|m-delta": 0.02405621442147768,
    "abs-k|m-delta": 0.02405621442147768,
    "k|m-fold-change": 1.4505862801426908,
    "expected-k|n": 0.4279234445792251,
    "k|n-delta": 0.19281643307879998,
    "abs-k|n-delta": 0.19281643307879998,
    "k|n-fold-change": 1.450586280142691,
    "coefficient": "NaN",
    "m-not-k": 76156.0,
    "n-not-k": 3906.0
  },
  "visualization": [ //This is defined in the protocol, but delivered in each result
    { //so the name of the variable and/or collection can be inserted
      "title": "Visualization", //into the dynamic text explanations
      "top": {
        "kn": "Users (6393) who rated Pirates of the Caribbean: The Curse of the Black Pearl five stars, divided by users who rated Blue Collar Comedy Tour: The Movie five stars (10299)"
      },
      "bottom": {
        "mN": "Users (82549) who rated Pirates of the Caribbean: The Curse of the Black Pearl five stars, divided by users who saw Pirates of the Caribbean: The Curse of the Black Pearl (192906)"
      },
      "is_default": true
    }
  ]
}

Running an ad-hoc Tag.script

The Tag.cortex platform can also respond to ad-hoc Tag.script requests. To run a Tag.script without referring to a registered protocol, insert a "script":true attribute at the top. The response from an API call with an ad-hoc Tag.script will be the same as an API call to a protocol, but without the protocol_instance and protocol_definition attributes.

{
  "method": "mmmm", //See the Tag.script Reference
  ...
}

Requesting information about registered protocols

The Tag.cortex platform can respond to queries about protocols it has registered. Here are some examples: This is the generic form of a protocol information request - note the p before the JSON object instead of the q used to run a protocol or ad-hoc Tag.script.

https://your-tag.cortex-url/p{...}

To get a list of all registered protocols, use the following JSON object:

{
  "request": "get_protocols" //Information for all protocols will be returned
}

To request information about a specific protocol:

{
  "request": "get_protocol",
  "name": "pppp" //Where name specifies the name of a protocol
}

To get all tags for registered protocols:

{
  "request": "get_tags" //A list of all tags available
}

To get all protocols that have been registered with a specific set of tags:

{
  "request": "get_protocols_for_tags",
  "tags": ["ttt1","ttt2"] //One or more tags
}

To get all subjects that protocols can use as arguments:

{
  "request": "get_subjects"
}

To get all protocols that have been registered to accept a subject:

{
  "request": "get_protocols_for_subject",
  "subject": "ssss", //A subject (team, player, patient, customer, etc.)
  "exact": ? //Optional, boolean value to require an exact match
}