Nutil: Neuroscience Image Processing and Analysis Utilities

Introduction

Nutil simplifies the pre-and-post processing of images of histological sections from mouse and rat brain. It is a standalone application and requires no coding experience to execute. It is an integral part of the QUINT workflow:

Tip

Visit EBRAINS for more information about QUINT. Find full user documentation here.

Nutil supports four operations:

1. TiffCreator: convert JPEG, PNG and normal TIFF images to tiled TIFF format.

2. Transform: rename, rotate, resize and compile thumbnails of large tiled TIFF images (typical microscopy output format).

3. Quantifier: for the batch extraction, quantification and spatial analysis of labelling in mouse or rat brain sections (for example, immunohistochemical labelling).

4. Resize: for resizing JPEG/PNG images with output in PNG format.

Check out the following articles that have used Nutil:

• Yao Y, Barger Z, Saffari Doost M, Tso CF, Darmohray D, Silverman D, Liu D, Ma C, Cetin A, Yao S, Zeng H, Dan Y. Cardiovascular baroreflex circuit moonlights in sleep control. Neuron. 2022 Sep 23:S0896-6273(22)00802-9. https://doi.org/10.1016/j.neuron.2022.08.027.

• Ham GX, Augustine GJ. Topologically Organized Networks in the Claustrum Reflect Functional Modularization. Frontiers in Neuroanatomy. 16 June 2022. https://doi.org/10.3389/fnana.2022.901807

• Bjerke IE, Cullity ER, Kjelsberg K, Charan KM, Leergaard TB, Kim JH. DOPAMAP, high-resolution images of dopamine 1 and 2 receptor expression in developing and adult mouse brains. Sci Data. 2022 Apr 19;9(1):175. https://doi.org/10.1038/s41597-022-01268-8

• Tocco C, Øvsthus M, Bjaalie J.G, Leergaard T.B and Studer M. Topography of corticopontine projections is controlled by postmitotic expression of the area-mapping gene Nr2f1. bioRxiv - May 2021 https://doi.org/10.1101/2021.05.10.443413

• Kim S, Jo Y, Kook G, Pasquinelli C, Kim H, Kim K, Hoe HS, Choe Y, Rhim H, Thielscher A, Kim J, Lee HJ. Transcranial focused ultrasound stimulation with high spatial resolution. Brain Stimul. 2021 Mar-Apr;14(2):290-300. https://doi.org/10.1016/j.brs.2021.01.002

• Whilden CM, Chevée M, An Seong Yeol, Pezon Brown S. The synaptic inputs and thalamic projections of two classes of layer 6 corticothalamic neurons in primary somatosensory cortex of the mouse. J Comp Neurol. 2021 Dec;529(17):3751-3771. doi: https://doi.org/10.1002/cne.25163. Epub 2021 May 6.

• McDonald MW, Jeffers MS, Filadelfi M, Vicencio A, Heidenreich G, Wu J and Silasi G. Localizing Microemboli within the Rodent Brain through Block-Face Imaging and Atlas Registration. eNeuro 16 July 2021, 8 (4) ENEURO.0216-21.2021; DOI: https://doi.org/10.1523/ENEURO.0216-21.2021

• Bjerke IE, Yates SC, Laja A, Witter MP, Puchades MA, Bjaalie JG and Leergaard TB. Densities and numbers of calbindin and parvalbumin positive neurons across the rat and mouse brain. 2021, iScience.https://doi.org/10.1016/j.isci.2020.101906

Technical information

Nutil is written as a stand-alone Windows 64-bit application written in Qt C++, which enables the full usage of both memory and processor cores. Nutil can be downloaded and compiled from the github page. When performing batch processes, Nutil will utilise all cores available on the system.

The external libraries that are used in Nutil are:

• Libtiff for fast and efficient TIFF file handling (http://www.libtiff.org/)

• LibXLNT for excel file IO (https://github.com/tfussell/xlnt/)

TiffCreator: TiffCreator produces tiled TIFF files from JPEG, PNG and standard TIFF images, and employs the support of multiple CPUs for efficient, parallelised operations.

Transform: Transform enables rotations, scaling and thumbnail compilation of large tiff files (currently up to 4GB).

Quantifier: Quantifier identifies individual binary objects in a PNG file, while matching these to output from QuickNII. The method first finds and sorts areas by using a standard pixel filler routine. Afterwards, a random area pixel is chosen as the look-up in the binary QuickNII label slice for this particular image. When all areas have been assigned a label ID, multiple selections of predefined area IDs are assembled (ID list from the excel input file), and finally output reports are assembled and written to disk (in xlsl format). In addition, original ilastik .png files with colour/ID coding added to underlying atlas slice data are assembled and saved to the output folder.

Tip

Nutil v0.8.0 has a new automatic plotting feature. This will work if Python is installed on the computer, with the Python.exe selected in Nutil through: File –> Settings. It is also necessary to install the following Python packages on your computer: numpy, pandas and matplotlib.

Installation

• Nutil is a stand-alone 64-bit Windows application.

• Download as a zip archive file and extracted and run anywhere on the computer by double click on “Nutil.cmd”.

• No installation executable is necessary, and the directory can be moved around the file system as required. Settings data are stored in the local program folder.

Hardware Requirements

• Nutil can be executed on either a server, desktop or laptop computer.

• It will employ all the cores available on the system. While there are no specific hardware limitations, the processing time is dependent on the system’s compute power. The more cores and memory available, the faster the operations will be performed. Running Nutil on a single-core laptop is also possible.

Conditions of use

Nutil is an integral part of the QUINT workflow, and is developed by the Neural Systems Laboratory at the Institute of Basic Medical Sciences, University of Oslo, Norway.

Authors: Nicolaas E Groeneboom, Sharon C. Yates, Maja A. Puchades, Jan G. Bjaalie.

Licence: GNU General Public License version 3.

Acknowledgements: Nutil was developed with support from the EBRAINS infrastructure, and funding from the European Union’s Horizon 2020 Framework Programme for Research and Innovation under the Framework Partnership Agreement No. 650003 (HBP FPA).

How to cite

• Nutil: Groeneboom NE, Yates SC, Puchades MA and Bjaalie JG (2020) Nutil: A Pre- and Postprocessing Toolbox for Histological Rodent Brain Section Images. Front. Neuroinform. 14:37. doi: 10.3389/fninf.2020.00037

• QUINT workflow: Yates SC, Groeneboom NE, Coello C, Lichtenthaler SF, Kuhn P-H, Demuth H-U, HartlageRübsamen M, Roßner S, Leergaard T, Kreshuk A, Puchades MA and Bjaalie JG (2019) QUINT: Workflow for Quantification and Spatial Analysis of Features in Histological Images From Rodent Brain. Front. Neuroinform. 13:75. doi: 10.3389/fninf.2019.00075.

How to cite the reference atlases

• Allen Mouse Brain Atlas: © 2004 Allen Institute for Brain Science. Allen Mouse Brain Atlas. Available here.

• Waxholm Space atlas of the Sprague Dawley rat brain version 2 , 3 and 4: RRID: SCR_017124; Papp et al., NeuroImage 97, 374-386, 2014; Papp et al., NeuroImage 105, 561–562, 2015; Kjonigsen et al., NeuroImage 108, 441-449, 2015; Osen et al., NeuroImage 199, 38-56, 2019; Kleven et al., in preparation.

For reuse of the Waxholm Space atlas of the Sprague Dawley rat brain, see the citation policy.

Release notes

Nutil v0.8.0

This is a major release with several new features. This includes:

• Point clouds that reflect the nonlinear refinement applied with the VisuAlign software.

• Updated object reports.

• Support for automatic generation of plots using Python scripts. These display the regional loads from the Reference Atlas reports and the Custom Region reports.

• Support for defining the Custom Regions with hierarchy.txt files from the QCAlign software.

• Stop button in Nutil has been fixed.

• Improvements to error and warning messages.

• Updates to the help text in the Nutil GUI.

• This version has been assigned DOI: 10.25790/bml0cm.107

Nutil v0.7.0

• This release introduces a new reference atlas: the Waxholm Space Atlas of the Sprague Dawley rat v4 (WHSv4). The citation policy has been updated in the Nutil GUI and Nutil readthedoc for use of the Waxholm Space Atlas.

• The default customised regions for the WHSv3 have been updated. See the customised region.xlsx in the Nutil package for more information.

• Bug 1 that was discovered in Nutil v0.5.0 and partially fixed in v0.6.0 has been fully fixed in this version: the regional load outputs in the slice reports are now correct irrespective of the pixel scale.

• The user documentation has been considerably improved. All user manuals have been removed from the Nutil package, and replaced with a “user documentation” button in the Nutil GUI with a direct link to the Nutil readthedocs. These are updated on a regular basis, and also include user documentation for use of ilastik for the QUINT workflow.

• Improvements to error and warning messaging, and updates to the help text in the Nutil GUI.

Nutil v0.6.0

This release does not introduce new features but fixes recently discovered bugs affecting the Quantifier reports in some older versions of Nutil.

Bug 1: Regional load output in the slice reports are incorrect for Nutil v0.4.0 – v0.5.0: the other results in the reports are correct. For Nutil v0.6.0_stable, Bug 1 has been fixed for Quantifier analyses run with a pixel scale = 1. A pixel scale of 1 is the default option in Nutil and will be applied in most cases. However, on application of a pixel scale > 1 or < 1, the regional load outputs in the slice reports remain erroneous. This will be fixed in the next version.

Bug 2: When using the mask feature: region pixels, region areas and loads in the reports are incorrect for Nutil v0.4.3 – v0.5.0. This bug does not affect analyses run without masks.

As the bugs affected core Quantifier functionality, we have introduced more stringent quality assurance routines, with continuous integration and automatic validation based on an expanded collection of ground truth datasets. We will provide more information about this in a future release.

Nutil v0.5.0

Nutil version 0.407 included an upgrade to Qt 6. This introduced several major bugs due to Qt library updates. We have decided to delete this version entirely, and present Nutil v0.5.0 with upgrades and bug fixes to solve the issues found in Nutil v0.407:

• Upper size limit for the “segmentation” input files has been removed.

• TiffCreator library fix.

• Improved XML error messaging to prevent spontaneous crashes.

• QuickNII and VisuAlign user manuals have been added to the Nutil package.

The release notes that followed version 0.407 still apply:

• There is a focus on usability improvements in the new release. This includes a scroll bar fix, improvements to file navigation, and improved error messaging. There are also several transform bug fixes.

• Support has been implemented in Quantifier for JSON files containing the registration information. Either the XML or JSON file from QuickNII, or the JSON file from VisuAlign may now be used to supply the linear anchoring information needed for coordinate extraction.

• Support has also been implemented for navigation to masks from a separate folder, and not from the segmentation folder as in earlier versions.

• There have been updates to the text in the Nutil GUI, and an extensive user manual update.

Nutil 0.403

• Significant improvements to the Quantifier reports including a bug fix for region area quantifications (the previous version had a slight rounding up error; old reports are still useable, but we recommend switching to the latest version).

• The Transform feature now supports import of file names and transformation parameters from an Excel template titled “TransformTemplate” (included in the Nutil package).

• Improvements to the inbuilt help text throughout. User manual updates.

Nutil 0.402

Several bug fixes including a major fix for Nutil Quantifier analysis with WHS rat atlas v3. Updated Nutil user manual and new ilastik user manual.

Nutil 0.4.01

Two minor bug fixes and command line interface script for batch processing added.

Nutil 0.4

Major release with new GUI. Bug fixes and performance improvements. Improved error messaging. Detailed help text for every input parameter. New resize feature implemented. Command line version.

Nutil 0.33

Download the Nutil Windows Binaries and extract the zip file. When running the main program “Nutil.cmd”, the executable will automatically check for and download new versions.The package includes a user manual and an example template.

Quality assurance / validation

Note

Nutil v0.7.0 and v0.8.0 are stable and validated with multiple ground truth datasets.

Warning

It is not recommended to use Nutil v0.4.0 - v0.6.0: they contain bugs that lead to incorrect results in some of the reports: see the release notes for more information.

Validation

More stringent quality assurance routines were introduced in February 2021 in light of several bugs discovered in Nutil affecting core Quantifier functionality (see the release notes for more information about the bugs). The routines include continuous integration and automated validation on Github, based on a collection of ground truth datasets. As Nutil has many options for customised analysis, which has evolved over time in response to users needs, not all features have been tested to the same extent. The core functionality is tested more extensively than less central features. The testing status of each feature is listed below.

• We recommend that all data from Nutil is validated externally prior to research use, as mistakes in image preparation and set-up may invalidate the output. It is also possible that bugs remain, especially in features that have not been tested as part of the automated validation.

• If you detect errors please post an issue on Github https://github.com/Neural-Systems-at-UIO/nutil/issues or contact EBRAINS support: support@ebrains.eu.

Automated validation

The automatic validator was implemented in Nutil on 22.02.21: it directly compares PNG, TIF, TIFF, CSV and HTML files from two sets of Nutil analyses, with any differences flagged. It is set up so that the output from new versions of Nutil are compared to ground truth data that have validated output, to ensure that any errors in the code are picked up prior to release. In order to pass the validation, the Nutil results and ground truth must be identical.

Two validation systems have been implemented that utilise the Validator:

1. Automated validation on Github that initiates with each pre-release

Nutil is open-source and shared with continuous integration and automatic validation on Github. For automatic validation, a new version of Nutil is compiled and used to process the ground truth datasets on a virtual machine. The result are compared to the corresponding ground truth with the Validator, with a release on Github if the result matches the ground truth exactly. If the Validator detects differences, the release is blocked and the differences are flagged. We then investigate and fix any code errors.

Ground truth datasets

1. Synthetic dataset described in the validation section of Groeneboom et al, 2020 (DOI: 10.3389/fninf.2020.00037). This comprises two sections, with objects of specified size and spatial location in the Allen Mouse Brain Atlas CCF3 v2015.

2. Same dataset as above but with hemisphere masks applied to validate the mask feature.

3. Synthetic dataset composed of three sections with objects of known size and anatomical location in the Waxholm Space Atlas of the Sprague Dawley rat v4.

4. Transform dataset.

Additional datasets have been added: see the collection on Github.

2. Automated validation on a local machine

For a more thorough validation, the Validator is initiated manually on a local machine with a larger collection of test datasets. These are not shared on Github.

Feature testing status

1. Reference atlases - (Allen mouse brain / Waxholm Space Atlas of the Sprague Dawley rat) - validated.

2. Object colour - standard colours are validated (black 0,0,0 , white 255,255,255, blue 0,0,255, red 255,0,0).

3. Object splitting - (YES/NO) - validated.

4. Mask feature - validated.

5. Customised reports - (default/custom) - validated.

6. Minimum object size - validated.

7. Pixel scale - validated.

8. Pixel scale unit - validated.

9. Output report type - CSV is validated. HTML has not been extensively tested, some errors known here, but nothing significant.

10. Coordinate extraction - the output “looks” right but this has not been validated thoroughly.

11. Coordinate random distortion - do not use, there is a bug here. This feature will be removed in future versions.

12. Point cloud density - the output “looks” right but this has not been validated thoroughly.

13. Nifti size - not validated.

14. Display object IDs - No known bugs but not validated thoroughly.

15. Display region IDS - No known bugs but not validated thoroughly.

16. Unique ID format - (_sXXX / user) - no known bugs.

Warning

In some instances, a bug may only occur with certain combinations of settings: It is not possible to test every combination, and so in rare instances bugs may remain despite being marked as “validated” above.

Nutil as a command line tool

Nutil is a standalone application with a graphical user interface that does not require coding ability to navigate. However, Nutil can also be run as a command line tool for batch processing. This is particularly useful if you have large numbers of series and want to automate the analysis process: it allows you to initiate batch processing of many image series using .NUT files that have been set up in advance. The batch processing script is called “process_folder.bat” and is located within the Nutil software in the following location:

Nutil\program\process_folder.bat

• Set up a unique .NUT file for each image series and save them in a folder.

• Navigate to the process_folder.bat file in the Nutil software using the command line.

• Enter the path to the folder containing the .NUT files, and type the no. of core processors (threads) to use for the analysis.

Windows example:

C:\nutil\program>process_folder.bat   Z:\HBP_Analytics\Nutil_data\batch   4

Contact us

To report issues: https://github.com/Neural-Systems-at-UIO/nutil/issues

For user support: email support@ebrains.eu or post an issue on github.

TiffCreator

The TiffCreator operation converts JPEG, PNG, BMP, GIF and untiled TIFF images to the tiled TIFF format that is compatible with Transform. TiffCreator operates in batch, converting all the images in an input folder and saving them in the specified output folder.

How to run TiffCreator

1. To begin, click “New”. Select “TiffCreator”.

2. Select the input folder (containing the images to be converted), output folder and enter the TiffCreator parameters in the Nutil GUI (e.g. output compression type).

3. Press “Save as”. This saves a copy of the selected settings in a simple text file in .NUT format. The NUT file is for your own records but may be reloaded into Nutil via the “load” button.

4. Nutil automatically detects the number of core processor available (8 in the example). Choose one less than the total available to ensure adequate processing power (6 or 7 here) and press “Start”. Wait until the process is complete.

5. The tiled TIFFs are saved in the specified output folder.

Nutil includes an inbuilt user manual accessed via the “Help” buttons.

Transform

The Transform operation enables the batch renaming, rotation, resizing and thumbnail compilation of tiled TIFF images (max size: 4 GB). The transformed TIFF images are in TIFF format, and the thumbnails are in PNG format.

Note

The tiled TIFF image format has an upper size limit of 4 GB. Nutil cannot transform or generate images that are bigger than 4 GB.

How to run Transform

1. Click “New”. Select “Transform”.

2. Give the project a title: this is for documentation purposes only.

3. Select compression type to apply to the images: LZW (lossless - all information retained, larger images), JPEG (lossy - some unimportant info removed, smaller images) and none.

Tip

If Nutil gives error message “Maximum TIFF file size exceeded”: switch to JPEG compression.

4. Select the input folder containing the images to be transformed and select the output folder where you want the images to be saved.

5. Switch autocropping “on” or “off”. To use the autocropping feature, fill in the background colour of the images and a background colour range. There is more information about this in the “Help” buttons in the GUI.

6. Press the “Fill files” button to view all the images in the input folder. To transform your TIFF images, enter new transformation parameters in the form. The files can also be renamed here. Alternatively, if you wish to downscale the images and convert to PNG images only (for example, for use with ilastik), leave the transformation parameters at the default settings. Open “advanced settings” and select “only create thumbnails”. For the thumbnail size enter the required resize factor. e.g. 0.5.

7. Once everything is filled in press the “Save as” button. This saves a copy of the transformation parameters in a simple text file in .NUT format. This is for your own records, but may also be reloaded into Nutil via the “load” button.

8. Nutil automatically detects the number of core processor available (8 in the example). Choose one less than the total available to ensure adequate processing power (6 or 7 here).

9. Press “Start” and wait until the process is complete.

Resize

The Resize operation enables rapid resizing of PNG, JPEG and untiled TIFF images by application of a resize factor or a fixed pixel width. The output images are in PNG format and are suited for ilastik segmentation.

How to run the Resize operation

1. To begin, click “New”. Select “Resize”.

2. Select the input folder, output folder and resize factor in the Nutil GUI (see the “help” buttons for more information).

3. Press “Save as”. This saves a copy of the parameters in a simple text file in .NUT format. This is for your future records but may also be reloaded into Nutil via the “load” button.

4. Nutil automatically detects the number of core processor available (8 in the example). Choose one less than the total available to ensure adequate processing power (6 or 7 here) and press “Start”. Wait until the process is complete.

5. The PNG files save automatically in the specified output folder.

Introduction

Quantifier is an integral part of the QUINT workflow. It support quantification of labelled features in images of histological sections from mouse and rat brain based on a reference atlas. The following atlases are currently supported:

• Allen Mouse Brain Atlas Common Coordinate Framework version 3 (2015 and 2017)

• Waxholm Atlas of the Spraque Dawley Rat, version 2, 3 and 4.

Warning

QUINT does not support quantification for regions that fall outside of the reference atlases, or quantification without use of an atlas.

Watch our video utorial:

Quantifier requires three sets of input:

1. Atlas maps in FLAT format (generate with QuickNII or VisuAlign).

2. Registration information in XML or JSON format (generated with QuickNII, VisuAlign or DeepSlice).

3. Segmentations with the features to be quantified in a unique RGB colour (indexed 8-bit PNG format) (generated with ilastik or another image analysis tool).

It generates three sets of results:

1. Reports with counts and percentage coverage per reference atlas region. There is also the option to generate reports for customized regions (compilations of reference atlas regions) (CSV format).

2. Images with the segmentations superimposed on the atlas maps (PNG format).

3. Point clouds for visualising the extracted objects in the Meshview Atlas Viewer (JSON format).

As the QUINT workflow requires the use of several software including QuickNII, Ilastik and Nutil, this section is split into several parts with information on how to prepare the input files, how to run Quantifier, and how to interpret the results.

Preparing the input files

File naming requirement

Tip

Change the names of the images to comply with the QUINT file naming convention as the first step of the QUINT workflow.

By using images that follow the naming convention in QuickNII, VisuAlign and ilastik, the output files from these software will also comply with the naming convention, and are thereby directly compatible with Quantifier.

• The file name of the segmentation and the atlas map corresponding to a particular section must contain the same unique ID. They should follow the _sXXX naming convention, with XXX representing the section number (not restricted to three digits).

• The section number should reflect the serial order and spacing of the sections, this is a requirement for QuickNII. For example, _s02, _s06, _s10 for every 4th section starting with section 2.

• The XML or JSON file from QuickNII or VisuAlign must contain the unique IDs (check this by opening with Notepad). This happens automatically as long as the images registered in QuickNII contain the unique IDs in the file name.

• Quantifier also supports user-defined IDs using regular expressions (RegExp). This means that it is possible to bypass the _sXXX naming convention. While this is not recommended, it is useful in some cases. For more information see the “Help” button in the Nutil interface or contact User Support.

Examples that comply with the naming convention:

Histological image: tg2345_MMSH_s001.png. Segmentation image: tg2345_MMSH_s001_segmentation.png. Atlas map: tg2345_MMSH_s001_nl.flat

Warning

Do not include periods (“.”) or spaces (” “) within the file names. This will not work.

As Quantifier scans and detects the “_s” part of the name, the file name should not contain additional “_s”., for example: tg2345_MMSH_ss_s001.png.

Preparing the Segmentations

Any image analysis software may be used to generate the segmentations as long as they meet the following requirements:

1. Format: Must be indexed 8-bit or 24-bit images in PNG format.

   Quantifier is only able to quantify one RGB colour at a time. Apply one RBG colour to all the objects-of-interest, and specify this colour in the Nutil GUI. For example, the objects here are red, so extract RGB colour: 255,0,0.

2. Image proportions: Must have the same proportions as the images used to generate the atlas maps.

   They do not have the same proportions as the actual atlas maps as QuickNII alters the proportions slightly.

3. Image size:

While Nutil supports segmentations up to 32767 x 32767 pixels (as long as there is enough memory installed on the computer: restriction of Qt: QImage class), we do not recommend running Quantifier on images larger than approximately 10000 x 10000 pixels. Downscale the images as much as possible before segmenting them.

They do not need to be the same size as the images used to generate the atlas maps and are typically larger in size. It is recommended to downscale the images prior to segmentation. This has several advantages:

• It improves the quality of the segmentation as it removes noise from the image, and makes them more compatible with the machine learning algorithms used by ilasti.

• It speeds up Nutil analysis and prevent crashes due to insufficient memory.

The aim is to downscale the images as much as possible but without losing information from the images that is actually important. The optimal scaling factor is determined by trial and error and should be applied consistenty to all the images in the series.

Tip

Software recommendations

Ilastik: We recommend the Pixel and Object Classification workflows in the ilastik software to generate the segmentations, with the Glasbey lookup table applied with FIJI to visualise the output. See here for instructions.

QuPath: is an alternative that can be used to generate the segmentations. In some cases QuPath may perform better than ilastik.

FIJI ImageJ: Fiji is also useful for generating segmentations.

Preparing the Atlas Maps

The atlas maps are generated with QuickNII, which applies linear registration of the sections to the atlas, or with VisuAlign that applies nonlinear refinement to an existing QuickNII registration. The VisuAlign atlas maps are thereby more accurate than the QuickNII atlas maps, but also take more time to generate. The atlas maps are customised to match the cutting plane and proportions of the brain sections.

File format: The atlas maps are in .FLAT format and cannot be viewed directly. The image below shows the information contained in an atlas map, but is not the .FLAT file itself.

Preparing the XML or JSON file

Either the XML or JSON file from QuickNII, DeepSlice or VisuAlign may be used here.

How to run Quantifier

1. Create three new folders: for example, “Segmentations”, “Atlas_maps” and “Output”. Transfer the segmentations to the “Segmentations” folder, the atlas maps to the “Atlas_maps” folder. Leave the “Output” folder empty.

2. To begin, click “New”. Enter a name for your project.

3. Press the “browse” buttons and navigate to the folders containing the segmentations, the atlas maps and the output folder, and to the XML or JSON file containing the registration information.

4. Select the reference atlas used in QuickNII and VisuAlign.

5. Fill in the rest of the form. The software includes “Help” buttons with more information for each parameter.

6. The “advanced settings” reveals more settings: this gives flexibility for customised analysis. For example, minimum object size cut-off, option to generate customised reports and to apply masks. If nothing is changed in the advanced settings, the default settings shown below are applied.

7. Press “Save as”. This saves a copy of the settings in a simple text file in .NUT format. This is useful for future reference, and may be reloaded into Nutil via the “load” button (for example, to repeat the analysis on a new set of images).

8. Nutil automatically detects the number of core processors (threads) available on the computer (8 in the example). To ensure adequate processing power, choose at least one less than the total available (6 or 7 here) and press “Start”. Wait until the process is complete: this may take minutes to hours depending on the number of sections and size of the segmentations. If your images are very large and Nutil crashes, select fewer cores.

9. The output files are automatically saved in the specified output folder.

Advanced Parameter	Default settings
Minimum object size	1 pixel
Pixel scale	1 pixel
Use custom masks	No
Output report type	CSV
Apply customised regions	Default
Coordinate extraction	All (Yes, for whole series and per section)
Pixel density	1 coordinate per pixel
Unique ID format	_sXXX…

Tip

See the FAQ for more information on the Pixel Scale.

Python plots

Tip

Nutil v0.8.0 has a new automatic plotting feature. The Python scripts are included as part of the Nutil package.

THe plotting feature will work if Python is installed on the computer, with the Python.exe selected in Nutil through: File –> Settings. It is also necessary to install the following Python packages on your computer: numpy, pandas and matplotlib.

For how to install Python and packages refer to Python documentation.

Object splitting explained

In Quantifier, users must specify whether to turn “object splitting” ON or OFF.

With object splitting switched ON, segmented objects that overlap atlas regions are divided into parts, with the individual object pixels assigned their precise regional location. This ensures accurate regional % load measurements (load is the percentage of the region occupied by objects: the % coverage or area fraction). This invalidates the object counts as some objects will be split and counted more than once which means that N/A appears in the reports.

With object splitting switched OFF, object counts are correct, but the load measurements may be incorrect since objects that overlap region boundaries will be assigned to one of the regions only, potentially skewing the regional load calculations. This is especially true if objects are large, since a large object that overlaps many regions (e.g. 1000 pixels) may be assigned to a small region (e.g. 100 pixels) giving false load output (1000% load in this case).

Note

Recommendation:

Select NO for small objects to get accurate object counts, e.g. cells.

Select YES for large objects that overlap atlas regions, e.g. connectivity data, or densely packed cells or features. This gives precise % load output.

See the object splitting help button in Nutil for an example image.

Custom masks explained

The mask feature is optional. It allows the application of masks to define which parts of the sections to include in the analysis. The mask is applied in addition to, and not instead of, the reference atlas maps. This is useful for investigating expression differences in the right and left hemisphere as a mask can be applied to differentiate the two sides. It is also useful for defining areas to exclude from the analysis (for example, in the case of hemibrain sections).

• Create binary masks (black and white) in PNG format with an application such as QuickMask, NIH ImageJ, Adobe Photoshop or GIMP. These should have the same proportions as the segmentations but are typically smaller in size.

Note

QuickMask is a desktop tool for automatically generating masks to differentiate the right and left hemisphere based on a QuickNII or VisuAlign registration. Peliminary versions of the QuickMask tool are available for download on the respective NITRC pages for the tools.

• To use the mask feature, select “yes”. This brings up a “custom mask folder” and “Custom mask colour” option.

• Name these with the unique ID for the section and a “_mask” extension. File name example: Bxb_hgt_s002_mask

• Navigate to this folder containing the masks.

• Click on the field for the “Custom mask colour”. Select the colour in the mask that corresponds to the ROI to include in the analysis. For example, for an analysis of the left hand side of an image with the mask shown here, specify black (RGB code: 0,0,0).

QuickMask application

QuickMask is a simple tool for generating masks that are compatible with the Nutil software.

There are two versions of QuickMask. They work in the same way.

QuickMask: generates masks that reflect the linear registration performed with QuickNII (download on the nitrc page for QuickNII).

QuickMask-NL: generates masks that reflect the nonlinear adjustments applied with VisuAlign (download on the nitrc page for VisuAlign).

1. Open the QuickMask tool.

2. Use the “pick JSON” button to navigate to the QuickNII JSON or VisuAlign JSON for your image series (the file that contains the registration information).

3. For left-right hemisphere masks, enter the following X, Y and Z coordinated in QuickMaskNL.

Top left: 227, 32.2, 292.8. Top right: 227, 367.9, 291.8 Bottom left: 227, 34.5, 48.7

Alternatively, enter the following coordinate string in the box at the bottom of the interface: 227 32.2 292.8 227 367.9 291.8 227 34.5 48.7

4. Use the “Destination” button to navigate to the folder where you want your masks to be saved.

5. Press Go. The masks are automatically generated for all the section images in the series. The masks have the original image file name with a _mask extension.

Customised reports explained

Quantifier generates several reports, including CustomRegion reports. These contain quantifications for broader regions. The broad regions are compilations of reference atlas regions and may either be user-defined (“Custom”) or the default regions included in the Nutil software (“Default”).

Tip

The QCAlign software has a viewer for exploring the reference atlas hierarchy, and can be used to create a custom region file (hierarchy sheet in TXT format) that is compatible with Nutil.

CustomRegion reports

1. The simplest option is to run the analysis with the “default” regions that are in-built in the Nutil software. Select “default”.

More information on the default regions are found in the CustomRegion files in the Nutil software package, located in the CustomRegion folder. The “default” option is a complete brain analysis, which means it includes all the reference atlas regions compiled into broader regions. For example, for the Allen Mouse Brain Atlas v3,2017, the custom regions are; the cortex; fiber tracts; hippocampus; olfactory regions; hypothalamus; regions in the striatum and pallidum; midbrain - hindbrain - and medulla; thalamus; cerebellum; and ventricular system.

2. Alternatively, generate CustomRegion reports based on your own compilations of reference atlas regions. Select “custom” and navigate to the relevant CSV or XLSX file.

There are two options for generating this file:

• Use the QCAlign software (hierarchy sheet in CSV format).

• Defined your own regions using the CustomRegionsTemplate.xlsx provided in the CustomRegion folder of the Nutil package. Fill in the template exactly as shown below:

ROW 1: assign your own names to the regions (For example, cortex. This is for your information only).

ROW 2: assign colours to the regions. Do this by typing a RGB colour code in the following format: 255;0;0 (for red). This colour will be assigned to the objects located in the custom region for the purposes of the image output and coordinate output (for display purposes only).

ROW 3: enter the colour name (this is for your information only).

ROW 4: define the region by listing the reference atlas IDs that you wish to include. The excel sheets in the AtlasHierarchy folder list all the regions and IDs for each atlas.

For mouse, see the ABAHier2015.xlsx or ABAHier2017.xlsx file for the full list of regions and IDs.

For rat, see the WHS_rat_atlas_v2.xlsx or WHS_rat_atlas_v3.xlsx file for the full list of regions and IDs.

The default .xlsx may be used as a guide for filling out the template.

How to interpret the results

Nutil generates up to three sets of reports, overlay images and a .NUT file. The sections below give more information on each type of file.

For each report, interpret the results as follows:

Region pixels	Number of pixels representing the region.
Region area	Area representing the region (region pixels x pixel scale).
Area unit	Region area unit (unit of the pixel scale).
Object count	Number of objects located in the region (N/A if object splitting “ON”).
Object pixels	Number of pixels representing objects in this region.
Object area	Area representing objects in this region (object pixels x pixel scale).
Load	Ratio of Object pixels to Region pixels (Object pixels / Region pixels).

The main results are:

• Load. This refers to the regional load or area fraction. Use this with object splitting switched ON (object splitting OFF may invalidate the % load).

• Count. This is a count of segmented objects that fall within the region. Use this for small objects only with the object splitting switched OFF (object splitting ON may invalidate the counts).

See Object splitting explained.

RefAtlasRegion report

RefAtlasRegion reports contain quantifications per atlas-region based on the finest level of granularity of the atlas. There is one report for the whole series (all sections combined) and one per section.

Note

The Allen Mouse Brain Reference Atlas includes regions that are not actually delineated in the atlas. These regions are either big regions that have been delineated into smaller regions and so are not assigned to any pixels in the reference atlas, or are smaller regions that are not delineated. In the reports, these regions have no results (zero for region pixels and for object pixels). They should be excluded from analysis.

The Clear Label ID covers objects that fall outside of the atlas maps

CustomRegion report

CustomRegion reports contain quantifications for broader regions. These broader regions are compilations of reference atlas regions, and may either be user-defined (“custom”) or the default regions included in the Nutil software (“default”). For more information see the “Customised regions explained” section. A report is provided for the whole series (all sections combined) and per section.

Object report

Object reports contain information about individual objects: it lists all the objects in the whole series and per section. As object splitting invalidates the object counts, this report is only generated when the object splitting feature is switched “OFF”.

By switching “ON” the “display object IDs in image file and reports”, a unique ID is assigned to each object in your dataset. These IDs are displayed in the image files and in the object reports to enable identification.

Overlay images

• Segmentations superimposed on the atlas maps in PNG format.

• The object colours are assigned based on the customised regions. If no regions are specified, or object falls outside of the specified areas, the objects are displayed in red by default.

• The object ID assigned to an object (for the purpose of identification in the Object report), as well as the reference atlas region ID corresponding to its location, may be printed on the overlay images by switching “ON” these options in the “Advanced Settings” for Nutil Quantifier. If both these are switched “ON”, the reference atlas region ID is printed at the top and the object ID at the bottom.

Coordinates

• JSON files containing point clouds with the coordinates following a Right-Anterior-Superior (RAS) orientation and expressed in voxels. These can be directly viewed with the MeshView Atlas Viewer.

• For more information on the coordinate system and how to convert to Allen CCFv3 and Waxholm Space coordinates, see here.

• Links to Meshview are available here

• Online converters are provided here.

Warning

The coordinates generated with Nutil version 0.8 reflect both the linear and nonlinear transformation applied with QuickNII and VisuAlign. Nutil version 0.4 - 0.7 are based on the linear transformation only and do not take into account the nonlinear transformation.

NUT file

The NUT file is a text file that contains the parameters that were used for the Nutil analysis. This can be loaded into Nutil Quantifier with the “load” button to recreate the analysis.

To view its content, open the NUT file in Notepad. As the NUT file is an internal document intended for the transfer of metadata only, it is not always easy to interpret. Some of the parameters stored in the file are conditional on other fields, and so are not activate unless the condition is met. For example, the custom_mask_colour field is not applied unless use_custom_masks = Yes. However, the NUT file does contain information about the Nutil version used for the analysis, and can give clues to potential errors and is useful for problem solving.

Warnings and error messages

Quantifier

Warning

WARNING: Some of the area matrices were not initialized.

• The JSON or XML file contains info about sections that are not included in the analysis: for example, if you run an analysis for a few sections only.

• This is not a problem, the analysis will generate correct results, but alerts you to missing sections in case this was not intended.

Warning

WARNING: Could not find data in .xml or .json file for slice ‘_s001’, so 3D data will be incorrect. Please make sure that there exists a corresponding field in the xml or json file!

This means what it says: Nutil can’t find the relevant anchoring information in the .json file. This can happen for a number of reasons.

• The slice is missing in the .json file. Open the .json file in a text editor such as notebook and check.

• The slice is missing anchoring information. This happens if it has not been registered to the reference atlas in QuickNII or VisuAlign. Sometimes it happens because the registration info has not been saved in QuickNII for the slice (remember to confirm the registration!).

• The default ID format is selected in Nutil Quantifier (_sXXX), but the slice ID does not match this format. In this case, switch to “user” defined ID and define the ID using RegEx. It is also possible that the RegEx is incorrect: make sure it correspond to the ID.

• The slice ID does not match the ID in the corresponding segmentation and atlas map. In this case, the IDs have to be revised so that they match across the board. We recommend using the _sXXX format.

Warning

ERROR: Could not find FLAT files that contains: _001.

• This means that there is a discrepancy in the atlasmaps and segmentation: Nutil will fail to run if there is a discrepancy.

• To fix this, either add the FLAT file for the missing section or remove the segmentation with this ID from the segmentation directory.

Warning

WARNING: Unrecognised atlas map in the anchor file. Might be a potential problem, please make sure the atlas is correct!

• Automatic atlas recognition was implemented in Nutil v0.8.0. This means that Nutil selects the atlas version based on the information in the .xml or .json file, rather than relying on the atlas selected by the user in the Nutil interface. This works for the AMBA CCF for the latest versions of QuickNII and VisuAlign, but is not implemented correctly for the rat brain.

• This warning will come up if older versions of QuickNII are used, or if the WHS atlas is selected. This is not a problem as Nutil will instead use the atlas selected by the user in the Nutil interface. If in doubt, open the .json file to check the atlas version.

Transform

Warning

TIFFAppendtoStrip: Maximum TIFF file size exceeded.

• Nutil cannot transform or generate images that are larger than 4 GB: this warning means the images exceed this limit.

• This may happen even if the images do not exceed 4 GB since rotation adds extra space to the image corners to retain the rectangular shape of the image.

• If the original images are below 4GB but you get this warning, select JPEG compression. This will reduce the size of the images that are generated.

FAQ

I can’t open the application. “Windows protected your PC”

“Windows protected your PC, Microsoft Defender SmartScreen prevented an unrecognized app from starting. Running this app might put your PC at risk”.’

To fix this, right click on the Nutil.cmd > Properties > General > check “unblock” under Security.

Nutil shuts down during a run and/or generates corrupt files

Nutil will either shut down or create corrupt files if it loses connection with the images while running. To prevent this, install the Nutil software locally (on the C: drive) and apply to images installed locally where possible. In many cases, Nutil can also be applied from the C:drive to files located elsewhere (for example, a remove drive). However, if you have problems with crashing and corrupt files, try saving the input images in the same location as the Nutil software.

There are no object counts in the reports (N/A)?

This is usually because Object Splitting is turned “on”, which means that each object pixel is assigned to its correct anatomical location. This gives correct percentage coverage per regioon, but invalidates the counts as objects that cross region boundaries are split into two or more objects. Therefore the object count: N/A. To get object counts, turn object splitting “off”. This means that each object is assigned to one region only, giving accurate counts per regions.

See for more info: https://nutil.readthedocs.io/en/latest/QuantifierOS.html

The reports (CSV) don’t open correctly in Microsoft Excel

Different countries have different conventions regarding file separators. The CSV files from Nutil have semi-colon (;) delimiters (this is the default delimiter in the Norwegian version of Microsoft Excel). However, comma (,) is the default separator in the US, UK and some European countries, which means that the CSV files will not open automatically in MicroSoft Excel. To open the CSV in Excel, open Excel, go to “Data” > “From Text” > select the report to open > select “Delimiter” > select “semicolon”.

It is also possible to change the default separator on your computer by changing the regional settings. Start > Control Panel > Regional and Language Options > Additional Settings > List Separator- enter a semicolon (;). This can then be changed back to comma (,) when you have finished your analysis.

I don’t understand what to enter for the Pixel Scale?

• It is not usually necessary to enter a Pixel Scale in Nutil. This is because the regional loads are ratios (no. of pixels corresponding to your objects divided by no. of pixels representing the region), which means that they are not affected by the pixel scale. If the goal is to measure regional loads or no. of objects per region, then leave the Pixel Scale blank.

• If you need the “real” size of your objects or regions, multiply the pixel counts in the reports by the area represented by each pixel in the segmentated images (pixel scale is an area, for example in um2). As long as all the segmented images have the same pixel scale, the pixel scale can be entered in Nutil and this calculation will be performed automatically. Note that it is the pixel scale of the segmentations that counts here, not the pixel scale of the images used for atlas registration!

How do I calculate the Pixel Scale of images that have been downscaled?

To do this, you need the pixel width of your original images in “real life” terms, for example, pixel width = 0.4 um (this depends on the microscope settings and is usually provided by the scanner). You also need to know the resize factor that was used to downscale the images prior to segmentation, for example, 0.5. The pixel width in the downscaled images can be calculated as follows: original width / resize factor, for example, 0.4 / 0.5 = 0.8 um. To calculate the pixel scale of your downscaled images, square this number. This converts it to an area, for example, 0.8 x 0.8 = 0.64 um2.

The QUINT coordinates do not match the Allen CCFv3. What’s going on?

This is true and confusing, but is easy to solve as we provide a converter.

The coordinates from QuickNII and the QUINT workflow follow Right-Anterior-Superior orientation and are expressed in voxels.

• First axis (x) starts from the left side of the volume, and points towards the right

• Second axis (y) starts from the backmost position in the volume, and points towards the front

• Third axis (z) starts from the bottom of the volume and points towards the top

The Allen CCFv3 follows a Posterior-Inferior-Right axis directions, and the values are expressed in μm . This necessitates a three-step transformation:

• Reordering coordinates: [x,y,z]RAS,vox => [y,z,x]ASR,vox

• Flipping posterior-anterior and inferior-superior axes: [x,y,z]RAS,vox => [527-y,319-z,x]PIR,vox

• Multiplying the components with 25: [x,y,z]RAS,vox => [(527-y)*25,(319-z)*25,x*25]PIR,μm

The QUINT coordinates do not match the WHS coordinate system. What going on?

The WHS rat brain atlas uses the same axis order and orientation as QuickNII, only translation of origin, and scaling have to be applied. WHS origin is at 244, 623, 248 voxel coordinates, and everything has to be converted to mm, where the atlas resolution is 0.0390625 mm (isotropic).

A converter is provided here.