Submit an Analysis

To the server and back

This page shows how PS after having all necessary information sets up the environment for the server to work properly and how it gets its results back.

Setting up the environment

Hitting the submit button in Step 3 executes toggleNextClass to show the Step 4 container and executeStage that executes the following block

var parameterObjs = $("#s3expparams input,#s3expparams select");
if (validateParameters(parameterObjs)) { //if all parameters are valid
	postParameters(parameterObjs);
	// Clear areas where results information appears.
	resetResultsInfoItms();
	} else {
	ret = false;
}

First, validateParameters gets all text boxes and lists under the expparams container to check their validity as PS options. If an item has the data-required attribute and is emoty then it is marked with red border. The conditions list is marked if none or only one condition is selected. expquantfiltlbl is marked if the condition inside is not contained in the conditions of the conditions list (this is not possible in fact but it is entered as another validation check to catch possible PS errors that might lead to expquantfiltlbl containing invalid values). This function also checks the validity of the names of all conditions. If the validation returns no invalid values postParameters is executed to upload all parameters to the server. postParameters gets all check boxes, text boxes and lists from the Step 3 and parses their values to thedata variable, a variable sent to upload_parameters.php. If the object is a check box it uses the following code:

thedata.append($(param_i).attr('name'), (theval ? "T" : "F"));

to match the box’s name to its value encoded as T/F. For lists ans text boxes it gets their value with

thedata.append($(param_i).attr('name'), theval);

and sends it with

thedata.append($(param_i).attr('name'), theval);

Especially for the conditions list, it gets all selected conditions from the list and send it one by one with the format of "explbl[counter]name"using:

thedata.append("explbl" + (tmp_i) + "name", my_temp_text);

In case we have Merging enabled, if the condition in the conditions list is authentic it is parsed as above. In case the condition is not authentic PS searches the second column of RenameArray against the selected merged condition and sends the corresponding authentic conditions to the backend. The information about how the authentic items are merged to others is sent below. As for the rest of the parameters most are simply sent as scalar variables:

thedata.append("labelfree", isLabelFree ? 'T' : 'F');
thedata.append("AllowMergeLabels", AllowMergeLabels ? "T" : "F");
thedata.append("AllowLS", AllowLS ? "T" : "F");
thedata.append("LeastBreps", LeastBRep);
thedata.append("LeastPeps", LeastPep);
thedata.append("PThreshold", Pthreshold);
thedata.append("RMbrepsRepInRawFiles", RMbrepsRepInRawFiles ? "T" : "F");
thedata.append("RMtrepsRepInRawFiles", RMtrepsRepInRawFiles ? "T" : "F");
thedata.append("RMconditionsRepInRawFiles", RMconditionsRepInRawFiles ? "T" : "F");
thedata.append("RMisused", RMisused ? "T" : "F");
thedata.append("IsIsobaricLabel", isIsobaricLabel ? "T" : "F");
thedata.append("All_MQ_Labels", my_all_mq_labels);

Special functions are used to: Create a tabular representation of rawfiles_structure (gen_expdesign creates a string like this: )

OT2_Terhune_2012-10-09_DMC-HLNF01_01	1	1	1
OT2_Terhune_2012-10-09_DMC-HLNF01_02	1	2	1
OT2_Terhune_2012-10-09_DMC-HLNF02_01	1	1	2
(...)
OT2_Terhune_2013-08-06_DC-SILAC-BR3Fr12_02	3	2	12

if RM is used, the string created is always the same:

RM_exmpl1  1   1   1
RM_exmpl2  2   1   1

that will not be used in the analysis but is created for backward compatibility issues. generate_tab_file creates tabular representations like the one above for RMRawFiles and RMTags, gen_RenameFile for RenameArray and gen_LSArray for LabelSwapArray. In case LS is not used, the string returned for LabelSwapArray is “This run contains\tno label\tswaps\n”. This is done to avoid using special loading options in server’s R when loading the experiment depending on whether the session has Labels swapped or not - it is simply not used after experiment’s loading. All the parameters above are sent via thedata to upload_parameters.php that will create the environment to run the analysis. upload_parameters.php gets the following contents of “parameters_template.R” and edits it to append all necessary parameters.

