wiki:AccessingMSEntryFromAnnotationModule

Version 3 (modified by sena, 3 years ago) (diff)

--

This page describes the process of accessing the MS Entry and its associated files from a new annotation entry (similar to GELATO).

The following is a sample handler (see org.grits.toolbox.importer.ms.annotation.glycan.simiansearch.handler.OpenGelatoWizard) method and shows how to get the selected MS Entry (clicked on project explorer pane) from a handler (to create a new annotation entry):

public class OpenGelatoWizard {
	//log4J Logger
	private static final Logger logger = Logger.getLogger(OpenGelatoWizard.class);

	@Inject private static IGritsDataModelService gritsDataModelService = null;
	@Inject static IGritsUIService gritsUIService = null;
	@Inject MApplication application;
	
	@Execute
	public Object execute(@Named(IServiceConstants.ACTIVE_SELECTION) Object object,
			IEventBroker eventBroker, @Named (IServiceConstants.ACTIVE_SHELL) Shell shell, EPartService partService) {
		try {
			List<Entry> msEntries = getMSEntries(object);
                        .....
      }

        /**
	 * @param object - an Entry or a StructuredSelection item
	 * @return List<Entry> - List of MS Entries to annotation
	 */
	private List<Entry> getMSEntries(Object object)  {
		List<Entry> entries = new ArrayList<Entry>();
		
		StructuredSelection to = null;
		Entry selectedEntry = null;
		if(object instanceof Entry)
		{
			selectedEntry = (Entry) object;
		}
		else if (object instanceof StructuredSelection)
		{
			if(((StructuredSelection) object).getFirstElement() instanceof Entry)
			{
				to = (StructuredSelection) object;
			}
		}
		if (selectedEntry != null) {
			if(selectedEntry.getProperty().getType().equals(MassSpecProperty.TYPE)) {
				entries.add(selectedEntry);
			}
		}
		// try getting the last selection from the data model
		if(gritsDataModelService.getLastSelection() != null
				&& gritsDataModelService.getLastSelection().getFirstElement() instanceof Entry)
		{
			to = gritsDataModelService.getLastSelection();
		}

		
		if(to != null) {
			List<Entry> selList = to.toList();
			for(int i=0; i < selList.size(); i++) {		
				Entry msEntry = selList.get(i);
				//if the right property
				if(msEntry.getProperty().getType().equals(MassSpecProperty.TYPE)) {
					if (!entries.contains(msEntry))
						entries.add(msEntry);
				}
			}
		}

		return entries;
	}
}

getMSEntries method shown above is a typical method for trying to find the selected item. This method specifically looks for MS Entries not just any Entry. This is done with this line:

if(selectedEntry.getProperty().getType().equals(MassSpecProperty.TYPE))

If there are no selections then the wizard or dialog to be opened for creation of the new annotation entry should provide an option for browsing the current entries and make a selection there. A sample selection dialog (see org.grits.toolbox.importer.ms.annotation.glycan.simiansearch.wizard.MassSpecChooserDialog) is shown below:

        ProjectExplorerDialog dlg = new ProjectExplorerDialog(newShell);
        // Set an entry type as a filter
        dlg.addFilter(MassSpecProperty.TYPE);
	// Change the title bar text
	dlg.setTitle("Mass Spec Selection");
	// Customizable message displayed in the dialog
	dlg.setMessage("Choose an MS Experiment to add");
	// Calling open() will open and run the dialog.
	if (dlg.open() == Window.OK) {
		Entry entry = dlg.getEntry();
		if (entry != null) {
                ....
         }

This generic ProjectExplorerDialog can be used anywhere to allow users to select a specific type of Entry. It is generally linked to a "Browse" button to let the users choose an Entry.

Once the MS entry or MS entries to be annotated are selected as shown above, their annotation files can be read and used in an annotation module. Please check GritsEntryProperty before proceeding to understand the Entry and Property model used in GRITS. MS entry is an Entry object whose Property is of class MassSpecProperty and has type MassSpecProperty.TYPE. Each Property object can have a list of datafiles (List<PropertyDataFile> dataFiles). For MassSpecProperty, there is a single file which is the msMetadata.xml file. Here is a snippet from MassSpecProperty class (see org.grits.toolbox.entry.ms.property.MassSpecProperty):

public class MassSpecProperty extends Property {
	// 01/12/18:  CInternal Standard Quant was added to the MetaData. No changes to the property, but this affects the reader but was able to keep at ver 1.3
	public static final String CURRENT_VERSION = "1.3";
	private static final Logger logger = Logger.getLogger(MassSpecProperty.class);
	public static final String TYPE = "org.grits.toolbox.property.ms";
	protected static MassSpecPropertyWriter writer = new MassSpecPropertyWriter();
	private static final String folderName = "ms";

	protected static ImageDescriptor imageDescriptor = ImageRegistry.getImageDescriptor(Activator.PLUGIN_ID, ImageRegistry.MSImage.MASSSPEC_ICON);
	public static String CONVERT_RAW = "<to be generated by GRITS>";

	private MassSpecMetaData msSettings = null;
....
}

msMetadata.xml file mentioned above is the serialization of msSettings (MassSpecMetaData) field shown in the code snippet. The references to the annotation files/raw files/quantification files etc. are all stored in this MassSpecMetaData (extends MassSpecUISettings) object.

public abstract class MassSpecUISettings {
	...
	private List<MSPropertyDataFile> fileList;
        ...

For an annotation module, we are mostly interested in getting the annotation files from the MS Entry. This can be done as follows once you have access to the property object:

Property prop = msEntry.getProperty();
List<MSPropertyDataFile> files = ((MassSpecProperty) prop).getMassSpecMetaData().getAnnotationFiles();

After accessing all the annotation files (there might be multiple), the user can choose the one to be used for annotation.

Last step is to be able to read the annotation file (mzxml/mzml file). The following code snippet (see org.grits.toolbox.ms.annotation.gelato package and org.grits.toolbox.importer.ms.annotation.glycan.simiansearch.handler.NewGelatoHandler) shows how to obtain a reader for MzXML file and read the scans from the file:

MSPropertyDataFile dataFile = // the user's selection for the annotation file from the list obtained above 
String workspaceLocation = PropertyHandler.getVariable("workspace_location");
String projectName = DataModelSearch.findParentByType(msEntry, ProjectProperty.TYPE).getDisplayName();
String pathToFile = workspaceLocation + projectName + File.separator + MassSpecProperty.getFoldername();

MSFile msFile = dataFile.getMSFileWithReader(pathToFile, prop.getMassSpecMetaData().getMsExperimentType());
if (msFile.getReader() != null && msFile.getReader() instanceof IMSAnnotationFileReader) {  // it must be
       List<Scan> scans = ((IMSAnnotationFileReader) msFile.getReader()).readMSFile(msFile);
}

There are several other methods that might be usable in IMSAnnotationFileReader interface:

public interface IMSAnnotationFileReader extends IMSFileReader {
	/**
	 * @param file MS file to be read
	 * @return List of {@link org.grits.toolbox.ms.om.Scan} from the given MS file
	 */
	List<Scan> readMSFile (MSFile file);
	
	/**
	 * get a list of all MSn scans for the given parent scan
         *
	 * @param file MS file to be read
	 * @param scanNumber scan number to be read
	 * @return List of {@link org.grits.toolbox.ms.om.Scan} from the given MS file for the given scan number
	 */
	List<Scan> readMSFile (MSFile file, int scanNumber);
	
	/**
	 * readMSFile: general method to read an mzXML file for a specific parent scan and scan.
	 * 
	 * NOTE: will not currently read the entire contents of an MS file. You have to specify at least one of
	 * msLevel, parentScanNum, or scanNum
	 * 
	 * @param file  MS file to be read
	 * @param msLevel  the MS level of scans to load from MS file. Use -1 if to be ignored.
	 * @param parentScanNum  the scan number to be read, along with its sub-scans. Use -1 if to be ignored.
	 * @param scanNum  the scan number to be read, ignoring all other data.  Use -1 if to be ignored.
	 * @return List<Scan> a list of {@link org.grits.toolbox.ms.om.data.Scan} objects
	 * 
	 */
	List<Scan> readMSFile(MSFile file, int msLevel, int parentScanNum, int scanNum);
	
	/**
	 * 
	 * @param file MS file to be read
	 * @param scanNumber parent scan number
	 * @return List of scan numbers from the given MS file for the given parent scan number
	 */
	List<Integer> getScanList (MSFile file, int scanNumber);
	
	/**
	 * getMaxScanNumber: returns the last scan number of the MS file.
	 *  
	 * @param file MS file to be read
	 * @return value of last scan number
	 */
	Integer getMaxScanNumber (MSFile file);
	
	/**
	 * returns the lowest scan number
	 * @param file MS file to be read
	 * @return value of the first scan number
	 */
	Integer getMinScanNumber(MSFile file);
	
	/**
	 * return the minimum MS Level from the file
	 * 
	 * @param file MS file to be read
	 * @return minimum MS Level
	 */
	Integer getMinMSLevel(MSFile file);
	
	/**
	 * checks whether the file has MS1 scan
	 * 
	 * @param file MS file to be read
	 * @return true if there is MS1 scan, false otherwise
	 */
	boolean hasMS1Scan(MSFile file);
	
	...
}

For the object model, please check org.grits.toolbox.ms.om plugin and its documentation folder for UML diagrams.