Last modified 2025-10-30 |
Work with Studies (Tutorial)
 | Abbreviations Key |
| AIFI | Allen Institute for Immunology |
| HISE | Human Immune System Explorer |
| IDE | integrated development environment |
| UI | user interface |
At a Glance
A HISE study is a workspace for collaborative research. A single project can contain multiple studies. This document explains how to create a study, how to work with study assets, and how to manage user access.
Description
Studies contain documents, data, visualizations, research methods, statistics, notebooks, Certificates of Reproducibility, and other project materials. The following image shows the Reports section of a typical HISE Collaboration Space.
The study workspace also has a team drive where you can upload files, such as PDF documents and images. This study-specific drive interacts with the native Google Workspace team drive UI. To open the study drive, click Open Drive in the sidebar.
Instructions
Minimize or expand the sidebar
To manage your study space, use the navigation menu in the sidebar.
1. To open or minimize the sidebar, click the expand/collapse icon.
The accompanying image shows the sidebar collapsed (left) and expanded (right).
Create a study
To create a study, you must describe the study and associate it with the project.
1. Navigate to HISE, and use your organizational email address to sign in.
2. From the top navigation menu, click COLLABORATION SPACE.
3. In the upper-right corner, click CREATE STUDY.
4. Complete the Create a New Study dialog box.
A. In the Study name field, enter a study name of 64 or fewer characters.
B. In the Google Workspace Prefix field, enter a prefix to identify the study folders in Google Drive.
C. In the Description field, give a brief but helpful description of your research for those who are unfamiliar with it. Include keywords likely to appear in a user's search.
D. In the Hero image field, upload an image:
i. To upload an image from Drive, click Open Drive.
ii. To upload a saved visualization from HISE, click Choose from Visualizations.
E. In the Tags field, click the arrow to select from the available tags, or use the keyboard to enter a new tag.
F. In the Project field, click the arrow and choose a project from the drop-down list.
G. Click Create Study.
View study details
The Study Details tab in the sidebar offers study metadata.
1. To expand the Description field, click Show more (left). To collapse it, click Show less (right).
2. To copy the Study ID, click the copy icon.
3. In the Google Drive Prefix field, view the prefix for this study.
4. In the Created On field, view the date created and the email address of the study owner.
5. In the Tags field, view the tags. To expand the field to show all tags, click the +[number] icon, in this case +2.
6. In the Who Has Access field, click Collaborators to view a list of users and their roles. For a description of each role, see the accompanying Role Definitions table. To edit collaborators or change role permissions, see the "Add or change study access" section of this document.
| Role Definitions | |||||
| Role | Description | ||||
| Owner | The owner is the study creator. This user is the only collaborator who has full admin privileges, including the ability to delete the study. The owners can also edit documents, manage users, create and manage reports, and manage files (including visualizations, file sets, and saved IDE instances). | ||||
| Co-Owner | A co-owner is another owner who is not the study creator but can nevertheless read, edit, add, or delete assets, including those in the Google Drive workspace. The only exception is that co-owners can't delete the study itself. | ||||
| Contributor | A contributor can read and comment on the study and can post study assets, but cannot edit or delete those assets. | ||||
Edit study details
If you are a study owner, co-owner, or admin, you can update the study name, prefex, description, hero image, collaborators, or tags, or change the project with which the study is associated.
 |
