Metadata-Version: 1.0
Name: freesurfer_pp
Version: 2.0.1
Summary: A simple/dummy app that simulates a FreeSurfer run
Home-page: https://github.com/FNNDSC/pl-freesurfer_pp
Author: Rudolph Pienaar
Author-email: rudolph.pienaar@gmail.com
License: MIT
Description: pl-freesurfer_pp
        ================
        
        .. image:: https://badge.fury.io/py/freesurfer_pp.svg
            :target: https://badge.fury.io/py/freesurfer_pp
        
        .. image:: https://travis-ci.org/FNNDSC/freesurfer_pp.svg?branch=master
            :target: https://travis-ci.org/FNNDSC/freesurfer_pp
        
        .. image:: https://img.shields.io/badge/python-3.5%2B-blue.svg
            :target: https://badge.fury.io/py/pl-freesurfer_pp
        
        .. contents:: Table of Contents
        
        
        Abstract
        --------
        
        ``freesurfer_pp.py`` is a *dummy* FreeSurfer plugin / container that is prepopulated with the results of several *a priori* FreeSurfer runs. For a given run, this script will simply copy elements of one of these prior runs to the output directory. 
        
        Synopsis
        --------
        
        .. code::
        
                python freesurfer_pp.py                                         \
                    [-v <level>] [--verbosity <level>]                          \
                    [--version]                                                 \
                    [--man]                                                     \
                    [--meta]                                                    \
                    [--copySpec <copySpec>]                                     \
                    [--ageSpec <ageSpec>]                                       \
                    <inputDir>                                                  \
                    <outputDir> 
        
        Run
        ----
        
        This ``plugin`` can be run in two modes: natively as a python package or as a containerized docker image. The PyPI mode is largely included for completeness sake and only useful if run against some pre-processed tree that exists in the filesystem. 
        
        Using PyPI
        ~~~~~~~~~~
        
        *You probably do not want to run the PyPI version unless you are a developer! Mostly likely you want the docker containerized run -- see the next section.*
        
        To run from PyPI, simply do a 
        
        .. code:: bash
        
            pip install freesurfer_pp
        
        and run with
        
        .. code:: bash
        
            freesurfer.py --man /tmp /tmp
        
        
        Using ``docker run``
        ~~~~~~~~~~~~~~~~~~~~
        
        The real utility of this package is to run it containerized against bundled data that is packed into the container.
        
        Assign an "input" directory to ``/incoming`` and an "output" directory to ``/outgoing``. Note that the "input" directory is effectively ignored by this plugin, but is required. Make sure that the host ``$(pwd)/out`` directory is world writable!
        
        In the simplest sense, the plugin can be run with
        
        .. code:: bash
        
            mkdir in out && chmod 777 out
            docker run --rm -v $(pwd)/in:/incoming -v $(pwd)/out:/outgoing      \
                    fnndsc/pl-freesurfer_pp freesurfer_pp.py                    \
                    /incoming /outgoing
        
        which will copy **only** the internal `stats` directory from a ``10-yr/06-mo/01-da`` subject to the output. By specifying a ``--copySpec stats,3D,sag,cor,tra`` several additional directories containing png image frames through parcellated sagittal, coronal, and transverse (axial) planes as well as multiple 3D images are also copied.
        
        Examples
        --------
        
        Check available pre-processed runs
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        To get a listing of the internal tree of already processed and available FreeSurfer choices:
        
        .. code:: bash
        
            docker run --rm -v $(pwd)/in:/incoming -v $(pwd)/out:/outgoing      \
                    fnndsc/pl-freesurfer_pp freesurfer_pp.py                    \
                    -T ../preprocessed                                          \
                    /incoming /outgoing
        
        This will print a tree of the available choices of `preprocessed` data in a directory tree. 
        
        Copy the default for a selected pre-processed run
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        Select one run, say the `08-yr/07-mo/16-da` and specify that to copy:
        
        .. code:: bash
        
            docker run --rm -v $(pwd)/in:/incoming -v $(pwd)/out:/outgoing      \
                    fnndsc/pl-freesurfer_pp freesurfer_pp.py                    \
                    -a 08-07-16 \
                    /incoming /outgoing
        
        Simulate a processing delay
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        To simulate a processing delay, specify some time in seconds:
        
        .. code:: bash
        
            docker run --rm -v $(pwd)/in:/incoming -v $(pwd)/out:/outgoing      \
                    fnndsc/pl-freesurfer_pp freesurfer_pp.py                    \
                    -a 08-07-16                                                 \
                    -P 20                                                       \
                    /incoming /outgoing
        
        Explicitly copy all the data including images from a pre-processed run
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        To copy all the image directories from the ``10-yr/06-mo/01-da`` subject, 
        
        .. code:: bash
        
            docker run --rm -v $(pwd)/in:/incoming -v $(pwd)/out:/outgoing      \
                    fnndsc/pl-freesurfer_pp freesurfer_pp.py                    \
                    -a 10-06-01                                                 \
                    -c stats,sag,cor,tra,3D                                     \
                    /incoming /outgoing            
        
        
        
Platform: UNKNOWN
