Parameters - saving and loading them

This page will analyse how the main options in Step 3 are set and sent to the server and how PS interface gathers back the analysed data

Options of a typical PS run

In step 3 the user is asked to type 2 descriptions for their experiment and select the conditions to compare. The reason for giving two desriptions (one id and one description) is that many parallel PS runs might have the same ID and different descriptions so that further analysis of the experiments can easily be done later on. In case more than 2 conditions are selected all possible comparisons will be done. Quantitation filtering is another option that was described in a previous oage of this documentation and here we will describe how the user options are sent to the server. Miscellaneous options like p value and protein disqualification criteria will also be described here: expid and exptpoint are the names of the two text boxes that contain the ID and the description of the experiment. The check box to choose whether you will use quantitation filtering or not is called expquantfilt and the list box to choose the background species for quantitation filtering is is called expquantfiltlbl. Another check box s used to tell PS if the filtering will be in peptide or protein level and it is called expquantfiltprot. conditions_list is the list (a multi-select list in fact) that contains all conditions to be compared. This is auto-filled when loading the experiment or when adding conditions for LFQ experiments in Step 2. When the user hits the Submit button, the executeStage function will call validateParameters and postParameters to read the parameters above and send them to the server. This function will be explained in detail after explaining all advanced procedures.

Saving and loading parameters

Since ProteoSign is kind of state-less it is necessary for the user to have all their parameters stored in a file since in a later run of the same file they may want to slightly alter the parameters. PS has a special function to create a simple text file to describe all these parameters. All of them are variables (scalar or arrays) that are saved in the text file. The function is CreateParamsFile and it creates a file with the structure like this:

#ProteoSign parameters files for SILAC_2_plex_MQ_ (session ID: 1587469012346)
#
#File Information:
isLabelFree
false
isIsobaricLabel
false
procprogram
MQ
#User Parameters and commands:
rawfiles_structure
OT2_Terhune_2012-10-09_DMC-HLNF01_01	1	1	1	1		OT2_Terhune_2012-10-09_DMC-HLNF01_02	1	2	1	1 (...)	
expid
SILAC_2_plex_MQ_
!Rename
H|H||L|L||
exptpoint
0h
conditions_to_compare
H	L	
quantitation_filtering
T
filtering_label
L
peptide_level_filtering
F
LeastBRep
2
LeastPep
2
Pthreshold
0.05
LFQconditions

!LS_Array

!LS_c_p_Add

!Select_Labels
H|L|
!RMrawfilesdata

!RMtagsdata

!RMbrepsRepInRawFiles
true
!RMtrepsRepInRawFiles
true
!RMconditionsRepInRawFiles
true
!RMisused
false

Where the lines strarting with # are comments, and all other lines are pairs of lines - the first describing a variable name and the second its value. Keep in mind that the arrays are stored in one-line representations. Hitting the save button in stage 4 or 5 will call SaveParams(output_file = 0) which will create the parameters file, return it stored in a string (mytext) and call download_param_file.php which since the argumment output_file is set to 0 will write a parameters file in the session folder of the current session and return a link pointing to that. SaveParams will display a message (using the msgbox function) that will provide the download link. When the user submits their analysis, the SaveParams function is called with output_file set to 1 which will also write the parameters file to the session folder with the only exception that it will contain “parameters_from_session” in its name. This will tell PS later to copy the parameters file in the results folder for the user to have a copy of it with the results. Also, no download link will be displayed. CreateParamsFile simply gets some variables and stores them in a multiline string using the format described above. The variables stored are: isLabelFree, isIsobaricLabel, procprogram, rawfiles_structure, expid, Rename, exptpoint, conditions_to_compare, quantitation_filtering, filtering_label, peptide_level_filtering, LeastBRep, LeastPep, Pthreshold, LFQconditions, LS_Array, LS_c_p_Add, Select_Labels, RMrawfilesdata, RMtagsdata, RMbrepsRepInRawFiles, RMtrepsRepInRawFiles, RMconditionsRepInRawFiles, RMisused The scalar variables are simply print below their names:

mytext += "isLabelFree\n";
mytext += isLabelFree + "\n";

