DeBias webserver user manual


DeBias is a freely-available web-based simulator to quantify the global bias and local interactions in biological systems, https://debias.biohpc.swmed.edu

I. Launch DeBias


At the bottom-right part of the page, fill-in the captcha('Enter Image Text', for security purposes), select 'DeBias' and press 'Submit'.


Launch_DeBias

Figure 1. Launch DeBias

II. Upload data and run DeBias


The following three steps must be completed to execute DeBias: (1) upload data; (2) select mode; (3) enter email and run DeBias.


DeBias_UI

Figure 2. DeBias user interface


1. Upload data


Upload data to the webserver for analysis. Click the Choose Files button to select the input datasets. Up to 50 files for a single submission (maximal size of 200 MB per file).


DeBias_workflow

Figure 3. Upload Data


DeBias_workflow

Figure 4. The helpicon provides information on the supported file formats and specific formatting instructions. Each input dataset must contain two arrays of the measured variables. Supported file formats are MATLAB MAT-file (*.mat), text file (*.txt) or excel file (*.xls, *.xlsx).


2. Select Mode

Chose between co-orientation and co-localization


DeBias_workflow

Figure 5. Select Mode of operation


3. Run DeBias


Enter email address and press the Run DeBias button. Results will appear at the bottom of the page after processing is completed..


Run_DeBias

Figure 6. Run DeBias


A downloadable link is sent to the user via email enables to access the results within 30 days from submission. The Data ID(together with the email address), should be later used to post-process the data via DeBias Analyst.


DeBias_workflow

Figure 7. Email with link to the data. Data ID is marked in red. Note that the email is sent upon the initialization of DeBias processing and the link will be affective once processing is completed.


II. Job status

The job status field is shown at the bottom part of the user interface and traces the progress of processing. After a job is submitted the processing status is displayed:

1. The DeBias logo status is the initial status displayed. It is shown until a job was accepted for processing. The webserver checks the file size and file extension of each input datasets fits the requirements (detailed below).


DeBias_workflow

Figure 8. Initial stuatus - the DeBias logo


2. The in progress status implies that the job is processed at the backend. Execution time depends on the size and numbers of datasets. For multiple datasets, the job status includes the number of datasets that have been completed.


DeBias_workflow

Figure 9. In progress - processing data


3. The completed status implies that the job was completed successfully and the results are ready below for viewing and downloading.


DeBias_workflow

Figure 10. Job completed



III. Errors

An error message will be displayed when the uploading failed or upon a data format error. An error message is displayed upon uploading when validation process fails:

  • "Please choose files to be uploaded before processing data". Datasets were not selected for uploading.
  • "File size is ** bytes, must be less than 200 megabytes". The size of a single dataset is limited to 200MB.
  • "Uploading error". May be caused by an internet or server side error, check your internet connection and try uploading the data again.
  • "Wrong file type": DeBias supports .txt, .xls, .xlsx and .mat files". Supported input data formats are MATLAB MAT-file (*.mat), text file (*.txt) and excel file (*.xls, *.xlsx), please format your data accordingly.

DeBias_workflow

Figure 11. Example error message


The error status implies that the job failed at runtime. Most errors are caused by erroneous formatting of the input data. The user can correct the data and then resubmit. Upon error invocation, an ERR icon will appear in the job status providing detailed information by clicking on it.

  • "Mat-file missing x, y variables". Mat-files must include variables named 'x', 'y' to be processed. The pair represents an observation./li>
  • "Erroneous data, variables must be in the [-180,180] (or [-pi,pi]) range". Angular data must be in the range of -180 to 180 degrees of -pi to pi radians. Please select "No" for the "isAngle" field if the data is not angular.


DeBias_workflow

Figure 12. Debias runtime error




IV. Results


1. Viewing results online

Upon job completion a results table is generated and displayed at the lower part of the page, scroll down to see it. The result table lists the local and global indices for each dataset. In addition, an online report is available for each dataset. It includes the histograms for the marginal and joint distribution as well as the observed and resampled alignment distribution and is accessible via the View Report link.


DeBias_workflow

Figure 13. Results Table


2. Downloading results

The raw data and higher quality downloadable figures are placed at the File Folder tab. The data folder contains the raw input datasets. The log folder contains code-related debugging information and should preferably be used when reporting errors to the developers. The output folder contains high quality figures in eps format and the actual data in a MAT-file format.


DeBias_workflow

Figure 14. Results


Each dataset contains the following outputs that are encoded in the file suffix:

  • *_X.eps: distribution of the first variable
  • *_Y.eps: distribution of the second variable
  • *_joint.esp: joint distribution
  • *_observed.eps: observed alignment distribution
  • *_resampled.eps: resampled alignment distribution
  • *_xy.mat: input data that was received for processing

DeBias_workflow

Figure 15: Output



V Setting parameters (for advanced users only)

The user can set the number of bins in the alignment histogram (K) either manually or automatically based on the data. This parameter affects the GI and LI values (through the EMD metric) and should be used very carefully only comparing experiments that were calculated with the same K values. Default K values are 15 (co-orientation) and 40 (co-localization). DeBias ability to discriminate between different experimental conditions is robust and should not be dependent upon specific selection of K values thus we recommend not using this option. For full details please refer to the manuscript.

To set K, the user needs to press the "Advanced Option" button


DeBias_workflow

Figure 16. Advanced option for setting K.


The user can either select K or apply the default value (same as when not using the set parameters option).


DeBias_workflow

Figure 17. set K or use default values


When selecting the Input K Value the user can either estimate K automatically (data driven) or manually select a K value.


DeBias_workflow

Figure 18. Calculate or manually input K


Manual selection of K is performed in the K value text-box. Estimate K button opens a new browser-tab when the user can upload data, run calculation and estimate K (this process is very similar to using DeBias and is not illustrated in the manual). Then the K must be manually inputted to the K value text-box in order to be applied when executing DeBias.




VI Sample data


Sample datasets are provided to allow validating the correct usage of DeBias. These datasets can be downloaded from the DeBias webpage. Another option is to simulate data using the corresponding Matlab code at the source code repository (https://github.com/DanuserLab/DeBias, check the matlabSrc/simulations/ folder).

  • testCME: a folder containing 1 dataset with scalar measurements (originating from protein-protein colocalization data).
  • testAngle: a folder containing 3 datasets with angular measurements.


VII Webserver workflow

The DeBias simulator can be applied to analyze data, view and download results. The core code was developed and tested in MATLAB and then integrated to the web-based platform, with the following workflow:

DeBias_workflow

Figure 19. DeBias workflow. Data upload and processing: upload data, choose parameters and (optionally) provide an email address to which a link to the results will be delivered. Upon submission: data validation and processing at the backend. Results: obtain results, error message or initialize a new processing.