beginners and baby-beginners

[DavidEpstein]

I sent an email to Jason Swedlow and he suggested that I register and
contribute to one of the forums (but he didn't suggest which forum). In view of the moans below, I should start by saying that I welcome OME, and think that it has great potential. Also I appreciate the effort that many people are putting in, unpaid and unthanked, to make OME a success.

First some context. I'm a pure mathematician by training. Since my
retirement I've been working with a group of biologists interested in
diabetes and cancer. Our group also works with experts in image
processing and image analysis. I'm reasonably computer literate, several
orders of magnitude more so than my biological colleagues, but
probably less so than most of the readers of this forum.

The robotically controlled microscope that we often work will
typically in a single run produce hundreds of PNG images, each roughly
1000x1000 pixels, all of the same tissue section, in a single run.
These files are then processed in various ways to produce images or
other information that convey significant biological properties.

I have been considering the problem of first providing metadata
files that provide information about the circumstances under which
the raw files were produced, and, subsequently, "history" files
associated with the results of image analysis. My contention is
that it should be possible to reconstruct a file, using only the
raw data files plus the history file.

For a long time I have wondered what on earth XML is. I now know, but
only vaguely. I have programmed in HTML, but I doubt whether any of my
biologist colleagues know what html is, apart from recognizing it as
something that occurs for some reason in web addresses. When I
came across OME-XML, it seemed likely that it would be an appropriate
vehicle for writing my history files.

So I put OME-XML into Google---result: much frustration. Here are
some of the problems I have come up with. It's hard for those thoroughly
familiar with all the jargon to understand what it's like for those
who find themselves in a sea of incomprehension.

1. openmicroscopy.org does not have a forum with a name that invites
beginners. I believe that some thought needs to be given to helping
beginners like me. If you want OME to catch on with the biology
community in general, you might need to think much further---about helping
baby-beginners. I would guess that 99% of biologists have never heard
of OME.
2. I don't know what is meant by the Bio-Formats library, nor by the
OME Data Model, and I only have the vaguest idea of what OMERO is. I'm
interested in XML, so which forum should I use?
3. What is OME-XML? There is plenty of reference to it on the OME
web pages. But where are the examples---there should be lots of
them? If there are rules or conventions already established, I
shouldn't be using different conventions when writing my history
files.
4. Where is the XML reader for the XML example files that I can't
find? People say "It's trivial to write an XML reader. That's why XML
was invented." I could be more easily convinced of this if I saw some
examples of OME-XML and how the authors envisaged this as being
printed out, for example on one of openmicroscopy.org's webpages. You
don't need to provide a reader for every platform imaginable. I would
be quite happy to compare XML-source with output from an XML-reader by
viewing the material in my favourite web browser.
5. Less important than the examples, but where is the formal
definition of OME-XML? Why is everything so hard to find?
6. I Googled OME-XML and went to the first hit http://www.ome-xml.org/.
I wanted to find a specification for OME-XML, so I went to Latest
OME-XML/OME-TIFF on that page. Only one thing to click, namely
"schema location". I don't have any idea of what a "schema" is. I
know several different meanings for "location" in this context.
But, I've no choice, so I click on it. Frustratingly, although
http://www.openmicroscopy.org/Schemas/ is a web page about schemas,
it gives no idea at all as to what a schema is. How about a reference
to Wikipedia (found an hour after my first draft of this email to the
forum)?
7. Maybe someone on this list would explain to me what a schema is
supposed to do. In particular I clicked on [BinaryFile.xsd] and found
the following incomprehensible stuff.
> <xsd:schema
> targetNamespace="http://www.openmicroscopy.org/Schemas/BinaryFile/2010-06"
> version="1" elementFormDefault="qualified">
> <xsd:import namespace="http://www.w3.org/XML/1998/namespace"
> schemaLocation="http://www.w3.org/2001/xml.xsd"/>
> <xsd:import
> namespace="http://www.openmicroscopy.org/Schemas/OME/2010-06"
> schemaLocation="http://www.openmicroscopy.org/Schemas/OME/2010-06/ome.xsd"/>
> −
> <xsd:annotation>
> −
> <xsd:documentation>
>
> The elements in this file are not yet
> represented by classes in the EA diagrams - ajp

At least if an xsd-reader had been provided, I wouldn't have had to
battle with the XML syntax, though I don't suppose I would have found
the document any more comprehensible than I now do.

That's more than enough from me. All I want to do is to write my
history files in XML. I do have my doubts as to
whether this OME approach will catch on. People are too busy with
their scientific concerns to go on the seemingly infinite regress of
finding out what things mean and how to actually use the tools.

I really do want help, and I would prefer not to wait until all my
moans have been dealt with. Even to get to this stage has taken several
hours of my time, time I can't really afford.

Thanks in anticipation

David

[cxallan]

Firstly thanks for your feedback David. Fundamentally much of your frustration comes from the perception that The OME Project's OME-XML resources are intended to be useful to "beginners and baby beginners". This is certainly not the target audience of the current documentation and the overarching efforts do not revolve around helping scientists use OME-XML, understand a schema or produce XML documents. Perhaps they should, but quite simply as they stand now they do not.

This isn't because of a lack of perspective, but more a reflection of the target audience of ALL the OME Project's initiatives. We have end user focused initiatives but they mostly revolve around data management, visualization and analysis. Very few of our end users are interested in file format design, acquisition data recording, or storage of raw metadata. The majority purchase commercial instruments which produce data files in proprietary formats and we build software that reads those files (Bio-Formats), rationalizes that data to common language (OME Data Model) and either imports that data into a data management system (OMERO) or converts it to a standardized file format (OME-XML and/or OME-TIFF). End users then get on with the business of doing great science.

All that said, we recognize that the software development inertia required to achieve something like it sounds like you want to achieve is currently far too high. At a minimum it requires an understanding of XML and XML Schema and an understanding of XML library use in your programming language of choice. For even some of our most dedicated commercial partners this is too high a bar.

With that in mind I'm going to respond point by point to your questions and comments with the locations to the resources I think best address the concerns with the hope that even if it's not useful to you it will be useful to someone else.

1. openmicroscopy.org does not have a forum with a name that invites
beginners. I believe that some thought needs to be given to helping
beginners like me. If you want OME to catch on with the biology
community in general, you might need to think much further---about helping
baby-beginners. I would guess that 99% of biologists have never heard
of OME.

An end user community is certainly not something we have a great place for at the moment and to date we haven't had great success in encouraging biologists to participate in any of our online communities. Regularly they are "far too busy with their scientific concerns" as you have already stated or they're intimidated by the technical nature of a lot of our resources.

Probably the best example of beginner documentation and resource we have are the OME feature pages:

http://www.openmicroscopy.org/site/prod ... ature-list

2. I don't know what is meant by the Bio-Formats library, nor by the
OME Data Model, and I only have the vaguest idea of what OMERO is. I'm
interested in XML, so which forum should I use?

The most applicable is the OME Data Model forum as it is an overarching moniker for all the file format resources and their usage which include, but are not limited to, OME-XML. If you are interested in OME-XML you are by association interested in the OME Data Model. We get OME-XML, OME-TIFF and OME Data Model questions regularly on all the forums and both mailing lists however.

3. What is OME-XML? There is plenty of reference to it on the OME
web pages. But where are the examples---there should be lots of
them? If there are rules or conventions already established, I
shouldn't be using different conventions when writing my history
files.

I suppose one thing that would be obvious to a regular XML developer that isn't particularly obvious to a beginner is that the XML Schema definitions are the conventions. They completely and in a validatable form express all the possible forms of OME-XML. This doesn't marginalize the usefulness of examples however and we have them enumerated in two places:

* The OME website (http://www.openmicroscopy.org/site/supp ... -downloads)
* The OME-XML website (http://www.ome-xml.org/wiki/OmeTiffData)

One of the rationales for the OME-TIFF linkage is that one of the founding principals of OME-XML and OME-TIFF is to, wherever possible, ensure data and metadata continuity in the same file. OME-XML and OME-TIFF aren't just meant to be left on the side, they are designed to handle data and metadata. This is one of the reasons you almost never see people writing OME-XML on its lonesome and why it makes sense to pair it with TIFF.

4. Where is the XML reader for the XML example files that I can't
find? People say "It's trivial to write an XML reader. That's why XML
was invented." I could be more easily convinced of this if I saw some
examples of OME-XML and how the authors envisaged this as being
printed out, for example on one of openmicroscopy.org's webpages. You
don't need to provide a reader for every platform imaginable. I would
be quite happy to compare XML-source with output from an XML-reader by
viewing the material in my favourite web browser.

See above. We also have recently been focused on providing tutorial documentation for use of the main OME-XML and OME-TIFF reference library which is written in Java. You can see the beginnings of this documentation here:

http://dev.loci.wisc.edu/svn/software/t ... oc/export/

5. Less important than the examples, but where is the formal
definition of OME-XML? Why is everything so hard to find?

Those are, as I've alluded to above, the schema files. They are the formal definitions for everything that is possible and expected in OME-XML. In addition we have what we consider the minimal amount of useful information specification which is outlined here:

http://www.ome-xml.org/wiki/MinimumSpecification

6. I Googled OME-XML and went to the first hit http://www.ome-xml.org/.
I wanted to find a specification for OME-XML, so I went to Latest
OME-XML/OME-TIFF on that page. Only one thing to click, namely
"schema location". I don't have any idea of what a "schema" is. I
know several different meanings for "location" in this context.
But, I've no choice, so I click on it. Frustratingly, although
http://www.openmicroscopy.org/Schemas/ is a web page about schemas,
it gives no idea at all as to what a schema is. How about a reference
to Wikipedia (found an hour after my first draft of this email to the
forum)?

While I disagree that a Wikipedia link to the definition of XML Schema is necessarily going to help a beginner who lands on that page understand, even remotely, XML and XML Schema and how they relate to OME-XML we certainly need to have better entry points for them. Fundamentally we have to do a better job of introducing beginners to the resources available before those pages will make even a modicam of sense.

7. Maybe someone on this list would explain to me what a schema is
supposed to do. In particular I clicked on [BinaryFile.xsd] and found
the following incomprehensible stuff.
> <xsd:schema
> targetNamespace="http://www.openmicroscopy.org/Schemas/BinaryFile/2010-06"
> version="1" elementFormDefault="qualified">
> <xsd:import namespace="http://www.w3.org/XML/1998/namespace"
> schemaLocation="http://www.w3.org/2001/xml.xsd"/>
> <xsd:import
> namespace="http://www.openmicroscopy.org/Schemas/OME/2010-06"
> schemaLocation="http://www.openmicroscopy.org/Schemas/OME/2010-06/ome.xsd"/>
> −
> <xsd:annotation>
> −
> <xsd:documentation>
>
> The elements in this file are not yet
> represented by classes in the EA diagrams - ajp

At least if an xsd-reader had been provided, I wouldn't have had to
battle with the XML syntax, though I don't suppose I would have found
the document any more comprehensible than I now do.

No doubt. The resources are certainly daunting to someone who isn't familiar with XML and XML Schema.

I suppose one way we can help is if you were a little more descriptive about what it is you want to achieve and how. You've been up, down, back and forward through out resources so you kind of know what we're about and you've said "all I want to do is to write my history files in XML." Frankly that language doesn't tell us a lot about how technically you want to achieve a solution to the problem of recording acquisition metadata. So in order to help us help you we're going to need to know what kinds of metadata you'd like to store, how you're likely to get access to it, what programming language you plan to use to create the OME-XML and/or OME-TIFF files and any other technical constraints you can think of. The devil with this stuff is definitely in the details.

Just a final note on saving time. We are about as open as humanly possible and try to be as friendly as possible. No question is too small and we don't consider any user too much of a beginner to prevent us from at least trying to guide him or her in the right direction. Ask early and often and you can probably avoid repeating frustrating times searching our resources for the exact answers to very complicated questions in a beginner context.

[DavidEpstein]

Dear cxallan
I appreciate your thoughtful reply and the offer of help.

All that said, we recognize that the software development inertia required to achieve something like it sounds like you want to achieve is currently far too high. At a minimum it requires an understanding of XML and XML Schema and an understanding of XML library use in your programming language of choice. For even some of our most dedicated commercial partners this is too high a bar.

Since my first post, I have been going through the tutorials at http://www.w3schools.com/, and things have become much clearer. I'm still on CSS, but will shortly be moving onto schemas. In my opinion, several of your web pages should have a link to this excellent collection. Such a link would have saved me a lot of time and frustration.

An end user community is certainly not something we have a great place for at the moment and to date we haven't had great success in encouraging biologists to participate in any of our online communities. Regularly they are "far too busy with their scientific concerns" as you have already stated or they're intimidated by the technical nature of a lot of our resources.

I don't know ImageJ and its web pages, but I have noticed that biologists are very easily attracted into using it. Are there some lessons for OME developers to learn from ImageJ? I say this from a position of ignorance, as I know nothing about ImageJ.

Probably the best example of beginner documentation and resource we have are the OME feature pages:
http://www.openmicroscopy.org/site/prod ... ature-list

If I start using the OMERO editor (quite likely), I will try to find time to write for you a description of the editor so that biologists will understand enough to be able to use it. Your feature list does not contain any such document. Jason sent me links to two movies about the OMERO editor which were very helpful in enabling me to see what it is capable of. It's pure chance that I had this personal contact.

I suppose one way we can help is if you were a little more descriptive about what it is you want to achieve and how. You've been up, down, back and forward through out resources so you kind of know what we're about and you've said "all I want to do is to write my history files in XML." Frankly that language doesn't tell us a lot about how technically you want to achieve a solution to the problem of recording acquisition metadata. So in order to help us help you we're going to need to know what kinds of metadata you'd like to store, how you're likely to get access to it, what programming language you plan to use to create the OME-XML and/or OME-TIFF files and any other technical constraints you can think of. The devil with this stuff is definitely in the details.

Just a final note on saving time. We are about as open as humanly possible and try to be as friendly as possible. No question is too small and we don't consider any user too much of a beginner to prevent us from at least trying to guide him or her in the right direction. Ask early and often and you can probably avoid repeating frustrating times searching our resources for the exact answers to very complicated questions in a beginner context.

That's a very generous offer, which I hope you won't live to regret.
1. We are working with pre-commercialized prototype equipment. Acquisition of metadata is a problem that did not occur to the supplier of our robotically controlled microscope. Our machine gives no read-out of the settings, let alone an XML read-out, and, at least for the moment, all acquisition data needs to be manually typed in. Therefore we need a method of typing the settings into a computer document, preferably with XML output, so that it can be easily dealt with by collaborators at other sites.
2. We would expect a large number of runs for each biological situation we study. The runs might all have very much the same metadata. To avoid unnecessary time-consuming and error-prone typing, one wants to be able to recall a previous metadata sheet, and change it in only a few places. Preferably some items in the recalled form (for example, the date of the experiment) would be blank at the recall.
3. One needs to be able to go back and forth when editing the metadata sheet, in order to be able to correct errors and easily change one's mind.
4. We need to be able to define our own variables (eg which antibody, which antibody manufacturer, manufacturer's batch number, antibody concentration, incubation time, number of washes, number of visual fields, (x,y) coords for visual fields, name of experimenter, type of tissue, exposure times and many other variables that I've forgotten)
5. These variables need to be tied to explicit numbers for each of the 50 or so proteins we might be using in one run. About 1000 numbers need to be typed in for each run. That's why recall of previous metadata sheets is so important.
6. I hadn't thought of this before but, after seeing Will Moore's movies about the OMERO editor, I realized that it would be a very good idea for a full verbal description of all the protocols as an integral part of the metadata sheet.
7. After the run, we look through the images and manually mark artifacts of various kinds. These need to be XML recorded with precise pixel positions so that subsequent processing steps can automatically mask them out.

After this comes the analysis part, which tries to extract biologically meaningful conclusions from the above images plus metadata. My concept is that the metadata is cumulative, so that when one looks at the result of some analysis, one can trace through from beginning to end how exactly the result was obtained.

8. For this one needs to include in the metadata (for the image resulting from analysis) the images on which one is basing this particular analysis plus their metadata files plus something like version numbers of our analysis programs that would allow reconstruction of the images from the raw images. A verbal description of what the analysis programs do is also required. I had in mind to specify the images by using file-names, but the OME philosophy seems to be to use instead a compressed form of the image data. This is obviously safer and more reliable, but my concern is that these cumulative metadata files will become very unwieldy and take up a lot of disk space.

So that's a brief description of the task.

Question: is the OMERO editor a suitable tool for the above task? The alternative for me would seem to be to construct a GUI editor in Matlab, specially directed to our needs. Almost certainly I would then be repeating, in a much less flexible and much less extensible style, a small proportion of the work already done in the OMERO editor, with less aesthetic results. So I'm hoping you will say that the OMERO editor is a suitable vehicle.

Thanks a lot
David

[jrswedlow]

Hi David-

We reviewed your post and have given it some discussion. Answering your points and queries in order:

I don't know ImageJ and its web pages, but I have noticed that biologists are very easily attracted into using it. Are there some lessons for OME developers to learn from ImageJ?

Indeed, and we are trying hard. Most ImageJ users make use of Bio-Formats http://www.openmicroscopy.org/site/support/bio-formats/bio-formats-downloads for opening files, and we have some overlap with the ImageJdev (http://imagejdev.org/) and Fiji groups (http://pacific.mpi-cbg.de/wiki/index.php/Fiji). We are learning from and working with each other.

Now, onto your proposed workflow, steps 1 through 8: In fact, this workflow isn't all that different from what most people want to do. All sites use their own customized protocols, and many use customized microscopes. Research-application driven customization is the rule, not the exception. And of course, all the generated data is the rule, not the exception.

OMERO.editor should provide the platform for doing steps 1-6. You'll need to specify the templates that describe your experimental setup. If you do try OMERO.editor, please let us know any problems, and even any successes. Positive feedback helps too!

Steps 7 and 8 are trickier. OMERO.editor contains no image viewing or analysis capability. That's the job of OMERO.server and it's other clients, OMERO.insight and OMERO.web. There's alot to digest about how this all works. The OMERO Features page (http://www.openmicroscopy.org/site/products/feature-list) is a start; for more technical details see http://www.openmicroscopy.org/site/support/omero4. Remember that once you have the data written down you need to view, share, annotate and analyse. You're probably familiar with Jim Gray and colleagues' discussion of filesystem-based (or in their terminology, 'nascent') databases (http://research.microsoft.com/apps/pubs/default.aspx?id=64537). What you want to do here is what we're trying to provide in OMERO. Critically, we only provide a framework that you can use to develop your own applications, so we can't solve your problem.

As Chris said, we try to be as helpful as possible, and have no problem answering any question, at any level. So have a look, at let us know where things don't make sense. We'll help in any way we can.

Cheers,

Jason

[DavidEpstein]

Thanks for the reply. Just a rapid and immediate response, with perhaps a more considered response later. I never had any intention of using OME tools for analyzing our data, as even the crudest and most widely applicable tools are not likely to be relevant to our specialized situation. We already have extensive programs that do this analysis, with many ideas for future development, some of which are likely to require new ideas in statistics (so not much hope there of using existing tools).

My point in mentioning Steps 7 and 8 was that annotation and other metadata descriptions need to be associated with images that result from analysis, and also maybe with non-image results of analysis. So I wondered whether OME tools could be helpful with supplying annotation and metadata at that stage.

I suppose the real alternative to OMERO is not to write our own editor as I suggested previously, but to just ask the user to fill in blanks, using some standard editor, maybe even Word (ugh), and also to write a program that turns this into our own version of XML. Before I go to the trouble of downloading and learning how to work with OMERO.editor, could someone possibly spell out some of the advantages and disadvantages?

Thanks again
David

[jrswedlow]

Hi David-

I'll try to be as clear and succinct as possible.

My point in mentioning Steps 7 and 8 was that annotation and other metadata descriptions need to be associated with images that result from analysis, and also maybe with non-image results of analysis. So I wondered whether OME tools could be helpful with supplying annotation and metadata at that stage.

Yes, that is correct. You have to decide how you want to do this. You can certainly directly annotate the images files themselves, or maybe the analysis files, or maybe store the annotations in separate files, as XML, or some other construct where the data is written to a file in some way. The list goes on and on. However, any computer scientist will tell you that that approach does not scale well, and eventually you end writing your own middleware layer to manage linkages with all the different parts. You also have to build a querying facility-- presumably you are not just storing the data, but providing search and other applications that use the data. Ultimately, you have to write the whole system, and it is completely customised. It's also brittle and requires full knowledge of its design and workings to use. In practice, as soon as the developer moves on, or gets busy with something else, noone else can understand what was done.

A well-established solution-- databases-- are used for exactly these reasons. In OME, we prefer the solution that scales, so we'd suggest you look at OMERO, Bisque (http://www.bioimage.ucsb.edu/bisque) or some other data management system. As I noted previously, OMERO.editor is one module of OMERO, that can run as a standalone application, or embedded within the full OMERO system. It sounds like OMERO.editor can write your files, but you'll still need the whole annotation, querying, and viewing systems.

It's your choice-- you can manage the associations yourself, as XML-based data in files that are somehow linked to the image data, or you can use any number of data management systems that already do alot of the work you want to do. However, all of these systems are complex, and require some commitment to learn their conventions, limitations, assumptions, etc. Some people certainly opt to do things themselves.

I suppose the real alternative to OMERO is not to write our own editor as I suggested previously, but to just ask the user to fill in blanks, using some standard editor, maybe even Word (ugh), and also to write a program that turns this into our own version of XML. Before I go to the trouble of downloading and learning how to work with OMERO.editor, could someone possibly spell out some of the advantages and disadvantages?

The most serious problem with the "user writes in Word" approach is that you have to convert free text into structured types and elements. Any changes by the user, and your program doesn't work. OK, maybe you have a defined, completely restricted template-- what happens when user uses a different version of Word? More importantly, you now have two things to develop and maintain-- the Word document template and the conversion program. Again, a scaling problem. Note that in OMERO.editor, the entry of free text from a protocol written in Word is supported.

Finally, one issue that we've been skirting in this thread, that seems not to have percolated through-- the value of open source development. Some will say "open source is free", and that justifies using it. That's usually incorrect. All software comes with a burden or cost for usage-- maybe it's a license fee, maybe it's not flexible, maybe it's had to install. However, the principle of open source development is that you have a (usually very dedicated) community to help you, and that will take your feedback and use it to improve the tools you want to use. So your effort helps others, and theirs helps you. Maybe it's an unusual way of working for academic researchers, but it is certainly very well-established in software development, especially where there are unsolved problems that are important to address. It does mean you have to think differently about the software you are using-- it's not a product, but a development project, that many are working on together. If it were easy, it would have been done. Since it's hard, why not get some help?

Hope that helps.

Cheers,

Jason

[wmoore]

Hi David,

The OMERO.editor can be run as a standalone application, so you can download and try it without needing to set up a server etc. Slightly confusingly it's part of the 'clients' package on the downloads page: https://www.openmicroscopy.org.uk/site/ ... /downloads

One other option that occurred to me, reading your discussion above, is something that I looked at a while back when working on the Editor: http://isatab.sourceforge.net/index.html. It won't help with the Image data (and it took me a little while to understand their concepts) but it might be suitable as a UI for large amounts of tabular data and it seems to have developed a fair bit since I last looked.

All the best,

Will.