How to edit MapAnnotation (key-value pair annotations)?

[Kouichi_C_Nakamura]

I'm trying to edit key-value pair annotation (MapAnnotation class) of an image in OMERO via MATLAB.

https://downloads.openmicroscopy.org/omero/5.4.6/api/ome/model/annotations/MapAnnotation.html

The getAnnotations.m seems to be the function to retrieve existing key-value pairs. But how do I know ids? It's annotation id, and not visible from omero.insight GUI. How do I obtain ids for a specific image?

https://github.com/openmicroscopy/openmicroscopy/blob/v5.4.6/components/tools/OmeroM/src/annotations/getAnnotations.m

Code: Select all

client = loadOmero('demo.openmicroscopy.org', 4064)

session = client.createSession('xxxxxxx', 'xxxxxxx')

img_id = 18686;
images = getImages(session, img_id)

ma = getAnnotations(session, ids,'map')

Also, how can I assign key-value pairs to a specific image by using ma = writeMapAnnotation(session, keys, values, varargin)? It appears to me that the syntax does not specify the target image.

https://github.com/openmicroscopy/openmicroscopy/blob/v5.4.6/components/tools/OmeroM/src/annotations/writeMapAnnotation.m

[Kouichi_C_Nakamura]

For retrieving MapAnnotation, the following worked:

Code: Select all

img_id = 18686;
ma = getObjectAnnotations(session, 'map', 'image', img_id);
li = ma.getMapValue;

fieldnames(li.get(0))
li.get(0).name
li.get(0).value

[Kouichi_C_Nakamura]

To edit existing MapAnnotation in OMERO server, use linkAnnotation.m.

Code: Select all

eval('import ome.model.annotations.MapAnnotation')

img_id2 = 18683;
ma2 = getObjectAnnotations(session, 'map', 'image', img_id2);

if ~isempty(ma2)
   
    ma2 = MapAnnotation;
    link1 = linkAnnotation(session, ma2, 'image', img_id2);
   
end

link1 = linkAnnotation(session, ma, 'image', img_id2);

ma3 = getObjectAnnotations(session, 'map', 'image', img_id2);

li3 = ma3.getMapValue
size(li3)

[Kouichi_C_Nakamura]

Now I need to be able to "delete" existing key-value pair annotations from an image.

In my current understanding, a MapAnnotation object is linked to an image object. Multiple images can share the same MapAnnotation object.

Let's say, image A and image B shared a MapAnnotation object ma. I want to "delete" the key-value pairs from image B, while keeping image A intact. How can I achieve that?

Maybe by unlinking?

ome.model.core.Image.clearAnnotationLinks() appears to be a solution.

It issued an error.

http://javadoc.scijava.org/OMERO/ome/mo ... ionLinks--

Code: Select all

>> images2.clearAnnotationLinks
Java exception occurred:
omero.UnloadedCollectionException: Error updating
collection:annotationLinksSeq
Collection is currently null. This can be seen
by testing "annotationLinksSeqLoaded". This implies
that this collection was unloaded. Please refresh this object
in order to update this collection.

   at
        omero.model.ImageI.throwNullCollectionException(ImageI.java:40)
           at
        omero.model.ImageI.clearAnnotationLinks(ImageI.java:1289)
           at
        omero.model.Image.clearAnnotationLinks(Image.java:185)


Any other idea, please?

[jmoore]

Now I need to be able to "delete" existing key-value pair annotations from an image.

In my current understanding, a MapAnnotation object is linked to an image object. Multiple images can share the same MapAnnotation object.

Let's say, image A and image B shared a MapAnnotation object ma. I want to "delete" the key-value pairs from image B, while keeping image A intact. How can I achieve that?

Maybe by unlinking?

Yes, in our terminology this would be unlinking (which amounts to deleting the link).

ome.model.core.Image.clearAnnotationLinks() appears to be a solution.

It issued an error.

http://javadoc.scijava.org/OMERO/ome/mo ... ionLinks--

Code: Select all

>> images2.clearAnnotationLinks
Java exception occurred:
omero.UnloadedCollectionException: Error updating
...


At any given time, you only have a part of the object graph that is in your database. You work on that portion of the graph and then save it. Here, the method you used to load the images2 object didn't load the annotations so you can't make modifications on that part of the graph. You have two options:

• either update the loading code so that you have all the annotations, and then remove those links from the collection that you no longer want
• or, if you've previously had the annotation link in hand, you can delete it directly.

If which of those is going to be easier is unclear, it will probably help to see the current state of the code. Do you have it on GitHub perhaps?

All the best,
~Josh

[Kouichi_C_Nakamura]

Thanks a lot for your inputs, Josh.

either update the loading code so that you have all the annotations, and then remove those links from the collection that you no longer want

My speculation is that I need to load annotations. Image object does not have load* methods, so I looked it up, and found that ome.logic.MetadataImpl class has a method called loadAnnotations.

http://javadoc.scijava.org/OMERO/ome/lo ... aImpl.html

This sounds like what I need. However, I can't instantiate ome.ome.logic.MetadataImpl.

I used jar tf omero_client.jar command in terminal to see the content of omero_client.jar. I found 15985 classes, but ome.logic.MetadataImpl was not part of it. I wonder why the Javadoc and the content of OMERO API in local hard disk do not tally.

omero.api.IMetadata also has the same method but this is an interface. And the method is not static. I cannot directly use it.

