Welcome to MicroMetaApp!¶

This page hosts the documentation for Micro-Meta App .

Introduction¶

What is Micro-Meta App?¶

Micro-Meta App is an easy to use and flexible software for the collection of Microscopy Metadata.

Micro-Meta App collects Microscopy Hardware, Imaging Acquisition Settings, and Quality Control metadata on the basis of the 4DN-BINA-OME (NBO) Microscopy Metadata Specifications which are a suite of scalable an extensions of the OME data model and have been developed in the context of the 4D Nucleome (4DN) initiative and the Bioimaging North America Quality Control and Data Management Working Group

Features include:¶

Intuitive graphical user interface metadata collection modality
Compatibility with the 4DN-BINA-OME (NBO) Microscopy Metadata Specifications extension of the OME data model
Storage of Microscope Hardware specifications metadata in re-usable JSON files that can be exchanged with other members of the community
Easy to use as a standalone app
Easy to integrate into pre-existing repositories
Pilot integration into the popular OMERO image data repository

Implementations:¶

Currently, three implementations of the Micro-Meta App are available on Github.

A standalone version implemented in Javascript Electron which can be downloaded here
A Javascript React version that can be integrated into any web portal, such as the 4DN Data Portal.
An OMERO plugin version that is only available as a pilot implementation on the UMMS-PMM instance of the OMERO server.

Tip

Please Note - If you want to know more about the React and OMERO plugin implementations and if you are interested in using them in your portal or OMERO server please contact: caterina.strambio@umassmed.edu.

Installation¶

Download¶

The latest version of Micro-Meta App for your platform (Windows, Linux, macOS) can be downloaded from GitHub

Requirements¶

Hardware: none
Software: Java 1.8.0 (to use the ome-bioformats based image metadata reader)

Tip

Note - In case you have issues with your Java version please check out our Tutorial videos that explain how to check your Java version and how to install the correct one and which can be found here .

Operating System:

Windows x32

Not tested
Windows x64
- Tested on:
  
  Win 8.1 Version: 6.3.9600
  
  Win 10 Home Version: 10.0.19040 - 10.0.19041 - 10.0.19042
  
  Win 10 Pro Version: 10.0.19041 - 10.0.19042
  
  Win 10 Enterprise Version: 10.0.18362, 10.0.19041, 10.0.19042
MacOS
- Tested on:
  
  High Sierra Version: 10.13.6
  
  Mojave Version: 10.14.6
  
  Catalina Verson: 10.15.7
  
  Big Sur Version: 11.0 - 11.1 - 11.2 - 11.3 - 11.3.1 - 11.4 - 11.5 Beta

Install¶

On Windows, download the .zip then extract its contents, drag the micro-meta-app-electron.exe file to the desired location and launch it.
On macOS, download the .zip, extract its content, drag micro-meta-app-electron.app to wherever you want to keep it, and launch it.

Install time: less than a minute.

Tip

Note - In case you have issues with the installation please check out our Tutorial videos here.

Tip

Note - If you are using MacOS v10.15.7 or later, we recommend that you use The Unarchiver App to extract the content of the .zip, instead of the native Mac unarchiver utility. In addition, please follow these instructions when you launch micro-meta-app-electron.app for the first time:

Open the left-click menu and select the Open command.
In case you receive an error message the first time you launch micro-meta-app-electron.app, please click OK and launch again using the left-click menu.
The second time you launch, you might be given a warning about opening an app from an unknown developer, in that case please select Open to continue.
After that, you should be able to launch the app as normal.

Example Data Files¶

At our Zenodo page it is possible to download an example raw image data file to be documented, and the associated Microscope.JSON and Settings.JSON that were created using Micro-Meta App to document the Microscope Hardware Specifications of the instrument that was used to acquire the image and Image Acquisition Settings that were applied to the microscope for acquisition.

Output¶

Micro-Meta App produces json two kind of structured json file as output, one for the Instrument and one for the Image Acquisition Setting.

The time necessary to produce a file is really based on the amount of metadata that a user wants to insert.

Instrument file¶

The following is an empty example of an Instrument file.

Please note the components array could be filled with any number of json object based on the number of elements that have been added in the instrument.

{

“Name”: “MicroscopeName”,

“Tier”: tier,

“ValidationTier”: validationTier,

“Schema_ID”: “Instrument.json”,

“ID”: “uuid”,

“Description”: ” … “,

“MicroscopeStand”: { … },

“AppVersion”: “versionNumber”,

“ModelVersion”: “versionNumber”,

“components”: [ … ],

“linkedFields”: { …. }

}

Image Acquisition Setting¶

The following is an empty example of an Image Acquisition Setting file.

Please note that the field “StageInsert”, “FocusStabilizationDevice”, “AcquisitionSoftware”, “MicroscopeStandSettings”, “Channels”, “ObjectiveSettings”, “ImagingEnvironment”, “MicroscopeTableSettings”, “SamplePositioningSettings” and “Planes” may be absent in your output based on the element that you have created in the application.

