Convert lh/rh z-score vector to FreeSurfer labelmap
Project description
Abstract
zlabelmap.py 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>
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).
Synopsis
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
pip install z2labelmap
and run with
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
docker run --rm -v $(pwd)/in:/incoming -v $(pwd)/out:/outgoing \
fnndsc/pl-z2labelmap z2labelmap.py \
Thus, getting inline help is:
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:
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
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:
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).
Command line arguments
<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
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.