Beginnings of the technical writing as example for IG Contributors.

NIH-NCPI · Jul 17, 2024 · b8f5f6d · b8f5f6d
1 parent c444212
commit b8f5f6d
Show file tree

Hide file tree

Showing 4 changed files with 209 additions and 10 deletions.
diff --git a/fsh-generated/resources/StructureDefinition-ncpi-participant.json b/fsh-generated/resources/StructureDefinition-ncpi-participant.json
@@ -0,0 +1,151 @@
+{
+  "resourceType": "StructureDefinition",
+  "id": "ncpi-participant",
+  "url": "https://nih-ncpi.github.io/ncpi-fhir-ig-2/StructureDefinition/ncpi-participant",
+  "version": "0.1.0",
+  "name": "NcpiParticipant",
+  "title": "NCPI Participant",
+  "status": "draft",
+  "description": "Research oriented patient",
+  "fhirVersion": "4.3.0",
+  "kind": "resource",
+  "abstract": false,
+  "type": "Patient",
+  "baseDefinition": "http://hl7.org/fhir/StructureDefinition/Patient",
+  "derivation": "constraint",
+  "differential": {
+    "element": [
+      {
+        "id": "Patient.id",
+        "path": "Patient.id",
+        "short": "ParticipantID - Unique participant identifier. System identifier used for internal references.",
+        "min": 1
+      },
+      {
+        "id": "Patient.extension",
+        "path": "Patient.extension",
+        "slicing": {
+          "discriminator": [
+            {
+              "type": "value",
+              "path": "url"
+            }
+          ],
+          "ordered": false,
+          "rules": "open"
+        }
+      },
+      {
+        "id": "Patient.extension:us-core-birth-sex",
+        "path": "Patient.extension",
+        "sliceName": "us-core-birth-sex",
+        "short": "Sex assigned at birth (or pre-natal observed sex)",
+        "min": 0,
+        "max": "1",
+        "type": [
+          {
+            "code": "Extension",
+            "profile": [
+              "http://hl7.org/fhir/us/core/StructureDefinition/us-core-birthsex"
+            ]
+          }
+        ]
+      },
+      {
+        "id": "Patient.extension:us-core-race",
+        "path": "Patient.extension",
+        "sliceName": "us-core-race",
+        "short": "US Core Race",
+        "min": 0,
+        "max": "1",
+        "type": [
+          {
+            "code": "Extension",
+            "profile": [
+              "http://hl7.org/fhir/us/core/StructureDefinition/us-core-race"
+            ]
+          }
+        ]
+      },
+      {
+        "id": "Patient.extension:us-core-ethnicity",
+        "path": "Patient.extension",
+        "sliceName": "us-core-ethnicity",
+        "short": "US Core Ethnicity",
+        "min": 0,
+        "max": "1",
+        "type": [
+          {
+            "code": "Extension",
+            "profile": [
+              "http://hl7.org/fhir/us/core/StructureDefinition/us-core-ethnicity"
+            ]
+          }
+        ]
+      },
+      {
+        "id": "Patient.extension:population",
+        "path": "Patient.extension",
+        "sliceName": "population",
+        "short": "Population, Race, and/or Ethnicity information.",
+        "min": 0,
+        "max": "1",
+        "type": [
+          {
+            "code": "Extension",
+            "profile": [
+              "https://nih-ncpi.github.io/ncpi-fhir-ig-2/StructureDefinition/research-population"
+            ]
+          }
+        ]
+      },
+      {
+        "id": "Patient.extension:dob-method",
+        "path": "Patient.extension",
+        "sliceName": "dob-method",
+        "short": "Specifies method used to alter DOB for research sharing. Details should be available in the study protocols.",
+        "min": 0,
+        "max": "1",
+        "type": [
+          {
+            "code": "Extension",
+            "profile": [
+              "https://nih-ncpi.github.io/ncpi-fhir-ig-2/StructureDefinition/research-date-of-birth-method"
+            ]
+          }
+        ]
+      },
+      {
+        "id": "Patient.extension:age-at-last-vital-status",
+        "path": "Patient.extension",
+        "sliceName": "age-at-last-vital-status",
+        "short": "Age or date of last vital status",
+        "min": 0,
+        "max": "1",
+        "type": [
+          {
+            "code": "Extension",
+            "profile": [
+              "https://nih-ncpi.github.io/ncpi-fhir-ig-2/StructureDefinition/research-age-at-last-vital-status"
+            ]
+          }
+        ]
+      },
+      {
+        "id": "Patient.identifier",
+        "path": "Patient.identifier",
+        "short": "External IDs for this participant. Requires scoping."
+      },
+      {
+        "id": "Patient.birthDate",
+        "path": "Patient.birthDate",
+        "short": "Date of Birth of the participant. Details of privacy method should be included in DOBMethod"
+      },
+      {
+        "id": "Patient.deceased[x]",
+        "path": "Patient.deceased[x]",
+        "short": "Implementers can provide relativeDateTime or actual date or T/F, depending on data available."
+      }
+    ]
+  }
+}
diff --git a/input/pagecontent/StructureDefinition-SharedDataModelResearchParticipant-intro.md b/input/pagecontent/StructureDefinition-SharedDataModelResearchParticipant-intro.md
@@ -0,0 +1,11 @@
+### NCPI Participant
+#### Participant
+Participants are a scoped entity that represents the anchor for all data for a specific real-world entity. Typically, this is a person involved in a research study and all of their data collected for that study (or set of studies). This entity has direct attributes (eg, demographics), so if two studies that share an identifier space present conflicting information, it may be necessary to have multiple participants.
+
+Participants (ie, data about an entity that is scope constrained) can be linked with a Person.
+Participants can be associated with different substudies (and with different data sharing restrictions) via Study Participation.
+
+#### Person
+In situations where a person participates in multiple studies that have participant data scoped in an exclusive way within one or more projects, we have a Person entity. It is functionally a “group” of Participants that are all describing one “actual” person. This is especially to support situations where access policies about that participant might be conflicting and cases where the data itself about the participant might conflict but cannot be adjudicated by the repository.
+Study Participation
+Study Participation (ResearchSubject) describes the relationship between a specific Participant and a Research Study that collects and is sharing data on that Participant. A single Participant may have this “Study Participation” relationship with multiple Research Studies, and each relationship may have a different sharing restriction. These relationships are primarily illustrative, as the Access Policy details of any given element are documented within that element. 
diff --git a/input/pagecontent/StructureDefinition-ncpi-participant-intro.md b/input/pagecontent/StructureDefinition-ncpi-participant-intro.md
@@ -1,11 +1,33 @@
-### NCPI Participant
-#### Participant
-Participants are a scoped entity that represents the anchor for all data for a specific real-world entity. Typically, this is a person involved in a research study and all of their data collected for that study (or set of studies). This entity has direct attributes (eg, demographics), so if two studies that share an identifier space present conflicting information, it may be necessary to have multiple participants.
+#### Key Guidelines
+The NCPI Participant profile is based on the standard resource type, [Patient](https://hl7.org/fhir/R4B/patient.html) and is intended to represent an individual participating in a specific research study. 
 
-Participants (ie, data about an entity that is scope constrained) can be linked with a Person.
-Participants can be associated with different substudies (and with different data sharing restrictions) via Study Participation.
+##### Added Profile Restrictions
+In order to ensure that our resources are interoperable across studies, we have employed a number of restrictions that should make consuming Patient resources more consistent.
 
-#### Person
-In situations where a person participates in multiple studies that have participant data scoped in an exclusive way within one or more projects, we have a Person entity. It is functionally a “group” of Participants that are all describing one “actual” person. This is especially to support situations where access policies about that participant might be conflicting and cases where the data itself about the participant might conflict but cannot be adjudicated by the repository.
-Study Participation
-Study Participation (ResearchSubject) describes the relationship between a specific Participant and a Research Study that collects and is sharing data on that Participant. A single Participant may have this “Study Participation” relationship with multiple Research Studies, and each relationship may have a different sharing restriction. These relationships are primarily illustrative, as the Access Policy details of any given element are documented within that element. 
+* ID **should** be a globally unique identifier associated with the patient. This practice is intended to make constructing queries for the same patient compatible across different servers (such as QA vs PROD) but also to make the resource URLs more meaningful. 
+* identifier **should** have all appropriate Identifiers with a meaningful system/value pair. Such identifiers may include DbGAP accession IDs, global and external IDs, etc. 
+* race and ethnicity **must** be defined using OMB Categories using the relevant US Core extensions ([us-core-race extension](https://hl7.org/fhir/us/core/STU7/StructureDefinition-us-core-race.html) & [us-core-ethnicity](https://hl7.org/fhir/us/core/STU7/StructureDefinition-us-core-ethnicity.html))
+* Where birth date is known, the extension, [reseearch-date-of-birth-method](StructureDefinition-research-date-of-birth-method.html) **must** be provided to indicate the method used in the construction of that value.  
+
+#### Recommended Practices
+TDOD: Write Recommended Practices
+
+##### FHIR Mappings
+The following fields from the shared data model are to be mapped into the NCPI Participant as shown below:
+
+| **Logical Model Property** | **Cardinality** |  **NCPI Participant Mapping** |**Usage Guidance** | **Notes** |
+[participantID](structuredefinition-shareddatamodelresearchparticipant-definitions.html#diff_SharedDataModelResearchParticipant.participantID)|1..1|id| Strongly recommended | It is strongly recommended for the Participant Resource ID to be a unique identifier with an appropriate system|
+[externalID](structuredefinition-shareddatamodelresearchparticipant-definitions.html#diff_SharedDataModelResearchParticipant.externalID)|0..*|identifier||
+[population](structuredefinition-shareddatamodelresearchparticipant-definitions.html#diff_SharedDataModelResearchParticipant.population)|0..*|TBD|Strongly recommended ||
+[ombRace](structuredefinition-shareddatamodelresearchparticipant-definitions.html#diff_SharedDataModelResearchParticipant.ombRace)|0..*|extension|Required if available |Use the [us-core-race extension](https://hl7.org/fhir/us/core/STU7/StructureDefinition-us-core-race.html)|
+[ombEth](structuredefinition-shareddatamodelresearchparticipant-definitions.html#diff_SharedDataModelResearchParticipant.ombEth)|0..*|extension|Required if available|Use the [us-core-ethnicity](https://hl7.org/fhir/us/core/STU7/StructureDefinition-us-core-ethnicity.html)|
+[sex](structuredefinition-shareddatamodelresearchparticipant-definitions.html#diff_SharedDataModelResearchParticipant.sex)|1..1|extension|Required if avaialble|Use the [us-core-birthsex](https://hl7.org/fhir/us/core/STU7/StructureDefinition-us-core-birthsex.html) extension|
+[dateOfBirth](structuredefinition-shareddatamodelresearchparticipant-definitions.html#diff_SharedDataModelResearchParticipant.dateOfBirth)|0..1|birthDate|Optional||
+[dobMethod](structuredefinition-shareddatamodelresearchparticipant-definitions.html#diff_SharedDataModelResearchParticipant.dobMethod)|0..1|extension [ResearchDateOfBirthMethod](StructureDefinition-research-date-of-birth-method)|Required if dateOfBirth is provided||
+[ageAtLastVitalStatus](structuredefinition-shareddatamodelresearchparticipant-definitions.html#diff_SharedDataModelResearchParticipant.ageAtLastVitalStatus)|0..1|extension [AgeAtLastVitalStatus](StructureDefinition-research-age-at-last-vital-status)|Recommended||
+[vitalStatus](structuredefinition-shareddatamodelresearchparticipant-definitions.html#diff_SharedDataModelResearchParticipant..vitalStatus)|0..1|deceased|Recommended||
+
+##### Study Participation
+The conventional FHIR mechanism to link Patient resources to a ResearchStudy is through the use of a ResearchSubject resource. **TODO: Write up details regarding the TBD Profile, NCPI Person, and the NCPI ResearchStudy.**
+
+**TBD Write up details about linking a patient to the research study access policy (consent)**
diff --git a/input/pagecontent/StructureDefinition-ncpi-participant-notes.md b/input/pagecontent/StructureDefinition-ncpi-participant-notes.md
@@ -1 +1,16 @@
--- Do we need any additional notes?
+#### US Core Race Values
+The extension binds the following [ValueSet](https://cts.nlm.nih.gov/fhir/res/ValueSet/$expand?url=http://cts.nlm.nih.gov/fhir/ValueSet/2.16.840.1.113762.1.4.1021.24). Please note that, in order to view this, you must have logged into your browser using your API key (or provided the key using appriate flow specified by UMLS's docs)
+
+For those who don't have a key, or just want a quick reminder, the codes are listed below:
+
+ValueSet URL: http://cts.nlm.nih.gov/fhir/ValueSet/2.16.840.1.113762.1.4.1021.24
+
+| **Code** | **Display** | **System** |
+| F | Female | http://terminology.hl7.org/CodeSystem/v3-AdministrativeGender |
+| M | Male | http://terminology.hl7.org/CodeSystem/v3-AdministrativeGender |
+| ASKU | asked but unknown | http://terminology.hl7.org/CodeSystem/v3-NullFlavor |
+| OTH | other | http://terminology.hl7.org/CodeSystem/v3-NullFlavor |
+| UNK | unknown | http://terminology.hl7.org/CodeSystem/v3-NullFlavor |
+| asked-declined | Asked But Declined | http://terminology.hl7.org/CodeSystem/data-absent-reason | 
+
+Please note that there are 3 different systems listed in the codes above.