Identify a Subject Cohort and Extract Clinical Data
This use case shows you how to identify a cohort of subjects and extract clinical data for these patients.
Use Case
I need all the Troponin lab results for a group of AMI subjects to observe how this level changes during their inpatient stay. I want to pull all of my cohort???s diagnoses to evaluate them for comorbidities prior to their enrollment date.
Description
This use case:
-
identifies a cohort of subjects having AMI diagnosis
-
who are part of a study related to AMI disease
-
who have been tested with Troponin T BldV-mCnc
After identifying the Cohort of Subjects, you can retrieve Troponin test results using the Get Observation details. This response will retrieve the Troponin Lab Results, which you can use to analyze the lab results across patients using external tools.
After identifying the list of subjects, you would evaluate the comorbidities. This can be extracted using the Get Condition API that retrieves all the diagnosis information for a particular patient.
To check if the diagnosis precedes the enrollment date, use the Get Demographics details of each subject and extract the enrollment date.
Step 1: Retrieve Subject Query Identifier
This API fetches the list of subjects that conform to the defined criteria. The following Request body is used to POST the API and fetch the subjects matching these criteria. The subjects are fetched using the URL given as the response to this API, as described in Step 2. For details, see the Invoke Subject Query endpoint.
API URL
http://localhost:7010/ohfapi/cg/v3.3/subjectapi/subjects/queries
Request Type
POST
Request Body
{
"executeAsync":false,
"minRetentionPeriodDays":1,
"queryCriteria":{
"allCriteriaList":[
{
"type":"DiagnosisCriteria",
"diagnosisNameList":[
"ST Elevation MI (Unspecified Site)"
]
},
{
"type":"StudyCriteria",
"studyIdentifierList":[
"11"
],
"studyNameList":[
"Troponin levels after AMI"
]
},
{
"type":"ObservationCriteria",
"observationNameList":[
"Troponin T BldV-mCnc"
]
}
]
}
}
JSON Response
[
{
"rel":"status",
"href":"/ohfapi/cg/v3.3/subjectapi/subjects/queries/17501"
},
{
"rel":"result",
"href":"/ohfapi/cg/v3.3/subjectapi/subjects/queries/17501/data"
}
]
Step 2: Retrieve Subject Identifiers for Query Identifier
In this step the API fetches the Subject Identifiers using the URL from the response of the step 1. For details, see the Retrieve Subject Query Results for a Query Identifier endpoint.
API URL
http://localhost:7010/ohfapi/cg/v3.3/subjectapi/subjects/queries/17502/data
Request Type
GET
JSON Response
{
"items":[
{
"subjectId":30004,
"subjectIdentifier":"101"
},
{
"subjectId":30006,
"subjectIdentifier":"102"
},
{
"subjectId":30008,
"subjectIdentifier":"103"
},
{
"subjectId":30009,
"subjectIdentifier":"104"
},
{
"subjectId":30010,
"subjectIdentifier":"105"
}
],
"count":5,
"hasMore":false,
"links":[
{
"rel":"self",
"href":"http://localhost:7001/ohfapi/cg/v3.3/subjectapi/subjects/queries/17502/data"
}
]
}
Step 3a: Retrieve Subject Observations for Subject IDs
This API fetches the Subject Observations for the Subjects IDs (30004, 30006, 30008, 30009 and 30010) retrieved in Step 2. You can extract the troponin values from the response by setting:
-
displaytoTroponin T BldV-mCncunder thecodearray -
valuefrom thevalueQuantityarray
You can then use scripting and external tools to plot the values against the subjects. For details, see the Retrieve Observations for Subject Identifiers endpoint.
API URL
http://localhost:710/ohfapi/cg/v3.3/subjectapi/observations?id=30004&id=30006&id=30008&id=30009&id=30010&offset=0&limit=5
Request Type
GET
JSON Response
{
"resourceType":"Observation",
"items":[
{
"identifier":{
"system":"CDM",
"value":"58661"
},
"code":{
"coding":[
{
"code":"6597-9",
"display":"Troponin T BldV-mCnc",
"description":"Troponin T.cardiac [Mass/volume] in Venous blood",
"sysId":"LOINC",
"sysName":"LOINC",
"sysVersion":"2.58"
}
]
},
"subject":{
"reference":"/ohfapi/cg/v3.3/subjectapi/subjects/30010"
},
"patient":{
"reference":"/ohfapi/cg/v3.3/subjectapi/subjects/30010/patients"
},
"valueQuantity":{
"value":"0.055",
"units":"MicroGramsPerLiter, ug/L",
"code":"MICROGRAMSPERLITER",
"description":"UCUM Code For MicroGramsPerLiter [Mass Concentration Units]",
"sysId":"PH_UOM_UCUM_EXP",
"sysName":"HL7 PH Common UoM Expressions",
"sysVersion":"1.8"
},
"specimen":{
"reference":"/ohfapi/cg/v3.3/subjectapi/clinicalspecimens/1"
},
"effectiveDateTime":"01/06/2017"
},
{
"identifier":{
"system":"CDM",
"value":"58662"
},
"code":{
"coding":[
{
"code":"6597-9",
"display":"Troponin T BldV-mCnc",
"description":"Troponin T.cardiac [Mass/volume] in Venous blood",
"sysId":"LOINC",
"sysName":"LOINC",
"sysVersion":"2.58"
}
]
},
"subject":{
"reference":"/ohfapi/cg/v3.3/subjectapi/subjects/30010"
},
"patient":{
"reference":"/ohfapi/cg/v3.3/subjectapi/subjects/30010/patients"
},
"valueQuantity":{
"value":"0.06",
"units":"MicroGramsPerLiter, ug/L",
"code":"MICROGRAMSPERLITER",
"description":"UCUM Code For MicroGramsPerLiter [Mass Concentration Units]",
"sysId":"PH_UOM_UCUM_EXP",
"sysName":"HL7 PH Common UoM Expressions",
"sysVersion":"1.8"
},
"specimen":{
"reference":"/ohfapi/cg/v3.3/subjectapi/clinicalspecimens/1"
},
"effectiveDateTime":"01/06/2017"
}
],
"count":2,
"hasMore":true,
"links":[
{
"rel":"self",
"href":"http://localhost:7010/ohfapi/cg/v3.3/subjectapi/observations?id=30004&id=30006&id=30008&id=30009&id=30010&offset=0&limit=2"
},
{
"rel":"next",
"href":"http://localhost:7010/ohfapi/cg/v3.3/subjectapi/observations?offset=2&limit=5&id=30004&id=30006&id=30008&id=30009&id=30010"
}
]
}
Step 3b: Retrieve Subject Demographics for Subject IDs
This API fetches the Subject Demographics for the Subjects IDs (30004) retrieved in Step 2. For details, see Retrieve Demographics for Cohort List Name or Subject Identifiers endpoint.
API URL
http://localhost:7010/ohfapi/cg/v3.3/subjectapi/subjects?id=30004offset=0&limit=5
Request Type
GET
JSON Response
{
"items":[
{
"identifiers":[
{
"system":"CDM",
"value":"30004"
},
{
"system":"Customer Defined",
"value":"101"
}
],
"studyName":"Troponin levels after AMI",
"studyIdentifier":"11",
"patientIdentifier":"P2344",
"patient":{
"reference":"/ohfapi/cg/v3.3/subjectapi/subjects/30004/patients"
},
"name":{
"text":"andrew philips love",
"family":"love",
"given":[
"andrew",
"philips"
]
},
"gender":{
"coding":[
{
"code":"1",
"display":"Male",
"description":"Male",
"sysId":"EHA_CUSTOM_CD_SYS",
"sysName":"EHA Custom Code System",
"sysVersion":"1"
}
]
},
"birthDate":"01/12/1966",
"deceasedBoolean":false,
"maritalStatus":{
"coding":[
{
"code":"1",
"display":"Married",
"description":"Married",
"sysId":"EHA_CUSTOM_CD_SYS",
"sysName":"EHA Custom Code System",
"sysVersion":"1"
}
]
},
"address":{
"line":[
"190 broad st"
],
"city":"Weymouth",
"state":{
"coding":[
{
"code":"MA",
"display":"Massachusetts",
"sysId":"EHA_CUSTOM_CD_SYS",
"sysName":"EHA Custom Code System",
"sysVersion":"1"
}
]
},
"postalCode":"2110",
"country":{
"coding":[
{
"code":"1",
"display":"USA",
"description":"United state of America",
"sysId":"EHA_CUSTOM_CD_SYS",
"sysName":"EHA Custom Code System",
"sysVersion":"1"
}
]
}
},
"enrollmentDate":"01/01/2017",
"race":{
"reference":"/ohfapi/cg/v3.3/subjectapi/subjects/30004/race"
},
"ethnicity":{
"reference":"/ohfapi/cg/v3.3/subjectapi/subjects/30004/ethnicity"
}
}
],
"count":1,
"hasMore":false,
"links":[
{
"rel":"self",
"href":"http://localhost:7010/ohfapi/cg/v3.3/subjectapi/subjects?id=30004&id=30006&offset=0&limit=5"
}
]
}
Step 3c: Retrieve Subject Conditions for Subject IDs
This API fetches the Subject Conditions for the Subjects IDs (30004, 30006, 30008, 30009 and 30010) retrieved in Step 2. Use the API in Step 3b to get the enrollmentDate and the API in this step to fetch conditions and assess comorbidities. For details, see Retrieve Conditions for Subject Identifiers.
API URL
http://localhost:7010/ohfapi/cg/v3.3/subjectapi/conditions?id=30004&id=30006&id=30008&id=30009&id=30010&offset=0&limit=5
Request Type
GET
JSON Response
{
"resourceType":"Condition",
"items":[
{
"identifier":{
"system":"CDM",
"value":"92501"
},
"code":{
"coding":[
{
"code":"I21.3",
"display":"ST Elevation MI (Unspecified Site)",
"description":"ST elevation (STEMI) myocardial infarct \nion of unspecified site",
"sysId":"ICD-10-CM",
"sysName":"ICD-10-CM",
"sysVersion":"2017"
}
]
},
"onsetDate":"01/03/2017",
"subject":{
"reference":"/ohfapi/cg/v3.3/subjectapi/subjects/30008"
},
"patient":{
"reference":"/ohfapi/cg/v3.3/subjectapi/subjects/30008/patients"
}
},
{
"identifier":{
"system":"CDM",
"value":"92502"
},
"code":{
"coding":[
{
"code":"K25.7",
"display":"Chronic gastric ulcer without hemorrhage or perforation",
"description":"Chronic gastric ulcer without hemorrhage or perforation",
"sysId":"ICD-10-CM",
"sysName":"ICD-10-CM",
"sysVersion":"2017"
}
]
},
"onsetDate":"07/12/2003",
"subject":{
"reference":"/ohfapi/cg/v3.3/subjectapi/subjects/30008"
},
"patient":{
"reference":"/ohfapi/cg/v3.3/subjectapi/subjects/30008/patients"
}
}
],
"count":2,
"hasMore":true,
"links":[
{
"rel":"self",
"href":"http://localhost:7010/ohfapi/cg/v3.3/subjectapi/conditions?id=30004&id=30006&id=30008&id=30009&id=30010&offset=0&limit=2"
},
{
"rel":"next",
"href":"http://localhost:7010/ohfapi/cg/v3.3/subjectapi/conditions?offset=2&limit=2&id=30004&id=30006&id=30008&id=30009&id=30010"
}
]
}