ratios.hist.colour<-"cyan"
reps.scatter.lmline.colour<-"red"
nRequiredLeastBioreps<-REPLACE14
nRequiredLeastPeps<-REPLACE15
pThreshold<-REPLACE16
GUI<-F
paramssetfromGUI<-F
keepEvidenceIDs<-F
exportFormat<-"pdf"
rep_order<-NA
mqValidation<-F
#working_directory<-REPLACE9
experimental_structure_file = "exp_struct.txt"
LFQ_conditions_file = "LFQ_conditions.txt"
Rename_Array_file = "Rename_array.txt"
LS_Array_file = "LS_array.txt"
pgroups_fname<-"msdiffexp_protein.txt"
evidence_fname<-"msdiffexp_peptide.txt"
RMrawfilesdata_file = "RMrawfiles.txt"
RMtagsdata_file = "RMtags.txt"
outputFigsPrefix<-REPLACE2
filterL_lbl<-REPLACE7
filterL_lvl<-REPLACE6
LabelFree<-REPLACE8
PDdata<-REPLACE1
IsobaricLabel<-REPLACE10
All_MQ_Labels<-REPLACE11
time.point<-REPLACE3
# bioreps<-3
# techreps<-1
ProteinQuantitation<-REPLACE4
filterL<-REPLACE5
AllowLabelRename<-REPLACE12
AllowLS<-REPLACE13
RMisused<-REPLACE17
RMbrepsinrawfiles<-REPLACE18
RMtrepsinrawfiles<-REPLACE19
RMconditionsinrawfiles<-REPLACE20

For example after editing it it might look like this:

ratios.hist.colour<-"cyan"
reps.scatter.lmline.colour<-"red"
nRequiredLeastBioreps<-2
nRequiredLeastPeps<-2
pThreshold<-0.05
GUI<-F
paramssetfromGUI<-F
keepEvidenceIDs<-F
exportFormat<-"pdf"
rep_order<-NA
mqValidation<-F
#working_directory<-"C:\xampp\htdocs\ProteoSign\uploads87934711865\msdiffexp_wd"
experimental_structure_file = "exp_struct.txt"
LFQ_conditions_file = "LFQ_conditions.txt"
Rename_Array_file = "Rename_array.txt"
LS_Array_file = "LS_array.txt"
pgroups_fname<-"msdiffexp_protein.txt"
evidence_fname<-"msdiffexp_peptide.txt"
RMrawfilesdata_file = "RMrawfiles.txt"
RMtagsdata_file = "RMtags.txt"
outputFigsPrefix<-"SILAC_2_plex_MQ_"
filterL_lbl<-"L"
filterL_lvl<-F
LabelFree<-F
PDdata<-F
IsobaricLabel<-F
All_MQ_Labels<-c("H", "L")
time.point<-"0h"
# bioreps<-3
# techreps<-1
ProteinQuantitation<-T
filterL<-F
AllowLabelRename<-T
AllowLS<-T
RMisused<-F
RMbrepsinrawfiles<-T
RMtrepsinrawfiles<-T
RMconditionsinrawfiles<-T
addLabel("H",c(""))
addLabel("L",c(""))

This contains much of the necessary information to run the analysis. It is in fact an executable R file that is always executed while initializing R backend to load the necessary parameters. the php script also creates the following files:

  • exp_struct.txt that contains rawfiles_structure in tabular format as seen above
  • LFQ_conditions.txt that contains RawFileConditions in tabular format
  • LS_array.txt that contains LabelSwapArray in tabular format
  • Rename_array.txt that contains RenameArray in tabular format
  • RMrawfiles.txt contains RMrawfilesdata in tabular format
  • RMtags.txt contains RMtagsdata in tabular format The two later files are created only if RM was used in the experiment All these files are written in the session’s folder under ‘uploads’. This completes setting up the environment for the analysis. After completing upload_parameters.php's execution, an anonymous .done function in postParameters is executed calling postFireUpAnalysisAndWait that will start the analysis.

Starting the analysis

The analysis is started with the execution of postFireUpAnalysisAndWait function. The first thing that this function does is to make sure that the current session has not been already submitted something that might happen if one hits the submit button many times before the connection with the server is established. sessions_that_run contain all sessions that have been submitted. If the session is not contained in the array it is simply added to it. SaveParams is called with output_file argument set to 1 so that ot creates a parameters file and saves it to the working folder, also 2 global variables are set to false, analysis_finished and RreturnedErrorsInCurSession. 4 things will be sent to php: the session id, the procprogram and 2 boolean variables informing R whether label merging will be used (AllowMergeLabels) and whether LabelSwap will be used (AllowLS). For the uyser not to be bored during analysis PS has a special function that can fetch RSS data from a feed and show them to the user one by one. This uses get_rss.php a server sided php Script that opens a RSS feed and fetches some specific RSS elements. This will be shortly presented here since one might want to change it and present another feed to their users. RSS_link and RSS_prefix are the main global variables that might be changed to customize RSS display. get_RSS.php opens the RSS link and loads the RSS feed. the following files get the elements of interest:

foreach ($xml->channel->item as $item)
{
	$server_response[trim((string)$item->title)] = trim((string)$item->link);
	$i++;
	if ($i > 40) break;
}

it is obvious that this is hardcoded to NAR’s feed for their current issue and targets the leements root > channel > item > [title and link]. One can open an RSS feed of their choice and get in a similar manner all descriptions of some links and the respective links and save them to $server_response. After the completion of get_RSS.php renderRSSData is executed that will take the returned data and will start an infinite loop of a function called updateFun. This function displays a link with its description as returned from the RSS feed:

prev_html = '<p>' + RSS_prefix + '<br><br><a href="' + data[item] + '" target="_blank"><strong>' + item + '</strong></a></p>';

and has a wait function inside so that the user has the time needed to read each description. It is possible that one might want to get descriptions and links by a webpage. Although this is not the best idea, we provide you a tool we used in the past. get_NAR_articles.php does this exact thing. It retrieves URL links and their descriptions using regexes on its html code. To enable this feature change RSS_link to the target web page and comment in the respective comment in getRSS. The commented in code and the code in get_NAR_articles.php will need to be customized before working properly for a specific webpage. When the RSS elements start being displayed perform_analysis.php is executed. perform_analysis will start by creating a folder called msdiffexp_wd inside the session folder. Over there it will copy:

  1. MSdiffexp.R, the main R file for the analysis (initially located in the cgi-bin folder)
  2. README.txt a text file describing all result files (initially located in the cgi-bin folder)
  3. Plot_Generator.R a file used to create all plots of the analysis after it is completed (initially located in the cgi-bin folder)
  4. MSdiffexp_definitions.R the initialization R script created especially for the current experiment
  5. exp_struct.txt
  6. LFQ_conditions.txt
  7. RMrawfiles.txt
  8. RMtags.txt
  9. Rename_array.txt
  10. LS_array.txt
  11. msdiffexp_protein.txt
  12. msdiffexp_peptide.txt

files 5-10 were explained before and the files 11-12 are the files output from MaxQuant and Proteome Discoverer (msdiffexp_peptide.txt is the evidence MQ file or the PSM PD file and msdiffexp_protein.txt is the proteinGroups file from MQ). To support both windows and unix php versions, PS checks whether the file “RScript.exe” or “R” is installed in the server and executes MSdiffexp.R with the respective tool. R’s STD OUTPUT is redirected to the log file msdiffexp_log.txt. MSdiffexp.R performs the analysis and writes all output files to the working directory along with some png plots. The log file is them read by perform_analysis.php and is searched against patterns such as Warn User Error User and Info User. If ther are any of these patterns the respective lines are appended to the response variable “UserInfo”. This will be used to inform the user about any errors or warnings the R script faced (for example not being able to create a plot - unfortunately fatal R errors most of the times will stop R’s execution providing nothing descreptive enough to show back to the user, in this case PS will simply display “The R script returned error(s)."). If the R execution was successful the results in the output folder will be zipped in a folder and will be saved to the main working folder of the session (uploads/[session_id]). results_preview is a result variable - array that contains links to all png plots created. If the analysis was successful check whether the session id of the results does not match the current session id and in this case abort the results. If this is not the case, remove the current session id from the sessions_that_run array.server_feedback is the container that will display the results. First, PS gets data.UserInfo that has all information by R that need to be displayed to the user. It splits the returned string in lines and paints the info blue the warnings yellow and the erros red and displays them with a message box to the user. Then, it gets all png plots paths as returned in data.results_preview and chooses all plots instead these created by limma directly and appends them as image - links to the server_feedback container. dndres is a span object that contains a link to the zipped folder with all the results. server_feedback is contained in Step 4 and dndres in Step 5 that is the last step in PS. When the user reaches step 5 the next button is renamed to “Reset” that if it is pressed it refreshes the webpage to start PS over. A feedback button is shown from the side to give feedback back to the users. In case of perform_analysis.php failure server_feedback is populated with a span saying “An AJAX error occured (…)” and in case the php was successful but R erturned errors another error message is displayed. The feedback procedures are based on expparamsDlgFeedback dialog box. When the user chooses how many stars to rate PS and write a feedback test it executes send_feedback.php that simply appends a line to a tab delimited file in the server that its full path is the value of the global configuration variable in script.JS server_Feedback_file. The procedures described above are shown in the diagram below:

The algorithm of loading a test dataset

This completes PS’s documentation pages.