New X!tandem form

[Fredrik Levander]

X!tandem has a lot of advanced parameters that are usually left untouched. the following should be brought to the simple form (in that order):

• Fragment monoisotopic mass error
• Fragment monoisotopic mass error units
• Parent monoisotopic mass error plus
• Parent monoisotopic mass error minus
• Parent monoisotopic mass error units
• Select modification mass
  • or specify own
• Select potential modification mass
  • or specify own
• Taxon - Eukaryotes
• Taxon - Prokaryotes
• Algorithm (Native/k-score)

In addition, some parameters should be removed:

• Default parameters (instrument selection - can be taken away completely)
• taxonomy information (the value 'taxonomy.xml' should still be submitted).

Default value for X!Tandem - Output - Maximum valid expectation value can be changed to 1.

New alternatives for modification masses should be taken from the current X!tandem search form: ​http://h.thegpm.org/tandem/thegpm_tandem.html

[olle]

Ticket accepted.

[olle]

Traceability note:

This ticket is related to the following tickets:

• Starting X!Tandem searches from Proteios was introduced in Ticket #362 (Run X! Tandem from Proteios).
• Ticket #698 (Move forms out of the FormFactory).

Before implementing the changes desired in this ticket, the X!Tandem form management will be refactored to comply better with the goal of ticket #698 (Move forms out of the FormFactory).

[olle]

Outline of design choices for creating an X!Tandem form class:

In order to comply with the goal of ticket #698 (Move forms out of the FormFactory), the following principles were followed:

• A new class XTandemParameterSetForm was created in gui/form/ in client/servlet/.
• Two constructors were created, one default constructor without arguments that creates all fields in the form, and a constructor with an XTandemParameterSet instance as argument, which calls the default constructor and then sets field values to the ones in the given XTandemParameterSet instance.
• Valid parameters related to the X!Tandem parameter set fields were moved from class SaveXTandemParameterSetStorage in action/xTandemInput/ in client/servlet/ to the new XTandemParameterSetForm class.
• Action classes that need to transfer values in an X!Tandem parameter set to a new form should do this by creating a temporary X!Tandem parameter set form with up-to-date values, and add the fields in the latter as hidden fields in the new form, using a nearly generic method parsing the source form, instead of previously used methods requiring detailed knowledge of the contents of the latter. This will be implemented for class SaveXTandemParameterSetStorage in action/xTandemInput/ in client/servlet/. Due to the relative complexity of the X!Tandem parameter set form, using text fields, pop-up menus, as well as single-choice and multiple-choice select boxes, the method adding data from one form to another cannot at present be made completely generic, but will still only contain a minimum of information about the X!Tandem parameter set form.

[olle]

(In [3881]) Refs #700. Refs #698. X!Tandem parameter set form now created by its own class:

1. New class/file gui/form/XTandemParameterSetForm.java in client/servlet/

added:

1. Valid parameters related to the X!Tandem parameter set fields were

moved to the new class from class/file action/xTandemInput/SaveXTandemParameterSetStorage.java in client/servlet/.

2. Two constructors were created, one default constructor without

arguments that creates all fields in the form, and a constructor with an XTandemParameterSet instance as argument, which calls the default constructor and then sets field values to the ones in the given XTandemParameterSet instance.

3. Management of option alternatives were moved to two new methods,

fetchDefaultOptionAlternatives() for setting default options, and fetchOptionAlternatives(), that exchanges the former for option alternatives obtained from an GPM web site, if avaliable.

2. Class/file action/xTandemInput/SaveXTandemParameterSetStorage.java in

client/servlet updated:

1. Valid parameters related to the X!Tandem parameter set fields were

moved to the new XTandemParameterSetForm class.

2. X!Tandem parameter set values are transfered to the current form by

creating a temporary X!Tandem parameter set form with up-to-date values, after which the fields in the latter are added as hidden fields by new private method Form addFormFields(Form targetForm, Form sourceForm)

