Referencing an instrument

[maxgitt]

Hello,

I'm trying to understand where the OME Instrument element comes into play. I looked over the Schema documentation and noticed that an Instrument (ex. Microscope) element can be referenced by an Image element. As an example I uploaded a random jpeg to OMERO.insight. Then under the 'Metadata view > Acquisition tab' I was hoping to find a place to insert the metadata that describes the microscope. However, you can see below that all of these fields are left blank with no option to update them.

image-acquisition.png (20.04 KiB) Viewed 4533 times

Where exactly does one create an Instrument element, must the metadata already be included in a Tiff file or can I add Instruments to the OME Data Model that can be referenced later on?

[sbesson]

Hi Max,

I'm trying to understand where the OME Instrument element comes into play. I looked over the Schema documentation and noticed that an Instrument (ex. Microscope) element can be referenced by an Image element. As an example I uploaded a random jpeg to OMERO.insight. Then under the 'Metadata view > Acquisition tab' I was hoping to find a place to insert the metadata that describes the microscope. However, you can see below that all of these fields are left blank with no option to update them.

The OMERO.web and OMERO.insight do not show all data from the OME Data Model and allow editing even less of it.

Where exactly does one create an Instrument element, must the metadata already be included in a Tiff file

Indeed, XML elements related to the image acquisition may be included in the OME-TIFF - see this dataset for an example of 5D image with some acquisition metadata specified in the OME-XML header. At import time they should be imported into OMERO and much of that information is displayed in OMERO.web's metadata pane. Other image formats, such as SVS and Zeiss LSM, or MIAS plates, may also create Instrument instances upon import - see https://docs.openmicroscopy.org/bio-for ... mmary.html for a detailed listing of all metadata fields populated per file format reader.

can I add Instruments to the OME Data Model that can be referenced later on?

Our training examples at https://github.com/openmicroscopy/openm ... /Training/ include various uses of OMERO.blitz's update service to adjust model objects on the server. This offers client-side scripts much freedom in allowing creation and editing of imported images' instruments. More developer-oriented reading on the topic is available at https://docs.openmicroscopy.org/latest/ ... data-model. Instruments may exist independently from images and be shared among images.

Note that OME-TIFF export from OMERO does not yet include much of the acquisition-related metadata that exists on the server.

Best,
Sebastien

[maxgitt]

Hi Sebastian,

I'm not quite sure I understand where the "Training" examples come into play. There is no readme, so it just seems to be a bunch of files in different languages that I can't really make sense of. I have also read through countless documents from the developer's page https://docs.openmicroscopy.org/omero/5.4.0/developers/index.html hoping I would find some tutorial on how to create an XML file that could be imported and displayed by the system. Instead I've become confused as to how changes should be made because of the many dependencies that exist between the XSD files, OMERO database, Data Model, tiff files, web client, and server. I looked at places for examples including http://downloads.openmicroscopy.org/images/OME-XML/2016-06/ but here lie lists of XML files that I again can't make sense of.

I would like to accomplish only one goal. To create a "Hello World" example where a simple XML file that, contains the Manufacturer's metadata (e.g. "SBesson, Inc") and a jpg, is accepted by the OME Data Model. The XML data should be displayed on OMERO-web and stored in the postgres database. Can this simple task be completed?

[mtbc]

Dear Max,

I am not aware of a format that carries XML metadata but JPEG-encoded image data. Could it work to import OME-XML with associated TIFF image data, in accordance with the OME-TIFF format, or to first import the JPEG image then through a client script attach the instrument? If the latter, should the instrument start out defined in XML? The OME-XML Data Model provides a means of defining instruments as part of image import but also the Update Service offered by OMERO.blitz instead allows programmatic manipulation of instruments as data objects like https://docs.openmicroscopy.org/latest/ ... instrument and the training examples include some examples of manipulating objects from that webpage via the API.

Either way, the data should end up displayable and persisted as desired; there are a couple of ways to get there.

Cheers,
Mark

[wmoore]

Hi Max,

A couple more questions and pointers...

