freesurfer-pp 2.0.8
A simple/dummy app that simulates a FreeSurfer run
License: MIT

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