Column Values API

Constructing a request payload for the Column Values API

Contents of the API Request Payload

In general, the API request payload is defined as a JSON containing an array of individual filter definitions. A filter definition can contain one or more filters, each specifying one concept to filter on. Filters can be combined using both AND and OR logic, allowing for complex queries to be developed that include multiple criteria for a patient. It is the same logic that is used in the patient-cohort API, however the distinction is that the column value API requires a user to specify which column they would like to count based on.

When using the column values API, a user must first specify which column they would like to get values for. They can also group by other columns in the data mart if desired, as well as add filters for specific CUIs. The payload of the column values API has the following parameters:

  • column (Required) - the element that values should be calculated for
  • group_by - column in the data mart by which the query should be further grouped
  • filter - a list of filters to be applied to the count
  • page - the number of pages to return
  • limit - a limit on the number of concepts to return in the response

Each individual filter configuration has three sub-components, same as the filters used in the patient cohort API:

  • column - the element to be filtered on
  • operator - the logical operator for the statement
  • value - the value to search for in that element

Sample Payload

The below shows a sample payload which can be used to count the number of times Type 2 Diabetes Mellitus or any of its children appear as a condition.

  {
  "column": "display",
  "page": 0,
  "limit": 100,
  "filter": 
    {
      "operator": "and",
      "type": "include",
      "config": [
        {
          "column": "cui",
          "operator": "is_a",
          "value": "C0011860"
        }
      ]
    }
}

Using the Column Values API

The difference between the patient-cohort and column_values APIs lies in what they return. While the patient cohort API returns a list of patients who meet the filter criteria, the column values API simply returns the count of each concept within the Digital Twin database that meet the filter criteria.

The column values API is therefore a great tool for understanding the dispersion of terms in the database and using that to refine your search. For example, if a user is interested in generating a cohort of patients with a subset of respiratory disease terms, they could use this API to understand which concepts are actually present in the database, select the concepts they are interested in, and then feed those concepts to the patient cohort API to generate the cohort.

Users can also leverage this API to summarize cohorts that have already been generated. By feeding a Diabetes query to this API, a user can see the dispersion of type 1 vs. type 2 concepts in our database, for example.

Note: this API returns the number of times a concept is mentioned, not the number of patients that have said concept. This distinction is small but necessary as a large count of a single term can but does not necessarily indicate that there are more patients with that term.

As with the patient cohort API, the column values API also supports hierarchical search. For details around how to leverage this functionality, please refer to the patient cohort API documentation.

When hierarchical search is selected, the column values API will return counts for all child terms of the CUI specified, as well as for the cui itself.

Edit on GitHub