- Purpose
- How to use the App
- Operating instructions
- How to adapt the App
- How to contribute
- License
The releases are available and citable on Zenodo
This repository contains a Shiny App that guides users to create a report for microscope images acquired at the Imaging Platform at LEIZA (IMPALA) with all the necessary metadata.
Once all fields are entered, the report can be exported to an ODS or XLSX file.
This report can and should be published together with the image data. While publishing them as a supplementary material to a paper is OK, I recommend publishing everything in open access on an online repository like Zenodo, Figshare or OSF for easy and long-term accessibility. Additionally or alternatively, the report could be attached to a protocol, for example on protocols.io.
For more details, check my repo publish-micro-image.
The App is designed for the instruments available at the IMPALA and currently includes the digital microscope (Zeiss Smartzoom 5), the upright light microscope + LSCM (Zeiss Axio Imager.Z2 Vario + LSM 800 MAT, abbreviated "LSM"), the reflected light microscope (Zeiss Axio Scope.A1) and the transmitted light microscope (Zeiss Axio Lab.A1). More instruments will be added later.
If you would like to adapt the App to your instrument(s), check the sections How to adapt the App, How to contribute and License.
The easiest is to run the App on the LEIZA server: https://tools.leiza.de/imaging-reports/
Alternatively, the App can also be run locally using RStudio.
This option is especially useful if you intend to edit the App (see sections How to adapt the App and How to contribute).
The Shiny App is written in Shiny using RStudio, so you first need to download and install R and RStudio. But fear not, no knowledge of R/Rstudio is needed to run the App!
There are two ways to get the App:
- Download my GitHub repository or its latest release as a ZIP archive, and unzip it. You can access the repository with the source code by clicking on the button in the side bar of the App (see side bar).
- Fork and clone my GitHub repository.
- Open the file imaging-reports.Rproj with RStudio.
- Open the file
imaging-reports/app.Rfrom within RStudio by clicking on it in theFilespanel.
Open the App from within RStudio.
- Run the App by clicking on the button
Run Appin the top right corner.
Run the App from within RStudio.
- The App will open in a new RStudio window. I recommend to open the App in your browser (click on
Open in Browserat the top to open the App), and to maximize the window (or at least make it large enough so that the fields do not overlap).
App freshly opened (no input yet).
- Enter the information as explained in the following section (Operating instructions).
In both cases (LEIZA server and local), no input is saved in the App. If you close the App (or the browser tab), all input will be deleted.
The only way to save input is by downloading the report to an ODS or XLSX file (see tab Report). Graphs in the tab Objectives can also be downloaded as PNG or PDF.
- In a strict sense, none of the fields are required. Yet, it is important that you fill as many fields as possible. Unedited fields will be filled with default values, so make sure you change them in case you did not apply default values.
- Some information that will be included in the report (see tab Report) is hard coded and does not depend on your input because it depends on the hardware only. Because of that (and also developments and bug fixes), make sure you use the latest version of the App.
- Every entered information summarizes all acquisitions about which you are reporting. Therefore, do not fill the forms for every single acquisition bur rather for all acquisitions of a project. Metadata for every acquisition should be made accessible with the acquisition files themselves (see repo publish-micro-image).
- While it is possible to jump from any tab to any other, conditional input (i.e. input based on other input) might not update correctly. Therefore, I recommend that you start in the side bar and then fill in every tab from left (tab General) to right (tab Pre-processing). The tab Report can be consulted any time to check how the output will look like, but you might get some errors until you have filled in all tabs.
- Sometimes, you get error messages even when it should work. So if an error message appears, (1) check whether you have entered the information required for a given tab to show properly (e.g. if you have not entered information about the objectives, an error will appear in the tab Report in the section Objectives), or (2) restart the App (it often works!).
- You can create a report for one instrument at a time.
- Refer to the instrument's user manual if you need information about the settings.
Enter your name and select the instrument you used from the list.
Start again at the tab General if you switch to another instrument.
Click on the GitHub button to access the repository with the source code.
Side bar
Select the software you used from the list and enter the version(s).
Make sure you specify the full details of the version including hot fixes (HF).
If you used more than 1 software packages, enter the versions in the same order as the software packages and separate them with semi-colons without space (e.g. "v12 HF5;v3 HF2"). If available on the instrument, tick the box if you used the module Shuttle-and-Find (correlative microscopy).
Tick the boxes for all acquisition modes you used.
General tab for the Axio Imager.Z2 Vario + LSM 800 MAT.
General tab for the Smartzoom 5.
General tab for the Axio Scope.A1 and Axio Lab.A1.
Select from the list how each objective has been used.
- Several uses can be assigned to every objective. To do so, click on every relevant use from the list.
Color imagehere is meant in the widest sense to refer to any WF image acquired with the camera, even in black & white mode, with any color filter or with any contrast method (bright field, polarization, dark field, C-DIC).3D topographyrefers to an LSM acquisition. Other choices arePreview scanandCoordinate system.- After selection, click on a use and press
DELETEto unassign it. Make sure that at least one use is assigned to each objective (selectNot usedif you have not used a given objective).
Objectives tab for the Axio Imager.Z2 Vario + LSM 800 MAT.
By default, none of the objectives has been used, so make sure you assign a use to at least one objective.
See Objectives for Axio Imager.Z2 Vario + LSM 800 MAT for details on choices of uses.
Objectives tab for the Smartzoom 5.
See Objectives for Smartzoom 5.
Objectives tab for the Axio Scope.A1.
See Objectives for Smartzoom 5.
Objectives tab for the Axio Lab.A1.
Below the fields to assign uses to objectives, a barplot shows the lateral optical resolutions of each used objective. For the Axio Imager.Z2 Vario + LSM 800 MAT, you have the choice for the wavelength of the light source (Violet laser (405 nm) - LSM for the LSM 800 MAT or White LED (550 nm) - WF for the Axio Imager.Z2 Vario) but only the latter is available on the other instruments.
The graph can be exported to PDF (vector) or PNG (raster) using the buttons below.
Graph of lateral optical resolution for each used objective, with download buttons.
In case of acquisitions for which no settings can be defined (e.g. simple 2D), the message "No input required" will be displayed in the tab. If you did define some settings, either you did acquire using a different mode and you therefore need to tick the corresponding boxes in the tab General, or some settings are actually related to pre-processing (especially in case of the Smartzoom 5, see tab Pre-processing).
- Choose the type of illumination: reflected or transmitted.
Acquisition tab for the Axio Imager.Z2 Vario + LSM 800 MAT.
-
In case of an LSM acquisition (
3D topography):- Enter the information for the objective used for this type of acquisition.
- Tick the box
Pinhole diameter = 1 AUto confirm that the pinhole diameter was set properly. - Enter the step size, the image size in X and Y, and the number of pixels in X and Y for the total image in case stitching was used. It is currently not possible to enter these pieces of information for several objectives. It is assumed that only 1 objective has been used for 3D topography.
- The pixel size in X and Y is calculated and showed interactively below, as well as whether the Nyquist criterion is fulfilled for this objective. The Nyquist criterion is fulfilled when the pixel size is 2 to 3 times smaller than the lateral optical resolution (see tab Objectives).
- In case the pixel size in X and Y differ, a warning will be displayed that the pixels are not square. The detector can only acquire square pixels, so at least one of the values you entered has to be wrong.
Warning about square pixels for the Axio Imager.Z2 Vario + LSM 800 MAT.
The only thing to choose is the z-stack mode (Continuous or Stepwise) in case of an EDF/3D acquisition.
Acquisition tab for the Smartzoom 5.
Choose the reflector (Epi BF or Epi C-DIC).
In case of a panorama acquisition, choose the panorama mode (Automatic or Interactive).
Acquisition tab for the Axio Scope.A1.
Tick the boxes for the polarization lenses (Polarizer, Analyzer or Bertrand lens) that you used, if any.
In case of a panorama acquisition, choose the panorama mode (Automatic or Interactive).
Acquisition tab for the Axio Lab.A1.
Enter the options of the pre-processing methods in this tab.
Some acquisition modes do not require pre-processing (e.g. 2D on all instruments), or the settings cannot be changed by the user (e.g. 3D/EDF on the Smartzoom 5). So if you did not select any acquisition mode that requires input about pre-processing settings in the tab General, a message notifies you of this in the tab Pre-processing.
No information on pre-processing is needed.
Different fields to fill in appear depending on instrument used and on the acquisition modes applied.
There are many settings related to EDF, stitching and 3D topography. In most cases, default values can be used.
Pre-processing tab for the Axio Imager.Z2 Vario + LSM 800 MAT.
Only settings related to stitching require input.
Pre-processing tab for the Smartzoom 5.
Pre-processing settings cannot be reported yet. WIP.
Pre-processing tab for the Axio Scope.A1 and Axio Lab.A1.
This tab lists the abbreviations used in other places of the App.
Abbreviations tab.
This tab shows a preview of the entered information.
I recommend that you check that everything is correct before you download the report (see below).
As mentioned already here, it can be that some fields are not updated in this tab. In such cases, go back to the beginning (side bar) and follow the tabs from left (General) to right (Pre-processing).
Once done, click on the Download Report to ODS or Download Report to XLSX button at the bottom of the tab. Save the file to your computer; I recommend to use the name provided. This is important as it is the only way to save your input (see section Save input). Check the file.
Save one report for each instrument you used.
Example report with the Axio Imager.Z2 Vario + LSM 800 MAT.
Example report with the Smartzoom 5.
Example report with the Axio Scope.A1.
Example report with the Axio Lab.A1.
I have tried to make the code of the App as clear as possible and to comment it as much as possible. This is surely not perfect, especially because the code is long and imbricated, but I hope this will be enough for future developments and adaptations.
If you would like to adapt the App to your instrument(s), feel free to do so on your own (see section Download the repository). Nevertheless, I would appreciate if you would be willing to contribute! You can also get in touch with me directly.
I appreciate any comment from anyone (expert or novice) to improve this App, so do not be shy!
There are three possibilities to contribute.
- Submit an issue: If you notice any problem or have a question, submit an issue. You can do so here.
- Propose changes: If you know how to write a Shiny App, please propose text edits as a pull request (abbreviated "PR").
- Send me an email: For options 1-2, you need to create a GitHub account. If you do not have one and do not want to sign up, you can still write me an email (Google me to find my email address).
By participating in this project, you agree to abide by our code of conduct.
This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License. See LICENSE.
Author: Ivan Calandra
License badge, file and image from Soler S. cc-licenses: Creative Commons Licenses for GitHub Projects, https://github.com/santisoler/cc-licenses.