or, if you've previously had the annotation link in hand, you can delete it directly.

I don't know the ID for the annotation link, so this is not possible now.

[Kouichi_C_Nakamura]

Reading this documenation, I found the getMetadataService method of session (omero.api.ServiceFactoryPrxHelper).

https://docs.openmicroscopy.org/omero/5.4.6/developers/Modules/Api.html

Code: Select all

client = loadOmero('demo.openmicroscopy.org', 4064)
session = client.createSession('xxxxxxxx', 'xxxxxxxx')

metadataService = session.getMetadataService


metadataService is an object of 'omero.api.IMetadataPrxHelper' class, and apparently this is an implementation of 'omero.api.IMetadata', and so it has the loadAnnotations method.

However, I could not get it work.

http://javadoc.scijava.org/OMERO/ome/ap ... arameters-

SYNTAX https://github.com/openmicroscopy/openmicroscopy/blob/be2754b18570ea97ee4e122116304461470181df/components/common/src/ome/api/IMetadata.java#L112

Code: Select all

public <T extends IObject, A extends Annotation>
    Map<Long, Set<A>> loadAnnotations(
            @NotNull Class<T> nodeType, @NotNull @Validate(Long.class)
            Set<Long> rootNodeIds, @NotNull @Validate(String.class)
            Set<String> annotationType,
@Validate(Long.class) Set<Long> annotatorIds, Parameters options);


Code: Select all

>> img_id = 18686;
>> metadataService.loadAnnotations('image',img_id,[],[])
No method 'loadAnnotations' with matching signature found for class
'omero.api.IMetadataPrxHelper'.

Strangely, I could not find definition of IMetadataPrxHelper class (and hence implementation of the loadAnnotations method) either on scijava or openmicroscipy websites. I could not find source code of the class in GitHub either.

http://javadoc.scijava.org/OMERO/allcla ... frame.html

https://downloads.openmicroscopy.org/om ... index.html

I'm still wondering the differences between these two API definitions. They look similar, but they are slightly different.

[jmoore]

Hi Kouichi,

sorry for the slow response. We've just ended our annual users meeting and are just now getting back to regular business.

However, I could not get it work.

http://javadoc.scijava.org/OMERO/ome/ap ... arameters-

...

I'm still wondering the differences between these two API definitions. They look similar, but they are slightly different

You are struggling with the difference between the internal API and the one exposed by Ice. The Ice API under `slice2html` is the one that will be made available in MATLAB. For example, your invocation should have parameters matching https://downloads.openmicroscopy.org/omero/5.4.6/api/slice2html/omero/api/IMetadata.html#loadAnnotations.

Strangely, I could not find definition of IMetadataPrxHelper class (and hence implementation of the loadAnnotations method) either on scijava or openmicroscipy websites. I could not find source code of the class in GitHub either.

No, that file is code-generated and only available in the jar file.

Looking at the code, I think the core problem is that getImages.m does not load the annotations in the first place. The easiest solution may be something like this query from ReadData.m:

Code: Select all

    images = session.getQueryService().findAllByQuery(['select img from Image as img left outer join fetch img.annotationLinks as link join fetch link.child as annotation where img.id =  ', num2str(imgId)], []);


Cheers,
~Josh

[Kouichi_C_Nakamura]

Thanks.

Code: Select all

>> images = session.getQueryService().findAllByQuery(['select img from Image as img left outer join fetch img.annotationLinks as link join fetch link.child as annotation where img.id =  ', num2str(imgId)], []);
>> img = images.get(0);
>> img.isAnnotationLinksLoaded
ans =
  logical
   1


Now is seems that AnnotationLinks are loaded, as you predicted.

However,

Code: Select all

>> ma = getObjectAnnotations(session, 'map', 'image', imgId);
>> img.unlinkAnnotation(ma2)


Nothing happened (no error).

Code: Select all

>> img.clearAnnotationLinks


Nothing happened (no error).

How can I unlink a MapAnnotation from the img object??

More generally, how on earth could I find relevant information for this? API documentation is hard to navigate through.

[jmoore]

Code: Select all

>> ma = getObjectAnnotations(session, 'map', 'image', imgId);
>> img.unlinkAnnotation(ma2)


Nothing happened (no error).

Code: Select all

>> img.clearAnnotationLinks


Nothing happened (no error).

Hi Kouichi. Those methods are only changing the data graph that you've retrieved. Now you are backing at the stage of either needing to resave the graph using saveAndReturnObject or you need to delete the link server side with deleteObjects.

More generally, how on earth could I find relevant information for this? API documentation is hard to navigate through.

Our apologies, Kouichi. Unfortunately for you, MATLAB is very much a second-class citizen. Very few of us have a working environment, so the documentation is certainly incomplete and providing snippets is problematic. Additionally, we have not yet updated OMERO.matlab to make use of the newer https://downloads.openmicroscopy.org/omero/5.4.6/api/omero/gateway/Gateway.html API.

Since MATLAB uses the Java API, the best introduction we have at the moment is https://docs.openmicroscopy.org/latest/omero/developers/Java.html and then you would have to apply that knowledge to MATLAB.


So coming back to your question:

How can I unlink a MapAnnotation from the img object??

I think the only step that you are missing is saving the `img` after you clear the links:

Code: Select all

img = session.getUpdateService().saveAndReturnObject(img);


Cheers,
~Josh