Publication Page Submission

Introduction

What is the purpose of publication pages?
The purpose of publication pages in the HuBMAP Data Portal is to:

• provide an overview of and showcase HuBMAP publications
• make it easy for members of the community to find datasets, samples, and donors included in HuBMAP publications
• feature exciting data through interactive Vitessce-based visualizations in ways not possible in PDF-based publications

Note: Authors are encouraged to reference dataset collections or individual dataset DOIs in their publications.
Publication pages do not have assigned DOIs, as they are able to be updated.

Who can contribute to a publication page?

• Any HuBMAP member can submit a publication page for any publication that uses publicly available data in the HuBMAP Data Portal.
• Both preprints and published papers can be shared as publication pages.
• Note: The HuBMAP HIVE will not be responsible for the creation of publication pages or maintenance of their content beyond regular HuBMAP Data Portal maintenance.

What is the process of submitting a publication page?
To re-use existing HuBMAP infrastructure and processes, publication pages use a process that is very similar to regular dataset submissions, see details below.

• Like datasets, a publication page (or “publication dataset”) can be updated at any time by the authors.
• Initially, publication pages will be in “QA” status and only accessible to consortium members.
• Once they have been reviewed by the authors, the HuBMAP HIVE curation team will switch the status to “Published.”

Prerequisites

1. The Globus organization associated with your Globus user account must be a “Data Provider” group. If you previously submitted data to the HuBMAP Data Portal, that will be the case. If not, please contact the HuBMAP Helpdesk.
2. Prepare a Submissions Directory. Similar to submitting datasets to the HIVE (HuBMAP), set up a directory based on the metadata and directory schemas for a “publication.”

Contacts

• For all general questions, including communication regarding QA, please contact the HuBMAP Help Desk
• For questions on Vitessce vignette preparation: Mark Keller
• For questions on Data Ingestion (ingestion portal, Globus, data provider groups): Brendan Honick

1. Create Publication

   a. Start at the Ingest Portal.
   b. Select “Publication” in the “Register New: Individual” menu. You can also follow this link to get to that page.
   The “Registering a Publication” dialog will display:

Click here to display ▼ (or hide ▶) the image below...

   c. Fill out all required fields and enter as much information as possible into the optional fields.
   Note: In particular, make sure to select all HuBMAP datasets in the portal that were used in your publication.
     This information will be used to automatically infer donors and samples that are part of your publication
     and display them on the publication page in addition to the datasets.

   d. To add datasets to the Publication, click the “Add+” button under “Sources.”
   e. Search for the datasets you want to add, click on a dataset to select it.

• Important: For wild card searches, add “*” at the beginning and / or end of your keyword string
• You can also select a group (institution)

   f. The selected dataset is listed under sources.

   g. Alternatively, selecting the BULK option allows you to add multiple datasets, separated by commas

Click here to display ▼ (or hide ▶) the image below...

   h. Once complete, click “Save” - The “Success” dialog should display:

• Note the HuBMAP ID - This will allow you to locate your Publication when the Success dialog is not present.
• The steps above create…
  • A HuBMAP record of your Publication
  • A Globus directory where everything associated with the Publication will be stored
• Click the link for the Publication’s HuBMAP ID to go directly to your Publication.
• If no changes are needed, you can click DONE on the “Success” dialog - which will close it.

2. Locating Your Publication

• In the main Ingest Portal search, enter the Publication’s HuBMAP ID and click SEARCH
• This will open the “Publication Information” dialog, where you can update the descripton or other information.

• From this dialog, to add or modify data files, click the link to the data repository, highlighted in light blue (above).

3. Preparing Files for Upload

Prepare the data for your publication.
This should include any supplementary data files and other information that you want to share with the community.

To prepare your data for upload, organize it according to the “publication” directory schema. Use the ingest validation tools to confirm that your directory structure and metadata files conform to the requirements of the publication assay type once you have assembled your dataset.

Directory structure:

• metadata.tsv - Use the schema for the “publication” assay type.
• extras/
  • contributors.tsv
    • Note: The contributors.tsv file will ONLY accept characters in the ASCII character set - see a reference list.
      • Modify the spelling of any names included in the contributors.tsv to avoid special characters, such as ö.
    • ORCIDs are required for ALL authors. If an ORCID is not available for an author, omit that author from the contributors.tsv
• vignettes/ - Follow instructions in the tutorial to construct your visualizations using Python and Jupyter notebooks.
• Note: Vignettes are not required!
  • vignette_01/
    • description.md
  • vignette_02/
    • description.md
    • vitessce.json
  • vignette_03/
    • description.md - Multiple Vitessce configurations can be added!
    • vitessce.json
• data/ - All supplementary data for your paper and everything else that you want to share goes here.
  • Ensure that everything referenced by your Vitessce visualizations is in the data directory.

Minimum Requirements:

• A directory including metadata.tsv, vignettes/, data/, and extras/ at the top level (no enclosing directory).
• These directories are required but can be empty.

See an example of a directory structure, which is from this publication.

3.1 Vignettes

Vignettes are optional features specified using Markdown files named “description.md.”
Vignettes can be used to link to external websites or resources and embed interactive visualizations using Vitessce.
You can share additional documentation, links to external resources, or one or more visualizations of key datasets as “vignettes”. “Vignettes” will be automatically embedded in the page for your publication.

3.1.a Links to External Resources

Links to additional collections or other resources can be included in the “description.md” file, using standard markdown link formatting:

