Neurolucida Companion for Spatial Distribution analysis (NCSD)

Olivier Friard, Serena Bovetti, Simona Gribaudo and Silvia De Marchis (Università degli Studi di Torino)


Table of Contents

1. Introduction
2. Legal
3. Install NCSD
3.1. Install NCSD for a command line usage (all platforms)
3.2. Install the NCSD Graphic User Interface (GUI)
4. How to use
4.1. Graphic interface
4.2. Command line use
4.3. Results
5. Spatial distributions of markers
5.1. Command line use
5.2. Results
6. Cell bodies analysis
6.1. Command line use
6.2. Graphic use
6.3. Results
7. Distance analysis
7.1. Command line use
7.2. Graphic use
7.3. Results

1. Introduction

This program is intended to further analyze the XML files produced by the Neurolucida software.

At the moment it is provided with 3 modules allowing to do various spatial distribution analysis:

Markers analysis
allow to draw sector with arbitrary angle and analyze the number of markers in each sector and the sector area.
Cell bodies analysis
Analyze cell bodies: sector, area and distance from arbitrary contour
Distance analysis
Analyze markers in subcontours of an arbitrary contour

NCSD can be either used in graphical mode and in command line mode.

Please contact olivier.friard@unito.it for questions, suggestions and bug reports.

2. Legal

"Neurolucida Companion for Spatial Distribution Analysis" is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or any later version.

"Neurolucida Companion for Spatial Distribution Analysis" is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

3. Install NCSD

3.1. Install NCSD for a command line usage (all platforms)

Download the following archive and expand it:

ncsd-7.src.tar.bz2 (about 15 Kb)

NCSD is written in Python (v 2.6 and greater but < v.3). Check the Python version of your Linux distribution.

3.2. Install the NCSD Graphic User Interface (GUI)

Linux

Install the source package (see "Install NCSD for a command line usage").

If you want to use the GUI, you must install the python-pyside package.

Mac OS X

If you want to use the GUI only, download the DMG archive corresponding to your system and mount it:

64-bit
ncsd-7.64bit.dmg (about 15 Mb)
32-bit
ncsd-7.32bit.dmg (about 30 Mb)

Microsoft-Windows®

Download the following auto-install archive corresponding to your system and launch it on your system.

This installation do not require administrator privileges. The program will be installed in the Application Data directory of the current user.

Windows 32-bit
ncsd_setup_win32.exe (about 7 Mb)
Windows 64-bit
ncsd_setup_win64.exe (about 9 Mb)
[Note]

How to determine if your Microsoft-Windows operating system is 32-bit or 64-bit:

Open the Start menu, and click on Programs → Accessories → System Tools → System Information

Look in the System Summary

The System Information tool will display detailed information about your Windows operating system. Once opened it will show the "System Summary" – it’s an overview of your computer and operating system.

On the right hand side of the window you will see a list of items. Look for the item called "System Type".

The value of this item will tell you whether your computer is 32-bit or 64-bit:

  • x86-based PC: It’s a 32-bit computer.
  • x64-based PC: It’s a 64-bit computer.

See Microsoft site for more details.

4. How to use

4.1. Graphic interface

NCSD GUI

Linux

Launch the ncsd.py Python script.

If you want to use the GUI, you must install the python-pyqt4 package.

Mac OS X

Launch the ncsd file.

Microsoft-Windows®

Click the "Neurolucida Companion for Spatial Distribution analysis from the Start menu.

All platforms

Select a single XML file produced with Neurolucida or a whole directory of XML files.

Select the module tab you want to use and press the analysis button.

When the analysis will be done, a message box will appear.

4.2. Command line use

Linux and Mac OS X

NCSD is written in Python. Check that your Python version is < v.3

From a terminal launch the module (./module_name.py) with all required parameters (see module section for details). If module_name.py is not executable, launch the python module_name.py command.

Microsoft-Windows®

[Important]

Python v.2.6 or greater (but not v.3) must be installed on your system.

From "cmd" launch the module (module_name.py) with all required parameters (see module section for details).

4.3. Results

Results are saved in a "tab separated values" text file. If the output parameter was ommitted the file is created in the same directory that the input file.

If you checked the "Produce SVG file" checkbox in the GUI or used the "-s" option in the command-line a SVG file with all objects (original and added by module) will be saved in the same directory that the input file.

5. Spatial distributions of markers

5.1. Command line use

Usage: ncsd_markers.py [options]

Options:

  -h, --help            show this help message and exit

  -a ANGLE, --angle=ANGLE
                        angle of sectors in degree (must be divisor of 360).
                        The default value is 20 degrees

  -i INPUT, --input=INPUT
                        Neurolucida XML file(s) (use "*.xml" to select more files)

  -o OUTPUT, --output=OUTPUT
                        write results to file

  -v, --verbose         Print program messages

  -s, --svg             Write SVG file

  -d, --debug           Add information useful for debugging in output

5.2. Results

Example of results:

Region  Animal  Lame    Coupe   GL  EPL GrL RMS-OB  ONL Cat6    Cat7    Cat8    Cat9    Cat10   Total   Surface                             >>> 42
Reg1            STIM10D1_BO_S1L1C2  0   0   0   0   0   0   0   0   0   0   0   228664
Reg2            STIM10D1_BO_S1L1C2  36  0   0   0   0   0   0   0   0   0   36  297044
Reg3            STIM10D1_BO_S1L1C2  0   0   0   0   0   0   0   0   0   0   0   22472
Reg4            STIM10D1_BO_S1L1C2  0   0   0   0   0   0   0   0   0   0   0   12974
Reg5            STIM10D1_BO_S1L1C2  0   0   0   0   0   0   0   0   0   0   0   7131
Reg6            STIM10D1_BO_S1L1C2  0   0   0   0   0   0   0   0   0   0   0   5077
...

6. Cell bodies analysis

6.1. Command line use

Usage: ncsd_cellbodies.py [options]

Options:

  -h, --help            show this help message and exit

  -a ANGLE, --angle=ANGLE
                        angle of sectors in degree (must be divisor of 360).
                        The default value is 20 degrees

  -c REF_CONTOUR, --contour=REF_CONTOUR
                        reference contour

  -e CENTER_CONTOUR, --center_contour=CENTER_CONTOUR
                        cEnter contour for slide center determination

  -i INPUT, --input=INPUT
                        Neurolucida XML file(s) (use "*.xml" to select more files)

  -o OUTPUT, --output=OUTPUT
                        write results to file

  -v, --verbose         Print program messages

  -s, --svg             Write SVG file

  -d, --debug           Add information useful for debugging in output

Example of analysis:

python ncsd_cellbodies.py -a 20 -i "slice1234.xml" -v -s -e gran -e glomint

This command will:

  • find center of slide by intersection of line contour and gran contour
  • draw 18 sectors of 20 degrees beginning at line
  • parse all objects beginning with cell
  • find area of cell object, sector position and distance from glomint contour

6.2. Graphic use

The corresponding analysis is done using the GUI with parameters described in the following image:

NCSD Cell bodies analysis

6.3. Results

Example of results:

Cell ID  sector  Area     Distance from glomint
cell01   17      48.38    100.95
cell02   16     124.08    141.978
cell03   16      47.81    155.07
cell04   16      59.50     79.38
cell05   16     369.03    113.02
cell06   16     119.78    141.05
cell07   16      57.26     77.21
cell08   16     486.75    194.41
cell09    3      88.19    974.09
cell10    3     460.25    972.11
cell11   18      41.17    768.62
cell12   18     285.59    801.21
cell13    8      90.32    835.85
cell14    8     352.15    894.31
cell15    8     166.54    839.83
cell16    3      59.48    957.33
...

Example of graphic output (SVG format):

NCSD cell bodies SVG

7. Distance analysis

7.1. Command line use

Usage: ncsd_distance.py [options]

Options:

  -h, --help            show this help message and exit

  -a ANGLE, --angle=ANGLE
                        angle of sectors in degree (must be divisor of 360).
                        The default value is 20 degrees

  -c REF_CONTOUR, --contour=REF_CONTOUR
                        reference contour

  -n N_SUBCONTOURS, --ncontours=N_SUBCONTOURS
                        number of subcontours

  -e CENTER_CONTOUR, --center_contour=CENTER_CONTOUR
                        cEnter contour for slide center determination

  -i INPUT, --input=INPUT
                        Neurolucida XML file(s) (use "*.xml" to select more files)

  -o OUTPUT, --output=OUTPUT
                        write results to file

  -v, --verbose         Print program messages

  -s, --svg             Write SVG file

  -d, --debug           Add information useful for debugging in output

Example of analysis:

python ncsd_distance.py -a 90 -e SVZ -c mitral -n 10 -i "slice1234.xml" -s

This command will:

  • find center of slide by intersection of line contour and SVZ contour
  • draw 4 sectors of 90 degrees
  • trace 10 subcontours of the mitral contour
  • count objects in each subcontours for each sector.

7.2. Graphic use

The corresponding analysis is done using the GUI with parameters described in the following image:

NCSD distance analysis

7.3. Results

Example of results:

Region      Total markers     Markers in sector 1  Markers in sector 2  ...  Area of sector 1    Area of sector 2  ...
mitral      496               86                   140                       122976              177712
mitral 1    5                 2                    1                         1229                1777
mitral 2    25                8                    7                         3689                5331
mitral 3    47                9                    13                        6148                8885
mitral 4    41                6                    13                        8608                12439
mitral 5    45                9                    11                        11067               15994
mitral 6    57                7                    13                        13527               19548
mitral 7    73                12                   23                        15987               23102
mitral 8    86                17                   24                        18446               26656
mitral 9    65                8                    22                        20905               30210
mitral 10   52                8                    13                        23365               33765
NCSD GUI