Uploading guide

Creating a dataset using the plugin

Start by preparing and uploading one or more datasets. Multiple datasets can be associated to with one study or page.

Quick start steps:

• Prepare the excel data set
  • Split the dataset into specific comparisons if neccesary.
  • Save the data as standard csv.
• Navigate to data sets on the left hand menu.
• If your species is not yet present, select species tab and create a species associated with your data.
• Select the group tab and create new groups to define your experiments, existing groups can be repurposed.
• If not yet uploaded, select the upload relations csv tab and select use default data. This is persisted across datasets.
• Once species, groups and relations are defined select add new datasets.
  • Provide a title for the dataset.
  • Under graph options perform the following actions:
    • Select Full width graph.
    • Select Display header.
    • Select Display title.
    • Edit the title of the Y-axis.
  • Under data set settings
    • Select the species associated with the data.
    • Select the groups associated with the data.
    • Add the number of replicates per group.
    • Once ready, generate data set.
  • Arrange the graph axis as desired.
  • Download the headers
    • Copy these headers and paste as the column names the csv files associated with the data.
    • The header columns should match the data.
  • Upload the csv to the website.
  • If required, change the visibility settings to password protected.
  • Copy the shortcode for later use.

Step 1: Prepare the data

The application requires a csv file representing expression data. This may be any type of data with rows and columns correpsonding to gene expression. The data can be manipulated in excel but should be saved as standard csv (not utf-8).

Dataset should resemble the following:

	Control 1	Control 2	Control 3	Treatment 1	Treatment 2	Treatment 3
Gene 1	10	8	9	1	2	1
Gene 2	0	0	0	5	7	6

If saved correctly, it should be possible to open the data with notepad and all headers and rows should be separated with a comma.

Step 2: Creating a species

Currently only model organisms are supported. This step may not be necessary as species are saved across datasets. Verify that your species is present by navigating to datasets and selecting the species tab. The only required field is the name, once done select add new tag to save the species.

Step 3: Creating groups

Similar to species, groups names are saved across datasets. If your groups is already defined this step can be skipped. Navigate to datasets and select group. The only required field is the name click add new tag to save the group. In the example table above, two groups should be created namely control and treatment.

Step 4: Uploading relational csv

This step is essential to for the search functionality and should only be altered if the search is no longer functional or if the relational csv has not yet been uploaded. If there is no banner stating The homologs-relations.csv has been uploaded then click the use default data button, this might take a while to process.

Step 5: Add new dataset

Once all the dataset, species and groups are prepared navigate to datasets and open the add new data set tab. Start by providing a name for the dataset and select the full width, display header, and display title checkboxes. The rest of the customisation is up to the discretion of the uploader.

Under the dataset settings tab select the species and the groups defined in the previous step. This will render a new widget where the number of replicates per group can be defined, in the example above there would be three replicates for control and three for treatment. Once the replicates are defined select generate datasets.

On the right hand side the download headers for the dataset button should be active. Download this file and replace the column names with the newly generated column names. Save the file as a csv before uploading using the upload csv button.

gene_id	newcontrol	newcontrol	newcontrol	newtreatment	newtreatment	newtreatment
Gene 1	10	8	9	1	2	1
Gene 2	0	0	0	5	7	6

Step 6: Set privacy and copy shortcode

If required set the privacy to password protected on the right hand side menu and copy the short code which will be used to render the plots when building the page that displays the data.

If all steps have been completed a new dataset with your title should appear in the datasets tab. Repeat these steps if there are multiple datasets associated with a single study. Once all datasets are made proceed to creating a data page and registering the study on the home page.

---

Creating a display for the data

To view the data we registered in the previous step we need to create a page that will render the data based on a searched gene. This process is quite involved as we have to consider that multiple datasets can be registered for one study. The major steps are creating the layout and adding the first dataset.

Creating the data page

This step is the most involved and will require editing a number of website elements.

If you are familiar with the process follow these quick start steps to create a page:

• Navigate to pages on the left hand menu.
• Select add new page.
• Provide the name of the study as the title.
• Add the search bar using short codes.
• Add two columns for the base layout spaced 1/3 and 2/3.
• Add custom HTML in the 1/3 section and define the buttons.
  • Repeat button HTML for each dataset.
• Add custom HTML in the 2/3 window and define the plotting window.
• Add shortcode defining the datasets (see upload dataset section).
• Edit the shortcode HTML and provide a ID to the parent div.
  • Repeat for each dataset.
• Add custom HTML to handle housekeeping events.

Step 1: Creating a new page

Step 2: Naming the dataset and adding the search shortcode

Step 3: Add buttons and plotting area

The plotting window is where the plot of each dataset will be displayed. To render our plots we need to define the plotting window using custom html and our project name. In this case we use vfp as the shorthand. To do so, create a custom html widget in the 2/3 section of the columns and create a div as below. replace id=”vfp-plotting-window” with your own study name, e.g. id=”custom-plotting-window”

<div id="custom-plotting-window"></div>

The buttons are made by using pre-defined custom classes and functions to that facilitates the toggling interactions and styling. We need to create our own buttons stacked on top of each other for each dataset and this requires custom HTML code. We start by creating a parent div, called “stack-parent” and each button will be placed within the parent div, see the example below for two buttons. To create more buttons simply copy and paste the start and stop of each button underneath each other.

<div class="stack-parent">
    <!-- BUTTON START 139 -->
    <div class="stack-vertical">
         <div 
            id="dataset-139-btn" 
            class="card" 
            onclick='togglePlot(
                    "vfp-plotting-window", 
                    "vfp-dataset", "dataset-139"
                     )'
         >
            <strong>Dataset 139</strong>
         </div>
    </div>
    <!-- BUTTON STOP -->
    <!-- BUTTON START 140 -->
    <div class="stack-vertical">
         <div 
            id="dataset-139-btn" 
            class="card" 
            onclick='togglePlot(
                    "vfp-plotting-window", 
                    "vfp-dataset", "dataset-140"
                     )'
         >
            <strong>Dataset 140</strong>
         </div>
    </div>
    <!-- BUTTON STOP -->