{

“Name”: “ImageAcquisitionSetting”,

“AcquisitionDate”: “day @ time”,

“Schema_ID”: “Image.json”,

“ID”: “uuid”,

“Tier”: tier,

“ValidationTier”: validationTier,

“Description”: “…”,

“InstrumentName”: “MicroscopeName”,

“InstrumentID”: “microscope uuid”,

“StageInsert”: [ … ],

“FocusStabilizationDevice”: [ … ],

“AcquisitionSoftware”: [ … ],

“MicroscopeStandSettings” : [ … ],

“Channels” : [ … ],

“ObjectiveSettings” : { … },

“ImagingEnvironment” : [ … ],

“MicroscopeTableSettings” : [ … ],

“SamplePositioningSettings” : [ … ],

“Planes”: [ … ],

“AppVersion”: “versionNumber”,

“ModelVersion”: “versionNumber”,

}

How to cite Micro-Meta App¶

Micro-Meta App was developed by Alex Rigano in the Strambio De Castillia’s lab at the Program of Molecular Medicine of UMMS to facilitate the documentation of fluorescence microscopy experiments. If you use Micro-Meta App in your work please remember to cite our work as follows:

Rigano A., and C. Strambio-De-Castillia, (2020). Micro-Meta App: a flexible and interactive tool for the collection of microscopy metadata. GitHub.com. Available at, https://github.com/WU-BIMAC/4DNMicroscopyMetadataToolReact

Acknowledgments¶

Project acknowledgments¶

Micro-Meta App could not have been developed without the help of multiple individuals, whose contribution we would like to acknowledge here: Mathias Hammer, Maximiliaan Huisman, Farzin Farzam and David Grunwald members of the Grunwald lab at the University of Massachusetts Medical School provided inspiration, many useful suggestions, continual support to the project and did lots of the initial testing; Burak Alver, Alexander Balashov, Shannon Ehmsen, Koray Kirli, and Peter Park, members of the 4D Nucleome DCIC at Harvard Medical School were instrumental throughout the project for the development of the graphical user interface, software testing, and backend integration in the 4DN Data Portal. Will Moore was very generous with his time for the initial development of the Micro-Meta App OMERO plugin.

Documentation acknowledgments¶

This documentation makes use of screenshots that were obtained using the TIRF Epi-Fluorescence Structured Light Microscope (TESM) as an example. TESM was developed at the University of Massachusetts Medical School Program in Molecular Medicine by members of the Bio-Medical Imaging Group. You can find more information about this microscope here.

Need Help?¶

If you have any problems using Micro-Meta App please contact caterina.strambio@umassmed.edu or alex.rigano@umassmed.edu.

Step-by-step instructions¶

This section contains step-by-step instructions on how to download, launch, and use Micro-Meta App to collect microscopy metadata.

Launching Micro-Meta App¶

The instructions on how to launch Micro-Meta App differ depending on whether you are using the standalone version on your local computer, the version that is integrated into the 4DN Data Portal, or the Micro-Meta App OMERO plugin.

A - Launching the standalone version of Micro-Meta App.¶

After downloading the Micro-Meta App, locate the Micro-Meta App on your local computer and double click on the icon to launch it. After launching the App select the Home folder where all saved Microscope files will be stored on your local computer and hit Confirm.

Figure 1: Select home folder where Microscope files will be locally saved.

B - Launching the Micro-Meta App from the 4DN Data Portal¶

Instructions on how to use the Micro-Meta App in the context of the 4D Nucleome Data Portal are coming up soon.

Figure 2: Micro-Meta App can be used in the context of the 4D Nucleome Data Portal.

C - Launching the Micro-Meta App OMERO.web plugin¶

For the moment the Micro-Meta App OMERO.web plug-in is only implemented on the OMERO server instance available at UMMS-PMM. In order to use this version of the Micro-Meta App please follow the instructions below.

Step 1¶

Using your favorite browser (Firefox or Chrome are good choices) navigate to http://omero.umassmed.edu:4080/webclient/login/ to access the UMM-PMM OMERO.web client.

Step 2¶

Use the OMERO login credentials provided to you by the UMMS-PMM OMERO server administrator (if you do not have them please contact: Caterina at caterina.strambio@umassmed.edu or Alex at alessandro.rigano@umassmed.edu) to login into OMERO.

Figure 3: Login into the OMERO server.

Step 3¶

By default, you will find yourself in the standard data management screen of OMERO and will be placed in your default group, for now, is “Micro-Meta App”.

Step 4¶

In order to see the microscopes, you will have to access the data owned by Alex Rigano (see Figure).

Figure 4: Switch user to access the dedicated Microscopes dataset to save Microscope files.

Step 5¶

Now you will see the “Microscope” project and you will be able to see the available attached microscope-files.

Figure 5: Launch the OMERO Micro-Meta App plugin.

Step 6¶

