Mar 08, 2023

Public workspaceGetting started with Micro-Meta App Tutorial V.7

DOI
dx.doi.org/10.17504/protocols.io.36wgq7ddxvk5/v7
  • 1Program in Molecular Medicine, UMass Chan Medical School, Worcester, MA, USA;
  • 2RNA Therapeutics Institute, UMass Chan Medical School, Worcester, MA, USA;
  • 3Advanced BioImaging Facility (ABIF), McGill University, Montreal, Quebec, Canada
Caterina Strambio De Castillia
Icon indicating open access to content
QR code linking to this content
DOI: dx.doi.org/10.17504/protocols.io.36wgq7ddxvk5/v7
External link: https://micrometaapp-docs.readthedocs.io/en/latest/docs/intro/index.html
Protocol Citation: Alessandro Rigano, Mathias Hammer, Joel Ryan, Claire M. Brown, David Grunwald, Caterina Strambio De Castillia 2023. Getting started with Micro-Meta App Tutorial. protocols.io https://dx.doi.org/10.17504/protocols.io.36wgq7ddxvk5/v7Version created by Caterina Strambio De Castillia
Manuscript citation:
Rigano, A., Ehmsen, S., Öztürk, S.U. et al. Micro-Meta App: an interactive tool for collecting microscopy metadata based on community specifications. Nat Methods 18, 1489–1495 (2021). https://doi.org/10.1038/s41592-021-01315-z
License: This is an open access protocol distributed under the terms of the Creative Commons Attribution License,  which permits unrestricted use, distribution, and reproduction in any medium, provided the original author and source are credited
Protocol status: Working
We use this protocol and it's working
Created: March 08, 2023
Last Modified: March 08, 2023
Protocol Integer ID: 78314
Keywords: Research Data Management, Metadata, Reproducibility, Rigor, Quality Control, Data Sharing
Funders Acknowledgement:
Chan Zuckerberg Initiative DAF, Imaging Scientist Program
Grant ID: 2019-198155 (5022)
Chan Zuckerberg Initiative DAF, Imaging Scientist Program
Grant ID: 2020-225398
USA - National Institutes of Health
Grant ID: U01CA200059
USA - National Institutes of Health
Grant ID: 1U01EB021238
USA - National Institutes of Health
Grant ID: 8U01DA047733-05
USA - National Science Foundation
Grant ID: 1917206
Abstract
For quality, interpretation, reproducibility, and sharing value, microscopy images should be accompanied by detailed descriptions of the conditions that were used to produce them. Micro-Meta App is an intuitive, highly interoperable, open-source software tool that was developed in the context of the 4D Nucleome (4DN) consortium and is designed to facilitate the extraction and collection of relevant microscopy metadata as specified by the recent 4DN-BINA-OME tiered-system of Microscopy Metadata specifications. In addition to substantially lowering the burden of quality assurance, the visual nature of the Micro-Meta App makes it particularly suited for training purposes.

In this protocol and in the associated videos (https://youtube.com/playlist?list=PLd2SsBj4SIsh7eE1M7l4v5_EsjUQcsfb0) you will learn how to get started using the Micro-Meta App for documenting your imaging experiments.

Want to learn more?
Please watch Video 1 of the Tutorial Series and read the publications listed in the References section of this protocol to learn more about the Micro-Meta App and the underlying 4DN-BINA-OME tiered system of Microscopy Metadata specifications.
Guidelines
These instructions are designed to help you best take advantage of a series of video Tutorials that were developed to help you get started using Micro-Meta App to document imaging experiments. You can find these video Tutorials on YouTube at the following link: https://youtube.com/playlist?list=PLd2SsBj4SIsh7eE1M7l4v5_EsjUQcsfb0


Need help?
Please contact us at:
  • Caterina Strambio De Castillia (caterina.strambio@umassmed.edu)
  • Alex Rigano (alex.rigano@umassmed.edu)
Materials
To participate in this tutorial, you will need the following material:

The Unarchiver.app
If you plan to use Micro-Meta App on Mac OS, we recommend that you use The Unarchiver.app to de-compress the Zip archive you will download from GitHub. The reason is that the Unarchiver App appears to work better than the unarchiver utility that is available on Mac OS.
To download The Unarchiver.app please click on the link below and follow the instructions you will find therein:

Java
For full functionality, Micro-Meta App requires Java 8 (v1.8.xxx) or later.
  1. To check the default Java version available on your system, please follow the instructions found here: https://tinyurl.com/3nm7xcph.
  2. If you do not have the correct version, please download it using the instructions here: https://tinyurl.com/5n84xv57.

Example metadata files to use in the tutorial
To perform this tutorial, you will need to download the following example metadata files:
  • Microscope.JSON file: A file that contains a description of the hardware components of an example microscope.
  • Settings.JSON file: A file containing a description of the settings that were used to acquire the example image data file.
  • Raw-image data file: An image data file that was acquired using the hardware specifications and acquisition settings described in the Microscope.JSON and Settings.JSON files.

1) To download the example metadata files described above, please click on the link below:
2) After downloading the three files, please move them to a new folder in your favorite location and call the folder “MMA Tutorial”
3) If you need help, please follow the instructions in these two videos that describe how to download and use Micro-Meta App example metadata files:

