Repository: mne-tools/mne-python

Issue:
time_as_index
Now that `raw.annotations.orig_time` is in sync with `raw.info['meas_date']`, the `raw.time_as_index` might be confusing. See the following:

```py
	from mne.io import RawArray
	from mne import create_info, Annotations

    meas_date=1
    info = create_info(ch_names=10, sfreq=10.)
    raw = RawArray(data=np.empty((10, 10)), info=info, first_samp=10)
    raw.info['meas_date'] = meas_date

    annot = Annotations(onset=raw.times,
                        duration=np.zeros_like(raw.times),
                        description='dummy',
                        orig_time=None)

    raw.set_annotations(annotations=annot)

    print(raw.times)
    print(raw.annotations.onset)
    print(raw.time_as_index(raw.times))
    print(raw.time_as_index(raw.annotations.onset))
```

```sh
[0.  0.1 0.2 0.3 0.4 0.5 0.6 0.7 0.8 0.9]
[1.  1.1 1.2 1.3 1.4 1.5 1.6 1.7 1.8 1.9]
[0 1 2 3 4 5 6 7 8 9]
[10 11 12 13 14 15 16 17 18 19]
```
Shall we add a reference parameter to `time_as_index`?


Discussion:
maybe a parameter called `origin` that takes a string `{'meas_date', 'fist_samp'}` ??

Resolving patch:
diff --git a/mne/io/base.py b/mne/io/base.py
--- a/mne/io/base.py
+++ b/mne/io/base.py
@@ -650,6 +650,37 @@ def last_samp(self):
         """The last data sample."""
         return self.first_samp + sum(self._raw_lengths) - 1
 
+    def time_as_index(self, times, use_rounding=False, origin=None):
+        """Convert time to indices.
+
+        Parameters
+        ----------
+        times : list-like | float | int
+            List of numbers or a number representing points in time.
+        use_rounding : boolean
+            If True, use rounding (instead of truncation) when converting
+            times to indices. This can help avoid non-unique indices.
+        origin: time-like | float | int | None
+            Time reference for times. If None, ``times`` are assumed to be
+            relative to ``first_samp``.
+
+            .. versionadded:: 0.17.0
+
+        Returns
+        -------
+        index : ndarray
+            Indices corresponding to the times supplied.
+        """
+        first_samp_in_abs_time = (_handle_meas_date(self.info['meas_date']) +
+                                  self._first_time)
+        if origin is None:
+            origin = first_samp_in_abs_time
+
+        absolute_time = np.atleast_1d(times) + _handle_meas_date(origin)
+        times = (absolute_time - first_samp_in_abs_time)
+
+        return super(BaseRaw, self).time_as_index(times, use_rounding)
+
     @property
     def _raw_lengths(self):
         return [l - f + 1 for f, l in zip(self._first_samps, self._last_samps)]


Test patch:
diff --git a/mne/io/tests/test_raw.py b/mne/io/tests/test_raw.py
--- a/mne/io/tests/test_raw.py
+++ b/mne/io/tests/test_raw.py
@@ -139,7 +139,7 @@ def _test_concat(reader, *args):
 
 
 @testing.requires_testing_data
-def test_time_index():
+def test_time_as_index():
     """Test indexing of raw times."""
     raw_fname = op.join(op.dirname(__file__), '..', '..', 'io', 'tests',
                         'data', 'test_raw.fif')
@@ -151,7 +151,27 @@ def test_time_index():
 
     # Test new (rounding) indexing behavior
     new_inds = raw.time_as_index(raw.times, use_rounding=True)
-    assert(len(set(new_inds)) == len(new_inds))
+    assert_array_equal(new_inds, np.arange(len(raw.times)))
+
+
+@pytest.mark.parametrize('offset, origin',
+                         [(0, None), (0, 2.0), (1, 1.0), (2, 0.0)],
+                         ids=['times in s. relative to first_samp (default)',
+                              'times in s. relative to first_samp',
+                              'times in s. relative to meas_date',
+                              'absolute times in s. relative to 0'])
+def test_time_as_index_ref(offset, origin):
+    """Test indexing of raw times."""
+    meas_date = 1
+    info = create_info(ch_names=10, sfreq=10.)
+    raw = RawArray(data=np.empty((10, 10)), info=info, first_samp=10)
+    raw.info['meas_date'] = meas_date
+
+    relative_times = raw.times
+    inds = raw.time_as_index(relative_times + offset,
+                             use_rounding=True,
+                             origin=origin)
+    assert_array_equal(inds, np.arange(raw.n_times))
 
 
 def test_annotation_property_deprecation_warning():