To launch the Micro-Meta App plugin in OMERO click on “Micro-Meta” in the top menu-bar.

Using Micro-Meta App¶

Micro-Meta App collects Microscopy Hardware, Imaging Acquisition Settings, and Quality Control metadata on the basis of the 4DN Nucleome (4DN)-BINA Microscopy Metadata specifications, which are described in our recent manuscript entitled “Towards community-driven metadata standards for light microscopy: tiered specifications extending the OME model” and available on BioRxiv.org `here <https://arxiv.org/abs/1910.11370>. The 4DN-BINA-OME Microscopy Metadata specifications are an extension of the OME Core Model and have been developed in the context of the 4D Nucleome (4DN) initiative and in close collaboration with the Bioimaging North America Quality Control and Data Management Working Group

One key feature of the 4DN-BINA-OME (NBO) extension of the OME Core Model is that in order to make things easier for the user, the metadata specifications scale with experimental intent and complexity. Thus the 4DN-BINA extension of the OME Core Model sets up a set of 3 Tiers that sanctions which metadata information has to be provided to facilitate reproducibility and sharing of imaging data in a way that takes into account the scientific questions and techniques being used.

For example, Tier 1 is set up to represent the Minimum Information about Fluorescence Microscopy Experiments guidelines and it recommended when no image analysis or simple image analysis procedures are required for the interpretation of image data. Tier 2 is utilized to document image data that requires advanced image analysis for knowledge extraction and interpretation. Finally, Tier 3 is recommended for the full description of Microscope Hardware and should be used by both academic and commercial microscope manufacturers.

In order to facilitate the documentation of Microscopy experiments, Micro-Meta App incorporates the Tiered Guidelines concept. As a result, when creating a brand new or when opening an existing Microscope metadata file it is first necessary to select the desired Tier level. This garners maximal flexibility as an existing Microscope metadata file can be successively opened at a higher Tier level while preserving information that had already been entered.

In addition, a Microscope metadata file that is opened at a given Tier level can be later validated and saved at a lower Tier level thus facilitating the gradual accumulation of the required information across multiple sessions.

Two Micro-Meta App data processing workflows¶

Micro-Meta App is organized around two data-processing workflows.

A . Manage Instrument¶

Manage Instruments allows to create a Tier-specific description of the hardware components of a fluorescence microscope.

A . Manage Settings¶

Manage Settings allows to create a description of the image acquisition parameters used to acquire a specific imaging dataset.

A. Managing Microscope Specification files¶

Please follow these step by step instructions.

A.1 Selecting Tier level¶

Click on the “Tier” selector and select the Tier level you are interested in and click on “Manage Instrument”.

Tip

Please note that a Microscope metadata file that has been opened at a given Tier level can be validated and saved at a lower level, thus facilitating the work required for full documentation by allowing it to be done over multiple sessions.

Figure 1: Select the desired Tier level.

A.2 Creating or Opening a Microscope file¶

After selecting the desired Tier level, select one of the four options by clicking on the on the “Create mode selector” button. “Create Inverted from scratch” and “Create Upright from scratch” allow to create a new Inverted or Upright Microscope file, respectively. “Load from file” allows to import a Microscope file that has not been loaded in the App yet (i.e., a Microscope file you might have received from someone else). “Load from repository” allows to work on a Microscope file that has already been imported in the App and you might need to modify.

A.2.1 Creating from scratch¶

After selecting one of the two “Create Inverted/Upright from scratch”, hit “Continue” and an empty Canvas will appear. To start building a new Microscope file, first hit “Edit Microscope”, enter the required attributes and hit “Confirm”. To add Hardware components follow instructions below.

A.2.2 Loading from file¶

After selecting “Load from file”, click on “Select an existing Microscope file you want to work on.”, select the desired Microscope file (e.g., those provided as Example Files with the App), click “Open” and then hit “Continue”.

Figure 2: Select the desired Microscope file to open.

A.2.3 Loading from the Repository/Home folder¶

Step 1¶

Select “Load from repository” to open an existing Microscope file to edit, and hit “Continue”.

Figure 3: Select “Load from repository” to open an existing Microscope file to edit.

Step 2¶

First select the Manufacturer of the Microscope and then select the desired Microscope file you need to edit.

Figure 4: Select the desired manufacturer and Microscope file from those available in the Repository/Home folder.

A.3 Adding and Editing Hardware components to the Canvas¶

After opening a new or an existing Microscope file, if available all pre-existing Hardware components will appear on the Canvas. In this example the TIRF Epi-Fluorescence Structured Light Microscope (TESM) custom built at the University of Massachusetts Medical School Program in Molecular Medicine by members of the Bio-Medical Imaging Group, is displayed with several existing components.

Tip

At any time in the process it is possible to click on the “Back” button to return to the the opening screen to work on a different Microscope metadata file or to choose a different Tier level for the current Microscope.

Figure 5: The opened TESM Microscope file with existing Hardware components.