Template metadata files
A set of Microscopy Metadata (Microscope.JSON and Settings.JSON) files were produced using the Micro-Meta App to document the Hardware Specifications of a variety of example microscopes and the Image Acquisition Settings associated with a variety of example image data files at 16 different core facilities around the world (https://doi.org/10.1038/s41592-021-01315-z).
These files are provided here as templates to use as a starting point to document similar microscopy experiments in your lab:


Before start
In order to participate in this tutorial, you will need some prerequisites and materials that are described in the Materials section of this protocol.
In particular, before you start you will need to download the following example metadata files:
  • Microscope.JSON file: A file that contains a description of the hardware components of an example microscope.
  • Settings.JSON file: A file that contains a description of the settings that were used to acquire the example image data file.
  • Raw-image data file: An image data file that was acquired using the hardware specifications and acquisition settings described in the Microscope.JSON and Settings.JSON files.

Before the tutorial
Before the tutorial
Video introduction


Note
This video provides a general introduction to the importance of Research Data Management to promote reporting and reproducibility in microscopy.

https://www.youtube.com/embed/lNumFns3yMQ

















Note
This short introductory video explains the purpose and general functionality of the Micro-Meta App.

https://player.vimeo.com/api/player.js

Note
To perform this tutorial, you will need to download the following example metadata files from Zenodo:
  • Microscope.JSON file: A file that contains a description of the hardware components of an example microscope.
  • Settings.JSON file: A file containing a description of the settings that were used to acquire the example image data file.
  • Raw-image data file: An image data file that was acquired using the hardware specifications and acquisition settings described in the Microscope.JSON and Settings.JSON files.

1) After downloading the three files, please move them to a new folder in your favorite location and call the folder “MMA Tutorial”
2) If you need help, please follow the instructions in these two videos that describe how to download and use Micro-Meta App example metadata files:


Tutorial - 1 - Download and Install Micro-Meta App
Tutorial - 1 - Download and Install Micro-Meta App
Download Micro-Meta App

  • Follow the instructions in this step and in Video 3 of the tutorial series to download and install the stand-alone version of the Micro-Meta App.

Note
If you need further instructions you can find them on ReadTheDocs.

Critical
Click on this link to access the Download page
Download and save ZIP file
  • Once you are on the download page please navigate to the bottom page and identify the ZIP file that is best suited for your operating system.
  • "Right-click" on the link and select "Save Link As..."
  • Save the ZIP file to the "MMA Tutorial" folder you have created to save the example metadata files (see the instructions that are found in the Materials section of this protocol).
Critical
Unarchive the ZIP file and launch Micro-Meta App
  • Unarchive the ZIP file by following the instructions that are appropriate for your operating system.
Note
IMPORTANT NOTE:
If you are planning to use Micro-Meta App on Mac OS, DO NOT USE the native Mac OS unarchiver utility to unzip the ZIP file. Instead, we strongly recommend that you use The Unarchiver.app.
For additional instructions please refer to the Materials section of this protocol.

In order to use The Unarchiver.app instead of the native unarchiver Mac OS utility, follow these instructions
  • Locate the downloaded micro-meta-app-electron-XXX-mac.zip file
  • "Right-click" (do not double click) on the ZIP file
  • Click on "Open-with"
  • Select "The Unarchiver.app" from the menu

Note
Micro-Meta App installation:
To install Micro-Meta App on your computer, you need to drag and drop the unarchived executable file to your favorite location.

Launch Micro-Meta App
  • Launch the Micro-Meta App by following the instructions that are appropriate for your operating system.
