DOCUMENTATION for Custom Lab Image Analysis/Processing Macros - 'Custom Macros' Plugin for ImageJ

Version 210111, Please visit our website for software and documentation updates: https://www.ijmacros.com

Please refer to our paper, found at https://doi.org/10.1016/j.jneumeth.2019.04.009 for additional reference. The paper can also be found here: Forlano Lab publications.

If you use Custom Macros in your work, please cite: Timothy, M., & Forlano, P. M. (2019). A versatile macro-based neurohistological image analysis suite for ImageJ focused on automated and standardized user interaction and reproducible data output. Journal of Neuroscience Methods, 324, 108286. doi: 10.1016/j.jneumeth.2019.04.009.

  Miky Timothy and Forlano Lab.  Software licensed under GPLv3.0.

Installation     ↺    

• IMAGEJ INSTALLATION
  • If you do not have ImageJ installed, you can download it from the NIH website.
  • Since ImageJ is a portable program, install it by extracting the contents of the installation zip to any directory of your choice (to which you have write permissions). There are also non-portable installation binaries. ImageJ can also be easily installed in Linux with a package manager. Please make sure to update to at least version 1.5t to use Custom Macros.
• CUSTOM MACROS INSTALLATION:
• Non-network (local mode) setup:
  • If the plugin only needs to be set up on a single computer and no cloud-networking functionality is desired, the Custom Macros can be installed in the same directory as the ImageJ program itself.
  • Download the latest version of the plugin from https://www.ijmacros.com. It is supplied as a zip file archive.
  • Extract the contents of the Custom Macros plugin zip into the /ImageJ/Macros/ folder. We recommend the free and open-source program 7-Zip as an all-around excellent solution in dealing with archive files. Overwrite, if prompted. Restart ImageJ.
• Network setup:
  • The above local installation should be performed first for each computer that will be using the plugin.
  • While documentation is updated, please refer to our paper, found at https://doi.org/10.1016/j.jneumeth.2019.04.009 for a detailed explanation, with schematic of the subsequent steps. The paper can also be found here: Publications.
• Recommended plugins:
  • It is strongly recommended that users download and install the Extended Depth of Field plugin for use with the Batch Stack Project macro.
  • It is also recommended that the Stitching plugin be installed, which is required for the Field of View Overlay macro.
  • Please make sure to cite these plugins if you use functionality they enable. See the respective subsections for papers to cite. Thank you.

Login and Save     ↺    

• After ImageJ starts up, press the orange button shown above.
• A login prompt is shown. Follow the directions in the prompt to sign in to a current experiment or create a new login.
• Read the directory creation instructions carefully. Note that folders are separated by spaces.
• If the folder specified in Network.ijm is not found, a message is shown reading "RUNNING IN LOCAL MODE" and ImageJ will use the saved macros and user list.
• All output data and images from analyses are saved in the desktop directory OUTPUT ImageJ in a subfolder based on your login.
• After each analysis run, results are added to a text file named based on your user login and ending in Results.txt. This file is found in your subfolder in OUTPUT ImageJ.
  • For brevity, this file will be referred to simply as Results.txt in the documentation.
• Information from Results.txt files can be opened in any spreadsheet program and formatted by separating columns based on colon : characters.
• An original version of your image with the suffix 'original' is also saved in your output subfolder.
• If you need to re-run an analysis, make sure to open Results.txt, remove the previously saved line, and re-save the file.
• We recommend working with Results.txt files using Notepad++. This excellent free and open source text editor is now also easy to set up in Linux using Snap. Other options include Geany or Gedit, which also work cross-platform. The important thing is for the text editor to dynamically prompt users upon changes to the file.
  • Once you start your analysis, open results.txt in Notepad++ and keep it open.
  • Each time you run an analysis step and generate an updated results file, a Reload message will appear in Notepad++.
  • Press yes and the file will be updated automatically. You can correct the results if needed, and re-save.
• Logins can be deleted once an experiment is done. Underlying folders will not be affected.

Scale Calibration     ↺    

