Submitting Data to BALSA

Main About BALSA

BALSA is specifically designed for sharing of extensively analyzed neuroimaging data organized into scene files generated in Connectome Workbench and typically associated with a study that is published (or soon to be published).

Before you can create a study and upload data to BALSA you must have a BALSA account, login to that account, and agree to the BALSA Data Submission Terms and Conditions. Refresh the page to confirm the “I Agree” button changes to “Agreed”.

The first stage of submitting your study to BALSA involves analyzing your data and creating scenes in wb_view, a part of the Connectome Workbench platform Get Connectome Workbench here. Be sure to use v1.3 or higher.

In a typical workflow, users (study owners):

  1. Load their analyzed data in wb_view with an appropriate set of surface or volume structures
  2. Create one or more figures for publication using wb_view (each as a separate scene), saving them to a scene file as they are created
  3. Upload the scene file and all associated data files into BALSA via the built-in uploader in wb_view
  4. Add study metadata (project description, authors, publication information, release date, etc.) to the study on BALSA
  5. Submit the study for curation in BALSA
  6. Add links to the BALSA study and scenes to manuscript
The process begins in wb_view and transitions to BALSA when you upload the dataset and create a BALSA study.

Uploading can be done at any time after the relevant scene file(s) are in advanced draft, near-final, or final form. If you haven’t used BALSA to share scene files among co-authors, we recommend uploading prior to or at the time of manuscript submission. If you instead wait until manuscript acceptance, adding the study-specific BALSA URL’s into your published paper would need to be done during final edits or in proofs. Data can also be uploaded to BALSA long after publication, though that of course precludes inclusion of BALSA URLs in the paper.

After submission, your study will be in Submitted status (in curation) and reviewed by BALSA curators who may send you suggestions or recommendations and help you resolve any issues. Once everything is in order, a curator will approve your study for release (Approved status). Upon publication or your chosen release date, your study will moved to Public status, making it publicly viewable and downloadable from BALSA.

Create and save your scenes in wb_view (click to open the Scenes Window). Help info on creating scenes is available by clicking and 1) searching for Create a New Scene File and 2) in the table of contents, clicking Best Practices Guides > Annotations and Scenes Best Practices.

We recommend generating scenes that match as closely as possible the actual layout of published figures. This includes using wb_view ‘annotations’ to label figures. If possible, it is most efficient to create your figures for publication using wb_view, saving them as scenes as you work on them, rather than recreating figures made using other programs. For an example, see the Glasser et al. study “A multimodal parcellation of human cerebral cortex”. Also, see Help: Workbench Help: Annotations in wb_view.

We strongly encourage the following “best practices” when generating scenes for your study:

  • Create a single scene file (with multiple scenes) for all of your main text figures.
  • Supplementary figures or additional related scenes can be uploaded as one or more separate scene files to the same study, using the same BALSA Study ID.
  • If possible, create one scene per figure. The Tile Tabs function of wb_view can help in creating multipanel figures.
  • Name each scene by its figure name. If more than one scene must be used for a single figure, indicate panel A, B, C, etc. in the scene name.
  • Use the figure legend as the scene description: In the wb_view ‘Scenes’ Window, select “Replace” for the corresponding scene. Copy the figure legend from the manuscript text and paste it into the Description field. Then press OK. Once all figure legends are pasted into the scene Description fields, press Save to save the scene file.
  • Regarding directory structure, keep the data files to be included in any given scene file as localized as is feasible, i.e., not in widely distributed directories that require going up and down many levels. See the Directory Tips tab for important recommendations on user-friendly ways to organize your data.
  • Consider using BALSA to share draft scene files with co-authors, especially if they are not at the same institution. In that case, you may wish to upload draft scene files to BALSA while still in the process of generating figures and adding relevant co-authors as Study Owners in BALSA. That enables them to access the study well in advance of its going public.

If you haven’t yet created a BALSA account and agreed to BALSA Data Submission Terms and Conditions, follow the instructions under the Get Started tab.

