Merge pull request #257 from kchawla-pi/events-not-paradigms-3

[MRG] Replace 'paradigm' with 'events', 'experimental paradigm' for BIDS compliance

doc/modules/reference.rst

@@ -99,8 +99,7 @@ uses.
    :toctree: generated/
    :template: function.rst
 
-   check_paradigm
-   paradigm_from_csv
+   check_events
 
 .. _model_ref:
 

examples/01_tutorials/plot_first_level_model_details.py

@@ -33,13 +33,13 @@
 fmri_img = data.epi_img
 
 ###############################################################################
-# Define the paradigm that will be used
+# Define the experimental events that will be used
 #
 # We just get the provided file and make it BIDS-compliant. 
 t_r = 2.4
-paradigm_file = data.paradigm
+events_file = data['events']
 import pandas as pd
-events= pd.read_table(paradigm_file)
+events= pd.read_table(events_file)
 
 ###############################################################################
 # Add a column for 'duration' (filled with ones) for BIDS compliance
@@ -81,21 +81,31 @@ def make_localizer_contrasts(design_matrix):
                       for i, column in enumerate(design_matrix.columns)])
 
     # Add more complex contrasts
-    contrasts['audio'] = contrasts['clicDaudio'] + contrasts['clicGaudio'] +\
-                         contrasts['calculaudio'] + contrasts['phraseaudio']
-    contrasts['video'] = contrasts['clicDvideo'] + contrasts['clicGvideo'] + \
-                         contrasts['calculvideo'] + contrasts['phrasevideo']
+    contrasts['audio'] = (contrasts['clicDaudio']
+                          + contrasts['clicGaudio']
+                          + contrasts['calculaudio']
+                          + contrasts['phraseaudio']
+                          )
+    contrasts['video'] = (contrasts['clicDvideo']
+                          + contrasts['clicGvideo']
+                          + contrasts['calculvideo']
+                          + contrasts['phrasevideo']
+                          )
     contrasts['computation'] = contrasts['calculaudio'] + contrasts['calculvideo']
     contrasts['sentences'] = contrasts['phraseaudio'] + contrasts['phrasevideo']
 
     # Short dictionary of more relevant contrasts
     contrasts = {
-        'left-right': (contrasts['clicGaudio'] + contrasts['clicGvideo']
-                       - contrasts['clicDaudio'] - contrasts['clicDvideo']),
+        'left-right': (contrasts['clicGaudio']
+                       + contrasts['clicGvideo']
+                       - contrasts['clicDaudio']
+                       - contrasts['clicDvideo']
+                       ),
         'H-V': contrasts['damier_H'] - contrasts['damier_V'],
         'audio-video': contrasts['audio'] - contrasts['video'],
         'computation-sentences': (contrasts['computation'] -
-                                  contrasts['sentences']),
+                                  contrasts['sentences']
+                                  ),
     }
     return contrasts
 

examples/01_tutorials/plot_single_subject_single_run.py

@@ -71,7 +71,7 @@
 # provided in an events.tsv file. The path of this file is
 # provided in the dataset.
 import pandas as pd
-events = pd.read_table(subject_data['paradigm'])
+events = pd.read_table(subject_data['events'])
 print(events)
 
 ###############################################################################

examples/02_first_level_models/plot_localizer_surface_analysis.py

@@ -47,10 +47,9 @@
 
 #########################################################################
 # Second the experimental paradigm.
-paradigm_file = data.paradigm
+events_file = data['events']
 import pandas as pd
-paradigm = pd.read_table(paradigm_file)
-fmri_img = data.epi_img
+events = pd.read_table(events_file)
 
 #########################################################################
 # Project the fMRI image to the surface
@@ -87,8 +86,10 @@
 # We specify an hrf model containing Glover model and its time derivative
 # the drift model is implicitly a cosine basis with period cutoff 128s.
 from nistats.design_matrix import make_design_matrix
