Main

For microscopy images to be appropriately interpreted and reproduced, and to satisfying Findable Accessible Interoperable and Reusable (FAIR) principles1, they should be accompanied by detailed descriptions of microscope hardware, image acquisition settings, image pixel and dimensional structure and instrument performance. Currently, documentation of imaging experiments is seriously impaired by the lack of easy-to-use software tools that facilitate the extraction and collection of relevant microscopy metadata. Micro-Meta App is an intuitive open-source software designed to tackle these issues that has been developed in the context of the 4D Nucleome (4DN) consortium2,3, and of nascent global bioimaging community organizations, including BioImaging North America (BINA)4,5 and Quality Assessment and Reproducibility in light microscopy (QUAREP-LiMi)6,7,8, whose goal is to improve reproducibility, data quality and sharing value for imaging experiments. The App provides a visual interface for building comprehensive descriptions of the conditions used to produce microscopy datasets as specified by the 4DN-BINA-OME tiered-system of Microscopy Metadata specifications9,10,11,12,13. To ensure wide adoption by microscope users with different skill levels and needs, Micro-Meta App is ideally suited for training purposes and interoperates closely with MethodsJ2 (refs. 14,15) and OMERO.mde16,17, two complementary tools described in parallel manuscripts.

Microscopy metadata improve data quality and reproducibility

In addition to providing essential information about the provenance (that is, origin, lineage)18,19 of microscopy results, the establishment of community-driven, documentation and quality control (QC) specifications for light microscopy would make it possible to faithfully interpret scientific claims, facilitate comparisons within and between experiments, foster reproducibility and maximize the likelihood of data reuse6,7,8,20,21,22,23,24,25. First and foremost, such information would facilitate the compilation of accurate Methods sections for scientific publications26,27,28,29. Furthermore, it would provide clear guidance to microscope and software manufacturers about what information should be written automatically in the headers of image files during image acquisition to ensure scientific rigor. Finally, machine-actionable versions of the same information30 could be uploaded alongside image-datasets on the growing number of public image data resources22,31,32,33,34,35,36,37,38,39,40,41,42,43 that allow the deposition of raw image data associated with scientific manuscripts, emulating for light microscopy the successful path that led to genomics community standards44,45,46,47,48.

To promote the development of shared standards, the NIH-funded 4DN2,3 and the CZI-funded BINA4,5 have recently proposed the 4DN-BINA-OME (NBO) Microscopy Metadata specifications9,10,11,12,13. These specifications consist of an extension of the Open Microscopy Environment (OME) data model (that is, the basis for the widely adopted BioFormats library)49,50,51,52, which is organized in three tiers (details in Supplementary Information), and allows the classification of imaging experiments into levels of increasing complexity11,12,13,53. These specifications not only provide an OME-based comprehensive set of metadata that should be recorded, but they also specify which information subset should be included depending on experimental intent, technical intricacy and image analysis needs. The 4DN-BINA-OME specifications lay the foundations for upcoming community-sanctioned standards being developed by QUAREP-LiMi6,7. Their purpose is to provide a scalable, interoperable and OME-Next-Generation File Format (NGFF)54,55 compatible framework, guiding scientists as to what provenance metadata and calibration metrics should be afforded to ensure quality, reproducibility and value for different categories of light microscopy experiments.

To render metadata specifications and QC standards actionable and easy to adopt, experimental scientists require software tools (or, even better, automated pipelines) to easily extract all available metadata from microscope configuration and image files and produce well-documented, high-quality, reproducible and reusable datasets. Despite some advances26,56,57, current tools offer limited functionalities, and are not integrated with community standards. Here, we present a suite of three interoperable software tools (Extended Data Fig. 1) that were developed to provide complementary, intuitive approaches for the bench-side collection of experimental and microscopy metadata10,11,13. In two related manuscripts, we describe: (1) OMERO.mde, which emphasizes the development of flexible, nascent specifications for experimental metadata16,17,58 and (2) the ImageJ/Fiji MethodsJ2 plugin14,15, which automatically generates Methods for scientific publications. Here, we present Micro-Meta App (Figs. 1 and 2 and Supplementary Video 1), which works both as a stand-alone app and as an integrated resource in web repositories2,59,60. It offers a visual guide to navigate the steps required for the rigorous documentation of imaging experiments as sanctioned by 4DN-BINA-OME11,12,13,59.