In the Scenes Window in wb_view, click the Upload button, then enter your BALSA Username and Password, and click Login (logging into a BALSA submitter account is required before you enter a Study Title).

Click Create/Select/ Rename (right side of Study Title), then click Create New Study, enter the title of the study (generally the manuscript title), and click OK. If you are adding a new scene file to an existing BALSA study, choose the title of the study you wish to upload to from the list of your existing studies, then click OK.

A BALSA Study ID will be generated for your dataset and autofilled in the Study ID field. In addition, your scene file will be automatically assigned a sceneFile_ID and each of the scenes within your scene file will be assigned a unique scene_ID provided by BALSA. (Note: the scene ID’s are not visible in the scene file unless you close and re-open the scene file or else use the ‘Replace’ option for individual scenes.) Each of these three categories of BALSA ID’s serve a useful purpose! This is important if you follow our recommended ‘best practice’ of adding scene-specific URL’s to your published figure legends.

Unzip Into Directory

This is the prefix for the ‘Extraction Directory’ that your dataset will unzip into when users download and extract your dataset; a suffix (_<StudyID>) will be automatically appended to this prefix by BALSA at the time of download. Adding the study-specific suffix protects against inadvertently unzipping a dataset into an identically named directory on the investigator’s own computer, which could be very disruptive!

The default Extraction Directory prefix is the name of the lowest level directory in your dataset’s base path (the lowest level path that contains your scene file and all files referenced by your scene file). If this directory name makes good sense for a publicly released dataset, then stick with the default. However, a different name may be preferable. For example, if the current directory is personalized or cryptic, it is advisable to provide a succinct, project-specific directory name (e.g., “Glasser_et_al_2016_HCP_MMP1.0_StudyData” is the unzip into directory prefix for the Glasser et al., (2016) cortical parcellation data). Importantly, the Extract Directory prefix can be edited at any time on the BALSA Study page.

Note: If your study will include multiple scene files that have different base directories, it will likely be preferable to choose a higher level directory prefix that all scene files (and their associated data files) will have in common. This entails options in the Advanced tab that are explained under the Directory Tips tab.

Click Upload. The Auto-Save Scene File is checked by default and will save the scene file with BALSA metadata (BALSAstudy_ID, sceneFile_ID, and scene_IDs) before uploading. A status bar will show the progress of your upload to BALSA.

Login into BALSA with your username and password. Once you are logged in, a panel of options will appear on the left. Click on Manage Your Studies.

Click on the Title of your study, which is in EDITABLE status. Your Study’s page will open with thumbnail images of the scenes you uploaded.

Editing Study Metadata

Click Edit to enter ‘metadata’ detailed information about your dataset. Information on the fields and options on this page is available here.

Extraction Directory

The Extraction Directory Prefix will be automatically populated at the time of upload by what’s been selected in wb_view as the “Unzips into Directory” field (default is the lowest level directory of the base path). This field can be updated by the study owner at any time, even after a study has been made public.

The dataset description should include any additional information beyond the publication abstract that you would like users to see displayed in BALSA (e.g. README information important for interpreting results displayed in scenes, links to relevant data shared outside of BALSA).

For the Species, select all that apply.

For the Publication tab, use the search fields to find journal titles and institution names (this helps with consistency in how journal titles and institution names are displayed across BALSA studies). Note that you may enter information on a preprint version (a manuscript released on a platform such as BioRxiv) as well as the final published version or both, depending on your preferences and the state of the manuscript. For the preprint DOI, the default is to display it on the Study page, but you can elect to disable this display once the journal article is published.

In the Ownership and Access tab, you may set the owner and viewers associated with the dataset, allowing you to control whom is able to edit the study information in BALSA (owners) and who is able to view and download your study dataset before public release (viewers). The ability to edit and download enables collaboration with an owner colleague on uploading/editing a single BALSA dataset submission. The viewer setting allows you to “preshare” your dataset with select users, if desired. However, investigators must first have a BALSA or HCP account (see Section 1 above) before they can be added.