Note
IMPORTANT NOTE:
If you are planning to use Micro-Meta App on Mac OS, please use the special instructions below when you launch the app for the first time.

  • Locate the icon corresponding to the unzipped Micro-Meta App executable file.
  • "Right-click" (do not double click) on the executable file and select "Open".
  • The system will give you an error message, click on "Cancel"
  • Right-click" (do not double-click) on the executable file and select "Open", again.
  • The system will give you an error and request if you want to continue, click on "OK".
  • From this point forward, it will be possible to launch the app by double-clicking on the executable file icon.

Tutorial - 2 - Manage Instrument
Tutorial - 2 - Manage Instrument
Manage Instrument
In this section of the tutorial, you will learn how to use the Manage Instrument functionality of Micro-Meta App to open an existing Microscope.JSON file and to create a simple new Microscope.JSON file from scratch.

To learn more about the Tier system of Microscopy Metadata used as the basis of Micro-Meta App please read the following publication:
CITATION
Hammer M, Huisman M, Rigano A, Boehm U, Chambers JJ, Gaudreault N, North AJ, Pimentel JA, Sudar D, Bajcsy P, Brown CM, Corbett AD, Faklaris O, Lacoste J, Laude A, Nelson G, Nitschke R, Farzam F, Smith CS, Grunwald D, Strambio-De-Castillia C (2021). Towards community-driven metadata standards for light microscopy: tiered specifications extending the OME model.. Nature methods.
LINK
https://doi.org/10.1038/s41592-021-01327-9

Open and inspect an existing Microscope.JSON file
In this part of the tutorial, you will learn how to open and inspect an existing Microscope.JSON file to evaluate its content and decide whether it needs further editing.
To get started, follow these steps:
  • Launch Micro-Meta App as described Go togo to step #2.4
  • Click on "Continue".
  • Click on “Manage Instrument”.
  • Click on "Tier 3,".
  • Click on “Import from file” and select the example Microscope.JSON file downloaded from Zenodo as described in the MATERIALS section and above Go togo to step #1 , and click on "Continue".
  • Follow the instructions in Video 4 of the Tutorial series to explore the hardware specifications metadata contained in the example Microscope.JSON file.

In this step, you will learn how to navigate and explore the hardware components of an existing Microscope.JSON file.

Create a new Microscope.JSON file from scratch
In this part of the tutorial, you will learn how to create a new Microscope.JSON file that describes a Tier 1 microscope that is only used for qualitative or simple quantitative experiments.
To get started follow the steps hereinafter:
  • Launch Micro-Meta App as described Go togo to step #2.4
  • Click on "Continue".
  • Click on “Manage Instrument”.
  • Click on "Tier 1".
  • Click on “Create Inverted from scratch” , and click on "Continue".
  • Follow the instructions in Video 5 of the tutorial series to add the following hardware components to the Microscope canvas and enter the hardware specifications listed in the specification files found following the links listed below:
→ Microscope Stand → Zeiss Axio-Observer
→ Fluorescence Light Source/LED → Zeiss Colibri 5/7 LED
→ Magnification/Objective → Zeiss PlanApo 63x/1.4
→ Fluorescence Light Path/Filter Cube
- Filter Set → Multiband filter set, optimized for GFP & DsRed ○ Excitation Filter ○ Emission Filter ○ Dichroic beamsplitter
→ Detector → Andor iXon Life 888 camera

In this step, you will learn how to create a new Microscope.JSON file and enter Tier 1 information about essential hardware components.

Tutorial - 3 - Manage Settings
Tutorial - 3 - Manage Settings
Manage Settings
In this section of the tutorial, you will learn how to use the Manage Settings functionality of theMicro-Meta App to open an existing Settings.JSON file, inspect its content and add a missing transmitted light Channel.
Open and inspect an existing Settings.JSON file
In this part of the tutorial, you will learn how to open and inspect an existing Settings.JSON file to evaluate its content and decide whether it needs further editing.
  • Launch Micro-Meta App as described Go togo to step #2.4
  • Click on "Continue".
  • Click on “Manage Settings.
  • Click on "Tier 3".
  • Click on “Import from file”, select the example Microscope.JSON file downloaded from Zenodo as described in the MATERIALS section and above Go togo to step #1 , and click "Continue".
  • Click on “Import from file”, select the example image-data file downloaded from Zenodo as described in the MATERIALS section and above Go togo to step #1 , and click "Continue".
  • Click on “Import from file” , select the example Settings.JSON file downloaded from Zenodo as described in the MATERIALS section and above Go togo to step #1 , and click "Continue".
  • Follow the instructions in Video 6 of the tutorial series to explore the image acquisition metadata contained in the example Settings.JSON file.

