Merge pull request #31 from uc-cdis/main

Merge in the CDE and updated VLMD documentation

docs/vlmd/index.md

@@ -1,17 +1,34 @@
-# Variable-level Metadata Submission 
+# Variable-level Metadata Submission  
+
+The HEAL Data Platform contains variable-level metadata (VLMD) from two sources:
+
+* [**Data Dictionaries:**](#data-dictionaries) these files describe each variable within a study's dataset
+* [**HEAL CDEs (Common Data Elements):**](#heal-cdes-common-data-elements) these are validated and structured questionnaires used by investigators conducting research with human participants to harmonize the data collected across studies
+
+!!! info 
+
+     In order to submit any VLMD to the Platform, two conditions must be true:
+     
+     **1) The study must already be registered:** If your study is not yet registered on the HEAL Data Platform, please see our instructions for how to register your study before submitting VLMD. 
+     
+     <p align="center">[How to Register Your Study](../study-registration/index.md){ .md-button }</p>
+
+     **2) You must have access to submit VLMD:** If you are the person who registered your study, you automatically have access. If someone else registered your study, you can follow the instructions below to request access to submit VLMD. 
+
+     <p align="center">[How to Request Access to Submit VLMD](vlmd_request_access.md){ .md-button }</p>
+
+## Data Dictionaries
 
 Data Dictionaries, which contain variable-level metadata, describe each variable within a dataset. Examples of variable-level attributes include the variable name, description (or variable label), type, format, terminology, and source.
 
