Merge pull request #28 from uc-cdis/data-access-update

update data availability and more

docs/platform_discovery_page.md

@@ -17,53 +17,72 @@ be embedded into the subsequent sections or have their own sections -->
 
 Different features such as free text search bar and tags on the Discovery Page help navigating and refining the search.
 
-1.  Free Text Search. Finding studies is made easy using keywords in the free text-based search bar or using tags. The free-text search bar can be used to search for study title, investigator name, or any keyword that is mentioned in the metadata of the study. Type in any keyword mentioned in the metadata, except for what is stored as Tags in "Study Characteristics".
-2.  Study Characteristics. Click "Study Characteristics" to expand the search options. Find a range of tags in eight categories (Study Setting, Study Design, Pain, Data Type, Subject Characteristics, Intervention/Treatment, Substance Use, Data Resources) to narrow down any search. Selecting multiple tags work in a "OR" logic. Click on "Reset Selection" to start a new search.
-3.  The total number of studies. Shows the amount of studies the HEAL Platform is currently displaying.
-4.  Export Options. Login first to leverage the export options. Select one or multiple studies and 1) download the attached data files, 2) download a file manifest (for data files whose sizes exceed 250 MB), or 3) export the metadata and data files to a secure cloud environment "Workspaces" to start your custom data analysis in Python, R, or Stata.
-5.  Studies. This feature presents all current studies on the HEAL Platform. Click on any study to show useful information about the study (metadata). 
-6.  Data Availability. Filter on available, pending, and not-yet-available datasets.
-7.  Documentation. This brings you to this page you are currently on.
-8.  Login Page. Login on the HEAL Platform to leverage all features. [Read further here](logging-in.md).
+1.  **Free Text Search:** Finding studies is made easy using keywords in the free text-based search bar or using tags. The free-text search bar can be used to search for study title, investigator name, or any keyword that is mentioned in the metadata of the study except for Filter options (see #3 below).
+2.  **Data Repository:** To filter studies by specific data repositories used by a study, click the Data Repository button (2A), which will reveal a Data Repository field (2B) in which you may select repositories of interest. If you select multiple repositories, it will use an "OR" logic to filter studies that have reported any of those repositories.  
+3.  **Filters:** Click "Filters" to expand the options to filter studies by different study metadata tags. Find a range of metadata tags in five categories (Study Type, Data Type, Subject Type, Gender, and Age) to narrow down any search. Selecting multiple tags can work in either an "AND" a "OR" logic, depending on the selecion at the top of the Filters drawer. Click on "Reset Filters" to deselect all filters and start over.
+4.  **Total number of studies:** Shows the number of studies the HEAL Platform is currently displaying that match the various search and filter criteria selected.
+5.  **Export Options:** Login first to leverage the export options. Select one or multiple studies by checking the checkbox at the beginning of the study row and you can then: 1) download the attached data files *(only available for some studies)*; 2) download a file manifest (especially useful for data files whose sizes exceed 250 MB); or 3) export the metadata and data files to secure cloud environment "Workspaces" to start your custom data analysis in Python, R, or Stata.
+6.  **Studies:** This feature presents all current studies on the HEAL Platform. Click on any study to show useful information about the study (metadata). 
+7.  **Data Availability:** Filter on available, pending, and not-yet-available datasets.
+8.  **Documentation:** This brings you to home page for the documentation (including this page you are currently on).
+9.  **Login Page:** Login on the HEAL Platform to leverage all features. [Read further here](logging-in.md).
 
-## Find available Study-level Metadata
+## Study Page  
 
-Finding available study-level metadata on the HEAL Platform is made easy by clicking on a study.
+You can view the study page by clicking on a study in the search results, which will open a drawer with the study page on the right.  
 
 ![DiscoveryStudyPageDatafiles](img/discovery_study_page_datafiles.png)
 
