Skip to main content

Convert lh/rh z-score vector to FreeSurfer labelmap

Project description <nav class="contents" id="table-of-contents" role="doc-toc">

Table of Contents


Abstract generates FreeSurfer labelmaps from z-score vector files. Essentially the script consumes an input text vector file of

<str_structureName> <float_lh_zScore> <float_rh_zScore>

for example,

G_and_S_frontomargin     ,0.5448091104245965,2.1984208046033986
G_and_S_occipital_inf    ,2.8903998330126033,0.4572919630956416
G_and_S_paracentral      ,1.2532502118658488,2.926149972421385
G_and_S_subcentral       ,0.08957410838556834,-1.0394448514419545
G_and_S_transv_frontopol ,2.506061659979438,2.9292234802387016
G_and_S_cingul-Ant       ,1.5676599314826145,1.2518433645260645
G_and_S_cingul-Mid-Ant   ,-2.0852613982062906,-1.8590432278757094
G_and_S_cingul-Mid-Post  ,-1.7092668741782007,0.3838372718413847
S_precentral-sup-part    ,-1.3960847017718006,1.6622440401857297
S_suborbital             ,2.8856830919767953,1.8816070202675919
S_subparietal            ,1.3496617403262476,-1.675320447065229
S_temporal_inf           ,1.4126969390609307,-0.6749188207976502
S_temporal_sup           ,-2.4332291352859303,2.5302245055483006
S_temporal_transverse    ,0.6026745551244295,-1.601135653918334

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

--posColor R --negColor RG

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


python                                            \
    [-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>                                                  \


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

pip install z2labelmap

and run with --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

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

Thus, getting inline help is:

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


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:

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

or without docker

mkdir in out                                                   \
        --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:

docker run --rm -v $(pwd)/in:/incoming -v $(pwd)/out:/outgoing  \
        fnndsc/pl-z2labelmap                      \
        --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).

Command line arguments

Required argument.
Input directory for plugin.

Required argument.
Output directory for plugin.

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

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'.

If specified, print version number.

If specified, print (this) man page.

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.7.tar.gz (10.7 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