-In order to submit a study’s data dictionary to the Platform, the data dictionary must conform to the HEAL [variable-level metadata schema](https://github.com/HEAL/heal-metadata-schemas/tree/main/variable-level-metadata-schema). The following instructions will demonstrate how to use the HEAL Data Utilities' VLMD tool to help you generate a HEAL-compliant data dictionary from your dataset or existing data dictionary.
+In order to submit a study’s data dictionary to the Platform, the data dictionary must conform to the HEAL [variable-level metadata schema](https://github.com/HEAL/heal-metadata-schemas/tree/main/variable-level-metadata-schema). The following instructions will demonstrate how to use the HEAL Data Utilities' VLMD tool to help you generate a HEAL-compliant data dictionary from your dataset or existing data dictionary, and then submit it to the Platform.
 
 1. [How to Generate a HEAL-compliant Data Dictionary](vlmd_healdata_utils.md)
 
 2. [How to Submit a HEAL-compliant Data Dictionary](vlmd_submission.md)
 
-!!! info 
+## HEAL CDEs (Common Data Elements)
 
-     Note: in order to submit a data dictionary to the Platform, the study must first be registered.
-     
-     If you have not done so, please see our instructions on how to register your study. 
-     
-     <p align="center">[How to Register Your Study](../study-registration/index.md){ .md-button }</p>
+HEAL CDEs are validated and structured questionnaires that include fields describing the human subject data collected, along with how the data was gathered, and how the response is represented in the dataset. HEAL investigators conducting research with human participants use CDEs to allow the data collected by different studies to be harmonized for further analyses. [*(To learn more about HEAL CDEs, visit this NIH page.)*](https://heal.nih.gov/data/common-data-elements)
+
+* To report the CDEs your study used to the Platform, follow the instructions on [this page](vlmd_submit_CDE.md).  

docs/vlmd/vlmd_request_access.md

@@ -0,0 +1,57 @@
+# Request Access to Submit Variable-level Metadata (VLMD)
+
+!!! info 
+
+     In order to submit a Data Dictionary to the Platform, **the study must already be registered on the HEAL Data Platform.** If your study is not yet registered, please see our instructions for how to register your study before submitting VLMD.
+
+     <p align="center">[How to Register Your Study](../study-registration/index.md){ .md-button }</p>
+
+---
+
+## Request Access to Submit Variable-level Metadata
+
+Requesting Access is the first step in submitting VLMD to the HEAL Data Platform. If you were the person that registered the study on the Platform, you can go directly to [Submit VLMD](#submit-vlmd). If someone else registered the study, follow the steps below to request access to submit VLMD.
+
+### Login to the HEAL Data Platform
+
+Click on the [Login button in the upper right corner](https://healdata.org/portal/login) to log in to the Platform.  
+
+<!-- If you want to play with sizing, you can use something like ![](../img/heal_login.png){: style="height:250px;width:534px"} -->
+![HEAL login screenshot](../img/heal_login.png)
+
+### Find your study
+
+From the [Discovery Page](https://healdata.org/portal/discovery), find the study for which you wish to request access to submit VLMD.
+
+- Click on the study to open the Study Page
+- At the top of the Study Page, select `Request Access to Submit Variable-level Metadata` to navigate to the VLMD Submission Request Form.
+
+![](../img/submit_vlmd_req_access_button.png)
+
+!!! info
+
+    If you do not see `Request Access to Submit Variable-level Metadata`, see below for how to proceed.  
+    If you see:
+
+    - **`Login to...`** - you are not logged in. [Log in first](https://healdata.org/portal/login), then repeat the instructions above.
+    - **`Request Access to Register This Study`** - your study is not yet registered on the HEAL Data Platform. Follow these instructions to [request access and register your study](../study-registration/index.md).  
+    - **`Submit Variable-level Metadata`** - You already have access to submit VLMD. Proceed to [submit your data dictionary or CDEs](#submit-vlmd). 
+
+### Complete the VLMD Submission Request Form
+
+- The field `Study Name - Grant Number` will already be filled in.
+- You will need to provide your name, your email address, institutional affiliation and role on the project/study.
+
+![](../img/submit_vlmd_req_access_form.png)
+
+After submitting, you will see a message indicating it was successfully sent. Within one business day, you will receive an email reporting that your request has been approved. When approved, you will then be able to submit VLMD (either a data dictionary or CDEs) to the Platform.  
+
+![](../img/submit_vlmd_req_access_popup.png)
+
+
+## Submit VLMD
+
+You are now ready to submit VLMD! Find instructions for submitting a Data Dictionary or reporting CDEs below:
+
+* [Generate](vlmd_healdata_utils.md) and [Submit a HEAL-compliant Data Dictionary](vlmd_submission.md)
+* [Report CDEs](vlmd_submit_CDE.md)

docs/vlmd/vlmd_submission.md

@@ -1,112 +1,78 @@
 # Submit a Data Dictionary
 
-In order to submit a HEAL-compliant data dictionary and have it be associated with your study on the HEAL Data Platform, that study must first be registered. If you have not already registered your study, please see our instructions on [study registration](../study-registration/index.md).
+!!! info 
 
-If you were the team member to register your study, please skip ahead to our instructions on how to [submit a data dictionary to the Platform](#submit-a-data-dictionary_1). 
-
-If your study was registered by another team member, you will first need to request access to submit a data dictionary. Please follow the instructions below. 
-<!--
-!!! info
-
-     These instructions will show you how to request access to submit a data dictionary to the Platform. 
-
-     If you were the team member to register your study, please skip to our instructions on how to submit a data dictionary to the Platform. 
+     In order to submit a Data Dictionary to the Platform, the following conditions must be true:
      
-     <p align="center">[Submit a Data Dictionary](#submit-a-data-dictionary_1){ .md-button }</p>
--->
-
----
-
-## Request Access to Submit a Data Dictionary
-
-### Login to the HEAL Data Platform
-
-<!-- If you want to play with sizing, you can use something like ![](../img/heal_login.png){: style="height:250px;width:534px"} -->
-![](../img/heal_login.png)
-
-
-### Find your study
-
-From the [Discovery Page](https://healdata.org/portal/discovery), find the study you
-wish to request access to register.
-
-- Click on the study to open the Study Page
-- At the top of the Study Page, select `Request Access to Submit a Data Dictionary`
-  to navigate to the Study Registration Access Request form.
-
-![](../img/submit_dd_req_access_button.png)
-
-
-### Complete the Data Dictionary Submission Request Form
-
-- The field `Study Name - Grant Number` will already be filled in.
-- You will need to provide your name, your email address, institutional
-  affiliation and role on the project/study.
-
-![](../img/submit_dd_request_form.png)
+     **1) The study must already be registered:** If your study is not yet registered on the HEAL Data Platform, please see our instructions for how to register your study before submitting VLMD. 
+     
+     <p align="center">[How to Register Your Study](../study-registration/index.md){ .md-button }</p>
 
-After submitting, you will receive an email indicating the status of your
-request within one business day. When approved, you will then be able to submit a data dictionary to the Platform.
+     **2) You must have access to submit VLMD:** If you are the person who registered your study, you automatically have access. If someone else registered your study, you can follow the instructions below to request access to submit VLMD. 
 
+     <p align="center">[How to Request Access to Submit VLMD](vlmd_request_access.md){ .md-button }</p>
 
-## Submit a Data Dictionary
+     **3) The Data Dictionary must conform to the HEAL VLMD schema:** See below for the instructions for how to generate a HEAL-compliant data dictionary. 
 
-!!! info
+      <p align="center">[Generate a HEAL-compliant Data Dictionary](vlmd_healdata_utils.md){ .md-button }</p>
 
-    Data dictionaries must conform to the HEAL [variable-level metadata schema](https://github.com/HEAL/heal-metadata-schemas/tree/variable-level-metadata/variable-level-metadata-schema). Please view our instructions on how to generate a HEAL-compliant data dictionary if you have not yet done so. 
-
-    <p align="center">[Generate a HEAL-compliant Data Dictionary](vlmd_healdata_utils.md){ .md-button }</p>
-
-    Additionally, submissions should not include data of any kind. Submissions containing data will be removed from the Platform.
+      **4) Submissions should not include data of any kind**. Submissions containing data will be removed from the Platform.
 
     More information and submission templates can be found [here](https://github.com/HEAL/heal-metadata-schemas/tree/variable-level-metadata).
 
-### Login to the HEAL Data Platform 
+## Login to the HEAL Data Platform  
+
+Click on the [Login button in the upper right corner](https://healdata.org/portal/login) to log in to the Platform.  
 
 ![](../img/heal_login.png)
 
-### Find Your Study
+## Find Your Study
 
-From the [Discovery Page](https://healdata.org/portal/discovery), find the study for which you wish to submit a data dictionary. _If you were not the member of your team to register the study, you will first need to [request access to submit a data dictionary](#request-access-to-submit-a-data-dictionary)._
+From the [Discovery Page](https://healdata.org/portal/discovery), find the study for which you wish to submit a data dictionary.  
 
-- Click on the study to open the Study Page 
-- At the top of the Study Page, select `‘Submit a Data Dictionary’` to navigate to the **Data Dictionary Submission Form**.
+- Click on the study to open the Study Page  
+- At the top of the Study Page, select `Submit Variable-level Metadata` to navigate to the **Variable-level Metadata Submission Form**.
+
+![](../img/submit_vlmd_submit_button.png)
 
-!!! info
 
-    A study must be registered in order to submit a data dictionary. 
+!!! info
 
-     If you have not registered your study, please see our instructions on [study registration](../study-registration/index.md)
+    If you do not see `Submit Variable-level Metadata`, see below for how to proceed.  
+    If you see:
 
-     If your study was registered by another team member, please see our instructions on [requesting access to submit a data dictionary](). 
+    - **`Login to...`** - you are not logged in. [Log in first](https://healdata.org/portal/login), then repeat the instructions above.
+    - **`Request Access to Submit Variable-level Metadata`** - you have not yet gotten access to submit VLMD. Follow these instructions to [request access to submit VLMD](vlmd_request_access.md). 
+    - **`Request Access to Register This Study`** - your study is not yet registered on the HEAL Data Platform. Follow these instructions to [request access and register your study](../study-registration/index.md). 
 
+## Submit Your Data Dictionary
 
-### Complete the Data Dictionary Submission Form
+The VLMD submission form defaults to the Data Dictionary tab (see box at top). 
 
-   ![](../img/vlmd_submission_form.png)
+   ![](../img/vlmd_dd_submission_form.png)
 
 - The `Study` field will already be filled in
 - Choose the `Select File` button to browse your local computer for your data dictionary.
   - Only TSV, CSV and JSON files can be submitted
   - While multiple dictionaries can be associated with a study, the process currently supports one submission at a time. Please repeat this process for each data dictionary you wish to submit
   - *Submissions should not include data of any kind.  Submissions containing data will be removed from the Platform.*      
-- Enter a unique name for your data dictionary.  This name will be used to identify the data dictionary for users on the Platform. 
-  - Previously submitted data dictionary names are displayed, if applicable - using the same name for a new submission will overwrite the existing record.
+- Enter a name for your data dictionary.  This name will be visible to users on the Platform.  
+  - Previously-submitted data dictionary names are displayed, if applicable; using the same name for a new submission will overwrite the existing record.
 - To facilitate processing of your submission, some administrative information is needed to allow HEAL Data Platform staff to contact you should the need arise:
     - First and Last name
     - E-mail address
     - *Note that this information is not stored on the Platform, but is simply needed to support you throughout the submission process.*
 - Submit your data dictionary
 
-### Processing Your Submission  
+## Processing Your Submission  
 
 Upon receipt of your successful submission, HEAL Data Platform staff will:
 
 - Review your submission for compliance with the HEAL Data Platform variable-level metadata schema 
 - Ensure no data are included.  Files containing study-generated data of any kind will not be accepted.
 - HEAL Data Platform staff will contact you with any questions and/or to work through any issues that may arise.  If there are no issues, you will be notified when processing is completed.
 
-###  Additional Help
+##  Additional Help
 
 More information about the HEAL variable-level metadata schema, as well as submission templates, can be found [here](https://github.com/HEAL/heal-metadata-schemas/tree/variable-level-metadata).
 

docs/vlmd/vlmd_submit_CDE.md

@@ -0,0 +1,78 @@
+# Submit HEAL CDEs
+
+!!! info 
+
+     In order to report your CDEs to the Platform, the following conditions must be true:
+     
+     **1) The study must already be registered:** If your study is not yet registered on the HEAL Data Platform, please see our instructions for how to register your study before submitting VLMD. 
+     
+     <p align="center">[How to Register Your Study](../study-registration/index.md){ .md-button }</p>
+
+     **2) You must have access to submit VLMD:** If you are the person who registered your study, you automatically have access. If someone else registered your study, you can follow the instructions below to request access to submit VLMD. 
+
+     <p align="center">[How to Request Access to Submit VLMD](vlmd_request_access.md){ .md-button }</p>  
+
+## Login to the HEAL Data Platform  
+
+Click on the [Login button in the upper right corner](https://healdata.org/portal/login) to log in to the Platform.  
+
+![](../img/heal_login.png)
+
+## Find Your Study
+
+From the [Discovery Page](https://healdata.org/portal/discovery), find the study for which you wish to report CDEs.  
+
+- Click on the study to open the Study Page  
+- At the top of the Study Page, select `Submit Variable-level Metadata` to navigate to the **Variable-level Metadata Submission Form**.
+
+![](../img/submit_vlmd_submit_button.png)
+
+
+!!! info
+
+    If you do not see `Submit Variable-level Metadata`, see below for how to proceed.  
+    If you see:
+
+    - **`Login to...`** - you are not logged in. [Log in first](https://healdata.org/portal/login), then repeat the instructions above.
+    - **`Request Access to Submit Variable-level Metadata`** - you have not yet gotten access to submit VLMD. Follow these instructions to [request access to submit VLMD](vlmd_request_access.md). 
+    - **`Request Access to Register This Study`** - your study is not yet registered on the HEAL Data Platform. Follow these instructions to [request access and register your study](../study-registration/index.md). 
+
+## Report CDEs
+
+The VLMD submission form defaults to the Data Dictionary tab, so click the CDE tab (see box at top) to navigate to the CDE submission form. The `Study` field will already be filled in.
+
+   ![](../img/vlmd_cde_submission_form_top.png)
+
+Below the `Study` field is a checklist of core CDEs. Check the box for any you wish to associate with your study. As you select CDEs, they will populate in the box at the bottom of the section.
+
+> If you or someone else on your team has already submitted CDEs, you will see these checked and listed in the box. You can update the CDE list by adding or removing CDEs and resubmitting the form.
+
+   ![](../img/vlmd_cde_submission_form_middle.png)
+
+To add Supplemental CDEs not in the core list, you can click in the box beneath the core list and begin typing CDE names or codes to filter other CDEs that include the typed string (see the yellow highlighting). Click the CDE in the filtered list to add.
+
+   ![](../img/vlmd_cde_submission_form_not-core.png)
+
+
+To facilitate processing your submission, some administrative information is needed to allow HEAL Data Platform staff to contact you if necessary:
+
+- First and Last name
+- E-mail address
+- *Note that this information is not stored on the Platform, but is simply needed to support you throughout the submission process.*
+
+Submit your CDEs by clicking the `Submit CDEs` button.
+
+   ![](../img/vlmd_cde_submission_form_bottom.png)
+
+## Viewing the CDEs on Your Study Record  
+
+The CDEs will be updated on your study record on the Platform within 24 hours of your submission. You will then be able to see the CDEs listed in the facets under the study name. 
+
+   ![](../img/vlmd_cde_facets.png)
+
+##  Additional Help
+
+If you have issues with a submission, or have a general inquiry, please contact us at [[email protected]](mailto:[email protected]).
+
+
+

mkdocs.yaml

@@ -15,8 +15,10 @@ nav:
     - cedar-getting-started.md
   - Variable-level Metadata Submission: 
     - vlmd/index.md
+    - Request Access to Submit VLMD: vlmd/vlmd_request_access.md
     - vlmd/vlmd_healdata_utils.md
     - vlmd/vlmd_submission.md
+    - vlmd/vlmd_submit_CDE.md
   - Workspace User Guide:
     - workspaces/index.md
     - workspaces/heal_workspace_registration.md