Skip to main content

Convert lh/rh z-score vector to FreeSurfer labelmap

Project description

pl-z2labelmap
=============

.. image:: https://badge.fury.io/py/z2labelmap.svg
:target: https://badge.fury.io/py/z2labelmap

.. image:: https://travis-ci.org/FNNDSC/z2labelmap.svg?branch=master
:target: https://travis-ci.org/FNNDSC/z2labelmap

.. image:: https://img.shields.io/badge/python-3.5%2B-blue.svg
:target: https://badge.fury.io/py/pl-z2labelmap

.. contents:: Table of Contents


Abstract
--------

``zlabelmap.py`` generates FreeSurfer labelmaps from z-score vector files. These labelmap files are used by FreeSurfer to color-code parcellated brain regions. By calculating a z-score to labelmap transform, we are able to show a heat map, hightlight brain regions that differ from some comparative reference, as shown below

.. image:: https://github.com/FNNDSC/pl-z2labelmap/wiki/images/subj1-heatmap/frame126.png

where positive volume deviations of a parcellated brain region are shown in red (i.e. the subject had a larger volume in that area than the reference), and negative volume deviations are shown in blue (i.e. the subject had a smaller volume in that area than reference).

*Note that this are randomly generated z-scores purely for illustrative purposes*.

Essentially the script consumes an input text vector file of

.. code::

<str_structureName> <float_lh_zScore> <float_rh_zScore>

for example,

.. code::

G_and_S_frontomargin ,1.254318450576827,-0.8663546810093861
G_and_S_occipital_inf ,1.0823728865077271,-0.7703944006354377
G_and_S_paracentral ,0.20767669866335847,2.9023126278939912
G_and_S_subcentral ,2.395503357157743,-1.4966482475891556
G_and_S_transv_frontopol ,-1.7849555258577423,-2.461419463760234
G_and_S_cingul-Ant ,-2.3831737860960382,1.1892593438667625
G_and_S_cingul-Mid-Ant ,0.03381695289572084,-0.7909116233500506
G_and_S_cingul-Mid-Post ,-2.4096082230335485,1.166457973597625
...
...
S_postcentral ,1.3277159068067768,-1.4042773812503526
S_precentral-inf-part ,-1.9467169777576718,1.7216636236995733
S_precentral-sup-part ,0.764673539853991,2.1081570332369504
S_suborbital ,0.522368665639954,-2.3593237820349007
S_subparietal ,-0.14697262729901928,-2.2116605141889094
S_temporal_inf ,-1.8442944920810271,-0.6895142771486307
S_temporal_sup ,-1.8645248463693804,2.740099589311164
S_temporal_transverse ,-2.4244451521560073,2.286596403222344

and creates a FreeSurfer labelmap where ``<str_structureName>`` colors correspond to the z-score (normalized between 0 and 255).

Currently, only the ``aparc.a2009s`` FreeSurfer segmentation is fully supported, however future parcellation support is planned.

Negative z-scores and positive z-scores are treated in the same manner but have sign-specific color specifications. Positive and negative z-Scores can be assigned some combination of the chars ``RGB`` to indicate which color dimension will reflect the z-Score. For example, a

.. code::

--posColor R --negColor RG

will assign positive z-scores shades of ``red`` and negative z-scores shades of ``yellow`` (Red + Green = Yellow).



Synopsis
--------

.. code::