• Most image analysis tasks generate continuous, spatial measurement data that corresponds to sum pixel values. ImageJ will automatically scale raw pixel data, e.g., 1 pixel =1 micron². Images sometimes have embedded calibration metadata, but more often do not, so these macros are designed not to rely on metadata and instead scale images based on filenames.
• If your image name contains a calibration multiplier value in the form of a space followed by a string of 1-4 integers and an x (e.g., Image 100x.tif), your pixel value will be scaled to the base calibration divided by your magnification.
• The base calibration corresponds to a digital camera sensor's cell size and is stored locally in the file /Macros/CustomMacros_Macros/Calibration.ijm. You will be asked to enter this value upon first running Custom Macros. Leaving it blank disables scale calibration, with output in pixels.
• Press keyboard shortcut 'shift + K' to change the base calibration from the ImageJ GUI.
• If you choose a base calibration value of 6.45um, image Brain12 Thalamus 40x 05 TxRed.tif will be calibrated to (6.45 / 40=0.16125) micron². Lowercase um is automatically changed to the greek micron notation.
• Remember, calibration multiplier values must be preceded by 1 space, contain no more than 4 integers, and be bound at the end, without an intervening space, by a lowercase x.
• If your image name does not have a magnification string, scale will be automatically calibrated to 20x. A calibration multiplier of 0x will scale per pixel.
• Finally, 'Manual Calibration Scaling', invoked via keyboard shortcut 'k', enables per-image scaling, with a calibration multiplier added to the filename. Users simply specify the real-world unit distance between two points in an image.
• Invoking this procedure sets the base calibration is set to 100units². This method allows images in Custom Macros to be easily, accurately, and reproducibly measured just by a filename string.

Close All Button     ↺    

• The black button with an x cut out in the middle is the custom 'close all' button.
• Click it to close all open ImageJ windows except the main program console.
  • Holding shift while clicking closes only non-image windows.
  • Conversely, holding alt or control while clicking closes only image windows.
  • Finally, holding space while clicking closes all but the top most image window.

Info Window/Training Image     ↺    

• Press 'F11' to open a window showing the current macro version, user name, output folder, and calibration settings for the current image(if one is open).
• Press 'v' to open the default training image. These images have contrast features useful for testing function and learning about image processing. Press 'shift+V' to create a customized training image, with choices for color, stack, and animation. Shortcut 'v' will open copies of your customized training image. You can again change the appearance of your image by pressing 'shift+V'.

Random Code Assignment     ↺    

• After pressing 'shift+R', a text window and directions message will open.
• Paste items that you want to assign a code to in the text window. Each item should be on a new line. Leave blank for a sequence of numbers.
• Alternatively, choose a bin size for subgrouping of items to a set number of codes.
• A table with random assignment of A-Z letter codes will be generated for review. It can be saved manually or by entering a file path in the preceding options dialog.

Histograms Tool     ↺    

• With a Results window or data table open, press 'h' to create a montage image of a set of automatically formatted and labeled histograms.
• A dialog box with provides options for histogram creation - which data columns to include, the formula to use for determining the number of bins, and saving location (optional).
• Table columns that do not meet criteria for histogram construction are automatically omitted in the check box list.
• This function is also invoked as part of the Area Measurement Batch macro.

Color Channel Selection Hotkeys     ↺    

• You can convert your image into an RGB composite stack and isolate color channels using these number hotkeys:
• '1' Red Only
• '2' Green Only
• '3' Blue Only
• '4' All Colors
• '5' Red and Green
• '6' Red and Blue
• '7' Green and Blue
• '8' Convert back to RGB

Masking Buttons     ↺    

• After selecting an area in your image, you can mask the foreground or background in black using the following buttons:
  • Holding shift while clicking the red mask also inverts the current selection.
• Click the red, left facing mask button to fill everything in your selection with black.
• Click the blue, right facing mask button to fill everything outside of your selection with black.
  • Holding shift while clicking the blue mask also crops your image to the selection.

Sampling Grid Selection     ↺    

• Press 'g' to set up your grid dimensions settings.
• Once dimensions are set, press 'g' again to randomly place a grid of that size over your image. Press repeatedly to change grid placement.
• Grid dimensions are stored in file 'Grid.ijm' in OUTPUT ImageJ in a subfolder based on your login, and need to be created for each new login.
• Press 'shift + G' to check your saved grid dimension settings or reset them.

Suffix Namer/Draw Point Counts     ↺    

