neuro_deconvolve.py


===========================================================================
neuro_deconvolve.py:

Generate a script that would apply 3dTfitter to deconvolve an MRI signal
(BOLD response curve) into a neuro response curve.

Required parameters include an input dataset, a script name and an output
prefix.

----------------------------------------------------------------------
examples:

    1. deconvolve 3 seed time series

        The errts time series might be applied to the model, while the
        all_runs and fitts and for evaluation, along with the re-convolved
        time series generated by the script.

        Temporal partitioning is on the todo list.

           neuro_deconvolve.py                                      \
              -infiles seed.all_runs.1D seed.errts.1D seed.fitts.1D \
              -tr 2.0 -tr_nup 20 -kernel BLOCK                      \
              -script script.neuro.txt

old examples:

    old 1. 3d+time example

           neuro_deconvolve.py         \
              -input run1+orig         \
              -script script.neuro     \
              -mask_dset automask+orig \
              -prefix neuro_resp

    old 2. 1D example

           neuro_deconvolve.py        \
              -input epi_data.1D      \
              -tr 2.0                 \
              -script script.1d       \
              -prefix neuro.1D


----------------------------------------------------------------------
informational arguments:

    -help                       : display this help
    -hist                       : display the modification history
    -show_valid_opts            : display all valid options (short format)
    -ver                        : display the version number

----------------------------------------
required arguments:

    -input INPUT_DATASET        : set the data to deconvolve

        e.g. -input epi_data.1D

    -prefix PREFIX              : set the prefix for output filenames

        e.g. -prefix neuro_resp

                --> might create: neuro_resp+orig.HEAD/.BRIK

    -script SCRIPT              : specify the name of the output script

        e.g. -script neuro.script

----------------------------------------
optional arguments:


    -kernel KERNEL              : set the response kernel

        default: -kernel GAM

    -kernel_file FILENAME       : set the filename to store the kernel in

        default: -kernel_file resp_kernel.1D

      * This data should be at the upsampled TR.

        See -tr_nup.

    -mask_dset DSET             : set a mask dataset for 3dTfitter to use

        e.g. -mask_dset automask+orig

    -old                        : make old-style script

        Make pre-2015.02.24 script for 1D case.

    -tr TR                      : set the scanner TR

        e.g. -tr 2.0

        The TR is needed for 1D formatted input files.  It is not needed
        for AFNI 3d+time datasets, since the TR is in the file.

    -tr_nup NUP                 : upsample factor for TR

        e.g. -tr_nup 25

        Deconvolution is generally done on an upsampled TR, which allows
        for sub-TR events and more accurate deconvolution.  NUP should be
        the number of pieces each original TR is divided into.  For example,
        to upsample a TR of 2.0 to one of 0.1, use NUP = 20.

        TR must be an integral multiple of TR_UP.

    -verb LEVEL                 : set the verbose level

        e.g. -verb 2


- R Reynolds  June 12, 2008
===========================================================================