BulkImportConceptSet REST APIs - National-Clinical-Cohort-Collaborative/Data-Ingestion-and-Harmonization GitHub Wiki
Externally curated and defined Concept Set can be imported into the N3C Enclave using the following REST APIs
Concept set is created by POST request. Concept set consists of concept set container, concept set version, concept set code system expression items
- Endpoint: https:unite.nih.gov/actions/api/actions
- headers should contain the authentication bearer token. Documentation about this can be found here
- headers should also include 'content-type: application/json'
- Specify the “actionTypeRid”: in the data along with all of its parameters and its ids.
- Use the Get request to retrieve the container version id. This is a required parameter to add the CodeExpressionItems.
- POST request to create the concept set container, concept set version, concept set expression items.
- concept set expression items can be code and code system pair as a stringList instead of OMOP concept_ids.
CreateNewConceptSet parameters
- Concept Set Name: Enter a descriptive name for this Concept Set. This name must be unique and cannot be changed so choose carefully.
- Intention: Select the intended scope of the of Concept Set (Broad, Narrow, Mixed) then type in a short description of the scope of what the Concept Set represents e.g., “Broad - Asthma diagnoses that are primary and wide range of severity.” Broad: A Concept Set that is as inclusive as possible, e.g., all systemic steroids. Narrow: A Concept Set very specific, eg., arterial labs. Mixed: Between Broad and Narrow Other: e.g., “based on CPT coding”
- Assigned Informatician: Specify the informatician (or data liaison) for the Concept Set. This field is optional and can be edited later.
- Assigned SME: Specify the subject matter expert for the Concept Set. This field is optional and can be edited later.
- Research Project: Select the research project the Concept Set is initially being created for.
- Example of data
"actionTypeRid": "ri.actions.main.action-type.ef6f89de-d5e3-450c-91ea-17132c8636ae",
"parameters": {
"ri.actions.main.parameter.1b5cd6e9-b220-4551-b97d-245b9fa86807":
{
"type": "string",
"string": "<concept name i.e. [VSAC BulkImport - Test] concept name goes here>"
},
"ri.actions.main.parameter.9e33b4d9-c7eb-4f27-81cd-152cc89f334b": {
"type": "string",
"string": "<intention text value goes here>"
},
"ri.actions.main.parameter.28448734-2b6c-41e7-94aa-9f0d2ac1936f": {
"type": "string",
"string": "<assigned informatician i.e.>"
},
"ri.actions.main.parameter.f04fd21f-4c97-4640-84e3-f7ecff9d1018": {
"type": "string",
"string": "<assigned sme>"
},
"ri.actions.main.parameter.2b3e7cd9-6704-40a0-9383-b6c734032eb3": {
"type": "string",
"string": "<status value set to>Under Construction"
},
"ri.actions.main.parameter.02dbf67e-0acc-43bf-a0a9-cc8d1007771b": {
"type": "string",
"string": "<stage value set to>Awaiting Edition"
},
"ri.actions.main.parameter.4e790085-47ed-41ad-b12e-72439b645031": {
"null": {},
"type": "null"
}, # domainteam, optional only if research-project is set
"ri.actions.main.parameter.a3eace19-c42d-4ff5-aa63-b515f3f79bdd": {
"type": "objectLocator",
"objectLocator": {
"objectTypeId" : "research-project",
"primaryKey": {
"research_project_uid": {
"type": "string",
"string": "RP-4A9E27"
},
}
}},
}}
CreateNewDraftOMOPConceptSetVersion parameters
-
While creating a new concept set, the version will be always the first version.
-
concept set container (object)
-
current max version number (integer)
-
version to start with (object)
-
update message (string)
-
intention (string) : this text is build from VSAC
-
limitations (string) : limitation of this concept set
-
provenance (string) : this text is generated from the concept set value set authoritative source
-
intended research project (object): set to Data Ingest & Harmonization research project id RP-4A9E27
-
domain team (object) :
-
codeset_id - the concept set version id of the version you're creating must be passed in. It needs to be unique, and it needs to be within the reserved range of ids, integer within the following range: 1,000,000,000, 1,001,000,000. Its id is ri.actions.main.parameter.eac89354-a3bf-465e-a4be-bbf22a6e2c50
-
Example of data
"actionTypeRid": "ri.actions.main.action-type.fb260d04-b50e-4e29-9d39-6cce126fda7f",
"parameters": {
"ri.actions.main.parameter.51e12235-c217-47e2-a347-240d379434e8": {
"type": "objectLocator",
"objectLocator": {
"objectTypeId": "omop-concept-set-container",
"primaryKey": {
"concept_set_id": {
"type": "string",
"string": "<cs_name, must match the concept name string specified in the container creation>"
}}}},
# deprecated, but required until it is dropped, current max version
"ri.actions.main.parameter.c58b7fa6-e6b4-49ad-8535-433507fe3d13": {
"null": {},
"type": "null"
},
# legacy version, but required for now, version to start with which is 1
"ri.actions.main.parameter.c3e857d9-a9d8-423c-9dec-610e4e90f971": {
"null": {},
"type": "null"
},
# update message, required
"ri.actions.main.parameter.ae8b8a16-c690-42fa-b828-e6032<4074661": {
"type": "string",
"string": "Initial [VSAC] version"
},
# intension
"ri.actions.main.parameter.2d5df665-6728-4f6e-83e5-8256551f8851" : {
"type": "string",
"string": "<intension string build from vsac source is set here>"
},
# limitations
"ri.actions.main.parameter.32d1ce35-0bc1-4935-ad18-ba4a45e8113f": {
"type": "string",
"string": "<limitations text from vsac source is set here>"
},
# provenance
"ri.actions.main.parameter.5577422c-02a4-454a-97d0-3fb76425ba8c": {
"type": "string",
"string": "<provenance built from the VSAC source is set here>"
},
# authority source or steward
"ri.actions.main.parameter.f6766c2d-79a6-445f-a664-d245e1abf199": {
"type": "string",
"string": authority
},
# research project
"ri.actions.main.parameter.465404ad-c767-4d73-ab26-0d6e083eab8e": {
"type": "objectLocator",
"objectLocator": {
"objectTypeId": "research-project",
"primaryKey": {
"research_project_uid": {
"type": "string",
"string": "RP-4A9E27"
}
}}}
}
AddCodesasVersionExpressions
-
Most of the externally curated and defined concept set expressions are defined in terms of ICD10CM, ICD10PCS, LOINC, RxNorm, SNOMEDCT vocabulary codes and various code system value set terminology codes. This API will allow to add the concept set expression items using the code and code system.
-
Version (object type) - omop-concept-set as ObjectTypeId and codeset_id is the primary key
-
Exclude (boolean type)
-
Include Descendents (boolean type)
-
Include Mapped (boolean type)
-
Optional Annotation (string | null type)
-
Codes (List of colon-delimited stringList)
{"actionTypeRid": "ri.actions.main.action-type.e07f2503-c7c9-47b9-9418-225544b56b71",
"parameters":
{"ri.actions.main.parameter.ad298972-0db3-4d85-9bbc-0c9ecd6ecf01":
{"type": "objectLocator", "objectLocator": {"objectTypeId": "omop-concept-set",
"primaryKey": {"codeset_id": {"type": "integer", "integer": 786650526}}}},
"ri.actions.main.parameter.4a7ac14f-b292-4105-b7f5-5d0817b8cdc4": {
"type": "boolean", "boolean": false},
"ri.actions.main.parameter.6cb950fd-894d-4176-9ad5-080373e26777": {
"type": "boolean", "boolean": true},
"ri.actions.main.parameter.1666c70c-0cb8-47c0-91e5-cb1d7e5bf316": {
"type": "boolean", "boolean": false},
"ri.actions.main.parameter.63e31a99-6b94-4580-b95a-a482ed64fed0": {
"null": {}, "type": "null"},
"ri.actions.main.parameter.c9a1b531-86ef-4f80-80a5-cc774d2e4c33": {
"type": "stringList",
"stringList": {
"strings":
["SNOMEDCT:253811003", "ICD10CM:K76.5", "ICD10CM:K76.6"]
}
}
}
}