| The Edit Study Details option is visible only to study owners, co-owners, and admins. You can request permission changes from the study owner, or contact Support to reach an administrator. |
1. On the Study Details tab, click the thumbnail that represents your study.
2. From the drop-down menu, click Edit Study Details.
3. In the Edit Study Details dialog box, enter the details you want to change, and click EDIT STUDY. For details, see the remaining sections on this page.
Add or change study access
|
|
1. Navigate to Study Details > Who Has Access > Collaborators.
A. To add a collaborator, click into Email field of the Add Users to the Study dialog box.
i. Enter the email address of the person you want to add.
ii. Alternatively, select a name from the drop-down list of email addresses. If necessary, use the A–>Z search filter to sort your results.
B. To change a collaborator's role, click the arrow next to the collaborator's email address, and choose a role from the drop-down list.
C. Click the checkbox to notify the collaborator by email that they've been added to the study.
Add a study asset
To add assets to your study, use the side navigation menu.
Study Assets | |||||
| Asset | Description | ||||
| Report | A report is a Google Doc, Sheet, or Slide, a Microsoft Word document, or a PowerPoint presentation saved to the team Google Drive. | ||||
| Files | HISE supports various analysis pipelines that generate searchable output files. These files typically contain analysis results plus one or more reports. | ||||
| File Sets | Result files of particular interest can be saved as file sets. These files sets can include reports, such as QC reports, or result files, such as labeled scRNA-seq files from an automated pipeline or files produced by an IDE. | ||||
| IDE Instances | HISE's Jupyter Notebook environment lets you explore data and derive further insights using Python or R. You can upload the results to a study | ||||
| Visualizations | You can use a subjects query or a samples query to save and visualize human metadata, or you can use a result files query to visualize the flow cytometry supervised gating pipeline. You can also create an IDE and use R or Python to generate Plotly graphs, or use Python to create a complex interactive visualization by building a Dash application. | ||||
1. Navigate to HISE, and use your organizational email address to sign in.
2. From the top navigation menu, click COLLABORATION SPACE.
3. Click the card that represents your study.
4. In the side navigation pane, choose the type of asset you want to add. For a description of each asset category, see the table at the end of this section.
A. Add a report
i. From the side navigation menu, click REPORTS.
ii. Click Create Report.
iii. In the dialog box, enter the requested information.
iv. Click SUBMIT. For details, see Prepare a Report (Tutorial).
B. Add a file
i. From the side navigation menu, click FILES.
ii. Click Open Drive.
iii. Click + New.
iv. Click File upload.
v. Browse your files and click the one you want to upload, such as Dash code.py.
vi. To upload the file, click Open.
The file now appears in the Google Drive workspace for this study.
vii. Alternatively, use the upload_files() SDK method to upload a file or files to your study. Then click Files in the HISE side navigation menu, and the files appear in tabular format. For details, see Use the Upload Files SDK Method (Tutorial) and Produce Searchable Output Files.
C. Add a file set
i. Click File Sets.
ii. Click Open Drive.
iii. Click + New.
iv. Browse your files and click the folder containing the file set you want to upload, such as survey-results.
v. Click Folder upload.
vi. If requested, click Upload to confirm.
vii. To upload the folder, click Open.
The folder containing your file set now appears in the Google Drive workspace for this study.
viii. Alternatively, use the upload_files() SDK method to upload a file set to your study. Then click File Sets in the HISE side navigation menu, and the files appear in tabular format. For details, see Use the Upload Files SDK Method (Tutorial) and Produce Searchable Output Files. For details, see Work with File Sets (Tutorial).
D. Add an IDE instance
i. In your IDE, use the upload_files() method to upload the output files to your study space. For details, see Use the Upload Files SDK Method (Tutorial)
ii. In HISE, click COLLABORATION SPACE, and click the card that represents your study.
iii. From the side navigation menu, click IDE Instances.
If the IDE was successfully uploaded to your study space, it appears here, along with a list of other IDEs associated with the study (if any). For detailed instructions, see Attach an IDE to a Study (Tutorial).
E. Add a visualization
i. From the side navigation menu, click Visualizations.
ii. Click Open Drive
iii. Click + New.
iv. Click File upload.
v. Browse your files and click the visualization you want to upload, such as pbmc_ref_10k_post_scanpy.h5ad.
vi. Click Open. If your file is large, a message appears showing that your file is being uploaded.
The uploaded visualization now appears in the Google Drive workspace for this study.
vii. Alternatively, use the save_abstraction() SDK method to save the visualization to your study. Then click Visualizations in the HISE side navigation menu, and the visualization appears as a card. For details, see Use the HISE SDK to Create Visualizations (Tutorial).
Add a hero image
When a study is created, a generic hero image is randomly placed. If you're a study owner, you can upload an image that better reflects your research.
|
| Choose an image from the team drive, from a saved visualization, or from a public internet site, such as Wikimedia. If you upload a copyrighted image to your study, it might not be visible to all users. |
1. Navigate to HISE, and use your organizational email address to sign in.
2. From the top navigation menu, click COLLABORATION SPACE.
3. Click the card that represents your study. On the Study Details tab, click the thumbnail that represents your study, and choose Edit Study Details.
A. To upload an image from the Google Drive workspace for this study, click CHOOSE FROM DRIVE.
i. Choose either the Upload tab or the Google Drive tab, depending on the location of your hero image file.
ii. Drag and drop your image file.
iii. Alternatively, click Select files from your device, and browse to find your image file.
iv. Click Upload.
B. To upload a visualization, click CHOOSE FROM VISUALIZATIONS.
i. On the Visualizations screen, click the image you want to use. Note that there might be duplicates.
ii. Click Select.
The new image appears in the Collaboration Space.
Delete a study
Only the study owner can delete a study. For help, contact Support.
1. Navigate to HISE, and use your organizational email address to sign in.
2. From the top navigation menu, click COLLABORATION SPACE.
3. Click the card that represents your study.
4. On the Study Details tab, click the thumbnail that represents your study. and choose Delete Study.
Related Resources