Fig. 1: Micro-Meta App data processing workflows.
figure 1

Flowchart depicting the three sections of Micro-Meta App (1). a, The function of the initial section is to select among the three available 4DN-BINA-OME11,13 documentation tier levels (2), which is most appropriate for a given experimental -design, instrument-complexity and image analysis needs (details in Supplementary Information). b, The purpose of the Manage Instrument section is to create (or edit) a visual representation of the hardware configuration of a given microscope, which is then saved in a Microscope.JSON file (3) containing a list of components and associated 4DN-OME-BINA-specified metadata-information. c, The aim of the Manage Settings section is to collect relevant hardware information from an existing Microscope.JSON file (3), use BioFormats52 to retrieve existing OME-compatible microscopy metadata from an image of interest (4) and create (or edit) a Settings.JSON file (5) containing a rigorous description of the acquisition settings used for a given imaging experiment.

Fig. 2: Micro-Meta App allows the intuitive and interactive documentation of imaging experiments.
figure 2

a, Illustrated is the use of the Manage Instrument section of Micro-Meta App to build a graphical record of the hardware components comprising the TIRF Epifluorescence Structured light Microscope (TESM) that was custom built at the Biomedical Imaging Group of UMass Chan Medical School. The resulting diagram allows the collection of all metadata-information sanctioned by Tier 3 (Fig. 1 and Supplementary Information) of the 4DN-BINA-OME model11,13. Specifically, by clicking on icons representing individual hardware components (for example, Objective, Filter Set or Camera), it is possible to record specific information describing each of them (for example, Objective Manufacturer, Model, Magnification and Numerical Aperture (NA)). b, Photograph depicting the TESM microscope illustrated in a. c, Use of the Manage Settings section of Micro-Meta App to build a graphical record of the lightpath (that is, from the illumination source to the detector) used for the acquisition of the 4,6-diamidino-2-phenylindole (DAPI) channel of the image in d. As shown, clicking on icons positioned along the lightpath it is possible to record the acquisition parameters (for example, Camera Bit Depth, Amplification Gain, Binning, etc.) that were used during the acquisition of a given image. d, Representative image obtained using the indicated microscope and settings (a and c).

Micro-Meta App: intuitive microscopy experiment documentation

In the absence of tools that expedite image data documentation and QC, the metadata provided by manufacturers often does not align with existing minimal information criteria (that is, OME and BioFormats)50,52 and, as a consequence, is extremely variable, interfering with quality assessment, reproducibility and meaningful reuse of third-party datasets (Extended Data Figs. 2 and 3). Micro-Meta App, developed to address these unmet needs, consists of an interactive open-source and interoperable software tool to facilitate and (where possible) automate the annotation of light microscopy datasets. It provides a visual approach for documenting imaging experiments based on available OME-compatible community-sanctioned tiered systems (details in Supplementary Information) of specifications, such as 4DN-BINA-OME11,12,13,53. Thus, Micro-Meta App can adapt to varying levels of imaging complexity and to evolving data-models emerging from the community. To this aim, Micro-Meta App uses two parallel dataflows (Fig. 1):

  1. 1.

    In ‘Manage Instrument’ (hardware specifications; Figs. 1b and 2a and Extended Data Fig. 4) microscope users and custodians create accurate graphical depictions of microscope configurations by dragging-and-dropping icons representing hardware components onto the workspace while collecting relevant information scaling with microscope modality, experimental design, instrument-complexity and image analysis needs according to the 4DN-BINA-OME tier-level system11,12,13,53. From this, Micro-Meta App automatically generates interoperable Microscope.JSON files containing structured descriptions of the microscope Hardware Specifications (examples illustrated in Supplementary Information)61 that can be saved locally, and shared with other scientists via community repositories such as the 4DN-Data-Portal2,29,60,62, thus substantially lowering the burden of rigorous record-keeping and facilitating dissemination. Furthermore, such files can be imported in MethodsJ2 to automatically generate the Methods and Acknowledgement sections of scientific publications14,15.

  2. 2.

    To document the conditions used to produce specific image-datasets, ‘Manage Settings’ (Figs. 1c and 2b and Extended Data Fig. 5) (1) automatically extracts Hardware Specifications metadata from available Microscope.JSON files, (2) uses BioFormats52 to import OME metadata stored in the header of image files (Extended Data Figs. 2 and 3) and (3) interactively guides the user to enter missing, instrument-specific, tier-appropriate, 4DN-BINA-OME sanctioned ‘Settings’ metadata used during the relevant ‘Image Acquisition’ session. From this, the App generates interoperable Settings.JSON files containing comprehensive documentation of the ‘Image Acquisition Settings’ relative to individual microscopy datasets (examples illustrated in Supplementary Information)61. These files can be stored as described in (1) and associated with related Microscope.JSON files and image-datasets to ensure proper imaging experiment documentation.

