{
    "info": {
        "author": "Rudolph Pienaar",
        "author_email": "rudolph.pienaar@gmail.com",
        "bugtrack_url": null,
        "classifiers": [],
        "description": "pl-z2labelmap\n=============\n\n.. image:: https://badge.fury.io/py/z2labelmap.svg\n    :target: https://badge.fury.io/py/z2labelmap\n\n.. image:: https://travis-ci.org/FNNDSC/z2labelmap.svg?branch=master\n    :target: https://travis-ci.org/FNNDSC/z2labelmap\n\n.. image:: https://img.shields.io/badge/python-3.5%2B-blue.svg\n    :target: https://badge.fury.io/py/pl-z2labelmap\n\n.. contents:: Table of Contents\n\n\nAbstract\n--------\n\n``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 and hightlight brain regions that differ from some comparative reference, as demonstrasted below \n\n.. image:: https://github.com/FNNDSC/pl-z2labelmap/wiki/images/subj1-heatmap/frame126.png\n\nwhere 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).\n\n*Note that these are randomly generated z-scores purely for illustrative purposes*.\n\nEssentially the script consumes an input text vector file of \n\n.. code::\n\n    <str_structureName> <float_lh_zScore> <float_rh_zScore>\n\nfor example,\n\n.. code::\n\n    G_and_S_frontomargin     ,1.254318450576827,-0.8663546810093861\n    G_and_S_occipital_inf    ,1.0823728865077271,-0.7703944006354377\n    G_and_S_paracentral      ,0.20767669866335847,2.9023126278939912\n    G_and_S_subcentral       ,2.395503357157743,-1.4966482475891556\n    G_and_S_transv_frontopol ,-1.7849555258577423,-2.461419463760234\n    G_and_S_cingul-Ant       ,-2.3831737860960382,1.1892593438667625\n    G_and_S_cingul-Mid-Ant   ,0.03381695289572084,-0.7909116233500506\n    G_and_S_cingul-Mid-Post  ,-2.4096082230335485,1.166457973597625\n                              ...\n                              ...\n    S_postcentral            ,1.3277159068067768,-1.4042773812503526\n    S_precentral-inf-part    ,-1.9467169777576718,1.7216636236995733\n    S_precentral-sup-part    ,0.764673539853991,2.1081570332369504\n    S_suborbital             ,0.522368665639954,-2.3593237820349007\n    S_subparietal            ,-0.14697262729901928,-2.2116605141889094\n    S_temporal_inf           ,-1.8442944920810271,-0.6895142771486307\n    S_temporal_sup           ,-1.8645248463693804,2.740099589311164\n    S_temporal_transverse    ,-2.4244451521560073,2.286596403222344\n\nand creates a FreeSurfer labelmap where ``<str_structureName>`` colors correspond to the z-score (normalized between 0 and 255).\n\nCurrently, only the ``aparc.a2009s`` FreeSurfer segmentation is fully supported, however future parcellation support is planned.\n\nNegative 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 \n    \n.. code::\n\n    --posColor R --negColor RG\n\nwill assign positive z-scores shades of ``red`` and negative z-scores shades of ``yellow`` (Red + Green = Yellow).\n\n                               \n\nSynopsis\n--------\n\n.. code::\n\n    python z2labelmap.py                                            \\\n        [-v <level>] [--verbosity <level>]                          \\\n        [--random] [--seed <seed>]                                  \\\n        [-p <f_posRange>] [--posRange <f_posRange>]                 \\\n        [-n <f_negRange>] [--negRange <f_negRange>]                 \\\n        [-P <'RGB'>] [--posColor <'RGB'>]                           \\\n        [-N  <'RGB'>] [--negColor <'RGB'>]                          \\\n        [--imageSet <imageSetDirectory>]                            \\\n        [-s <f_scaleRange>] [--scaleRange <f_scaleRange>]           \\\n        [-l <f_lowerFilter>] [--lowerFilter <f_lowerFilter>]        \\\n        [-u <f_upperFilter>] [--upperFilter <f_upperFilter>]        \\\n        [-z <zFile>] [--zFile <zFile>]                              \\\n        [--version]                                                 \\\n        [--man]                                                     \\\n        [--meta]                                                    \\\n        <inputDir>                                                  \\\n        <outputDir> \n\nRun\n----\n\nThis ``plugin`` can be run in two modes: natively as a python package or as a containerized docker image.\n\nUsing PyPI\n~~~~~~~~~~\n\nTo run from PyPI, simply do a \n\n.. code:: bash\n\n    pip install z2labelmap\n\nand run with\n\n.. code:: bash\n\n    z2labelmap.py --man /tmp /tmp\n\nto get inline help.\n\n\nUsing ``docker run``\n~~~~~~~~~~~~~~~~~~~~\n\nTo 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!*\n\nNow, prefix all calls with \n\n.. code:: bash\n\n    docker run --rm -v $(pwd)/in:/incoming -v $(pwd)/out:/outgoing      \\\n            fnndsc/pl-z2labelmap z2labelmap.py                          \\\n\nThus, getting inline help is:\n\n.. code:: bash\n\n    docker run --rm -v $(pwd)/in:/incoming -v $(pwd)/out:/outgoing      \\\n            fnndsc/pl-z2labelmap z2labelmap.py                          \\\n            --man                                                       \\\n            /incoming /outgoing\n\nExamples\n--------\n\nCreate a sample/random z-score file and analyze\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n* In the absense of an actual z-score file, the script can create one. This can then be used in subsequent analysis:\n\n.. code::\n\n    mkdir in out\n    docker run --rm -v $(pwd)/in:/incoming -v $(pwd)/out:/outgoing  \\\n            fnndsc/pl-z2labelmap z2labelmap.py                      \\\n            --random --seed 1                                       \\\n            --posRange 3.0 --negRange -3.0                          \\\n            /incoming /outgoing\n\nor without docker\n\n.. code::\n\n    mkdir in out\n    z2labelmap.py                                                   \\\n            --random --seed 1                                       \\\n            --posRange 3.0 --negRange -3.0                          \\\n            /in /out\n\n\nIn this example, z-scores range between 0.0 and (+/-) 3.0.\n\nGenerate labelmap and also copy pre-calculated image set to output\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n* Analyze a file already located at ``in/zfile.csv`` and copy pre-calculated image data\n\n.. code::\n\n    docker run --rm -v $(pwd)/in:/incoming -v $(pwd)/out:/outgoing  \\\n            fnndsc/pl-z2labelmap z2labelmap.py                      \\\n            --negColor B --posColor R                               \\\n            --imageSet ../data/set1                                 \\\n            /incoming /outgoing\n\nThis 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). \n\n\nControl relative brightness and lower filter low z-scores from final labelmap\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n* To analyze a file already located at ``in/zfile.csv``, apply a ``scaleRange`` and also filter out the lower 80\\% of z-scores:\n\n.. code::\n\n    docker run --rm -v $(pwd)/in:/incoming -v $(pwd)/out:/outgoing  \\\n            fnndsc/pl-z2labelmap z2labelmap.py                      \\\n            --scaleRange 2.0 --lowerFilter 0.8                      \\\n            --negColor B --posColor R                               \\\n            /incoming /outgoing\n\nThis 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). \n\nUsing the above referenced z-score file, this results in:\n\n.. code::\n\n    0       Unknown                         0   0   0   0\n    11101\tlh-G_and_S_frontomargin     \t0\t0\t0\t0\n    11102\tlh-G_and_S_occipital_inf    \t0\t0\t0\t0\n    11103\tlh-G_and_S_paracentral      \t0\t0\t0\t0\n    11104\tlh-G_and_S_subcentral       \t103\t0\t0\t0\n    11105\tlh-G_and_S_transv_frontopol \t0\t0\t0\t0\n    11106\tlh-G_and_S_cingul-Ant       \t0\t0\t110\t0\n    11107\tlh-G_and_S_cingul-Mid-Ant   \t0\t0\t0\t0\n    11108\tlh-G_and_S_cingul-Mid-Post  \t0\t0\t111\t0\n                                ...\n                                ...\n    12167\trh-S_postcentral            \t0\t0\t0\t0\n    12168\trh-S_precentral-inf-part    \t0\t0\t0\t0\n    12169\trh-S_precentral-sup-part    \t0\t0\t0\t0\n    12170\trh-S_suborbital             \t0\t0\t110\t0\n    12171\trh-S_subparietal            \t0\t0\t103\t0\n    12172\trh-S_temporal_inf           \t0\t0\t0\t0\n    12173\trh-S_temporal_sup           \t119\t0\t0\t0\n    12174\trh-S_temporal_transverse    \t0\t0\t0\t0\n\nCommand line arguments\n----------------------\n\n.. code::\n\n        <inputDir>\n        Required argument.\n        Input directory for plugin.\n\n        <outputDir>\n        Required argument.\n        Output directory for plugin.\n\n        [-v <level>] [--verbosity <level>]\n        Verbosity level for app. Not used currently.\n\n        [--random] [--seed <seed>]\n        If specified, generate a z-score file based on <posRange> and <negRange>.  In addition, if a further optional <seed> is passed, then initialize the random generator with that seed, otherwise system time is used.\n\n        [-p <f_posRange>] [--posRange <f_posRange>]\n        Positive range for random max deviation generation.\n\n        [-n <f_negRange>] [--negRange <f_negRange>]\n        Negative range for random max deviation generation.\n\n        [-P <'RGB'>] [--posColor <'RGB'>]\n        Some combination of 'R', 'G', B' for positive heat.\n\n        [-N  <'RGB'> [--negColor <'RGB'>]\n        Some combination of 'R', 'G', B' for negative heat.\n\n        [--imageSet <imageSetDirectory>]\n        If specified, will copy the (container) prepopulated image set in <imageSetDirectory> to the output directory.\n\n        [-s <f_scaleRange>] [--scaleRange <f_scaleRange>]\n        Scale range for normalization. This has the effect of controlling the\n        brightness of the map. For example, if this 1.5 the effect\n        is increase the apparent range by 50% which darkens all colors values.\n\n        [-l <f_lowerFilter>] [--lowerFilter <f_lowerFilter>]\n        Filter all z-scores below (normalized) <lowerFilter> to 0.0.\n\n        [-u <f_upperFilter>] [--upperFilter <f_upperFilter>]\n        Filter all z-scores above (normalized) <upperFilter> to 0.0.\n\n        [-z <zFile>] [--zFile <zFile>]\n        z-score file to read (relative to input directory). Defaults to 'zfile.csv'.\n\n        [--version]\n        If specified, print version number. \n        \n        [--man]\n        If specified, print (this) man page.\n\n        [--meta]\n        If specified, print plugin meta data.",
        "description_content_type": "",
        "docs_url": null,
        "download_url": "",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "https://github.com/FNNDSC/pl-z2labelmap",
        "keywords": "",
        "license": "MIT",
        "maintainer": "",
        "maintainer_email": "",
        "name": "z2labelmap",
        "package_url": "https://pypi.org/project/z2labelmap/",
        "platform": "",
        "project_url": "https://pypi.org/project/z2labelmap/",
        "project_urls": {
            "Homepage": "https://github.com/FNNDSC/pl-z2labelmap"
        },
        "release_url": "https://pypi.org/project/z2labelmap/2.0.1/",
        "requires_dist": null,
        "requires_python": "",
        "summary": "Convert lh/rh z-score vector to FreeSurfer labelmap",
        "version": "2.0.1"
    },
    "last_serial": 5040884,
    "releases": {
        "1.0": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "3cd4250d0ac488b017b25e1f6772fb3f",
                    "sha256": "8a3111ecb755c53bee15f81cd0ea30c353e7951e198686a1fe45d853ccdc7aeb"
                },
                "downloads": -1,
                "filename": "z2labelmap-1.0.tar.gz",
                "has_sig": false,
                "md5_digest": "3cd4250d0ac488b017b25e1f6772fb3f",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 8612,
                "upload_time": "2019-03-24T20:14:48",
                "url": "https://files.pythonhosted.org/packages/f8/4e/fe72b5f56a53c85f629795a84b3ac27ca89a71e9c2d8fbf4ba9ac2a646bb/z2labelmap-1.0.tar.gz"
            }
        ],
        "1.1.0": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "cd3bf9830005df0627cc31d48e6ef95c",
                    "sha256": "dec75420acb0859dc1365436dd1d280a68ebe7dc0db836df8a25316a4da02ba1"
                },
                "downloads": -1,
                "filename": "z2labelmap-1.1.0.tar.gz",
                "has_sig": false,
                "md5_digest": "cd3bf9830005df0627cc31d48e6ef95c",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 9251,
                "upload_time": "2019-03-24T20:25:40",
                "url": "https://files.pythonhosted.org/packages/52/f2/26a4c129e6e533f10d949d4235d52b52d5a0a6892a51ab41b32eb0fcb4a5/z2labelmap-1.1.0.tar.gz"
            }
        ],
        "1.1.1": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "cd927afeb35163ace79078d1d2560161",
                    "sha256": "dc760e1c771d7839ff90945d836965606a55738d26ee32de88aa259c5d57ed4d"
                },
                "downloads": -1,
                "filename": "z2labelmap-1.1.1.tar.gz",
                "has_sig": false,
                "md5_digest": "cd927afeb35163ace79078d1d2560161",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 9307,
                "upload_time": "2019-03-24T20:29:26",
                "url": "https://files.pythonhosted.org/packages/69/d7/83d5c9de2ee456da1e8581ab4fd8d0a589c139e3ca5eba0e9416626f2e88/z2labelmap-1.1.1.tar.gz"
            }
        ],
        "1.1.3": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "95b0cd14652c688585c29539d9daa71b",
                    "sha256": "4e80788c8cd21745107ecd91d567c001496a857db6aa1c8b99584083cfe9f2b4"
                },
                "downloads": -1,
                "filename": "z2labelmap-1.1.3.tar.gz",
                "has_sig": false,
                "md5_digest": "95b0cd14652c688585c29539d9daa71b",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 9600,
                "upload_time": "2019-03-24T20:45:01",
                "url": "https://files.pythonhosted.org/packages/b5/ef/d4757313c496d57a2bf884e0d43101888f47b1f026ab6d9ff33d50088f1a/z2labelmap-1.1.3.tar.gz"
            }
        ],
        "1.1.5": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "a0f5c90651819e02709415c3077a8e02",
                    "sha256": "2155fc8157b5a978cfa3d33db4c6fefa15b6e277b4d607cba76454f7d22efec3"
                },
                "downloads": -1,
                "filename": "z2labelmap-1.1.5.tar.gz",
                "has_sig": false,
                "md5_digest": "a0f5c90651819e02709415c3077a8e02",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 9663,
                "upload_time": "2019-03-24T20:48:39",
                "url": "https://files.pythonhosted.org/packages/24/a4/d503c1056d469f0e0c02c46b425bb90c993d89fba22a935d9e1360c6e597/z2labelmap-1.1.5.tar.gz"
            }
        ],
        "1.1.6": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "c8e2af87867463f68dd7397890f3a0f8",
                    "sha256": "7ea737e05aa2ac90955290b49f6558462d0e0511bca1613d785f49aa6c02c985"
                },
                "downloads": -1,
                "filename": "z2labelmap-1.1.6.tar.gz",
                "has_sig": false,
                "md5_digest": "c8e2af87867463f68dd7397890f3a0f8",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 9675,
                "upload_time": "2019-03-24T20:50:56",
                "url": "https://files.pythonhosted.org/packages/b7/be/84fe0dc144376df8dc9fb4d21ef19bd7a7ad2a42cfb6881a039d8099723c/z2labelmap-1.1.6.tar.gz"
            }
        ],
        "1.1.7": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "cd4e27e499f0d11ef1c1ea73f1fde667",
                    "sha256": "2dc1da1abd2f092d7a1939be4ed5b366f96101f9989c64ceef6e438e8574eb00"
                },
                "downloads": -1,
                "filename": "z2labelmap-1.1.7.tar.gz",
                "has_sig": false,
                "md5_digest": "cd4e27e499f0d11ef1c1ea73f1fde667",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 10722,
                "upload_time": "2019-03-24T20:56:36",
                "url": "https://files.pythonhosted.org/packages/cd/6b/8fc977a8ed4c728aeaa80b3899e915b420731f12a2e72971512bdf0df10b/z2labelmap-1.1.7.tar.gz"
            }
        ],
        "1.1.8": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "a4b15c265e1ed49d8a86f70d45db6ea9",
                    "sha256": "7784249b97393ffdbff7d39e738da13f234da058d9c2ab8d58e4e8976169f4c8"
                },
                "downloads": -1,
                "filename": "z2labelmap-1.1.8.tar.gz",
                "has_sig": false,
                "md5_digest": "a4b15c265e1ed49d8a86f70d45db6ea9",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 10298,
                "upload_time": "2019-03-25T15:58:09",
                "url": "https://files.pythonhosted.org/packages/c0/78/41d1ecc748a75808a869ae85dae64917b03cb96a19a84bd10aeb51095e18/z2labelmap-1.1.8.tar.gz"
            }
        ],
        "1.1.9": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "59605fc68a1ec4a1e2f62a58a8d59182",
                    "sha256": "5c1d0d2cc71aa614cc0f7095d491ce987161ef4128c92d1467c0c4069d501330"
                },
                "downloads": -1,
                "filename": "z2labelmap-1.1.9.tar.gz",
                "has_sig": false,
                "md5_digest": "59605fc68a1ec4a1e2f62a58a8d59182",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 10294,
                "upload_time": "2019-03-25T16:07:42",
                "url": "https://files.pythonhosted.org/packages/83/f4/449807aee6e48a0709145ea26de782fc14a564738d845c28b5230cfa90c8/z2labelmap-1.1.9.tar.gz"
            }
        ],
        "2.0.1": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "58c0fbc10e6d515db8f498dcee4f6154",
                    "sha256": "fe9604f0186f98db9eadd1b89c20b885f150be9373452d281eafb7cd9af8f3e1"
                },
                "downloads": -1,
                "filename": "z2labelmap-2.0.1.tar.gz",
                "has_sig": false,
                "md5_digest": "58c0fbc10e6d515db8f498dcee4f6154",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 11044,
                "upload_time": "2019-04-01T20:21:24",
                "url": "https://files.pythonhosted.org/packages/9e/b9/77d767e7f32803f00b24e28a88caae312f29ca4d58a3442b22456f3e3367/z2labelmap-2.0.1.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "58c0fbc10e6d515db8f498dcee4f6154",
                "sha256": "fe9604f0186f98db9eadd1b89c20b885f150be9373452d281eafb7cd9af8f3e1"
            },
            "downloads": -1,
            "filename": "z2labelmap-2.0.1.tar.gz",
            "has_sig": false,
            "md5_digest": "58c0fbc10e6d515db8f498dcee4f6154",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 11044,
            "upload_time": "2019-04-01T20:21:24",
            "url": "https://files.pythonhosted.org/packages/9e/b9/77d767e7f32803f00b24e28a88caae312f29ca4d58a3442b22456f3e3367/z2labelmap-2.0.1.tar.gz"
        }
    ]
}