3. Class/file action/xTandemInput/ViewActiveXTandemParameterSetStorage.java

in client/servlet/ updated:

1. Public method void runMe() updated by creating X!Tandem parameter set

form by new class XTandemParameterSetForm.

2. Old methods related to creation of an X!Tandem parameter set form

and adding X!Tandem parameter set fields to a fieldset have been removed: private List<Option> stringListToOptionList(List<String> stringList) public Form getXTandemParameterSetForm(...) public Fieldset addXTandemParameterSetToFieldset(...) public Fieldset addXTandemParameterSetListPathFieldsToFieldset(...) public Fieldset addXTandemParameterSetSpectrumFieldsToFieldset(...) public Fieldset addXTandemParameterSetResidueFieldsToFieldset(...) public Fieldset addXTandemParameterSetProteinFieldsToFieldset(...) public Fieldset addXTandemParameterSetRefineFieldsToFieldset(...) public Fieldset addXTandemParameterSetScoringFieldsToFieldset(...) public Fieldset addXTandemParameterSetOutputFieldsToFieldset(...) private boolean itemInOptionList(List<Option> optionList, String item) private boolean allItemsInOptionList(List<Option> optionList, List<String> itemList) private List<String> listStringToStringList(String listString, String delimiterRegex)

4. Class/file gui/form/Select.java in client/servlet/ updated:
5. Public constructor Select(D param, List<Option> optionList, List<String> selected)

updated by first checking if selected list is null before using it.

2. New public method void selectOptions(List<String> selected) added.

It sets all options matching any value in the input list to selected.

[olle]

Change in default settings due to technical reasons:

The options in the X!Tandem parameter set form in Proteios SE were based on the options in the search form on the GPM (Global Proteome Machine) web site. For some options like residue modifications, the user has the alternative of selecting a modification in a menu/select box or enter his/her own value in a text field. When Proteios SE displays a form showing an X!Tandem parameter set, the menu/select box option is selected if the parameter value corresponds to an option in the menu/select box, otherwise the value is shown in the text field.

Default values are stored in file conf/xtandem_default_input.xml in client/servlet/, and were taken from an XML file with default values for running X!Tandem searches using a locally installed program. However, the default value for the residue modification in this file is "57.022@C", which differs in the decimals from the default setting in the menu, which is "57.021464@C" for "Carbamidomethyl (C)", resulting in that the latter option is not selected in the pop-up menu. Clearly the default choices are meant to be the identical, so the default value for residue modifications in file xtandem_default_input.xml should be changed to "57.021464@C", leading to menu option "Carbamidomethyl (C)" being selected in the form.

[olle]

(In [3883]) Refs #700. Configuration XML file conf/xtandem_default_input.xml in client/servlet with default X!Tandem parameter values updated:

1. Default value for residue modification mass changed from

"57.022@C" to "57.021464@C", in order to correspond to value for "Carbamidomethyl (C)" in option menu.

[olle]

(In [3884]) Refs #700. Configuration XML file conf/xtandem_default_input.xml in client/servlet with default X!Tandem parameter values updated:

1. Default value for output maximum valid expectation value changed

from "0.1" to "1".

[olle]

(In [3885]) Refs #700. Refs #698. Class SaveXTandemParameterSetStorage updated to fix problems with adding string lists as list strings in hidden fields in the form. The list string to save could be too long for the valid VString parameter coupled to the hidden text field. A string list is now added as a list also in the added hidden field.

1. Class/file action/xTandemInput/SaveXTandemParameterSetStorage.java in

client/servlet updated:

1. Private method Form addFormFields(Form targetForm, Form sourceForm)

updated to add a string list as a list also in the added hidden field. In addition to solving the problem with strings being too long to be saved in a hidden field coupled to a specific valid parameter, this has the added benefit of not requiring detailed knowledge of the data being saved.

2. New private convenience method

void addHiddenField(Fieldset fieldset, VParameter param, String value) added. It creates and adds a hidden field with a String value to the given field set.

[olle]