python z2labelmap.py \
[-v <level>] [--verbosity <level>] \
[--random] \
[-p <f_posRange>] [--posRange <f_posRange>] \
[-n <f_negRange>] [--negRange <f_negRange>] \
[-P <'RGB'>] [--posColor <'RGB'>] \
[-N <'RGB'> [--negColor <'RGB'>] \
[-s <f_scaleRange>] [--scaleRange <f_scaleRange>] \
[-l <f_lowerFilter>] [--lowerFilter <f_lowerFilter>] \
[-u <f_upperFilter>] [--upperFilter <f_upperFilter>] \
[-z <zFile>] [--zFile <zFile>] \
[--version] \
[--man] \
[--meta] \
<inputDir> \
<outputDir>

Run
----

This ``plugin`` can be run in two modes: natively as a python package or as a containerized docker image.

Using PyPI
~~~~~~~~~~

To run from PyPI, simply do a

.. code:: bash

pip install z2labelmap

and run with

.. code:: bash

z2labelmap.py --man /tmp /tmp

to get inline help.


Using ``docker run``
~~~~~~~~~~~~~~~~~~~~

To run using ``docker``, be sure to assign an "input" directory to ``/incoming`` and an output directory to ``/outgoing``. *Make sure that the* ``$(pwd)/out`` *directory is world writable!*

Now, prefix all calls with

.. code:: bash

docker run --rm -v $(pwd)/in:/incoming -v $(pwd)/out:/outgoing \
fnndsc/pl-z2labelmap z2labelmap.py \

Thus, getting inline help is:

.. code:: bash

docker run --rm -v $(pwd)/in:/incoming -v $(pwd)/out:/outgoing \
fnndsc/pl-z2labelmap z2labelmap.py \
--man \
/incoming /outgoing

Examples
--------

Create a sample/random z-score file and analyze
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* In the absense of an actual z-score file, the script can create one. This can then be used in subsequent analysis:

.. code::

mkdir in out
docker run --rm -v $(pwd)/in:/incoming -v $(pwd)/out:/outgoing \
fnndsc/pl-z2labelmap z2labelmap.py \
--random \
--posRange 3.0 --negRange -3.0 \
/incoming /outgoing

or without docker

.. code::

mkdir in out
z2labelmap.py \
--random \
--posRange 3.0 --negRange -3.0 \
/in /out


In this example, z-scores range between 0.0 and (+/-) 3.0.

Control relative brightness and lower filter low z-scores from final labelmap
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* To analyze a file already located at ``in/zfile.csv``, apply a ``scaleRange`` and also filter out the lower 80\% of z-scores:

.. code::

docker run --rm -v $(pwd)/in:/incoming -v $(pwd)/out:/outgoing \
fnndsc/pl-z2labelmap z2labelmap.py \
--scaleRange 2.0 --lowerFilter 0.8 \
--negColor B --posColor R \
/incoming /outgoing

This assumes a file called 'zfile.csv' in the <inputDirectory> that ranges in z-score between 0.0 and 3.0, and uses the --scaleRange to reduce the apparent brightness of the map by 50 percent. Furthermore, the lower 80 percent of z-scores are removed (this has the effect of only showing the brightest 20 percent of zscores).

Using the above referenced z-score file, this results in:

.. code::

.. code::



0 Unknown 0 0 0 0
11101 lh-G_and_S_frontomargin 0 0 0 0
11102 lh-G_and_S_occipital_inf 0 0 0 0
11103 lh-G_and_S_paracentral 0 0 0 0
11104 lh-G_and_S_subcentral 103 0 0 0
11105 lh-G_and_S_transv_frontopol 0 0 0 0
11106 lh-G_and_S_cingul-Ant 0 0 110 0
11107 lh-G_and_S_cingul-Mid-Ant 0 0 0 0
11108 lh-G_and_S_cingul-Mid-Post 0 0 111 0
...
...
12167 rh-S_postcentral 0 0 0 0
12168 rh-S_precentral-inf-part 0 0 0 0
12169 rh-S_precentral-sup-part 0 0 0 0
12170 rh-S_suborbital 0 0 110 0
12171 rh-S_subparietal 0 0 103 0
12172 rh-S_temporal_inf 0 0 0 0
12173 rh-S_temporal_sup 119 0 0 0
12174 rh-S_temporal_transverse 0 0 0 0

Command line arguments
----------------------

.. code::

<inputDir>
Required argument.
Input directory for plugin.

<outputDir>
Required argument.
Output directory for plugin.

[-v <level>] [--verbosity <level>]
Verbosity level for app. Not used currently.

[--random]
If specified, generate a z-score file based on <posRange> and <negRange>.

[-p <f_posRange>] [--posRange <f_posRange>]
Positive range for random max deviation generation.

[-n <f_negRange>] [--negRange <f_negRange>]
Negative range for random max deviation generation.

[-P <'RGB'>] [--posColor <'RGB'>]
Some combination of 'R', 'G', B' for positive heat.

[-N <'RGB'> [--negColor <'RGB'>]
Some combination of 'R', 'G', B' for negative heat.

[-s <f_scaleRange>] [--scaleRange <f_scaleRange>]
Scale range for normalization. This has the effect of controlling the
brightness of the map. For example, if this 1.5 the effect
is increase the apparent range by 50% which darkens all colors values.

[-l <f_lowerFilter>] [--lowerFilter <f_lowerFilter>]
Filter all z-scores below (normalized) <lowerFilter> to 0.0.

[-u <f_upperFilter>] [--upperFilter <f_upperFilter>]
Filter all z-scores above (normalized) <upperFilter> to 0.0.

[-z <zFile>] [--zFile <zFile>]
z-score file to read (relative to input directory). Defaults to 'zfile.csv'.

[--version]
If specified, print version number.

[--man]
If specified, print (this) man page.

[--meta]
If specified, print plugin meta data.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

z2labelmap-1.1.8.tar.gz (10.3 kB view hashes)

Uploaded source

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page