************************************
Import Parameters File Specification
************************************

| Yimeng Zhang
| Mar. 1, 2016

This document describes how to write the import parameters file for :mat:func:`+cdttable.import_files`.

The import parameters are specified by a JSON file with a specific format. One example is given below.

    .. literalinclude:: ../tests/import_params_example.json
        :language: json

Required Fields
===============

This JSON document has a format similar to that of a Python dictionary, and has the following required fields (``comment`` is ignored by the program):

.. todo:: @summer change user guide to follow the demo file.

``subtrials``
    this is the most important field. It specifies pairs of the (start/end) markers to look for in each trial and will save their times relative to trial start minus ``margin_before`` (see below). It is an array (enclosed with ``[]``), and must have at least 1 element of either of the two forms below:

    #. start code + end code.

        .. code-block:: json

            {
              "start_code":X,
              "end_code":Y
            }

        X and Y are integers that can be found in the event codes for each trial, and Y should appear not earlier than X (so they can be the same if you don't want a subtrial interval but just a time marker).

    #. start code + end time.

        .. code-block:: json

            {
              "start_code":X,
              "end_time":Z
            }

        X and should be found in the event codes for each trial, and Z is a nonnegative number specifying the location of end marker as Z second after the appearance of X.

    the orders of start_code and end_code/time pairs determine the order they will appear in starttime/stoptime of the final CDT table. See the mat file generated by :mat:func:`demos.import_NEV_demo` and :doc:`CDT_use/user_guide`.

    For a more concrete example, see :ref:`what-is-in-the-demo`.


``trial_to_condition_func``
    this specfies how to extract the condition number for the trial, given all the event codes in the trial and the trial index (1-based). It should start with ``(X,Y)``, where ``X`` and ``Y`` denotes event codes and trial index respectively. For example, if the condition number is the fifth event code minus 100, then we should have ``trial_to_condition_func: "(X,Y) X(5)-100"``.


``margin_before``
    this specifies the extra margin to extract before :ref:`def-trial-start`, which is defined by the time of the first start code in ``subtrials``. this is useful when one needs to see the spiking data before the stimulus onset (if stimulus onset is used as start code in ``subtrials``) as well. The unit is in second. For example, if this value is set to 0.5, then all the event codes and spikes within 0.5 second before stimulus onset will be saved in the final CDT table.

``margin_after``
    similar to ``margin_before``, but specifies the extra margin to extract after :ref:`def-trial-end`.


Optional Fields
===============

You can supply exactly one of two forms of optional fields, at the same level of required fields, to redefine :ref:`def-trial-start` and :ref:`def-trial-end`.

trial_start_code/end_code


    .. code-block:: json

        {
            ... // other fields
            "trial_start_code":X,
            "trial_end_code":Y,
            ... // other fields
        }

trial_start_code/end_time


    .. code-block:: json

        {
            ... // other fields
            "trial_start_code":X,
            "trial_end_time":Z,
            ... // other fields
        }

X, Y, Z are defined in the same way as those in ``subtrials``.


Definitions
===========


.. _def-trial-start:

trial start
-----------

the time of the first start code in ``subtrials`` if no optional field is supplied. Otherwise, it would be defined by the trial_start_code and trial_end_code/time pair.


.. _def-trial-end:

trial end
---------

the time of the last end code/time in ``subtrials`` if no optional field is supplied. Otherwise, it would be defined by the trial_start_code and trial_end_code/time pair.


Constraints
===========
In any case, the start time of each subtrial must not greater than its end time, and each subtrial must not appear earlier than :ref:`def-trial-start` and not persist later than :ref:`def-trial-end`. Otherwise, the program would complain.