-Clicking on any study will display the available study-level and dataset metadata.
+The study page defaults to open the Summary tab, but there are 4 tabs in the study page:
+
+* **Summary tab:** Includes information about the study, with selected study-level metadata tags listed at the bottom (reflecting metadata reported in the CEDAR form). *(Shown in figure above)*
+* **Data tab:** Provides buttons to download variable-level metadata, study-level metadata, a manifest of the metadata files, or download all files. *Note: you must be logged in to use some of these features.*  This tab will also display a link to the data in the repository if it has been provided to the platform.  
+
+    ![Study Page - Data tab](img/discovery_study_page_datatab.png)
+
+* **Cite tab:** Provides citation information for the study on the platform and for the study data in the repository
+
+    ![Study Page - Cite tab](img/discovery_study_page_citetab.png)
+
+* **Related Studies tab:** Shows other very-closely-related studies on the platform that share the same NIH serial number ([read more about NIH serial numbers here](https://www.nimh.nih.gov/funding/grant-writing-and-application-process/research-funding-frequently-asked-questions-faqs#content_4)). Most studies will not have any related studies listed.  
+
+    ![Study Page - Related Studies tab](img/discovery_study_page_relatedstudies.png)
+
+
+## Find available Study-level Metadata
+
+You can find available study-level metadata for a study on the HEAL Platform from the study page. There are two ways to see the metadata. 
+
+* The study page opens on the Summary tab, which includes information about the study with selected study-level metadata tags listed at the bottom (see figure in [Study Page](#study-page), above).  
+* The Data tab on the study page includes a button to download study-level metadata (see Data tab figure, above).
 
 ## Find accessible Datasets
 
-Users can select and filter studies from multiple resources and conduct analyses on the selected datasets in a workspace. Users can find search only available data they have access to by selecting the data access button in the top right corner of the study page and selecting “Data Availability" - "Available" as shown below. The Discovery Page will automatically update the list of studies that have available datasets.
+On the Discovery page, users can filter for studies that have data available through the platform using the Data Availability filter in the right-most column of the search results. Click on Data Availability (#1), then select only the Available box (#2) to find data that is available and that you have access to through the platform, then click OK (#3). The Discovery Page will automatically update the list of studies that have available datasets.  
 
 ![Access_Box_Select_Window](img/access_box_select_window.png)
 
-Select the symbol next to Data Availability to open all options. Three options are available. Find available datasets by clicking on the “Available” button.
+The filter allows you to check more than one availability status, and uses an "OR" logic to filter studies. To interpret the different availability status options, please see the next section.  
 
-## Data Availability Options
+### Data Availability Options
 
-Different options for Data Availability exist and will be explained below.
+![Access_boxes](img/access_options.png){: style="height:250px"}
 
-![Access_boxes](img/access_options.png)
+**Waiting:**  
+“Waiting” is the default data availability status for studies added to the platform. This status means:  
 
-Three options for Data Availability.
+* Data have not yet been submitted to a repository; or, 
+* The repository has not yet released the data; or, 
+* The study team has not yet provided the link to the data to the HEAL Data Platform. (To [submit a data link, see our documentation about this](reporting-repo.md/#get-the-permalink-to-your-study))
 
-*   Available: This option will display only studies with datasets users have access to and entails all open-access studies. Studies can be selected and exported to a workspace or downloaded by clicking on the associated checkbox on the left-hand side of the study entry and selecting one of the options in the top right.  
-
-![discovery_options](img/discovery_options.png)
+**Available:**
+“Available” means you are now able to access these data via the HEAL Data Platform, by [downloading them](downloading_files.md/#download-data-files-from-the-discovery-page) and/or by [importing them in a workspace](workspaces/heal_workspaces.md)
 
-Once available, each study can be selected and exported to workspace or downloaded.
-
-*   Not available: This option will filter out all studies that will only have metadata but no datasets available. The checkbox next to the study will be greyed out and non-clickable.  
-
-    ![Access_greyed_out_box](img/access_greyed_out_box.png)
-
-    Studies will grey out if they're not available, have no data attached, users have no access to, or are in pending mode.
-
-*   Pending: This option will display studies located on any data resource or repository, for which attached datasets will be added in the near future. The checkbox next to the study will be greyed out and non-clickable as shown above.  
-
+**Request Access:**
+“Request Access” means that the data has been deposited in a repository and is available. To access the data, you will first need to visit the host repository to request access to it, following the repository’s standard procedures. Once that is complete, authorized users can then [bring these data into a HEAL workspace for analysis](workspaces/heal_workspaces.md).
+
+**Not Available:**
+“Not Available” means that no data will be made available for this study.
 
 ## Select Files on the Discovery Page and bring them to the Workspace
 

docs/platform_request_access.md

@@ -1,24 +1,18 @@
 # Check and request access
 
-Users can find out to which projects they have access to by navigating to [the Discovery Page](https://healdata.org/portal/discovery) and by selecting “Data Availability" - "Available" - ”OK” as shown below.
+Users can find out for which studies they have access to data from the platform by navigating to [the Discovery Page](https://healdata.org/portal/discovery) and selecting “Data Availability" (#1), then "Available" (#2), then ”OK” (#3), as shown below. **Note: users should log in before** they try to filter for studies with access to make sure that they are maximizing studies for which they have data access.  
 
-![Access_Data](img/access_box_1.png)
+![Access_Data](img/access_box_select_window.png)
 
-Available data can be found when the box next to "Available" is selected.
+If you also check the Request Access box, you will identify additional studies with data for which you can request access. (see our [documentation about the Data Availability filter](platform_discovery_page.md/#data-availability-options))
 
 ## Access to individual Studies
 
-You can check access by clicking on a study in the Discovery Page, as shown below:
+You can also check access by clicking on a study in the Discovery Page (#1), then clicking on the Data tab in the study page (#2), as shown below.
 
-![Discovery_Study_Page](img/discovery_study_page.png)
+![Discovery_Study_Page](img/discovery_study_access.png)
 
-The Study Page will display access permissions in the top right corner. Click the “Permalink” button in the upper right to copy the link to the clipboard.
-
-If you have access, a green box will show “You have access to this study”.
-
-![Yes_Access](img/access_YES.png)
-
-Access is displayed as a yellow box on top of each Study Page.
+The Data tab will display access permissions in the Data Files section. If you have access, a green box will show “You have access to this study”.
 
 ## Current (open-access) studies