-design_matrix = make_design_matrix(
-    frame_times, paradigm=paradigm, hrf_model='glover + derivative')
+design_matrix = make_design_matrix(frame_times,
+                                   events=events,
+                                   hrf_model='glover + derivative'
+                                   )
 
 #########################################################################
 # Setup and fit GLM.
@@ -115,18 +116,22 @@
 
 #########################################################################
 # add some intermediate contrasts
-basic_contrasts["audio"] = basic_contrasts["clicDaudio"] +\
-                           basic_contrasts["clicGaudio"] +\
-                           basic_contrasts["calculaudio"] +\
-                           basic_contrasts["phraseaudio"]
-basic_contrasts["video"] = basic_contrasts["clicDvideo"] +\
-                           basic_contrasts["clicGvideo"] + \
-                           basic_contrasts["calculvideo"] +\
-                           basic_contrasts["phrasevideo"]
-basic_contrasts["computation"] = basic_contrasts["calculaudio"] +\
-                                 basic_contrasts["calculvideo"]
-basic_contrasts["sentences"] = basic_contrasts["phraseaudio"] +\
-                               basic_contrasts["phrasevideo"]
+basic_contrasts["audio"] = (basic_contrasts["clicDaudio"]
+                            + basic_contrasts["clicGaudio"]
+                            + basic_contrasts["calculaudio"]
+                            + basic_contrasts["phraseaudio"]
+                            )
+basic_contrasts["video"] = (basic_contrasts["clicDvideo"]
+                            + basic_contrasts["clicGvideo"]
+                            + basic_contrasts["calculvideo"]
+                            + basic_contrasts["phrasevideo"]
+                            )
+basic_contrasts["computation"] = (basic_contrasts["calculaudio"]
+                                  + basic_contrasts["calculvideo"]
+                                  )
+basic_contrasts["sentences"] = (basic_contrasts["phraseaudio"]
+                                + basic_contrasts["phrasevideo"]
+                                )
 
 #########################################################################
 # Finally make a dictionary of more relevant contrasts
@@ -138,13 +143,15 @@
 # Of course, we could define other contrasts, but we keep only 3 for simplicity.
 
 contrasts = {
-    "left - right button press": (basic_contrasts["clicGaudio"] +
-                                  basic_contrasts["clicGvideo"] -
-                                  basic_contrasts["clicDaudio"] -
-                                  basic_contrasts["clicDvideo"]),
+    "left - right button press": (basic_contrasts["clicGaudio"]
+                                  + basic_contrasts["clicGvideo"]
+                                  - basic_contrasts["clicDaudio"]
+                                  - basic_contrasts["clicDvideo"]
+                                  ),
     "audio - video": basic_contrasts["audio"] - basic_contrasts["video"],
     "computation - sentences": (basic_contrasts["computation"] -
-                                basic_contrasts["sentences"])
+                                basic_contrasts["sentences"]
+                                )
     }
 
 #########################################################################

examples/02_first_level_models/plot_spm_multimodal_faces.py

@@ -61,7 +61,7 @@
 #########################################################################
 # loop over the two sessions
 for idx, img in enumerate(fmri_img, start=1):
-    # Build paradigm
+    # Build experimental paradigm
     n_scans = img.shape[-1]
     events = pd.read_table(subject_data['events{}'.format(idx)])
     # Define the sampling times for the design matrix

examples/04_low_level_functions/plot_design_matrix.py

@@ -22,7 +22,7 @@
 import numpy as np
 tr = 1.0  # repetition time is 1 second
 n_scans = 128  # the acquisition comprises 128 scans 
-frame_times = np.arange(n_scans) * tr  # here are the corespoding frame times
+frame_times = np.arange(n_scans) * tr  # here are the correspoding frame times
 
 #########################################################################
 # then we define parameters related to the experimental design
@@ -42,37 +42,37 @@
 # Create design matrices
 # -------------------------------------
 # The same parameters allow us to obtain a variety of design matrices