Data Use Terms

Also on the Ownership and Access tab, you must indicate whether investigators will be required agree to a set of Data Use Terms (DUT) before downloading the data from your study. A DUT can apply to any study, but is especially important in relation to human studies. It is incumbent on each investigator to determine whether sharing of human data for their project meets any requirements or constraints of their home institutional IRB (or equivalent entity at a non-U.S. institution). The Data Use Terms field displays a list of previously uploaded DUTs for owners to select if they apply to your study. For example, for a study that uses open access HCP data, simply select the “WU-Minn HCP Consortium Open Access Data Use Terms” in the Data Access Terms field.

Click the blue Save Changes button at the top of the page to save changes to Edit Study, then press Return to Study.

Editing Scene Files and Individual Scenes Metadata

Click the Edit Scenes button at the top of the Study page. Here you can add BALSA tags and descriptive for your scene file(s) and individual scenes.

Tags are bits of additional information (metadata) attached to files and scenes to assist users searching or filtering for specific datasets and scenes. Tags are optional, but they will help other users find your dataset within BALSA.

When files are uploaded to BALSA, they are automatically scanned for keywords that indicate that a given tag may be appropriate. Scenes and files in your dataset should be reviewed to verify that the tags attached to them are correct and to add additional tags as appropriate.

If you would like to modify the tags to all scenes in your study (applies to all scenes in all scene files), click on the arrows to the left of appropriate tags on the right. Click the Add tags button to add the tags to all scenes in your study. Click the Save Changes button at the top of the page to write these tags as BALSA metadata to the selected scenes (here, all scenes in study).

Specific tags may be added to all scenes in your study, all scenes in a particular scene file, to individual scenes, or any combination of these.

Click on the file name of your first (or only) scene file listed. Now, when you add tags you will add them to all the scenes in the selected scene file only.

Click on an individual scene listed. Similarly, when you add tags here, you will only add them to the selected individual scene only. Currently, removing tags can only be done at the individual scene level. To remove tags, click on the ‘X’ to the right of each tag you wish to remove in the current list.

At the scene file and individual scene levels on this page, you may also add a more descriptive name for the scene file or scenes to be displayed on the Study dataset page. Adding a BALSA descriptive name is particularly useful for datasets that contain multiple scene files so that the end user can distinguish each scene file, select, and download only the scene files and/or scenes they need. Currently, wb_view does not have a way to add a description that applies across an entire scene file (rather, it encourages you to add descriptions for each scene).

Note: any changes to your scene name or descriptions made will only be shown in BALSA, i.e., they will not propagate back to the uploaded scenes/scene file that will be downloaded and viewed by users in wb_view. A best practice is to instead make any critical edits to scene names and descriptions in wb_view and reupload the scene file to BALSA (see Revising and re-uploading scene files, below), which will then automatically update this information in BALSA.

Again, remember to click the Save Changes button at the top of the page to write the changes made at all levels to the dataset.

When you are done editing your dataset, click Submit for Curation. This will change the status of your dataset to SUBMITTED. Note: you will not be able to edit your dataset in SUBMITTED status. When your dataset is reviewed by BALSA curators, they may suggest changes or additions and will return your dataset to EDITABLE status until any issues are resolved.

After submission, a BALSA Curator will contact you to help prepare your dataset for release.

BALSA Curation and Release steps:

  1. Study owner(s) submits study for curation
  2. Curators identify any issues for review and send back comments to study owner(s)
  3. Study owner(s) resolve issues with the help of Curators
  4. Study is approved for release by Curators
  5. Study is released on set release date or upon publication date

Adding a Study ID

To obtain the study URL to add to your manuscript, open a web browser, login to BALSA, select Manage Your Studies, and then click on your study.