Detailed descriptions of the functionality, implementation and documentation material of Micro-Meta App are available in Supplementary Information, Methods and ref. 63.

Case studies: use at core facilities

To demonstrate feasibility and test usability, Micro-Meta App was employed, with minimal initial training, at 16 partnering core facilities (Extended Data Fig. 6) to document both example microscope instrumentation and the settings used for the acquisition of exemplar image-datasets (Fig. 2, Extended Data Figs. 7–9 and Supplementary Figs. 3–15)64,65,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80,81,82,83. The most striking result (detailed in Supplementary Information) was that, in comparison with the baseline represented by BioFormats alone (Extended Data Figs. 2 and 3), the use of Micro-Meta App considerably increased the uniformity of reported metadata fields, facilitating comparison of image data within and across different microscopes and imaging experiments. In addition, since the App’s data model is defined dynamically on the basis of shared and evolving community specifications, the use of this method maximizes reproducibility, quality and value, while minimizing effort on the part of individual scientists. Example Microscope.JSON, Settings.JSON and image files produced for the use case in Extended Data Fig. 9 are publicly available on Zenodo as illustrated in the Data Availability section and in Supplementary Information61.

Case studies: integration to 4DN-Data-Portal

An initial impetus for the development of Micro-Meta App was the need to expedite and, where possible, automate the rigorous reporting of imaging experiments and QC procedures for the purpose of integrating 4DN imaging and omics experiments2. Thus, the Micro-Meta App was embedded into the 4DN-Data-Portal (Extended Data Fig. 10)59,60,62 and the content of the Microscope .JSON file was integrated directly into the portal’s database. This allows microscopy metadata associated with individual experiments to be used for searching, filtering and visualization purposes.

Case studies: teaching with Micro-Meta App

Micro-Meta App provides a digital representation of freely configurable microscopes, ideal for microscopy custodians to provide users with a detailed inventory of all available microscopes and for teaching purposes (Supplementary Video 1). Micro-Meta App was used by graduate students at UMass Medical School84 for working on (1) specific problem sets and (2) self-driven exploration of microscope components, functions and imaging modalities. The success of these pilots indicates that Micro-Meta App could be used in online teaching-modules (for example, GlobalBioImaging (GBI) Training Resources)85 for familiarizing users with the intricacies of specific instrument hardware configurations and for the interactive application of microscopy concepts.

Future directions

Micro-Meta App has been developed and will continue to evolve in close collaboration with communities that include 4DN2,3, BINA5, GBI86 and QUAREP-LiMi6,7,8,87. Ongoing efforts include:

  1. 1.

    Outreach and education: to increase awareness and promote adoption of microscopy documentation and QC, and disseminate the use of Micro-Meta App, we have initiated an extensive outreach effort directed towards microscope users, custodians and manufacturers, which includes university classes (Case Studies), online training and workshops88,89,90. This will be augmented with specialized inperson courses as circumstances allow and in close collaboration with our community partners91,92.

  2. 2.

    Creation of Instrument and Hardware components databases: while engaging with microscopy manufacturers to ensure the full automation of light microscopy data provenance and QC reporting, it will be necessary to engage the community to reduce the burden imposed on individual microscope custodians and users that need to document similar imaging experiments, therefore maximizing their adoption of community standards. For this purpose, and echoing 4DN59,60,62, we are developing exchange-sites for microscopy metadata JSON files, similar to ImageJ/Fiji plugin repositories. Furthermore, integration with the Research Resource ID (RRID) effort93 could promote the recognition of microscope configurations as a quantifiable scientific output, providing credit to the work of imaging scientists.

  3. 3.

    Further integration with MethodsJ2: Micro-Meta App will be extended to automatically generate text for scientific publications and MethodsJ2 (refs. 14,15) will be adapted to use Micro-Meta App Settings.JSON files as sources of image acquisition settings and QC metadata.

  4. 4.

    Further OMERO and OMERO.mde integration: a pilot Micro-Meta App OMERO plugin is available94. Future development will include extracting experimental metadata developed using OMERO.mde16,17 and saving 4DN-BINA-OME metadata11,12,13 as collections of key-value pairs associated with individual OMERO image-datasets.

  5. 5.

    Implementation of additional microscopy modalities and QC: currently, the App implements the Core OME data model and the 4DN-BINA-OME Basic extension11,12,13. Efforts to implement the Confocal and Advanced as well as the Calibration and Performance 4DN-BINA-OME extensions are underway. As a proof-of-concept, we are collaborating with QUAREP-LiMi95 to automatically annotate imaging datasets with calibration metrics calculated using the open-hardware Meta-Max96 calibration tool.