In this step, you will learn how to navigate and explore the acquisition settings that were used to acquire an example image data file and which were stored in an existing Settings.JSON file.

Add an additional transmitted light Channel to an existing Settings.JSON file
  • Follow the steps described here Go togo to step #4.1
  • Click on "Edit Channels".
  • Click on the "+" button, click on "Channel 3", and click on "Edit selected".
  • Follow the instructions in Video 7 of the tutorial series to enter information about a new transmittance light Channel in an existing Settings.JSON file.

In this step, you will learn how to add an additional Transmittance Light channel to an existing Settings.JSON file.

After the tutorial
After the tutorial
Provide feedback
After testing the Micro-Meta App, we would love to have your feedback.
Want to learn more?
Please read the publications and consult the resources listed below to learn more about Micro-Meta App, the underlying 4DN-BINA-OME tiered system of Microscopy Metadata specifications, and related metadata collection tools.
Community-driven 4DN-BINA-OME (NBO) Microscopy Metadata Specifications
To learn more about the 4DN-BINA-OME tiered system of Microscopy Metadata specifications that underlies the Micro-Meta App please consult the resources below:

CITATION
Hammer M, Huisman M, Rigano A, Boehm U, Chambers JJ, Gaudreault N, North AJ, Pimentel JA, Sudar D, Bajcsy P, Brown CM, Corbett AD, Faklaris O, Lacoste J, Laude A, Nelson G, Nitschke R, Farzam F, Smith CS, Grunwald D, Strambio-De-Castillia C (2021). Towards community-driven metadata standards for light microscopy: tiered specifications extending the OME model.. Nature methods.
LINK
https://doi.org/10.1038/s41592-021-01327-9


Software
4DN-BINA-OME Microscopy Metadata Specifications
NAME
Mathias Hammer, Alessandro Rigano, Caterina Strambio-De-Castillia
DEVELOPER
https://github.com/WU-BIMAC/NBOMicroscopyMetadataSpecs
SOURCE LINK

Note
Submit issues, suggestions, questions, requests for model extensions
→ https://github.com/WU-BIMAC/NBOMicroscopyMetadataSpecs/issues



Micro-Meta App
To learn more about the Micro-Meta App please consult the resources below:

CITATION
Rigano A, Ehmsen S, Öztürk SU, Ryan J, Balashov A, Hammer M, Kirli K, Boehm U, Brown CM, Bellve K, Chambers JJ, Cosolo A, Coleman RA, Faklaris O, Fogarty KE, Guilbert T, Hamacher AB, Itano MS, Keeley DP, Kunis S, Lacoste J, Laude A, Ma WY, Marcello M, Montero-Llopis P, Nelson G, Nitschke R, Pimentel JA, Weidtkamp-Peters S, Park PJ, Alver BH, Grunwald D, Strambio-De-Castillia C (2021). Micro-Meta App: an interactive tool for collecting microscopy metadata based on community specifications.. Nature methods.
LINK
https://doi.org/10.1038/s41592-021-01315-z


Software
Micro-Meta App
NAME
MacOS, Windows
OS
Alessandro Rigano, Caterina Strambio-De-Castillia
DEVELOPER
https://github.com/WU-BIMAC/MicroMetaApp-Electron
SOURCE LINK

Note
ReadTheDocs
Full documentation and video tutorials for Micro-Meta App can be found on ReadTheDocs at:
→ https://micrometaapp-docs.readthedocs.io


Other metadata collection tools
To learn more about other interoperable metadata collection tools please consult the resources below:

CITATION
Ryan J, Pengo T, Rigano A, Llopis PM, Itano MS, Cameron LA, Marqués G, Strambio-De-Castillia C, Sanders MA, Brown CM (2021). MethodsJ2: a software tool to capture metadata and generate comprehensive microscopy methods text.. Nature methods.
LINK
https://doi.org/10.1038/s41592-021-01290-5

Software
MethodsJ2
NAME
Joel Rigano, Claire M. Brown
DEVELOPER
https://github.com/ABIF-McGill/MethodsJ2
SOURCE LINK