• “[link name here] (https://link-address-here.example.com)” – Be sure to OMIT the space between “] (“ !
• Please follow the above directory structure for “vignette_01/,” and include a “description.md” file.
• The vitessce.json file is not required, Vitessce visualizations are not required to display this markdown information.

3.1.b Embedding iframes

You may also add externally-hosted iframes to the “description.md” to use an embeddable visualization that does not use Vitessce.

• These iframes can be provided in the “description.md” file.
• The vitessce.json file is not required, Vitessce visualizations are not required to display this markdown information.
• Servers hosting the visualization must be configured to allow external embedding of the iframe via
  Content Security Policy headers. See an example description.md file

3.1.c Vitessce Visualizations

Visualizations of key datasets will automatically be embedded in the publication page if Vignettes are included in the Globus file upload.

• Visualization configurations can be generated directly from an existing visualization on the Portal. To do this:
  • Navigate to the desired dataset visualization
  • Configure preferred settings (e.g., filters, colormaps, zoom level, etc.) for that visualization
  • Click the Share button (top right of Vitessce window) and select one of the options for copying or downloading Configuration files. See example below:
    
    
• To construct alternative or additional visualizations, follow the instructions in the Vitessce tutorial using Python and Jupyter notebooks.
• An example can be viewed for this publication.
• The Globus directory for the above publication can be viewed here (requires Globus login).

3.2 Globus File Upload

This section provides options for uploading files associates with publications via Globus.

Note for Mac Users: Ensure there are no “.DS_Store”files in the directories prior to upload to Globus.

• Instructions for deleting these files from Globus via the CLI are here.

Option 1: Web browser-based

This option works well for most publication pages due to small file sizes (small files or small set of files).
Option 2 (below) is better for larger files and submissions.

• The upload instructions below are not comprehensive.
• See the Globus FAQ regarding Globus Connect and Endpoints for more detail.

As specified in the HuBMAP Data Submission Guide, here is some essential information about Globus uploads:

• Your Globus ID must be an institutional ID. Note: eRA Commons and ORCID IDs are not acceptable for this purpose.
  • When registering for HuMBAP or SenNet, if your institution does NOT appear in the dropdown on this page,
    contact the Helpdesk and request a sponsored Pitt (University of Pittsburgh) account.
  • Check that your institution ID is linked to your Globus ID.
  • See also Globus’ How To & FAQs for more information.
• Write access to your team’s Globus folder
  • This will be granted after confirming that you will submit data via the HuBMAP Ingest Portal OR SenNet Data Sharing Portal (required).

Option 2: Globus Connect Personal

Use for larger-scale uploads (multi-gigabyte)

   a. For Globus Connect Personal, first make sure that the local directory you want to upload is marked as “Shareable” in Preferences.

   b. Then select “Web: Transfer Files” from the Globus menu.

   c. Navigate to the local directory that you want to upload in the left pane of Globus.

• On the right side, enter “HuBMAP Data” as the Collection
• Enter the path that was created for the publication

   d. Select files on the left side then click the blue Start button on the left side to transfer files to the right side:

   e. Use the “Activity” tab to check the progress of the upload:

See Globus Connect Personal for more information.

• This site provides installation instructions if the user isn’t already familiar with the tool.

4. Navigating to a Publication

After the upload is complete, navigate to the publication in the Ingest Portal.

• In the main search, enter the Publication’s HuBMAP ID or search by TYPE, then click SEARCH
  
• This will open the “Publication Information” dialog, where you can update the descripton or other information.

Click here to display ▼ (or hide ▶) the image below...

4.1 Submitting Your Publication

   a. Make any changes or updates to the publication description or other fields, if needed.

• After making any such changes, click “Save”
• In no changes are needed, proceed to the next step.

   b. Click “Submit” - This will change the status of the publication to “Submitted”.

• Behind the scenes, this alerts the curation team, who will manually trigger the processing of the publication dataset.

   c. Once submitted, the publication page may immediately appear here for logged-in users.

• Some information (e.g., Vitessce visualizations, author information, etc.) will not appear until
  backend processes are complete…
  • The page has to reach QA status (Step 5 - see below)
  • Processing status indicates the file or publication is being actively processed and not yet available.
  • Invalid status indicates that there is some error with the file or publication.
    • Hover over a status value to display more information about it…
      
  • QA status indicates that the file or publication is undergoing quality assurance checks or validation.

5. Approving Your Publication

Following processing, the publication will be in “QA” state.

• You will receive an email from Curation with a request to review your publication.
• Publications will be publicly visible here.
• If you submitted your publication as a preprint, navigate to the “Preprint” tab to see your publication.

Click here to display ▼ (or hide ▶) the image below...

6. Updating a Publication

Reasons to Update:

• Preprint changes status to Published
• Finalized citation info becomes available (volume, issue, pages)
• Corrections to metadata (title change, author updates)
• Add or update links, supporting resources, and/or visualizations in vignettes

Metadata Updates:

• Publication entities can be modified prior to submission.
  • Updates to metadata such as the publication title or abstract can be performed in the Ingest Portal.
• After submission, if further changes are needed, submit a Help Desk Ticket
  • Be sure to include the fields and changes required.

Data and Vignette Updates:

• Updates to data files or vignettes should be made in the data directory.
• A link to the data directory is provided on the “Publication Information” page in the HuBMAP Ingest Portal.
• After completing updates to the data directory contents, submit a Help Desk Ticket
• Once a publication page’s status is Published, a new publication version must be created.
• Create a new Publication submission and reference the previous publication’s HuBMAP ID or UUID.

Click here to display ▼ (or hide ▶) the Update Workflow diagram below...

Workflow Diagram for Updates