One line representation of arrays has already been described when talking about the test data database. A 2 dimension array is represented in one line with a separator. The presence of the separator one time denotes a column break and its presence twice a line break. For example H|H||L|L|| is a representation of | H | H | |—|—| | L | L | The separator though might be a tab character as seen in rawfiles_structure. For rawfiles_structure PS gets all its elements and creates a one line representation as above with tab as seperator. The used property is transformed from true / false to 1 / 0. In case RM is used, PS will create a variable temp_rf_structure that contains all rawfile names and the default values ('-’ for brep trep, frac and condition and 1 for used). This way the user will see their structure set under RM when they load the parameters but will have the default rawfiles structure in case they want to get back to usual structure setting. !Rename stores the RenameArray in one line representation with | as seperator. conditions_to_compare stores AuthenticItemsinRename with \t as seperator, LFQconditions stores RawFileConditions with \t as seperator, LS_Array LabelSwapArray with | as seperator. LS_c_p_Add stores LS_counters_per_Add with | as seperator (note that LS_counters_per_Add is a 3 dimension array). Select_Labels stores a one dimension array of all the conditions that are currently selected. As for RMrawfilesdata and RMtagsdata they use a recursive function (array_to_string) that creates one line representations with | as seperator of arrays with up to 15 dimensions - even if they are jagged ones. Its comments describe how it works. It is advisable in case we add more functionality to PS and we want to make it a save-able parameter to use this array to transform arrays to teir one line representations. The only restriction is that all elements of the array should not contain | and ~. Also, its counterpart string_to_array can get a one line representation and turn it back to an array and this is really used in loading a parameters file. Note that some of the variables described above are stil not explained but will be explained later on.

Loading a parameters file

Loading the parameters file follows the exactly opoosite steps. Hitting the load link in PS performs a click on the hidden upload link __upldparams. This enables the user to upload a file to the server. When the button changes value the uploadParameters function is called that executes server-sided upload_param_file. This script simply gets the uploaded file stores it in the session folder and then reads it to return the data in a multi line string (restext). uploadParameters done function gets the restext and calls LoadParams that loads all parameters from the multiline string and performs some validation checks. First it calls the CheckParamsValidity function to make all the necessary validity checks. It first demands that the parameters file has the same experiment type as the loaded experiment and that the processing program is the same. CheckParamsValidity also calls add_raw_file_structure with checkvalidity set to true to make sure that all rawfiles in the dataset are included in the parameter’s file. The block below does this job:

var lines = tab_sep_string.split("\t\t");
var validityresponse = true;
$.each(lines, function(idx, my_line){
	if (my_line == "") return;
	var my_vals = my_line.split("\t");
	if(my_vals[0] == "rawfile")
	{
		return;
	}
	
	if (check_validity == true)
	{
		//in this case the only reason to run the function is to check if all the rawfiles in the file uploaded exist in the current dataset
		if($.inArray(my_vals[0], local_rawfiles) == -1)
		{
			//if one rawfile in the params file is not in the dataset abort
			validityresponse = false;
		}
	}
	else
	{
		// if check validity == false then we should renew the rawfiles structure object
		rawfiles_structure.push({rawfile: my_vals[0], biorep: my_vals[1], techrep: my_vals[2], fraction: my_vals[3], used: my_vals[4]});
	}
}); // END for each line

// Now, validityresponse is true if all rawfiles in the param save file have a match in the dataset
if (check_validity)
{
	return validityresponse;
}

if CheckParamsValidity returns false the procedure of loading is stopped. LoadParams demands that the file starts with the comment “#ProteoSign parameters files” and for each line it checks if a valid variable name is present. In this case it consumes the line right below and sets the variable to the respective value. In case the variable to be set is rawfiles structure PS calls add_raw_file_structure with check_validity = false to set the rawfiles_structure array. The rest of the variables are easily set and the function is well documented. Selecting specific conditions to compare is done by select_labels_according_to_test_dataset function and all DOM objects related to the variables set are always refreshed. A message box is displayed at the end depending on if CheckParamsValidity returned true or false.