CITATION
Kunis S, Hänsch S, Schmidt C, Wong F, Strambio-De-Castillia C, Weidtkamp-Peters S (2021). MDEmic: a metadata annotation tool to facilitate management of FAIR image data in the bioimaging community.. Nature methods.
LINK
https://doi.org/10.1038/s41592-021-01288-z

Note
ReadTheDocs
Full documentation for MDEmic can be found on ReadTheDocs at:
→ https://omero-guides.readthedocs.io/en/latest/mde/docs/index.html



Get more involved
If you want to get more involved and help us with developing or testing Micro-Meta App please join us by joining the QUAREP-LiMi Working Group WG7 on Metadata by clicking on the link below:

CITATION
Boehm U, Nelson G, Brown CM, Bagley S, Bajcsy P, Bischof J, Dauphin A, Dobbie IM, Eriksson JE, Faklaris O, Fernandez-Rodriguez J, Ferrand A, Gelman L, Gheisari A, Hartmann H, Kukat C, Laude A, Mitkovski M, Munck S, North AJ, Rasse TM, Resch-Genger U, Schuetz LC, Seitz A, Strambio-De-Castillia C, Swedlow JR, Nitschke R (2021). QUAREP-LiMi: a community endeavor to advance quality assessment and reproducibility in light microscopy.. Nature methods.
LINK
https://doi.org/10.1038/s41592-021-01162-y

Citations
Step 3
Hammer M, Huisman M, Rigano A, Boehm U, Chambers JJ, Gaudreault N, North AJ, Pimentel JA, Sudar D, Bajcsy P, Brown CM, Corbett AD, Faklaris O, Lacoste J, Laude A, Nelson G, Nitschke R, Farzam F, Smith CS, Grunwald D, Strambio-De-Castillia C. Towards community-driven metadata standards for light microscopy: tiered specifications extending the OME model.
https://doi.org/10.1038/s41592-021-01327-9
Step 6.1
Hammer M, Huisman M, Rigano A, Boehm U, Chambers JJ, Gaudreault N, North AJ, Pimentel JA, Sudar D, Bajcsy P, Brown CM, Corbett AD, Faklaris O, Lacoste J, Laude A, Nelson G, Nitschke R, Farzam F, Smith CS, Grunwald D, Strambio-De-Castillia C. Towards community-driven metadata standards for light microscopy: tiered specifications extending the OME model.
https://doi.org/10.1038/s41592-021-01327-9
Step 6.2
Rigano A, Ehmsen S, Öztürk SU, Ryan J, Balashov A, Hammer M, Kirli K, Boehm U, Brown CM, Bellve K, Chambers JJ, Cosolo A, Coleman RA, Faklaris O, Fogarty KE, Guilbert T, Hamacher AB, Itano MS, Keeley DP, Kunis S, Lacoste J, Laude A, Ma WY, Marcello M, Montero-Llopis P, Nelson G, Nitschke R, Pimentel JA, Weidtkamp-Peters S, Park PJ, Alver BH, Grunwald D, Strambio-De-Castillia C. Micro-Meta App: an interactive tool for collecting microscopy metadata based on community specifications.
https://doi.org/10.1038/s41592-021-01315-z
Step 6.3
Ryan J, Pengo T, Rigano A, Llopis PM, Itano MS, Cameron LA, Marqués G, Strambio-De-Castillia C, Sanders MA, Brown CM. MethodsJ2: a software tool to capture metadata and generate comprehensive microscopy methods text.
https://doi.org/10.1038/s41592-021-01290-5
Step 6.3
Kunis S, Hänsch S, Schmidt C, Wong F, Strambio-De-Castillia C, Weidtkamp-Peters S. MDEmic: a metadata annotation tool to facilitate management of FAIR image data in the bioimaging community.
https://doi.org/10.1038/s41592-021-01288-z
Step 7
Boehm U, Nelson G, Brown CM, Bagley S, Bajcsy P, Bischof J, Dauphin A, Dobbie IM, Eriksson JE, Faklaris O, Fernandez-Rodriguez J, Ferrand A, Gelman L, Gheisari A, Hartmann H, Kukat C, Laude A, Mitkovski M, Munck S, North AJ, Rasse TM, Resch-Genger U, Schuetz LC, Seitz A, Strambio-De-Castillia C, Swedlow JR, Nitschke R. QUAREP-LiMi: a community endeavor to advance quality assessment and reproducibility in light microscopy.
https://doi.org/10.1038/s41592-021-01162-y