(In [3893]) Refs #700. Class/file gui/form/XTandemParameterSetForm.java in client/servlet/ updated to comply with some requests for Ticket #700 (New X!Tandem form):

1. Entry for fragment monoisotopic mass error units should be placed directly

after entry for fragment monoisotopic mass error. In order to keep the correspondence between source code and displayed form high, the order of variables has been changed also in places not directly involved with the visual elements of the form.

2. List path default paraameters are left out, and list path taxonomy information

should be submitted, but not shown in the form.

3. Since none of the list path entries should be shown, field set "List Path"

is removed. Hidden field for list path taxonomy information is instead added to the "Spectrum" field set.

[olle]

Design discussion:

• In addition to the new simple X!Tandem search form, it is still desirable to be able to inspect and edit the complete set of parameters available in the current X!Tandem form, which will therefore be referred to as the advanced search form in the future.
• The advanced search form will include a full set of search options, including the standard settings in the simple form.
• A simple solution would be to use only a single web form, but visually separate the parameters into two groups, standard and advanced settings. However, this leads to a form that is even longer than the current one, and most field set headers will be shown both in the standard and advanced section of the form, which might be confusing. If possible, a more clear separation into two separate forms will therefore be the goal.
• It should be possible to change from display of the simple search form to the advanced search form, and vice versa. The simple search form should be the default one.
• If possible, it is desirable that changes made in one type of the form (simple or advanced) should be transferred to the other type, even if the changes have not been saved to the database, e.g. if one wants to check some setting only visible in the advanced form, while filling in the simple form. Technically, several actions and forms may be involved in the latter scenario, but from the user's view he/she perceives it as filling in the simple form, if no changes are made to the fields unique to the advanced form.

Technical details and tests affecting design choices for the first version of the routine:

• Having the simple and advanced forms as separate tabs in a single form would be a nice solution, with the tab with the simple form shown by default. However, the way tabs are currently implemented in forms, does not guarantee safe transfer of data from all components in both tabs at once.
• It would be desirable to create the simple form by parsing the advanced form and mark all fields not to be displayed as hidden, as this would eliminate the need for a new class for the simple form. Tests using this approach worked regarding creation of a simple form, but for unknown reasons failed regarding transfer of form data between actions. The first version of implementing a simple form will therefore be based on a separate class for the new form.
• Test revealed that information in hidden fields and select boxes were transferred correctly between actions, with the exception of multiple choice select boxes, where only the first choice was transferred automatically. A fix for this will therefore be needed in the first version of the routine.
• The Select class should be updated to allow hidden components, as this will increase the similarity code-wise between the simple and advanced forms.
• The switch between the two type of forms in the first version will be implemented by a button coupled to a Boolean flag variable, by which the other type of form will be displayed. Preferably the same action class will be used to display both type of forms.
• The Boolean flag variable coupled to the form type switch button will have a null value when the action is first entered, while it is set to either true or false when invoked from the button. This can be used to identify the first time the action is entered, and the form data should be obtained from a database entry, while data should be obtained from valid parameters for the forms in later stages, in order to transfer data from filled-in fields.

[olle]

(In [3897]) Refs #700. Select boxes updated to allow hidden select boxes:

1. Class/file gui/form/Select.java in client/servlet/ updated with new

private instance variable Boolean hidden and public accessor methods Boolean isHidden() and void setHidden(Boolean hidden).

2. Class/file gui/web/GUIConverter.java in client/servlet/ updated

to support hidden select boxes:

1. Private method

Tag convertFieldset(org.proteios.gui.form.Fieldset fs, Form form) updated to set attribute CLASS="hidden" for HTML <TR> tag enclosing a hidden Select GUIElement.

2. Public method

Tag convert(org.proteios.gui.form.Select<?> select) updated to set attribute STYLE="display:none;" for HTML <SELECT> tag for hidden Select GUIElement.

[olle]

(In [3898]) Refs #700. Class/file gui/form/Select.java in client/servlet/ updated to create a multiple choice select box if a constructor with an argument equal to a list of selected elements is used:

1. Public constructor

Select(D param, List<Option> optionList, List<String> selected) updated to set Boolean attribute multiple to true for the created select box.

[olle]

(In [3900]) Refs #700. Creation of option alternatives for X!Tandem searches is put in its own helper class/file gui/form/XTandemParameterSetOptionsHelper.java in client/servlet/, in order to simplify references from more than one class, and make class XTandemParameterSetForm only responsible for the design of the actual form. Some general utility methods related to option lists were also moved to the new helper routine:

1. New class/file gui/form/XTandemParameterSetOptionsHelper.java in

client/servlet/ added. It contains methods moved from class/file gui/form/XTandemParameterSetForm.java in client/servlet/ related to creation of option alternatives for X!Tandem searches. It uses methods in class/file io/XTandemParameterSetOptionsUtil.java in api/core/ to obtain option alternatives from a GPM web site.

2. Class/file gui/form/XTandemParameterSetForm.java in client/servlet/

updated to use new helper class XTandemParameterSetOptionsHelper to obtain option alternatives for X!Tandem searches:

1. New private method

XTandemParameterSetOptionsHelper fetchXTandemParameterSetOptionsHelperInstance() added. It returns an existing XTandemParameterSetOptionsHelper instance or creates a new one if needed.

2. Public constructor XTandemParameterSetForm(XTandemParameterSet obj)

updated to calls methods in the new helper class to process option lists.

3. Public method void fetchOptionAlternatives() updated to call

methods in the new helper class to obtain option alternatives.

4. Other methods moved to the new class are removed from class

XTandemParameterSetForm.

[olle]

(In [3901]) Refs #700. Class/file gui/form/XTandemParameterSetForm.java in client/servlet/ updated:

1. Private method Select<VString> createMultipleSelectBox(...)

updated by removing command setting the select box attribute multiple to true, since the used constructor for the select box now automatically does this.

2. Private method Select<VString> createSingleSelectBox(...)

removed, since it is no longer called.

[olle]

(In [3902]) Refs #700. New class/file gui/form/XTandemParameterSetFormSimple.java in client/servlet/ added. It is intended to create a simple X!Tandem search form. The added file is just a dummy template that is basically a copy of class XTandemParameterSetForm, but with another name. when this template file will later be updated to the real version, the changes relative to class XTandemParameterSetForm can be easily inspected in the change set.

[olle]

(In [3903]) Refs #700. Class/file gui/form/XTandemParameterSetFormSimple.java in client/servlet/ updated to create a simple X!Tandem search form:

1. Valid parameters defined in class XTandemParameterSetForm used for form elements, in order to ensure that form data can be

transferred between the two classes.

2. Public constructor XTandemParameterSetFormSimple() sets

attribute hidden to true for all form elements that should not be visible in the simple form. Hidden fields and select boxes that were originally placed in a field set that is now unused, are instead added to one of the used field sets, hiddenFieldContainerFS, which is set to the spectrum field set in this version.

3. Public constructor XTandemParameterSetFormSimple(XTandemParameterSet obj)

stores data for the hidden multiple-choice selection box for refine potential modification mass in hidden text fields coupled to the same valid parameter as the select box, since this method at present was more successful in transferring data between forms.

[olle]

(In [3904]) Refs #700. Refs #287. First version of support for simple search form for X!Tandem searches:

1. Class/file action/xTandemInput/ViewActiveXTandemParameterSetStorage.java

in client/servlet/ updated to support both a simple and an advanced X!Tandem search form:

1. New public static valid parameter VBoolean VXTANDEMPARAMETERSETSIMPLEFORMFLAG

added. It is used to store a flag indicating if a simple form is desired.

2. Public method void runMe() updated to retrieve the value of new valid