-# We first create an event object
+# We first create an events object
 import pandas as pd
-paradigm = pd.DataFrame({'trial_type': conditions, 'onset': onsets,
+events = pd.DataFrame({'trial_type': conditions, 'onset': onsets,
                          'duration': duration})
 
 #########################################################################
-# We sample the paradigm into a design matrix, also including additional regressors
+# We sample the events into a design matrix, also including additional regressors
 hrf_model = 'glover'
 from nistats.design_matrix import make_design_matrix
 X1 = make_design_matrix(
-    frame_times, paradigm, drift_model='polynomial', drift_order=3,
+    frame_times, events, drift_model='polynomial', drift_order=3,
     add_regs=motion, add_reg_names=add_reg_names, hrf_model=hrf_model)
 
 #########################################################################
 # Now we compute a block design matrix. We add duration to create the blocks.
 # For this we first define an event structure that includes the duration parameter
 duration = 7. * np.ones(len(conditions))
-paradigm = pd.DataFrame({'trial_type': conditions, 'onset': onsets,
+events = pd.DataFrame({'trial_type': conditions, 'onset': onsets,
                          'duration': duration})
 
 #########################################################################
 # Then we sample the design matrix
-X2 = make_design_matrix(frame_times, paradigm, drift_model='polynomial',
+X2 = make_design_matrix(frame_times, events, drift_model='polynomial',
                         drift_order=3, hrf_model=hrf_model)
 
 #########################################################################
 # Finally we compute a FIR model
-paradigm = pd.DataFrame({'trial_type': conditions, 'onset': onsets,
+events = pd.DataFrame({'trial_type': conditions, 'onset': onsets,
                          'duration': duration})
 hrf_model = 'FIR'
-X3 = make_design_matrix(frame_times, paradigm, hrf_model='fir',
+X3 = make_design_matrix(frame_times, events, hrf_model='fir',
                         drift_model='polynomial', drift_order=3,
                         fir_delays=np.arange(1, 6))
 

examples/04_low_level_functions/write_paradigm_file.py → examples/04_low_level_functions/write_events_file.py

@@ -1,4 +1,4 @@
-"""Example of a paradigm .csv file generation: the neurospin/localizer paradigm.
+"""Example of a events.tsv file generation: the neurospin/localizer events.
 =============================================================================
 
 The protocol described is the so-called "archi standard" localizer
@@ -59,7 +59,7 @@
                        'duration': duration})
 
 #########################################################################
-# Export them to a csv file
-csvfile = 'localizer_paradigm.csv'
-events.to_csv(csvfile)
-print("Created the paradigm file in %s " % csvfile)
+# Export them to a tsv file
+tsvfile = 'localizer_events.tsv'
+events.to_csv(tsvfile, sep='\t', index=False)
+print("Created the events file in %s " % tsvfile)

nistats/datasets.py

@@ -283,7 +283,7 @@ def fetch_openneuro_dataset(
     return data_dir, sorted(downloaded)
 
 
-def _make_bids_compliant_localizer_first_level_paradigm_file(paradigm_file):
+def _make_events_file_localizer_first_level(events_file):
     """ Makes the first-level localizer fMRI dataset events file
     BIDS compliant. Overwrites the original file.
         Adds headers in first row.
@@ -292,20 +292,20 @@ def _make_bids_compliant_localizer_first_level_paradigm_file(paradigm_file):
     
     Parameters
     ----------
-    paradigm_file: string
+    events_file: string
         path to the localizer_first_level dataset's events file.
     
     Returns
     -------
     None
     """
-    paradigm = pd.read_csv(paradigm_file, sep=' ', header=None, index_col=None,
+    events = pd.read_csv(events_file, sep=' ', header=None, index_col=None,
                            names=['session', 'trial_type', 'onset'],
                            )
-    paradigm.drop(labels='session', axis=1, inplace=True)
+    events.drop(labels='session', axis=1, inplace=True)
     # duration is required in BIDS specification
-    paradigm['duration'] = np.ones_like(paradigm.onset)
-    paradigm.to_csv(paradigm_file, sep='\t', index=False)
+    events['duration'] = np.ones_like(events.onset)
+    events.to_csv(events_file, sep='\t', index=False)
 
 
 def fetch_localizer_first_level(data_dir=None, verbose=1):
@@ -319,15 +319,15 @@ def fetch_localizer_first_level(data_dir=None, verbose=1):
     Returns
     -------
     data: sklearn.datasets.base.Bunch
-        dictionary-like object, keys are:
+        dictionary-like object, with the keys:
         epi_img: the input 4D image
-        paradigm: a csv file describing the paardigm
+        events: a csv file describing the paardigm
     """
     url = 'ftp://ftp.cea.fr/pub/dsv/madic/download/nipy'
 
     dataset_name = "localizer_first_level"
     files = dict(epi_img="s12069_swaloc1_corr.nii.gz",
-                 paradigm="localizer_paradigm.csv")
+                 events="localizer_paradigm.csv")
     # The options needed for _fetch_files
     options = [(filename, os.path.join(url, filename), {})
                for _, filename in sorted(files.items())]
@@ -339,11 +339,11 @@ def fetch_localizer_first_level(data_dir=None, verbose=1):
 
     params = dict(zip(sorted(files.keys()), sub_files))
     try:
-        _verify_events_file_uses_tab_separators(params['paradigm'])
+        _verify_events_file_uses_tab_separators(params['events'])
     except ValueError:
-        _make_bids_compliant_localizer_first_level_paradigm_file(paradigm_file=
-                                                             params['paradigm']
-                                                                 )
+        _make_events_file_localizer_first_level(events_file=
+                                                             params['events']
+                                                )
 
     return Bunch(**params)
 
@@ -491,13 +491,13 @@ def fetch_spm_auditory(data_dir=None, data_name='spm_auditory',
         _download_spm_auditory_data(data_dir, subject_dir, subject_id)
     spm_auditory_data = _prepare_downloaded_spm_auditory_data(subject_dir)
     try:
-        spm_auditory_data['paradigm']
+        spm_auditory_data['events']
     except KeyError:
         events_filepath = _make_path_events_file_spm_auditory_data(
                                                             spm_auditory_data)
         if not os.path.isfile(events_filepath):
             _make_events_file_spm_auditory_data(events_filepath)
-        spm_auditory_data['paradigm'] = events_filepath
+        spm_auditory_data['events'] = events_filepath
     return spm_auditory_data
 
 
@@ -555,12 +555,12 @@ def _glob_spm_multimodal_fmri_data(subject_dir):
         if not _subject_data:
             return None
         try:
-            paradigm = _make_events_file_spm_multimodal_fmri(_subject_data, session)
+            events = _make_events_file_spm_multimodal_fmri(_subject_data, session)
         except MatReadError as mat_err:
             warnings.warn('{}. An events.tsv file cannot be generated'.format(str(mat_err)))
         else:
             events_filepath = _make_events_filepath_spm_multimodal_fmri(_subject_data, session)
-            paradigm.to_csv(events_filepath, sep='\t', index=False)
+            events.to_csv(events_filepath, sep='\t', index=False)
             _subject_data['events{}'.format(session)] = events_filepath
 
 
@@ -617,9 +617,9 @@ def _make_events_file_spm_multimodal_fmri(_subject_data, session):
     conditions = (['faces'] * len(faces_onsets) +
                   ['scrambled'] * len(scrambled_onsets))
     duration = np.ones_like(onsets)
-    paradigm = pd.DataFrame({'trial_type': conditions, 'onset': onsets,
+    events = pd.DataFrame({'trial_type': conditions, 'onset': onsets,
                              'duration': duration})
-    return paradigm
+    return events
 
 
 def fetch_spm_multimodal_fmri(data_dir=None, data_name="spm_multimodal_fmri",