</div>

To finish creating the button we need to change a few parameters to reflect the uploaded dataset (see below). Uploading a dataset will provide a unique ID number, we need to assign this number in the html so that the button knows which plot to display.

Change the following fields:

• <!-- BUTTON START 139 -->
  • replace 139 with your own dataset id
• id="dataset-139-btn"
  • replace 139 with the dataset id
• "vfp-plotting-window"
  • replace with your own plotting window id from the previous step
• "vfp-dataset", "dataset-139"
  • replace vfp-dataset with your own shorthand, this will be used in the state
  • replace 139 with your own dataset id
• Replace the name of the dataset, located between the <strong> tags

Repeat these steps with each subsequent dataset.

Step 4: Add and edit database shortcode

In addition to adding the shortcode code we also need to edit the html of this code directly. Click the three dots on the top right corner and select code editor, alternatively use the keyboard shortcut cntrl+shift+alt+M. If perform correctly the layout should display the raw html.

Step 5: Add housekeeping code:

We need certain actions to run on page load in order to control the display of the images. This is the final step to be completed on the page displaying the data.

• Create a column with the /column shortcut and add a custom html element with /custom html element.
• if not yet present add the housekeeping function
  • <img src onerror="housekeeping('custom-dataset', 'custom-plotting-window')">
  • replace custom-dataset with your own study shorthand as in step 3. This will also be used in the state (see below)
  • replace custom-plotting-window with the plotting window defined in step 3.
• Add the hidePlot function for each dataset
  • <img src onerror="hidePlot('#dataset-1')">
  • replace dataset-1 with the ID used in step4.
  • Take note of the # and the quotations, these are neccesary.

Step 6: Publish the page

On the right hand side under the Page tab the visibility can be changed prior to publication. Click on public and set it to password protected in order to have data online under password protection. Only users with the password will be able to view the page. Once done publish the page in order to go live. It is recommended to publish the page after registering the study in the application state and creating the card on the homepage.

---

Registering the new study in the application state

We have to add our dataset to the state of the website, this way certain information is retained on each page on each load. When creating the page displaying the data we were required to assign a dataset-id to each dataset loaded. This ID as well as the study name will be registered in the state. In the examples above the study name was “vfp-dataset” and one of the dataset-id’s was dataset-164. We only need to register the study once and we need to register each subsequent dataset under the study.

Follow these quick start steps to register a study in state:

• Navigate to code snippets in the left hand menu and select header & footer.
  • This is a plugin but should already be installed, if not install and activate code snippets from the plugin menu
• In the header there should be a <script> tag containing a JSON object called activeDatasetStates.
  • Add the study ID to this variable
  • IDs cannot have spaces, replace spaces with hyphens
  • The JSON object follows the following notation { "study-name": { "dataset-id": false} }
  • Set the dataset to true that should be displayed on load.

Step 1: Navigate to code snippets

Navigate to code snippets and open the header and footer page. It should resemble the image below

If no studies have been created yet the activeDatasetStates variable will be empty.

In the case of the first study, create add the new study and datasets in the following manner:

var activeDataSets = {
    "my-dataset": {
        "dataset-1": true,
        "dataset-2": false
    }
}

Take notice of the quotation marks and comma’s these are important. One dataset should be set to True and others set to false. The dataset that is set to true will be the first one displayed as the page loads. Add as many datasets as is created for each study.

The process is similar if a study already exists, simply create a new study following the same pattern as above:

var activeDataSets = {
    "vfp-dataset": {
        "dataset-169": true,
        "dataset-170": false
    },
    "my-dataset": {
        "dataset-1": true,
        "dataset-2": false
    }
}

---

Creating a card on the home page

Follow these quick start steps to create a card on the home page

• Navigate to blue host in the left hand menu and select edit you site in the site preview.
• If not present, create a column split in 1/3 pieces, each third will display a card.
• In the 1/3 chunk create custom HTML
• Copy the card HTML and replace the link reference as well as the names.

Step 1: Open the site editor

Navigate to the Bluehost tab on the left hand side and hovering over site preview. Select edit your site.

Step 2: Add a card

If this is the first study create a three column layout and use the /custom html shortcut to add custom html elements to one section of the column. Repeat this for each study. This step requires a page to be created which we will link in the card. Copy and paste the html below and apply the appropriate edits.

<a
    class="card-mainpage-link"
    href="add-page-link-here"
>
    <div
        class="card-mainpage"
    >
        <div class="stack-parent">
            <div class="stack-vertical">
                 <span 
                      class="dashicons dashicons-database"
                 > 
                 </span>
            </div>
            <div class="stack-vertical">
                 <strong>Add study name here</strong> 
            </div>
            <div class="stack-vertical">
                 <p style="font-style: italic">Experiment type here</p> 
            </div>
        </div>
    </div>
</a>

• Replace “add-page-link-here” in the href with the link to the study page.
  • The link can be found by opening a preview of the page or if published opening the live page in the web browser.
  • This will follow the following convention.
    • https://[website-domain]/[name-of-page]/
  • As an example, this is the link to the vfp-dataset.
    • https://hipsc-endo-rnaseq.org/vfp-inflammation/
• Replace Add study name with your study name.
• Replace Experiment type with the type of experiment done, e.g. bulk RNAseq.
• Save the page once done in order to reflect the changes live.

Once all of these steps are completed the site should be live and it should be possible to search the uploaded datasets for specific gene expression.