parameter VBoolean VXTANDEMPARAMETERSETSIMPLEFORMFLAG and set a flag variable useSimpleForm indicating if a simple form is desired. If the value of the valid parameter is null, the latter variable is set to true, as a simple form is the default. Since the value of the new valid parameter only is null the first time the action is entered for the form, the value is also used to set a boolean flag variable firstEntry. If a simple form is to be used, form class XTandemParameterSetFormSimple is used, otherwise class XTandemParameterSetForm. The first time the action is entered for a form X!Tandem data is read from the database, otherwise it is retrieved from data supplied with the form. In this case, one of two new methods named updateAdvancedFormMultipleChoiceFields(...) is called to update the multiple choice data in the current form. A new button is added to toggle the form type between simple and advanced. This button sets the value of valid parameter VXTANDEMPARAMETERSETSIMPLEFORMFLAG to force a change of form type when the action is re-entered.

3. New private method

XTandemParameterSetForm updateAdvancedFormMultipleChoiceFields(XTandemParameterSetForm form) added. It updates advanced form multiple choice fields.

4. New private method

XTandemParameterSetFormSimple updateAdvancedFormMultipleChoiceFields(XTandemParameterSetFormSimple form) added. It updates simple form multiple choice fields.

5. New private convenience method

List<String> fetchValidStringList(String quantityName, VString param) added. It fetches a string list from for a VString valid parameter from the HTTP request.

2. English dictionary file locale/en/dictionary in client/servlet/

updated with new entries for various string keys.

[olle]

Traceability note:

The functionality added 2010-10-20 to show/hide a field set might be used for a simpler design separating standard and advanced settings in a single form:

• Ticket #711 (Let the user show/hide fieldsets in a form).

[olle]

Design update:

In order to keep both the user interface and the code as simple as possible, it was decided to updated the design of the X!Tandem search form to a single form, with settings separated into open and closed field sets for standard and advanced settings, respectively. This was made possible by the functionality added in Ticket #711 (Let the user show/hide fieldsets in a form).

• All X!Tandem settings will be available in a single form.
• Standard settings will be placed in a new field set, that is open be default. These settings will be removed from their original field sets.
• Remaining advanced settings will be placed in their original field sets, that are closed by default.
• Since all new functionality will be available in a single form, class XTandemParameterSetFormSimple will be removed.
• Since there will be no need to shift between different actions to edit standard and advanced settings, the button to toggle between these will be removed.

[olle]

(In [3906]) Refs #700. Changes added to class ViewActiveXTandemParameterSetStorage and dictionary file in changeset ​[3904] in connection with first version of support for simple X!Tandem search form reverted, in preparation for new version of the routine using a single form:

1. Class/file action/xTandemInputViewActiveXTandemParameterSetStorage.java

in client/servlet/ restored to previous version, except for removal of unused imports.

2. English dictionary file locale/en/dictionary in client/servlet/ updated by removal of entries for first version of support for

simple X!Tandem search form.

[olle]

(In [3907]) Refs #700. New single-form version of routine for separating standard and advanced settings for X!Tandem searches:

1. Class/file gui/form/XTandemParameterSetForm.java in

client/servlet/ updated:

1. Public constructor XTandemParameterSetForm() update to place

fields and select boxes for standard settings in new field set, that is open by default. These settings will no longer be added to their original field sets, but will be kept in the original place in the source code. Remaining advanced settings will be placed in their original field sets, that are closed by default.

2. Class/file gui/form/XTandemParameterSetFormSimple.java in

client/servlet/ is removed, since it is no longer used.

3. English dictionary file locale/en/dictionary in client/servlet/

updated with new and changed entries for various string keys.

[olle]

The ticket is closed, as the desired functionality has been added. Should problems with the current solution appear, this ticket may be reopened, or a new ticket created.

[olle]

(In [4062]) Refs #700. Class/file gui/form/XTandemParameterSetForm.java in client/servlet/ updated:

1. Valid VSTRING parameters for modification masses updated to allow 150 instead of 32 characters. Size 150 was taken from the character limit valid parameter VString VXTANDEM_RESIDUE_POTENTIAL_MODIFICATION_MASS.