Files for hits import registration from biomaterial annotations

[Fredrik Levander]

There should be an alternate first step of the non-gel hits import where the local sample id is taken from the sample/extract name of the associated biomaterial for the file.

Presumably there could be a check box in the first step of the hits report which when checked means that the local sample id for each PeakListToHits job is taken from the biomaterial that the file is associated with. If no biomaterial is associated to any of the selected files, an error message should appear.

[olle]

Wiki escape characters added.

[olle]

Ticket accepted.

[olle]

Traceability note:

• Import of non gel-based data to the hits report was introduced in Ticket #392 (import of non-gel search results to hits report).

[olle]

Design discussion.

Background:

• A File item can have a set of BioMaterial items (which includes Sample and Extract items) associated with it, as well as a number of Annotation items. The BioMaterial items can be obtained from a File item through its public method Set<BioMaterial> getBioMaterials(). Annotations can be obtained from a File file item through use of an Annotator annotator instance with annotator.getAnnotationSet(file).getAnnotations(), that returns an ItemQuery<Annotation> object, that can be used to get the annotations, if any.

Design of the new functionality:

• If a single BioMaterial item is associated with a file item, the name of the BioMaterial item is used as local sample id. If no name of the BioMaterial item exists, the external id string of the BioMaterial item is used.
• If several BioMaterial items are associated with a file item, the local sample id is obtained as follows:
  1. For each BioMaterial item, a candidate string is obtained from the name of the item, or, if no name exists, the external id string (same procedure as for a single BioMaterial item).
  2. The local sample id is obtained by concatenating the candidate strings, separated with a comma. Since the set of BioMaterial items do not have a predefined order, the candidate strings will be applied in alphabetical order, to avoid any ambiguity.
• If the file item has an annotation with name "fraction" (technically, it is the name of the annotation type associated with the annotation), the value of the annotation is used as fraction id. Otherwise, the fraction id is obtained by using a supplied regular expression on the filename, provided that this option has been selected (current functionality).

[olle]

Design update:

• Current GUI for non gel-based hits import contains two steps for registering peaklist files:
  
  a. Selection of local sample id and optional regular expression for obtaining fraction id.
  b. Selection of peaklist file[s].
  
  To support obtaining local sample id from bio material associated with the peaklist file, a new initial step should be introduced, where the local sample id input method is selected. The new second step should be based on the first step in the original design, but renamed "Additional parameters", and adapted to the setting selected in the first step:
  
  a. Selection of local sample id input method.
  b. Selection of additional parameters. Settings for fraction id are always included (same options as previously), while input fields for local sample id are only shown if explicit entry of this parameter has been selected in step a.
  c. Selection of peaklist file[s].
  
  This design also makes it easier to introduce new alternative ways of selecting local sample id in the future.
• The GUI for the second step should include a new initial field set, where the local sample id input method selected in the first step is reported. This will help the user understand that the settings available here are depending on this initial choice.
• In non gel-based hits import, the first two steps in the GUI for registering peaklist files should be extended with explanatory info boxes, with instructions/descriptions for the available options.
• The classes managing the original registering of peaklist files in non gel-based hits import are (excluding used form classes): ImportHitsNonGelWizard, ImportHitsNonGelWizardStep1a, ImportHitsNonGelWizardStep1b, and PeakListToHitNonGelPlugin. Class ImportHitsNonGelWizard controls the GUI for the full wizard, where step 1 is registering of peaklist files, and step 2 is import of protein identification results. Class ImportHitsNonGelWizardStep1a transfers selected settings and displays a page for selecting peaklist files, after which class ImportHitsNonGelWizardStep1b creates one job for each peaklist file, where each job is controlled by class PeakListToHitNonGelPlugin. The names of classes ImportHitsNonGelWizardStep1a and ImportHitsNonGelWizardStep1b can lead to confusion when an extra initial step for selecting local sample id input method is introduced, but they will not be changed in the first implementation of this update. A new class ImportHitsNonGelWizardStep1AdditionalParameters will be added to manage the GUI for the new initial step, in addition to needed form classes.
• Although all information for obtaining the local sample id is available before the job is created, in the original design the optional fraction id is obtained by class PeakListToHitNonGelPlugin, when the job is executed. If not explicitly entered, the local sample id will therefore also be obtained during job execution in the first implementation of this update.

[olle]

(In [4122]) Refs #740. Refs #392. Refs #287. Non gel-based hits import updated with support for obtaining local sample id from BioMaterial associated with peaklist file:

