Import Parameters File Specification

Yimeng Zhang

Mar. 1, 2016

This document describes how to write the import parameters file for +cdttable.import_files().

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

{
  "comment":"",
  "subtrials":[
    {
      "end_code":75,
      "start_code":-15
    },
    {
      "start_code":25,
      "end_time":1.444632574557966
    }
  ],
  "trial_to_condition_func":"(codes, idx) codes(1)+idx",
  "margin_after":0,
  "margin_before":0
}

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:

1. start code + end code.

   {
     "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).

2. start code + end time.

   {
     "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 demos.import_NEV_demo() and User Guide for CDT table format.

For a more concrete example, see What’s done by 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 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 trial end.

Optional Fields

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

trial_start_code/end_code

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

trial_start_code/end_time

{
    ... // 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

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.

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 trial start and not persist later than trial end. Otherwise, the program would complain.