Merge pull request #1881 from teonlamont/read_raw_fif

dengemann · dengemann · commit 4ae85b5714b5 · 2015-03-21T14:33:52.000+01:00
Add reader function for Raw FIF files
diff --git a/doc/source/python_reference.rst b/doc/source/python_reference.rst
@@ -110,6 +110,7 @@ Functions:
   read_raw_kit
   read_raw_brainvision
   read_raw_egi
+  read_raw_fif
 
 .. currentmodule:: mne.io.kit
 
diff --git a/doc/source/whats_new.rst b/doc/source/whats_new.rst
@@ -81,6 +81,8 @@ Changelog
 
    - Add support for adding an empty reference channel to data by `Teon Brooks`_
 
+   - Add reader function for Raw FIF files by `Teon Brooks`_
+
 BUG
 ~~~
 
diff --git a/mne/io/__init__.py b/mne/io/__init__.py
@@ -26,6 +26,7 @@
 from .edf import read_raw_edf
 from .egi import read_raw_egi
 from .kit import read_raw_kit
+from .fiff import read_raw_fif
 
 # for backward compatibility
 from .fiff import RawFIFF
diff --git a/mne/io/brainvision/brainvision.py b/mne/io/brainvision/brainvision.py
@@ -620,6 +620,11 @@ def read_raw_brainvision(vhdr_fname, montage=None,
     verbose : bool, str, int, or None
         If not None, override default verbose level (see mne.verbose).
 
+    Returns
+    -------
+    raw : Instance of RawBrainVision
+        A Raw object containing BrainVision data.
+
     See Also
     --------
     mne.io.Raw : Documentation of attribute and methods.
diff --git a/mne/io/bti/bti.py b/mne/io/bti/bti.py
@@ -1208,14 +1208,23 @@ def read_raw_bti(pdf_fname, config_fname='config',
     translation : array-like
         The translation to place the origin of coordinate system
         to the center of the head.
-    ecg_ch: str | None
+    ecg_ch : str | None
       The 4D name of the ECG channel. If None, the channel will be treated
       as regular EEG channel.
-    eog_ch: tuple of str | None
+    eog_ch : tuple of str | None
       The 4D names of the EOG channels. If None, the channels will be treated
       as regular EEG channels.
     verbose : bool, str, int, or None
         If not None, override default verbose level (see mne.verbose).
+
+    Returns
+    -------
+    raw : Instance of RawBTi
+        A Raw object containing BTI data.
+
+    See Also
+    --------
+    mne.io.Raw : Documentation of attribute and methods.
     """
     return RawBTi(pdf_fname, config_fname=config_fname,
                   head_shape_fname=head_shape_fname,
diff --git a/mne/io/edf/edf.py b/mne/io/edf/edf.py
@@ -657,6 +657,11 @@ def read_raw_edf(input_fname, montage=None, eog=None, misc=None,
     verbose : bool, str, int, or None
         If not None, override default verbose level (see mne.verbose).
 
+    Returns
+    -------
+    raw : Instance of RawEDF
+        A Raw object containing EDF data.
+
     See Also
     --------
     mne.io.Raw : Documentation of attribute and methods.
diff --git a/mne/io/egi/egi.py b/mne/io/egi/egi.py
@@ -167,8 +167,12 @@ def read_raw_egi(input_fname, montage=None, eog=None, misc=None,
 
     Returns
     -------
-    raw : instance of mne.io.Raw
-        A raw object containing EGI data.
+    raw : Instance of RawEGI
+        A Raw object containing EGI data.
+
+    See Also
+    --------
+    mne.io.Raw : Documentation of attribute and methods.
     """
     return _RawEGI(input_fname, montage, eog, misc, include, exclude, verbose)
 
diff --git a/mne/io/fiff/__init__.py b/mne/io/fiff/__init__.py
@@ -1 +1,2 @@
 from .raw import RawFIFF
+from .raw import read_raw_fif
diff --git a/mne/io/fiff/raw.py b/mne/io/fiff/raw.py
@@ -2,6 +2,7 @@
 #          Matti Hamalainen <msh@nmr.mgh.harvard.edu>
 #          Martin Luessi <mluessi@nmr.mgh.harvard.edu>
 #          Denis Engemann <denis.engemann@gmail.com>
+#          Teon Brooks <teon.brooks@gmail.com>
 #
 # License: BSD (3-clause)
 
@@ -621,3 +622,53 @@ def _check_raw_compatibility(raw):
                       'could result in precision mismatch. Setting '
                       'raw.orig_format="unknown"')
         raw[0].orig_format = 'unknown'
+
+
+def read_raw_fif(fnames, allow_maxshield=False, preload=False,
+                 proj=False, compensation=None, add_eeg_ref=True,
+                 verbose=None):
+    """Reader function for Raw FIF data
+
+    Parameters
+    ----------
+    fnames : list, or string
+        A list of the raw files to treat as a Raw instance, or a single
+        raw file. For files that have automatically been split, only the
+        name of the first file has to be specified. Filenames should end
+        with raw.fif, raw.fif.gz, raw_sss.fif, raw_sss.fif.gz,
+        raw_tsss.fif or raw_tsss.fif.gz.
+    allow_maxshield : bool, (default False)
+        allow_maxshield if True, allow loading of data that has been
+        processed with Maxshield. Maxshield-processed data should generally
+        not be loaded directly, but should be processed using SSS first.
+    preload : bool or str (default False)
+        Preload data into memory for data manipulation and faster indexing.
+        If True, the data will be preloaded into memory (fast, requires
+        large amount of memory). If preload is a string, preload is the
+        file name of a memory-mapped file which is used to store the data
+        on the hard drive (slower, requires less memory).
+    proj : bool
+        Apply the signal space projection (SSP) operators present in
+        the file to the data. Note: Once the projectors have been
+        applied, they can no longer be removed. It is usually not
+        recommended to apply the projectors at this point as they are
+        applied automatically later on (e.g. when computing inverse
+        solutions).
+    compensation : None | int
+        If None the compensation in the data is not modified.
+        If set to n, e.g. 3, apply gradient compensation of grade n as
+        for CTF systems.
+    add_eeg_ref : bool
+        If True, add average EEG reference projector (if it's not already
+        present).
+    verbose : bool, str, int, or None
+        If not None, override default verbose level (see mne.verbose).
+
+    Returns
+    -------
+    raw : Instance of RawFIFF
+        A Raw object containing FIF data.
+    """
+    return RawFIFF(fnames=fnames, allow_maxshield=allow_maxshield,
+                   preload=preload, proj=proj, compensation=compensation,
+                   add_eeg_ref=add_eeg_ref, verbose=verbose)
diff --git a/mne/io/fiff/tests/test_raw.py b/mne/io/fiff/tests/test_raw.py
@@ -20,7 +20,8 @@
 
 from mne.datasets import testing
 from mne.io.constants import FIFF
-from mne.io import Raw, concatenate_raws, get_chpi_positions
+from mne.io import (Raw, concatenate_raws, get_chpi_positions,
+                    read_raw_fif)
 from mne import (concatenate_events, find_events, equalize_channels,
                  compute_proj_raw, pick_types, pick_channels)
 from mne.utils import (_TempDir, requires_nitime, requires_pandas,
@@ -51,7 +52,7 @@
 def test_hash_raw():
     """Test hashing raw objects
     """
-    raw = Raw(fif_fname)
+    raw = read_raw_fif(fif_fname)
     assert_raises(RuntimeError, raw.__hash__)
     raw = Raw(fif_fname, preload=True).crop(0, 0.5)
     raw_2 = Raw(fif_fname, preload=True).crop(0, 0.5)
diff --git a/mne/io/kit/kit.py b/mne/io/kit/kit.py
@@ -653,6 +653,15 @@ def read_raw_kit(input_fname, mrk=None, elp=None, hsp=None, stim='>',
         If False, data are not read until save.
     verbose : bool, str, int, or None
         If not None, override default verbose level (see mne.verbose).
+
+    Returns
+    -------
+    raw : Instance of RawKIT
+        A Raw object containing KIT data.
+
+    See Also
+    --------
+    mne.io.Raw : Documentation of attribute and methods.
     """
     return RawKIT(input_fname=input_fname, mrk=mrk, elp=elp, hsp=hsp,
                   stim=stim, slope=slope, stimthresh=stimthresh,

Original file line number	Diff line number	Diff line change
`@@ -1 +1,2 @@`
`1`	`1`	`from .raw import RawFIFF`
	`2`	`+from .raw import read_raw_fif`