1. Class/file action/hit/ImportHitsNonGelWizard.java in client/servlet/ updated:
   a. New text info box added.
   b. Form obtained from new class ImportHitsNonGelWizardStep1EntryModeForm.
   c. Link for "Next" button changed to action link to new class ImportHitsNonGelWizardStep1AdditionalParameters.

2. New class/file gui/form/ImportHitsNonGelWizardStep1EntryModeForm.java in client/servlet/ added. It calls new class LocalSampleIdEntryModeMenu to display a menu to select local sample id input method from.

3. New class/file gui/form/LocalSampleIdEntryModeMenu.java in client/servlet/ added. It creates a menu for selecting local sample id input method. The value is stored in new valid parameter VSTRING LocalSampleIdEntryModeMenu.VPARAM. Default is "Enter explicitly", as previously used.

4. New class/file action/hit/ImportHitsNonGelWizardStep1AdditionalParameters.java in client/servlet/ added. It displays a text info box with text and displays options for selecting additional parameters, adapted to previously made choices. Link for "Next" button is coupled to action link to class ImportHitsNonGelWizardStep1a.

5. Class/file gui/form/ImportHitsNonGelWizardStep1Form.java in client/servlet/ updated:
   a. New constructor which takes extra argument String localSampleIdEntryMode added.
   b. It displays an initial field set that reports the selected setting for local sample id input.
   c. Input fields for local sample id are only shown if explicit entry of this parameter has been selected.

6. Class/file action/hit/ImportHitsNonGelWizardStep1a.java in client/servlet/ updated:
   a. It obtains value of valid parameter VSTRING LocalSampleIdEntryModeMenu.VPARAM and saves it as a session parameter.
   b. It only checks and transfers a local sample id value if the latter has been chosen to be explicitly entered.

7. Class/file action/hit/ImportHitsNonGelWizardStep1b.java in client/servlet/ updated to transfer value of valid parameter VSTRING LocalSampleIdEntryModeMenu.VPARAM to created job as job parameter.

8. Class/file plugins/PeakListToHitNonGelPlugin.java in plugin/ updated:
   a. Value of local sample id entry mode obtained from new job parameter.
   b. Local sample id is obtained from bio material associated with the peaklist file, if this option has been selected. In this case, an attempt is made to obtain fraction id from an annotation for the peaklist file, with annotation type name "fraction". If this attempt fails, an attempt is made to obtain fraction id from the peaklist filename through use of a regular expression pattern, if this option has been chosen.

9. English dictionary file locale/en/dictionary in client/servlet/ updated with new entries for various string keys.

[olle]

(In [4123]) Refs #740. Refs #290. Non gel-based hits import updated with icon assignment för "Next" button and exchange of option text "Enter explicitly" for "Select existing or enter new", in order to avoid misunderstanding that an existing local sample id cannot be selected from a list:

1. Default icon settings file "default" in icons/ in client/servlet/ updated with icon assignment for "Next" button.

2. Class/file action/hit/ImportHitsNonGelWizard.java in client/servlet/ updated in info box text by exchange of text "Enter explicitly" for "Select existing or enter new",

3. Class/file gui/form/ImportHitsNonGelWizardStep1.java in client/servlet/ updated by exchange of option text "Enter explicitly" for "Select existing or enter new".

4. Class/file gui/form/LocalSampleIdEntryModeMenu.java in client/servlet/ updated by exchange of option text "Enter explicitly" for "Select existing or enter new".

[olle]

Design update:

• The same options for obtaining optional fraction id value should be available whatever method was used to obtain the local sample id. However, the default option may differ depending on the latter. The current checkbox for obtaining fraction id from a regex pattern used on the peaklist filename should be replaced by a menu with the following options:

Option name	Way to obtain fracion id
Annotation / File name	From annotation if possible, otherwise name of peaklist file
Annotation	From annotation of peaklist file
File name / Annotation	From filename if possible, otherwise annotation of peaklist file
File name	From name of peaklist file
No fraction ID	No fraction ID used

• Default option for obtaining fraction id should be as follows:

Way to obtain local sample id	Default option for obtaining fraction id
Existing or new local sample id selected	No fraction ID
From associated biomaterial for peaklist file	Annotation / File name

[olle]

(In [4126]) Refs #740. Refs #392. Refs #287. Non gel-based hits import updated to make options for obtaining optional fraction id independent of the way local sample id is obtained:

1. Class/file action/hit/ImportHitsNonGelWizardStep1AdditionalParameters.java in client/servlet/ updated in info box text.