Conclusions

Easily accessible and facile tools such as Micro-Meta App, MethodsJ2 and OMERO.mde are essential for microscope custodians and users to see image data documentation and QC as routine tasks in their imaging workflow, therefore promoting better quality, reproducibility and value for imaging data. In addition, reaching this goal will entail partnering with manufacturers to promote the automated interpretation of metadata stored in image file headers, the development of community-wide repositories for microscopy hardware metadata specifications and the automated annotation of datasets to be uploaded in imaging data repositories30. Thus, key support from funding agencies and institutions will ultimately lead to automating all aspects of the process used by members of the community to annotate and upload metadata-rich imaging datasets to both local and public repositories38,40,51. As an added advantage, full documentation of the provenance and QC of imaging experiments will be key for the development of pipelines to integrate images and their metadata with -omics data from the same experiment, such as is underway as part of 4DN.

Methods

Software implementation

Micro-Meta App is available in two JavaScript (JS) implementations. The first was designed to facilitate integration of the software into third-party web portals, such as the 4DN-Data Portal)2,59,60,62,97 and OMERO94, and was developed using the JS React library, which is used widely to build web-based user interfaces. Starting from this version, a stand-alone version of the App was developed by wrapping the React implementation using the JS Electron library, with the specific purpose of lowering the barrier of adoption of the tool by laboratories that do not have access to, or prefer not to use, imaging databases.

Dependencies

For the Micro-Meta App to work, the following elements are generated in advance as described in the following sections and made available via GitHub:

  1. 1.

    JSON schema: a JSON file or a series of files that define the underlying schema, which are used to construct the graphical user interface (GUI) of the application on the basis of the 4DN-BINA-OME Microscopy Metadata specifications11,12,13.

  2. 2.

    Dimensions and coordinates: a JSON file that codifies the dimensions of the canvases used by the Manage Instrument GUI of the Micro-Meta App as well as the position on the canvas occupied by icons representing each microscope hardware component.

  3. 3.

    Icons: a series of SVG files, each containing an icon representing the individual hardware components.

In addition, the stand-alone version of Micro-Meta App depends on the 4DN Microscopy Metadata Reader98, which implements the BioFormats library52 to allow the user to import known OME metadata directly from the file header of an image data file of interest. To maximize flexibility, these elements can be customized to meet the needs of individual users.

XSD to JSON schema converter