As Mark said, you can't simply use an XML file alongside your jpeg to add metadata for import to OMERO. You'd need to create an OME-TIFF file. Either the OME-TIFF file contains ALL the metadata in the header
e.g. http://downloads.openmicroscopy.org/ima ... rtificial/)
or the OME-TIFF contains minimal metadata in the header that references a companion XML file (see http://downloads.openmicroscopy.org/ima ... companion/).

What language are you working with? The samples in the first link above were generated with this Java code
https://github.com/openmicroscopy/biofo ... eTiff.java
and you can do much the same in C++ using OME-Files.

An example of how you'd add Instrument metadata to OME-XML can be found at
e.g. http://downloads.openmicroscopy.org/ima ... nt.ome.xml

The other alternative is to add the metadata into OMERO after importing your JPEG. Would this be an option for you? We could provide examples of how to do this in Python or Java (or Matlab). It would be pretty easy for Instrument alone, but would be more complex for the extended metadata in the instrument.ome.xml above. Do you plan to work with more metadata in future or will Instrument alone be sufficient for a while?

Regards,

Will.

[maxgitt]

Hi Will,

Your final alternative works best with me.

The other alternative is to add the metadata into OMERO after importing your JPEG

Here is the use case:

1) A researcher named Alice at Arvard University takes a JPEG of a cell line and uploads her image through OMERO.web (I have found out that OMERO.web does not have this functionality which is upsetting but I suppose the researcher can upload through OMERO.insight and then open OMERO.web).

2A) Next she would like to include metadata about the image, maybe the instrument used, and the magnification, and possibly categorize it under a specific experiment named Experiment 42.

2B) And if the instrument already exists in the database, she can select it from a drop down menu. (Currently none of this seems possible, as all of this data is embedded in a TIFF and hard coded. Is there an Instrument Table in Postgres that stores unique instrument manufacturers that can be retrieved by OMERO.web at runtime?)

3) Next, Alice would like to share her findings with a researcher named Bob at Boston University. Unfortunately they cannot share a central database so she must export the image or experiment into an XML standard and send the file to Bob.

4) Bob receives the file in an email and uploads directly to his own running OMERO.web where he can view and annotate the experiment and associated images.

Is this doable? I find that defining user stories in an Agile format makes life easier for developers. Let me know if you have any questions.

Thanks ahead of time,
Max

[wmoore]

Hi Max,

You didn't say what language you'd want to access the OMERO API, (Python or Java?) but here's an example of using the Python API to add some Instrument and Objective metadata to an image in OMERO:

https://gist.github.com/will-moore/b9ba ... b1d1b47858

Here we are creating new Microscope and Objective objects instead of looking-up existing objects.
In general this approach is easiest and it's what happens when you import an Image with existing metadata.

You could make an OMERO.script based on this Python code to allow users to add this kind of metadata to images using the OMERO.insight or OMERO.web clients.

You can place an Image in a Project -> Dataset -> Image hierarchy and add description or other annotations to those containers to describe the Experiment.

Unfortunately, image export doesn't yet fully support experimental metadata so this won't be preserved when exporting to OME-TIFF.
The nicest workflow for sharing data in OMERO with colleagues at other locations is to create an account for them on your own OMERO server, allowing them to access and annotate your images without having to e-mail files.

Hope that helps,

Will.

[maxgitt]

Hi Will,

Thank you for the reply. I'll take a look at the Python API to try and build out my use case.

Best,
Max

[maxgitt]

Hi Will,

So one question I have is where I can import your code for a working OMERO.web app. I would like to edit the OMERO.web app from the OMERO.web Docker image found here (https://github.com/openmicroscopy/omero-web-docker) but I can't seem to find the directory where the Django apps live.

I looked through this doc (https://docs.openmicroscopy.org/omero/5 ... roWeb.html) telling me I should edit the source code but wasn't told where that is exactly. I entered the Docker container but don't see any remnants of Django apps.

edit-omero-web.png (11.96 KiB) Viewed 4400 times

I also opened the main OME repo https://github.com/openmicroscopy/openmicroscopy but couldn't find the OMERO-web apps either. Any hint as to where I can make use of your python script? What I'd like to do is allow the user to edit the acquisition pane via the OMERO.web frontend and then use BlitzGateway to submit that metadata to the OMERO.server.

[jmoore]

A quick late-response, Max: the apps are installed as Python modules and will be picked up based on the name that is registered. See:

https://github.com/openmicroscopy/openmicroscopy/blob/develop/components/tools/OmeroWeb/omeroweb/settings.py#L1086

So you'll need to look on the effective PYTHONPATH, which includes lib/python from the OMERO installation. For a core plugin that means:

Code: Select all

$ docker run -ti --rm --entrypoint=ls openmicroscopy/omero-web:5.4 /opt/omero/web/OMERO.web/lib/python/omeroweb


And for one that has been pip installed:

Code: Select all

$ docker run -ti --rm --entrypoint=ls openmicroscopy/omero-web:5.4 /opt/omero/web/venv/lib/python2.7/site-packages


Night.
~Josh