2. Class/file gui/form/ImportHitsNonGelWizardStep1Form.java in client/servlet/ updated to display a pop-up menu for selecting method to obtain fraction id instead of a checkbox for obtaining fraction id using a regex pattern on the peaklist filename (this is now one of the available options). The pop-up menu is obtained from new class FractionIdEntryModeMenu.

3. Class/file gui/form/client/servlet/src/org/proteios/gui/form/FractionIdEntryModeMenu.java in client/servlet/ added. It creates a pop-up menu for selecting method to obtain fraction id.

4. Class/file action/hit/ImportHitsNonGelWizardStep1a.java in client/servlet/ updated to obtain value of new valid parameter VSTRING FractionIdEntryModeMenu.VPARAM from request and save it to session.

5. Class/file action/hit/ImportHitsNonGelWizardStep1b.java in client/servlet/ updated to obtain value of new valid parameter VSTRING FractionIdEntryModeMenu.VPARAM from session and transfer it to created job as job parameter.

6. Class/file plugins/PeakListToHitNonGelPlugin.java in plugin/ updated:
   a. Value of string defining method to obtain fraction id value obtained from job parameter and used to decide how the fraction id is obtained.
   b. New private convenience method String fetchFractionIdFromFileAnnotation(DbControl dc, File file) added. It attempts to obtain fraction id from file annotation "fraction".

7. English dictionary file locale/en/dictionary in client/servlet/ updated with new entries for various string keys.

[olle]

Design update:

• An error message should be displayed if no peaklist files are selected.

[olle]

(In [4154]) Refs #740. Refs #392. Non gel-based hits import updated to display an error message if no peaklist files are selected:

1. Class/file action/hit/ImportHitsNonGelWizardStep1b.java in client/servlet/ updated in protected method void runMe() to display an error message if no peaklist files are selected.

[olle]

Design update:

• Non gel-based hits import where local sample id is obtained from BioMaterial associated with the peaklist file should be updated to display an error message if no selected peaklist file had BioMaterial associated with it.
• Non gel-based hits import where local sample id is obtained from BioMaterial associated with the peaklist file should be updated to only create import jobs for peaklist files that do have BioMaterial associated with them, and in the job creation message report the names of peaklist files, for which jobs were not created.

[olle]

(In [4155]) Refs #740. Refs #392. Class/file action/hit/ImportHitsNonGelWizardStep1b.java in client/servlet/ updated for non gel-based hits import where local sample id is obtained from BioMaterial associated with the peaklist file to only create import jobs for peaklist files that do have BioMaterial associated with them, and in the job creation message report the names of peaklist files, for which jobs were not created:

1. Protected method void runMe() updated:
   a. Job creation is extracted into a separate private method Job createJob(...).
   b. When local sample id should be obtained from BioMaterial associated with the peaklist file, import jobs are only created for peaklist files that do have BioMaterial associated with them. The job creation message now reports the names of peaklist files, for which jobs were not created.
   c. When local sample id should be obtained from BioMaterial associated with the peaklist file, and no selected peaklist file had BioMaterial associated with it, an error message is displayed.

2. New private method Job createJob(ItemFactory factory, PluginDefinition plugin, File file, String localSampleIdEntryMode, String fractionIdEntryMode, String localSampleId, Project project, String regexPattern) added. It creates a non gel-based import job.

[olle]

Test of new functionality:

• Setup: No peaklist files were selected.
  Result: An error message "Please select at least one peaklist file" was displayed.
• Setup: When local sample id should be obtained from BioMaterial associated with the peaklist file, two peaklist files were selected, that did not have any associated BioMaterial.
  Result: An error message "No jobs created as no peaklist file had associated BioMaterial" was displayed.
• Setup: When local sample id should be obtained from BioMaterial associated with the peaklist file, two peaklist files were selected, that did have associated BioMaterial.
  Result: Import jobs were created for the two peaklist files that had associated BioMaterial, and the job creation message simply reported "Job created - Wait for jobs to finish before next step".
• Setup: When local sample id should be obtained from BioMaterial associated with the peaklist file, three peaklist files were selected, where only two had associated BioMaterial.
  Result: Import jobs were created for the two peaklist files that had associated BioMaterial, and the job creation message reported the name of the peaklist file for which no job was created, and the reason for this.
• Setup: When local sample id should be obtained from BioMaterial associated with the peaklist file, four peaklist files were selected, where only two had associated BioMaterial.
  Result: Import jobs were created for the two peaklist files that had associated BioMaterial, and the job creation message reported the names of the peaklist files for which no jobs were created, and the reason for this.

In all cases the result was the intended one, so the tests passed with successful result.

[olle]

Ticket closed as the requested functionality has been added.