The main function of this Java-encoded component99 is to transform the XML schema definition (XSD) implementation of the 4DN-BINA-OME data model11,12,13,100 into a JSON-based schema, which is subsequently ingested by Micro-Meta App to automatically generate the software GUI and the associated data insertion forms. The XSD to JSON schema converter middleware uses the Xerces2 Java XML Parser101 and W3C Java XML bindings libraries102 to navigate the XSD schema, and produces two kinds of version-aware JSON files:

  1. 1.

    A comprehensive JSON file containing an array of schemas for all necessary individual components that constitute the 4DN-BINA-OME data model (for example, Objective, Filter or Detector). This comprehensive JSON file is made available on GitHub and is designed specifically to facilitate the remote loading of the schema by web portal embedded React implementations of the Micro-Meta App. This schema is available as an individual file on GitHub (https://github.com/WU-BIMAC/4DNMetadataSchemaXSD2JSONConverter/blob/master/latest/fullSchema.json).

  2. 2.

    A series of JSON files, each containing the schema of individual components, which were designed to be employed by the Electron implementation of the App. These individual schema files are available within a subdirectory of the main repository on GitHub (https://github.com/WU-BIMAC/4DNMetadataSchemaXSD2JSONConverter/tree/master/latest/schemas).

The middleware was designed specifically to maximize flexibility and extensibility. As such, the software allows the introduction of implementation-specific modifications of the resulting JSON schema so that it can be adapted for special purposes. For example, the introduction of a ‘Version’ field allows validation of whether the data being saved is compatible with the specific version of the schema being employed. As a further example, the introduction of the ‘Category’ field allows the organization of different components in specific submenus across the sidebar. To facilitate the evolution of the model while ensuring back-compatibility, the GitHub repository supports versioning by storing all revisions of the output JSON schema.

TXT to JSON dimensions converter

This Java-encoded component99 is used to process an input text file containing the dimensions of the Manage Instrument canvas of Micro-Meta App alongside the desired x,y positions where each icon has to be placed. As a result, the software produces a Dimensions and Coordinate JSON file that is made available for remote loading from GitHub (https://github.com/WU-BIMAC/4DNMetadataSchemaXSD2JSONConverter/tree/master/latest/dimensions)99 and is ready to be used to implement the ‘snap-in-place’ functionality of the software.

ICON

Scalable vector graphic (SVG) files containing icons representing the different microscope hardware components were generated specifically for this project and are made available in a version-aware manner for remote loading from GitHub (https://github.com/WU-BIMAC/4DNMetadataSchemaXSD2JSONConverter/tree/master/latest/images)99. Custom-made icons can be similarly generated by developer users and manufacturers for representation of their hardware components within the application.

Microscopy metadata reader

This software is written in JAVA to fully take advantage of the BioFormats library and the OME-XML metadata structure98. Using these two dependencies, this software accesses all the OME-compatible metadata present in user-selected images and maps it to the 4DN-BINA-OME microscopy metadata specifications11,12,13 that extend the OME Data Model50,52 to produce a temporary, Micro-Meta App-compatible JSON object that can be read by Micro-Meta App. The object is then passed on to the Micro-Meta App and read by the Manage Settings section of the App to prepopulate the corresponding metadata fields.

JS React implementation of Micro-Meta App

This is the core implementation of the Micro-Meta App, and it is the starting point for embedding it into a third-party web portal, and for wrapping it into Electron for local execution97. This component ingests JSON schema files, JSON Dimension and Coordinate files and Icon images produced as described above and uses a series of custom React classes to produce a set of individual windows composing the GUI. Specifically, these windows can be categorized into two main sections: the Manage Instrument and the Manage Settings (Figs. 1 and 2 and Supplementary Figs. 2 and 3). In the Manage Instrument section, the application employs a Canvas setup that provides the flexibility to incorporate as many icon elements as necessary to describe the hardware components of any given microscope. For this purpose, the toolbar is generated dynamically as dictated by the underlying JSON schema produced as described above and by the selected tier level. On this basis, elements present in each of the graphical menus present on the sidebar can be dragged to the canvas and dropped either to a custom position specified by the user, or they can be snapped-in-place as defined by the position and dimension file produced by the Dimension Converter component.

In the Manage Settings, the application builds a series of nested windows that are launched by individual buttons allowing the user to select individual hardware components and enter specific settings for each of them. Of particular interest is the Channel interface in which the user can define the LightPath configuration associated with each channel of a given image by following a predefined graphical flowchart (Supplementary Fig. 3d).

JS Electron implementation of Micro-Meta App

This implementation of the Micro-Meta App is encoded in JS103. It uses the Electron library to wrap the React implementation of Micro-Meta App with all necessary schemas, icon images and position/dimension to ensure its correct functionality. This discrete executable file can interact directly with the underlying operating system and launch the software from the local file system.

Beta testing

Micro-Meta App was developed in the context of community efforts organized around the 4DN Consortium need for imaging data dissemination and integration with omics datasets2,3 and the BINA5 effort to improve rigor, QC and reproducibility in light microscopy. As part of this effort, several core facilities were identified to serve as reference beta-testing sites for the Micro-Meta App (a subset of the facilities listed in Extended Data Fig. 6). To this aim, the stand-alone JS Electron implementation of Micro-Meta App was deployed locally and microscope custodians at individual beta-testing sites were trained both on the use of the App and on bug and feature request reporting. Such feedback was collected either directly or by taking advantage of the GitHub issue-reporting feature and incorporated into the main development branch in a close-iterative cycle ahead of the release of the initial production version of the software

Reporting Summary

Further information on research design is available in the Nature Research Reporting Summary linked to this article.