/q requests

As described above, the /q API method invokes a script or protocol in indeterminate mode - i.e. the response to the request will be the result of the invocation, and the client must wait until that response is complete.

Request

The JSON payload requires either a valid Tag.bio script or protocol_instance.

Example request (protocol)

{
  "protocol_instance": {
    "name": "summary", // <--Reference to a registered protocol in namespace
    "arguments": {
      "background_cohort": {
        "data_function_type": "categorical",
        "collection": "Species",
        "variable": "Iris-virginica"
      },
      "sepal_and_petal__Sepal": [
        "Sepal width",
        "Sepal length"
      ]
    }
  }
}

Example request (script)

{
  "method":"summary" // <--Scripts are powerful, but typically not allowed on secure/compliant FCs due to the ability for a client to request unauthorized data. This one-line script will tell the FC to summarize every variable in the data source and return appropriate statistics.
}

Response

The response to the /q request will typically return a response object in JSON from the FC. The response might also be a gzipped CSV file, PNG image, Plotly HTML/JS content, or some other text or blob, depending on the “method” of the script/protocol and other attributes. In other words, the response depends on how the protocol wants to respond.

Content-Type

The FC will respond with the appropriate Content-Type header for the response payload.

Example /q response

(truncated for brevity)

{
  "method": "summary",
  "results": [
    {
      "query_type": "numeric-summary",
      "values": {
        "data_reference_type": "numeric",
        "collection": {
          "name": "Sepal"
        },
        "collection-size": 2,
        "collection-entity-count": 150,
        "variable": {
          "data_function_type": "numeric",
          "name": "Sepal length"
        },
        "variable-size": 150,
        "score": "NaN",
        "p-value": "NaN",
        "signed-score": "NaN",
        "greater_than_expected": true,
        "N": 150,
        "count": 150,
        "count-nonzero": 150,
        "m": 150,
        "mean": 5.8433,
        "geo-mean": 5.7857,
        "abs-mean": 5.8433,
        "minimum": 4.3,
        "5th-percentile": 4.6,
        "25th-percentile": 5.1,
        "median": 5.8,
        "abs-median": 5.8,
        "75th-percentile": 6.4,
        "95th-percentile": 7.345,
        "maximum": 7.9,
        "variance": 0.6857,
        "total": 876.5,
        "iqr": 1.3,
        "interquartile-range-by-median": 0.2241,
        "mean-difference": "NaN",
        "abs-mean-difference": "NaN",
        "distribution": [
          5.1,
          4.9,
          4.7,
          ... // <-- truncated for brevity
        ]
      },
      "visualization": [
        {
          "minimum": "4.3",
          "fifth_percentile": "4.6",
          "twenty_fifth_percentile": "5.1",
          "median": "5.8",
          "seventy_fifth_percentile": "6.4",
          "ninety_fifth_percentile": "7.344999999999999",
          "maximum": "7.9",
          "mean": "5.843333333333334",
          "variance": "0.6856935123042504",
          "total": "876.5",
          "iqr": "1.3000000000000007",
          "interquartile_range_by_median": "0.2241379310344829",
          "mean_difference": "NaN",
          "abs_mean_difference": "NaN",
          "m": 150,
          "N": 150,
          "visualization_type": "numeric-summary",
          "descriptors": [
            {
              "descriptor_type": "mean",
              "stat": "5.843333333333334",
              "text": "Mean value for Sepal length (150 / 150 not null)",
              "header": "Mean value for variable"
            }
          ],
          "labels": {},
          "is_default": true,
          "slim_stat": "mean"
        }
      ]
    },
    {
      "query_type": "numeric-summary",
      "values": {
        "data_reference_type": "numeric",
        "collection": {
          "name": "Sepal"
        },
        "collection-size": 2,
        "collection-entity-count": 150,
        "variable": {
          "data_function_type": "numeric",
          "name": "Sepal width"
        },
        "variable-size": 150,
        "score": "NaN",
        "p-value": "NaN",
        "signed-score": "NaN",
        "greater_than_expected": true,
        "N": 150,
        "count": 150,
        "count-nonzero": 150,
        "m": 150,
        "mean": 3.0573,
        "geo-mean": 3.0266,
        "abs-mean": 3.0573,
        "minimum": 2,
        "5th-percentile": 2.3,
        "25th-percentile": 2.8,
        "median": 3,
        "abs-median": 3,
        "75th-percentile": 3.325,
        "95th-percentile": 3.8,
        "maximum": 4.4,
        "variance": 0.19,
        "total": 458.6,
        "iqr": 0.525,
        "interquartile-range-by-median": 0.175,
        "mean-difference": "NaN",
        "abs-mean-difference": "NaN",
        "distribution": [
          3.5,
          3,
          3.2,
          ... // <-- truncated for brevity
        ]
      },
      "visualization": [
        {
          "minimum": "2.0",
          "fifth_percentile": "2.3",
          "twenty_fifth_percentile": "2.8",
          "median": "3.0",
          "seventy_fifth_percentile": "3.3249999999999997",
          "ninety_fifth_percentile": "3.8",
          "maximum": "4.4",
          "mean": "3.0573333333333332",
          "variance": "0.1899794183445191",
          "total": "458.59999999999997",
          "iqr": "0.5249999999999999",
          "interquartile_range_by_median": "0.17499999999999996",
          "mean_difference": "NaN",
          "abs_mean_difference": "NaN",
          "m": 150,
          "N": 150,
          "visualization_type": "numeric-summary",
          "descriptors": [
            {
              "descriptor_type": "mean",
              "stat": "3.0573333333333332",
              "text": "Mean value for Sepal width (150 / 150 not null)",
              "header": "Mean value for variable"
            }
          ],
          "labels": {},
          "is_default": true,
          "slim_stat": "mean"
        }
      ]
    }
  ],
  "meta": {
    "analysis_variables_size": 2,
    "method": "summary",
    "entity_collection": "Unique ID",
    "background_size": 150,
    "background": {
      "data_function_type": "categorical-all"
    },
    "numeric_tag_algorithm": "mann-whitney"
  },
  "protocol_instance": {
    "name": "summary",
    "arguments": {
      "background_cohort": [
        {
          "collection": "Species",
          "variable": "Iris-virginica",
          "multiple_arguments": "or",
          "data_type": "categorical",
          "data_function_type": "categorical"
        }
      ],
      "sepal_and_petal__Sepal": [
        "Sepal width",
        "Sepal length"
      ]
    }
  },
  "protocol_output": {
    "dynamic_title": "Summary",
    "dynamic_description": "A summary report of 150 observations."
  },
  "protocol_definition": {
    "name": "summary",
    "title": "Summary",
    "description": "Produce a summary report using the Tag.bio native method.",
    "require_auth": false,
    "asset": {
      "path": "chart-axes-box-plot-hoz-line-mixed.png"
    },
    "tags": [],
    "method": "summary"
  }
}