Dec 17, 2024
Exporting and renaming raw microscopy images
This protocol is a draft, published without a DOI.
- 1University of Oslo
Protocol Citation: Ingvild Elise Bjerke 2024. Exporting and renaming raw microscopy images. protocols.io https://protocols.io/view/exporting-and-renaming-raw-microscopy-images-drvt566n
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: November 18, 2024
Last Modified: December 17, 2024
Protocol Integer ID: 112275
Funders Acknowledgements:
EU Horizon Europe
Grant ID: 101147319
Research Council of Norway
Grant ID: 269774
Abstract
This protocols describes the export and preparation of images for further processing. It covers data organization, exporting, and renaming to a standard naming convention. The protocol is based on the use of CZI files and the Zen software, but the steps on data organization and naming are relevant for image files exported from any software.
Data organization
Data organization
Prior to starting file processing, consider the data organization scheme you would like to follow. In general, it is advisable to organize data into folders and subfolders with the same setup throughout a project. To facilitate the use of protocols and scripts throughout this protocol collection, we recommend organizing data into folders per subject with the following subfolders:
"1_CZI"
"1_original_tiffs"
"2_TIF"
"thumbnails"
"thumbnails_for_anchoring"
The numerical prefixes to some of the folders are there to indicate the provenance of the data, where CZI files are the most "raw" files followed by original tiffs, final tiffs (TIF), and finally thumbnail files at different resolutions, which can be used for various purposes. The original tiffs should be considered temporary files and can be deleted when the files in the TIF folder are finalized (unless storage space is not a concern, in which case they might be kept as a backup). The exact naming of these folders is not important, as long as they are descriptive with regards to their content and implemented consistently throughout the project.
Naming raw microscopy (CZI) files
Naming raw microscopy (CZI) files
CZI microscopy files consist of one or more imaged sections, and each section is treated as a "scene". To use renaming scripts provided later in this protocol, it is important that all section numbers represented in the file are included in the name and separated by underscores. They should not be preceded by the letter "s" as this prefix is used by Zen export to indicate scene numbers. The format of the rest of the name is flexible, as long as there are no instances of "sX" anywhere in the file name.
Example of a CZI file name that will work with scripts provided in this protocol:
"m255F_P21_Calb_sn3_9_15_21.czi", "m255F_3_9_15_21.czi", "m255F_section3_section9_section15_section21.czi"
Example of a CZI file name that will not work with scripts provided in this protocol:
"m255F_P21_Calb_s3_s9_s15_s21.czi"
Adjust display settings of CZI files
Adjust display settings of CZI files
The display settings of each slide can be adjusted in the "Display" panel in Zen. Be aware that if the images are to be used for quantitative intensity-based analyses, it is crucial to process all images in an identical manner.
Open the CZI file(s) in the Zen software. Each file will be adjusted individually.
For each file, untick the “Scene” option in the "Dimensions" panel to view the whole slide at a time. This allows you to see how the changes affects each section on the slide. Any change applied will be applied to the whole slide (i.e. to all sections on that slide).
Note
If the display settings for individual sections on the same slide needs to be adjusted separately, it is possible to split the CZI file into individual files per scene. For each scene on the slide, go to Edit > Create image from view. Now each scene is a separate file that can be adjusted and saved individually.
For brightfield images: It is advisable to adjust the settings to avoid gray "edges" around the section. This will make the images appear more uniform and might also improve performance of some automatic image processing tools. This can be achieved by adjusting skewing the curve on the right side of the histogram in the Display panel so that the empty area is excluded. Sometimes, there is a peak in the red curve at the end that also needs to be removed for the grey areas to disappear.
Example of a brightfield image before (left) and after (right) adjustment of image parameters as described above, removing gray edges around a section.
For fluorescent images: The histogram in the Display panel can be adjusted in the same way as for brightfield images. Individual channels can be adjusted separately, by clicking each channel under "Histogram" in the Display panel and then adjusting the curves.
When the desired adjustments have been made, save the CZI file. The changes are reversible even after saving the file, so it can safely overwrite the original version.
Export images from CZI files
Export images from CZI files
When all CZI files have been adjusted, they are ready to be exported as tiff files. This can be done in batch mode using the Processing tab available in the top left corner of the Zen interface.
Select Processing > Batch > Image Export.
In the main window, open all the CZI files to be exported by pressing "Add" in the lower left corner.
Under Method Parameters, the parameters for the export are specified. Choose a file in the list of CZI files, and adjust the settings to the desired ones.
Important considerations for export parameters include:
- File type: The Tiff Format (64Bit) (BigTiff) allows export of tiled tiff files, which are practical for use in some downstream software. Make sure that the "Tiff Tiles" option is ticked when using this file type.
- Compression: Lossy compression generally works very well for fluorescent images, with little to no noticable difference in the visual output.
- Resize factor: Exporting at 100% resolution can yield quite large size of the tiff files. Depending on the scanning resolution, it might be a good option to apply some resizing during export. However, this will affect the resolution of the images.
- Channel and merge parameters: For fluorescent images, it might be practical to export a merged version of the images. To export both a merge image and individual channels, tick the boxes for both in the Parameter window. To export a merge of a subset of channels, select "Define subset" and choose the channels you want to merge. Note that if you do merge a subset of channels, only individual channels corresponding to this subset will be exported. Thus, if you want to export all channels individually and export a merge of a subset of channels, you will have to do two separate export rounds.
To copy these parameters to all the files, click the “Copy parameters” button, select all files in the list, and click “Paste parameters”. Start the export.
Rename exported files
Rename exported files
Exported files from Zen carry the same name as the raw file, plus a suffix indicating the scene number. If files have been named as explained in step 1, the section number can be inferred from the file name and scene suffix. However, it is advisable to rename the tiff files so that only the section number corresponding to the scene number of the image is retained. For example, a tiff file exported from Zen might have the name:
"m255F_P21_Calb_sn3_9_15_21-Image Export-01_s1"
Here, the string "_sn3_9_15_21" gives the section numbers on the slide, whereas the string "_s1" tells us that this file corresponds to the first scene on the slide, i.e. sn3, or section number 3. There will also be files named "m255F_P21_Calb_sn3_9_15_21-Image Export-02_s2", "m255F_P21_Calb_sn3_9_15_21-Image Export-03_s3", and "m255F_P21_Calb_sn3_9_15_21-Image Export-03_s4" corresponding to section 9, 15 and 21, respectively. While these filenames are perfectly understandable with some background information, they are not optimal for further use. Ideally, the section number should be identifiable by a single consistent string (e.g. on the format sXXX) and not from a combination of strings in the file name. The "Image Export-XX" string is added by the Zen software and does not provide important information.
For use with other parts of this protocol collection and accompanying scripts, we recommend renaming the exported tiff files following these guidelines:
- Use the animal ID as the first part of the name
- Indicate section numbers by "sXXX" (for example, s001, s002, etc.). See the note below for more detailed advice on numbering sections.
- Include any other group indicators, staining or channel names as desired, and separate all of these with underscores.
- Do not use slashes, periods, or special characters in the file name. Dashes may be used.
Examples of file names following this convention:
"mouse255_P21_F_calb_s093"
"mouse178_P21_F_s050_DAPI"
In these names, the mouse ID constitutes the first part. Other group indicators include the age ("P21"), sex ("F"), stain ("calb") or channel ("DAPI"), and are separated by underscores. The section number is indicated with "sXXX".
Note
When numbering your sections, ensure that:
- Sections are ordered from one anatomical extreme to the other (anterior to posterior, dorsal to ventral or lateral to medial depending on the cutting plane).
- Section numbers are assigned to the images with the convention "sXXX", e.g. "s001".
- The physical space between sections is represented in the section numbering. For example, if every fourth section was cut, name them "s001", "s005", "s009" etc.
Depending on how the files are named when they are exported, more or less complex renaming procedures will be needed. To rename files efficiently, several software options are available.
- The PowerRename function from the Microsoft Powertoys is easy to use and works well for simple cases of exchanging parts of a file name for something else.
- Bulk Rename Utility provides a free renaming software that allows flexible renaming of files or entire folders of files.
- We provide Python code to rename files exported from Zen to names according to the convention described in Step 13. See the script called file_naming_functions.py in https://github.com/ingvildeb/brain_section_scripts. For an example implementation of these functions, see https://github.com/ingvildeb/CalciMAP/blob/main/1_preprocessing_images/02_renaming_raw_tiffs.py.