There are several ways to add annotations to objects in OMERO. Here, addition and filtering of annotations using OMERO.web is described. You can add annotations using the OMERO.web interface to any object(s) that you can select in the left-hand-side tree or central pane, this means Project, Dataset, Image, Screen, Plate and Well.
# Annotate data manually #
- **Tags**
Select one or several images from the web client, and in the right-hand pane in {nav General tab}, click the {nav +} button under the {nav Tags} harmonica to add tags manually.
{F18510951}
Select tags from your available tags or create new ones:
{F18510991}
Hit {nav Save}
- **Tag sets**
Tags can also be organized in tag sets, i.e tag containers that gather different tags. If you select a tag set when adding tags to an omero object (image, project, dataset..), the corresponding object will be tagged with all tags contained in the tag set.
{F19856505, size=full}
- **Key-value pairs**
The Key-Value Pairs allow you to add lab-book-like additional metadata for the Image. These Key-Value Pairs are also specifically searchable.
{F18510883}
Select an Image from the web client, and in the right-hand pane in {nav General tab}, click the {nav +} button under the {nav Key-Value Pairs} harmonica to add Key-value pairs manually.
See below part //Adding Key-value pairs from a csv file// to learn how to generate key-value pairs in a batch manner using a .csv file.
- **Attachments**
Select one or more objects in the left-hand side tree, such as Dataset, Project or Image. Expand the Attachments harmonica in the right-hand pane and click the {nav +} button.
{F18511054}
You can attach any type of file using this function. If you select a file from your local filesystem using the {nav Browse} button, the feature will upload that file to the OMERO.server and save it there. The content of .pdf, CSV and plain text files is also searchable in OMERO.
- ** Others**
You can also add Comments and Rating to selected objects - follow analogous steps to the ones descirbed above for Tags, Key-Value pairs and File Attachments.
# Annotate Data using the auto-tagger#
When an image is uploaded to OMERO, the original filename, including extensions and the path from which it was uploaded, is preserved. It is common for useful metadata to be encoded into the filenames and paths of data. In order to make use of this metadata for searching and organising the data, Auto-tagger enables it to be added as annotations in the form of tags.
###**Terminology**###
• **Tag**: an OMERO text annotation
• **Token**: a section of text which has been automatically parsed from the filename after splitting up the filename by a space, period or underscore. e.g. token1_token2_token3.dv or token3 token4.dv or token5.token6.dv
• **Mapping**: selecting a certain tag to correspond to a certain token, e.g. the tag “Deconvolved” might be created from a token “Deconvolved”.
###**Step-by-step guide**###
1. Select a dataset or image in the data tree. Select {nav Auto Tag} from the view menu in the centre pane toolbar.
{F18511128, size=full}
2. Columns headed with a token name are displayed in the centre pane, with a row representing each image in the dataset. The initial display shows only existing tags, either already attached to images or not attached but matching a token. If an image already has a tag applied to it, or if the token for a column is present in this image, checkboxes in the rows are auto-selected. A green background in a cell indicates the image has that tag applied to it. **Select the {nav Show All Potential Tags} checkbox** to generate columns for tokens from the filename path and extensions.
{F18511149, size=full}
3. The drop-down buttons in the headers of the columns are colour-coded as:
- **Pink** (empty drop-down button) - indicating a token which did not match any existing tags in the system, or there were multiple matching tags and there was no way to make a determination as to which was intended.
- **Blue** (tag name in drop-down) - indicating a token which matched exactly one existing tag and has been automatically mapped to this tag. Blue columns are also shown when the user manually applies a mapping.
- **Green** (tag name in drop-down) - indicating a tag which is already applied to some images in this dataset, but does not match any of the tokens.
{F18511188, size=full}
4. The default rarity threshold setting is 2. Use the Rarity Threshold slider to adjust the threshold to a higher value to refine the display of tokens according to how commonly they were detected on images. Click the Apply button to save the changes. Click the Refresh button to reset the table to its original state without applying changes.
IMPORTANT: Tokens that are only numbers are ignored, as these are usually very numerous and it is impossible to intelligently map them at this time.
The filename is tokenised using a **space**, **period** or **underscore** as the splitter. **Dashs** are not recognized as splitters.
{F18511225, size=full}
5. Click on the Pink button drop-down to add a suggested tag. Select {nav New/Existing Tag}. Edit or accept suggested tag name. Add a description if required. Click {nav OK}. Once happy with the suggestions indicated by the boxes ticked in the centre pane, click the {nav Apply} button, which will attach the tags to the images.
{F18511247, size=full}
# Adding Key-value pairs from a csv file #
It is possible to batch-annotate images in a dataset with key-value pairs using a coma-separated file (.csv).
The idea is that the author keeps track of image filenames and metadata information in a spreadsheet document (e.g. MS Excel (R)) either during the microscopy session or when importing the images into Omero. This spreadsheet can then be uploaded to Omero and attached to the container object (i.e project or dataset) hosting the referenced images.
In the spreadsheet, each row should correspond to an image contained in the dataset, and the first column should contain the exact names of the omero images, as shown in the example below:
{F19849644, size=full}
Attach the .csv (as an **attachment**, see above) to the omero dataset: In the left panel, select the dataset that holds the images to annotate. Locate the Attachments menu
{F19849713}
The next step is to extract the attached csv file and attach the extracted information as key-value pairs to the images. The images are identified by the image name given in the first column of the spreadsheet. The remaining column names are used as keys and the cell values of each row are then entered as values in the new key-value pairs.
First, we select the csv file to extract the metadata from: Click the {icon cogs} **button under the Attachment harmonica** shown above. Then, select (check the box) next to the csv file uploaded in the previous step.
{F19849774}
This step really matters if you have several .csv files attached to the same omero dataset.
Next, we run a script from the Omero scripts collection:
Click on the {icon cogs} button** from the menu bar on the top of the omero web client**.
{F19849791, size = full}
Go to {nav bulk_annotation_scripts>03-KeyVal from csv...}
This will bring up the script configuration dialog.
{F19858627, size = full}
Check that the “IDs” field shows the ID of the dataset holding the images to annotate, and that the “File Annotation” states the ID of the attachment.
{F19849856}
In case you did not select the attachment in the previous step, you could enter the attachment ID here.
Finally, click {nav Run Script}.
After a little while, you should see a notification telling you about the success (or failure) of the script. If all goes well, you’ll see something like this:Select one or several images from the web client, and select the {nav General tab} from the right-hand pane. Hit the {nav +} button under the {nav Tags} harmonica to add tags manually.
{F18510951}
Select tags from your available tags or create new ones:
{F18510991}
Hit {nav Save}
- **Tag sets**
Tags can also be organized in tag sets, i.e tag containers that gather different tags. If you select a tag set when adding tags to an omero object (image, project, dataset..), the corresponding object will be tagged with all tags contained in the tag set.
{F19856505, size=full}
- **Key-value pairs**
The Key-Value Pairs can be used for adding lab-book-like metadata (e.g experimental conditions) to your images. Key-Value Pairs are also specifically searchable.
{F18510883}
Select an Image from the web client, and select the {nav General tab} from the right-hand pane. Hit the {nav +} button under the {nav Key-Value Pairs} harmonica to add Key-value pairs manually.
See below part //Adding Key-value pairs from a csv file// to learn how to generate Key-Value pairs in a batch manner using a .csv file.
- **Attachments**
Select one or more objects in the left-hand side tree, such as Dataset, Project or Image. Expand the {nav Attachments} harmonica in the right-hand pane and click the {nav +} button.
{F18511054}
You can attach any type of file as an attachment. If you select a file from your local filesystem using the {nav Browse} button, the file will be uploaded to the OMERO.server and linked to your Omero object. The content of .pdf, CSV and plain text files is also searchable in OMERO.
- ** Others**
You can add Comments and Ratings to any Omero object; To do so, follow analogous steps to the ones descirbed above for Tags, Key-Value pairs and File Attachments.
# Annotate Data using the auto-tagger#
When an image is uploaded to OMERO, the original filename, including its extensions and the path from which it was uploaded, is preserved. It is common for useful metadata to be encoded into the filenames and paths of data. In order to make use of this metadata for searching and organising the data, the {nav Auto-tagger} web plugin enables it to be added as annotations in the form of tags.
###**Terminology**###
• **Tag**: an OMERO text annotation
• **Token**: a section of text which has been automatically parsed from the filename after splitting up the filename by a space, period or underscore. e.g. token1_token2_token3.dv or token3 token4.dv or token5.token6.dv
• **Mapping**: selecting a certain tag to correspond to a certain token, e.g. the tag “Deconvolved” might be created from a token “Deconvolved”.
###**Step-by-step guide**###
1. Select a dataset or image in the data tree. Select {nav Auto Tag} from the view menu in the centre pane toolbar.
{F18511128, size=full}
2. Columns headed with a token name are displayed in the centre pane, with a row representing each image in the dataset. The initial display shows only existing tags, either already attached to images or not attached but matching a token. If an image already has a tag applied to it, or if the token for a column is present in this image, checkboxes in the rows are auto-selected. A green background in a cell indicates the image has that tag applied to it. **Select the {nav Show All Potential Tags} checkbox** to generate columns for tokens from the filename path and extensions.
{F18511149, size=full}
3. The drop-down buttons in the headers of the columns are colour-coded as:
- **Pink** (empty drop-down button) - indicating a token which did not match any existing tags in the system, or there were multiple matching tags and there was no way to make a determination as to which was intended.
- **Blue** (tag name in drop-down) - indicating a token which matched exactly one existing tag and has been automatically mapped to this tag. Blue columns are also shown when the user manually applies a mapping.
- **Green** (tag name in drop-down) - indicating a tag which is already applied to some images in this dataset, but does not match any of the tokens.
{F18511188, size=full}
4. The default rarity threshold setting is 2. Use the Rarity Threshold slider to adjust the threshold to a higher value to refine the display of tokens according to how commonly they were detected on images. Click the {nav Apply} button to save the changes. Click the {nav Refresh} button to reset the table to its original state without applying changes.
IMPORTANT: Tokens that are only numbers are ignored, as these are usually very numerous and it is impossible to intelligently map them at this time.
The filename is tokenised using a **space**, **period** or **underscore** as the splitter. **Dashs** are not recognized as splitters.
{F18511225, size=full}
5. Click on a pink drop-down to add a suggested tag. Select {nav New/Existing Tag}. Edit or accept suggested tag name. Add a description if required. Click {nav OK}. Once happy with the suggestions indicated by the boxes ticked in the centre pane, click the {nav Apply} button, which will attach the tags to the images.
{F18511247, size=full}
# Adding Key-value pairs from a csv file #
It is possible to batch-annotate images in a dataset with key-value pairs using a coma-separated file (.csv).
The idea is that the author keeps track of image filenames and metadata information in a spreadsheet document (e.g. MS Excel (R)) either during the microscopy session or when importing the images into Omero. This spreadsheet can then be uploaded to Omero and attached to the container object (i.e project or dataset) hosting the referenced images.
In the spreadsheet, each row should correspond to an image contained in the dataset, and the first column should contain the exact names of the omero images, as shown in the example below:
{F19849644, size=full}
Locate the Attachments menu in the right-hand pane. Attach the .csv file (as an **attachment**, see above) to the omero dataset: In the left panel, select the dataset that holds the images to annotate.
{F19849713}
The next step is to extract the attached csv file and attach the extracted information as key-value pairs to the images. The images are identified by the image name given in the first column of the spreadsheet. The remaining column names are used as keys and the cell values of each row are then entered as values in the new key-value pairs.
First, we select the csv file to extract the metadata from: Click the {icon cogs} **button under the Attachment harmonica** shown above. Then, select (check the box) next to the csv file uploaded in the previous step.
{F19849774}
This step really matters if you have several .csv files attached to the same omero dataset.
Next, we run a script from the Omero scripts collection:
Click on the {icon cogs} button** from the menu bar on the top of the omero web client**.
{F19849791, size = full}
Go to {nav bulk_annotation_scripts>03-KeyVal from csv...}
This will bring up the script configuration dialog.
{F19858627, size = full}
Check that the “IDs” field shows the ID of the dataset holding the images to annotate, and that the “File Annotation” states the ID of the attachment.
{F19849856}
In case you did not select the attachment in the previous step, you could enter the attachment ID here.
Finally, click {nav Run Script}.
After a little while, you should see a notification telling you about the success (or failure) of the script. If all goes well, you’ll see the following log message:
{F19849866}
Select one of the images and confirm that it is now annotated with Key-Value pairs, generated from the information given in the spreadsheet.
{F19849879}
# Filter using annotations #
Images can be filtered by Name, Tag, Key-Value pairs or Rating in the centre pane, using the {nav Add filter} chooser above the thumbnails.
{F18511262, size=full}
# Advanced filtering: OMERO.parade #
==**Description:**==
**OMERO.parade** is a metadata-mining plugin for OMERO.web. Among other things, it offers more advanced filtering options than the filtering tool available from OMERO.web's main page. Supported metadata includes number of ROIs, Key-Value pairs, and data stored in OMERO.tables or in .csv files. Please visit [[ https://c4science.ch/w/bioimaging_and_optics_platform_biop/image-processing/omero/analysis/omerotablesandparade/ | this page of the present documentation ]] to learn how to use OMERO.parade to filter data.
# Remove an annotation / attachment #
Find the annotation you want to remove. Click on the minus sign to the right of it.
For attachments, clicking on the minus sign just unlinks the {nav File Attachment} from the selected object(s). The {nav File Attachment} is not deleted from the server. If deletion is needed, click in the workflow above on the **cross icon** instead of the **minus icon**.
{F18666551}
= More documentation on this topic... =
To learn more about annotating OMERO images, we recommend you to visit the [[ https://omero-guides.readthedocs.io/projects/introduction/en/latest/annotate.html? | dedicated page from the official OMERO guide ]].
---
{icon hand-o-right} [[ https://c4science.ch/w/bioimaging_and_optics_platform_biop/image-processing/omero/managing-data/ | NEXT STEP: Managing data ]]
---