• Suffix Namer
  • The Suffix Namer function allows you to enter and save up to six terms, per user login, that can be used to add suffixes to image names or to name regions of interest based on those suffixes.
  • This is especially useful if you need to do multiple analyses on the same image, such as during colocalization, or need to differentially designate multiple regions in an image .
  • Press 'F2' to bring up the suffix renamer tool.
  • Type in up to six suffixes.
  • These settings are saved in the file 'CustomNameConfig.ijm' in OUTPUT ImageJ in a subfolder based on your login, and need to be created for each new login.
  • In the second dialog, select your desired suffix to rename your image with the added suffix. Otherwise press cancel to only designate suffixes, without renaming the image.
    • Keyboard shortcuts 'q', 'w', 'e', 'shift + Q', 'shift + W', and 'shift + E', can be used to quickly add suffixes to image names based on the six terms entered, respectively. Press the shortcut key again to remove the suffix and revert the image name to its original.
  • If a user selection, such as a rectangle or wand selection, is active, the above shortcuts will instead add and name regions of interest (roi's) based on the respective terms. Each region added is numbered, so multiple regions can be created based on the same term.
• Draw and Label Point Counts
  • By default, images saved after running the Manual Count or Object Count with Find Maxima macros do not have the selected points labeled or numbered. To add count and/or suffix name labels, use these two check boxes.
  • Draws count numbers next to your points.
  • Draws the first letter of the chosen suffix next to your points.
• To reset your suffix list/draw points setting, press 'F2' to select the check box to do so. You can leave suffix choices blank.

Object Count with Find Maxima     ↺    

• Open or drag and drop an image into ImageJ.
• If you are restricting counts to a specific region, either trace that region or use the Sampling Grid Selection macros. Note that everything outside of your selection will be blacked out.
• Press 'F4'.
• Confirm your save directory and set a preliminary maxima threshold.
• 'Signal of interest in one color channel?' setting:
  • If your image is a color (RGB) micrograph, choose the color channel that contains your signal of interest (the label you intend to count). This scenario is almost always the case.
  • However, if you do not want to isolate a color channel in your RGB image for some reason (for example, if you are working with a brightfield micrograph), choose 'no'.
  • Also, if your image is an 8-bit single channel (grayscale) micrograph choose 'no'.
• To crop your image around a selection, click the check box to do so. Note that if an image is cropped, xy coordinate data will not be representative of the entire image. Select the last check box to save the above settings for this session.
• Press OK after the first dialog box with maxima threshold count. The log window follows your progress.
• In the Find Maxima dialog, check 'preview point selection'. Set 'noise tolerance' (maxima threshold) to a desired value - lower tolerance yields more points and higher tolerance fewer points. Only check light background for brightfield images like those stained with DAB.
  • Note that it tends to be easier to add points than to remove them, so setting a slightly higher threshold in which not all points are selected is generally a better idea than setting a low threshold that yields false positives.
• Next, remove any excess points identified by the maxima function. Click points while holding down the alt key to remove them.
  • While the above step is intended only for removing points, it is technically possible to add points at this time, as well, and doing so should result in an accurate final count. It is still recommended to wait until the next step to add points.
• Add points by clicking on your image. Move points by hovering over them with the mouse until the cursor turns into a hand. Remove points by alt-clicking.
• Check over the resulting picture and press OK. To continue analysis with more images, open another image and follow the above procedure.

Manual Count     ↺    

• The Suffix Namer/Draw Point Counts macros are often used during manual counts, so read that section.
• Before running manual counts, select the multipoint tool, if not already selected, from the main ImageJ window.
• To better visualize your signal of interest, you may want to toggle color channels and adjust levels while adding points.
  • Note that isolated color channels and level adjustments are not saved in your final image.
• Add points by clicking on your image. Move points by hovering over them with the mouse until the cursor turns into a hand. Remove points by alt-clicking.
• Press 'F3' to finalize the analysis.
• Resulting images, count data (with xy coordinates for each point), and regions are saved in your OUTPUT ImageJ login subfolder.
• Point count is logged in the 'Log' window and saved in the Results.txt file, also in your login subfolder.

Area Measurement     ↺    

• To only analyze part of your image, create a selection around that region.
• Otherwise, the entire image will be selected automatically.
• Press 'F5'.
• Confirm that your target directory is the one desired.
• Choose which selection tool you will be using or leave default chosen if no selections are needed.
• 'Signal of interest in one color channel?' setting:
  • If your image is a color (RGB) micrograph, choose the color channel that contains your signal of interest (the label you intend to measure). This scenario is almost always the case for fluorescence.
  • However, if you do not want to isolate color channels (for example if your image is an 8-bit single channel (grayscale) micrograph), choose no.
• If you check the 'set above options' box, you will not see this dialog the next time you press 'F5' and will need to restart ImageJ to reset the above options.
• Press 'F6' to start threshold steps.
• The macro now predicts a good threshold. Use keys 'z' and 'x' to lower and raise the threshold black point. Press 'c' to toggle threshold visibility on and off.
• You can also use the sliders in the threshold window. With fluorescence, inclusive threshold for light objects is almost always the goal, so only the top slider should be moved.
• Once you are satisfied with your threshold, press 'F7'.
• A selection and image of your threshold has been created and saved.
• Press 'F8' to finish. Data, region selections, and output images have been saved in a new image directory, and new line of data added to Results.txt (see Save Directory section in Login and Save for details).
• The above procedure can be run on different color channels of the same image to measure regional colocalization. This is done by reloading your RGB image, dragging and dropping the roi threshold.zip region file from the previous run, and selecting a different color channel to extract. The region will limit measurement to the previously thresholded area, in the same way as if you manually created a selection as a first step.
• Important: If you are performing colocalization analysis on the same image, create a new login for that part of the procedure. Otherwise, you will be prompted to overwrite the folders from the first measurement run. Also, do use the 'original' version image, saved in your subfolder, for colocalization! Read below for the appropriate procedure.

Colocalization in Detail and Data Naming Best Practices:
• Colocalization involves the analysis, in the same image, of threshold-limited data in one color channel that is bound in a region created previously from a threshold in another color channel.
• Complex experiments may require multiple channel thresholds nested in series - red within green, green within blue, blue within a traced anatomical boundary.
• Thus, it is crucial that the data in Results.txt reflect which label (color channel) is being analyzed and in what region (which roi threshold.zip was loaded).
• The simplest approach for large experiments is to use the 'Batch Suffix Renamer' macro (shortcut 'r'):
  • Copy all the images you plan to analyze into one folder.
  • Press 'r'. For a suffix, enter the name of the label you will be analyzing (i.e., the signal found in that color channel).
  • Enter the directory of the folder containing your images and the output folder directory into which you wish to create file copies with suffixes.
  • It is recommended that a new output folder be created for each label. Output folders are created automatically, if they do not already exist.
  • Repeat for each label you plan to analyze for colocalization.
  • Load the file with the corresponding suffix for each area measurement run of your colocalization analysis.
• Below is an example of data combined from three Results.txt files that shows how using image file suffixes makes reading colocalization results comprehensible.

  Filename: A_OE_1 20x ChAT :roi=A_OE_1 20x ChAT select    :Threshold=43 :AreaFraction=56.3 :Area=304.1 :IntegDensity=24827.1 Filename: A_OE_1 20x TH   :roi=A_OE_1 20x ChAT threshold :Threshold=37 :AreaFraction=51.9 :Area=157.8 :IntegDensity=10353.7 Filename: A_OE_1 20x pTH  :roi=A_OE_1 20x TH   threshold :Threshold=44 :AreaFraction=25.7 :Area=40.5  :IntegDensity=2986.3

• The filename contains the name of the label being analyzed. The region-of-interest ('roi') contains the name of the label it is being colocalized with ('threshold') or whether it is a traced anatomical region ('select').

Area Measurement Batch     ↺    

• Area measurement can be automated as a batch function for a folder containing multiple images.
• Press 'F10' to call up the dialog for this command.

ROI Masking Batch     ↺    

• This function will mask the background or foreground of each image in a selected folder based on each similarly named ROI region file in that folder.
• Press 'm' to call up the dialog for this command.

Region Review     ↺    

• You may want to review selections and markups you've made after processing an image to compare your work with what that image looked like originally.
• This is especially useful for point count analyses for the purpose of toggling overlaid points on and off to see the area underneath.
• Since both a region file and an original unaltered version of an image are saved in a subfolder every time you run any kind of analysis macro, performing such a region review is especially straightforward.
  • Note that this macro will also load any region with the same name as an open image, if both files are in the same folder.
• Open or drag and drop an image into ImageJ. You'll probably want to use the 'original' version found in an output folder.
• Press '9'. If a region file is found in the same folder as your image, your selection region, point counts region, etc., will show up on the image.
• Note that regions are not the same as overlays! This is a somewhat subtle difference, but unlike regions, overlays cannot be manipulated or measured like regions can. See Overlays from Saved Regions macro for more information.

Points from Saved Regions     ↺    

• There are situations when you may want to add, remove, or otherwise manipulate point selection regions from a previously analyzed image.
• Open or drag and drop a region file (usually a .zip file ending in the word roi) into ImageJ. The 'Region Review' macro (shortcut '9') above is an expedient way of loading relevant regions.
• Press 'p'. The saved data points from your region have now been added to your image.
  • Note that if your region was a curved lined or other shape, a series of points along that line is generated instead.
• You can now move or remove these points or add new ones with the multipoint tool. Running a manual count or other analysis will quantify all points on the image.

Overlays from Saved Regions     ↺    

• There are situations when you may want to review a mask or outline from a pre-or--postprocessed image.
• Open or drag and drop a region file (usually a .zip file ending in the word roi) into ImageJ. The 'Region Review' macro (shortcut '9') above is an expedient way of loading relevant regions.
• Press 'o'. An overlay from your region has now been added to your image.
• Press 'i' to toggle overlay visibility on and off. You cannot, however, move or manipulate an overlay like you can a region.

Additional Macros     ↺    

• Not all macros are installed upon startup. This is done to prevent cluttering the core interface with too many commands and to avoid potential performance issues from loading an excess of procedures and variables into memory.
• Loading the 'additional macros' can be accessed from the drop down menu by clicking the brown box button.
• While these macro sets are loaded, most of the core image analysis commands are not accessible. Press the Start Button to login again and access core functionality.

Batch Image Preprocessing     ↺    

• These functions are accessed by pressing the above four buttons. The commands are listed invoked by the above buttons, from left to right respectively. These commands provide a great deal of functionality, and the present documentation is being updated to reflect this. Please refer to our paper, found at https://doi.org/10.1016/j.jneumeth.2019.04.009 for a thorough reference. The paper can also be found here: Publications.
• Please also see above paper for explanation of 'Range testing' feature.
• Subtract Background Batch
  • Useful filter prior to image analysis, especially segmentation.
• Enhance Contrast Batch
  • Filter that works well for images with illumination issues.
  • Can dramatically improve segmentation efficacy.
• Stack Project Batch
  • Feature-rich batch z-stack implementation.
  • Multiple stack algorithms can be implemented on a set of images in one run.
  • It is strongly recommended that users download and install the Extended Depth of Field plugin. Download it from the Biomedical Imaging Group site and extract and install 'EDF.zip' found under the 'ImageJ plugin - developer distribution' heading.
    • If you use the EDF functionality, make sure to cite Forster, B. , Van De Ville, D. , Berent, J. , Sage, D. and Unser, M. (2004).
• Threshold Outline Batch
  • Powerful batch segmentation procedure, based on particle analysis process.
  • Supports the use of previously generated thresholds and regions.
  • A chosen threshold can be averaged with a second auto-threshold.
• Press keyboard shortcut 'F12' to open the batch output folder from the most recent procedure.

Look-Up table Batch     ↺    

• The Look-Up Table Batch macro utilizes the LUTs found in the /ImageJ/luts/ folder and applies them to images.
  • For single images, it applies all available LUTs displaying the results as a stack.
  • Alternatively, it can apply a set of LUTs to each image in a folder, saving each result as a separate image.
• To use the LUT Batch macro on a single image, open or create an image and press the 'colorful rainbow button' and then follow dialog instructions.
  • Extract the desired LUT image by pressing the 'gray rainbow button'.
• To use the batch folder function, press the 'folder/rainbow' button and follow dialog instructions on applying LUTs to a folder of images.

Macro Development Mode     ↺    

• Macro Development Mode makes it easier for users to quickly develop and debug their own ImageJ macros. Clicking the above interface button pastes the clipboard contents installs the text as a macro. The command also saves the text to the local folder /ImageJ/Macros/CustomMacros_Macros/Testing/. Up to ten files are stored.
  • Press keyboard shortcut 'F12' to open this folder.
• Holding 'shift' while clicking the Macro Development button installs and runs the user's macro.
• Finally, holding 'space' while pressing the Start Button likewise installs and runs the user's macro, and also enters Macro Development Mode. This shortcut works in a context you see the Start Button.

Field of View Overlay     ↺    

• This macro utilizes the Stitching plugin to derive image registration parameters to generate, label, and save a side-by-side montage from two open images with an overlay grid indicating the location of the higher magnification image.
• Note that the Stitching Plugin must be installed in addition to Custom Macros prior to use. You can download it here: Preibisch Laboratory. If you use this function, please make sure to cite Preibisch, S. , Saalfeld, S. , and Tomancak, P. (2009) if you use the Field of View Overlay functionality. Thank you.