Assuming that this brings up the desired BALSA Study page, copy your browser’s current URL (e.g.,, where ‘XXXX’ is a 4-character string that matches the Study ID at the top of your BALSA Study page). Place this URL into your paper in an appropriate place with appropriate wording. Note that this URL will not work for other people until after the BALSA curators approve it, and not until after the release date. As such, the phrasing in the draft sent to reviewers should explain this, and be changed before final publication (e.g., submitted manuscript might read “Data from many of the figures in this study will (upon manuscript acceptance) be freely available at”).

Adding Study ID’s to Figure Legends

Besides providing a link to the overall Study ID, it is useful to provide ‘scene-specific’ URLs at the end of relevant figure legends. Doing this reminds readers that they are one click away from viewing a preview of the specific scene associated with each figure.

On your BALSA Study page, scroll down to the list of scenes; copy the link to the first scene; and paste it into the end of your figure legend associated with that scene so that it now ends with: “Data at”. Alternatively, you can click on each scene hotlink, then copy and paste the full URL from the browser into your document.

Continue this process until all scene-associated figure legends end with an appropriate URL. If a given figure is associated with multiple scenes, indicate appropriately, e.g., “Data at and”, etc.

Often, one or more figures in a manuscript are modified during revisions among coauthors as well as during the review process. Fortunately, BALSA and wb_view are designed for smooth handling of revisions and updates to scene files (so that’s not a good reason to postpone the initial upload!).

In brief, a scene file that has been revised by changes to one or more existing scenes (including re-ordering the sequence) can simply be re-uploaded to BALSA, keeping the metadata that was added at the first upload intact. This will change the scene file ID, so if you have used the older scene file ID elsewhere (e.g., in a draft of a manuscript) it should be updated.

If additional scenes are added to a scene file, then they will be assigned new Scene IDs that will be incorporated into the scene file, simply by saving it when prompted during the upload process. Note: For this reload process to work seamlessly, the revised scene file’s name and path must not change. Otherwise, the file will be treated as a new (separate) scene file upload and you will need to delete the old version from your BALSA study.

Scene files in Connectome Workbench can point to many distinct files. These need not be in the same directory, because the scene file includes the directory structure for each data file relative to the scene file’s own directory. This provides valuable flexibility, but as noted above, it means that care should be taken in managing the directory structure for scene files and data files, especially for data to be shared via BALSA.

We recommend saving your scene file in a local directory reasonably close to the associated data and keeping your overall directory structure relatively flat. The directory structure of all files contained in the scene file relative to the base directory (see below) will be preserved in your dataset when it is downloaded from BALSA and extracted by other users.

If the constituent files are in many different directories at many levels of the directory structure this might be confusing for end users. For some studies, a good solution is to put the scene file in a main directory along with the other data files and perhaps various subdirectories. For other studies having multiple major directories representing different aspects of the analysis, it may be better to put the scene file(s) in a separate ‘nearby’ subdirectory.

Base Path

The automatically determined ‘base path’ for a scene file is the “lowest level” path that contains the scene file and all of the data files it references. It is used when creating a zip file for the scene, which is included in the process of uploading to BALSA.

To view the base path for your scene, press Scene: Upload, then press the Advanced tab near the middle of the Upload Scene File to BALSA popup. The automatically determined base path is reported next to the default Automatic setting. Using the Custom setting, it is possible to specify a custom base path above the automatically determined one, but this will add additional directory layers to the dataset when it is downloaded and unzipped by other users. However, if your study will contain multiple scene files that have different base directories, then it will likely be preferable to choose a higher level directory that all scene files (and their associated data files) will have in common. For this, select the Advanced tab in the Upload Scene File to BALSA window. Use Custom: Browse to choose suitable directory level.

If the lowest (farthest right) level subdirectory in Custom is not what you wish to use for the Extract Directory prefix, then select the Upload tab in the Upload Scene File to BALSA window and enter the desired Extract Directory prefix. When uploading is initiated, wb_view checks the current Extraction Directory prefix in BALSA; if there is a mismatch, a popup window allows the uploader to choose which one to use.