0.2.3 -> 0.3.0 shims

jams/core.py

@@ -29,7 +29,7 @@
     JamsFrame
     Sandbox
     JObject
-
+    Observation
 """
 
 import json
@@ -45,6 +45,10 @@
 import gzip
 import copy
 import sys
+from collections import namedtuple
+
+from decorator import decorator
+
 
 from .version import version as __VERSION__
 from . import schema
@@ -54,7 +58,31 @@
 __all__ = ['load',
            'JObject', 'Sandbox', 'JamsFrame',
            'Annotation', 'Curator', 'AnnotationMetadata',
-           'FileMetadata', 'AnnotationArray', 'JAMS']
+           'FileMetadata', 'AnnotationArray', 'JAMS',
+           'Observation']
+
+
+def deprecated(version, version_removed):
+    '''This is a decorator which can be used to mark functions
+    as deprecated.
+
+    It will result in a warning being emitted when the function is used.'''
+
+    def __wrapper(func, *args, **kwargs):
+        '''Warn the user, and then proceed.'''
+        code = six.get_function_code(func)
+        warnings.warn_explicit(
+            "{:s}.{:s}\n\tDeprecated as of JAMS version {:s}."
+            "\n\tIt will be removed in JAMS version {:s}."
+            .format(func.__module__, func.__name__,
+                    version, version_removed),
+            category=DeprecationWarning,
+            filename=code.co_filename,
+            lineno=code.co_firstlineno + 1
+        )
+        return func(*args, **kwargs)
+
+    return decorator(__wrapper)
 
 
 @contextlib.contextmanager
@@ -489,6 +517,11 @@ def validate(self, strict=True):
         return valid
 
 
+Observation = namedtuple('Observation',
+                         ['time', 'duration', 'value', 'confidence'])
+'''Core observation type: (time, duration, value, confidence).'''
+
+
 class Sandbox(JObject):
     """Sandbox (unconstrained)
 
@@ -711,6 +744,7 @@ def add_observation(self, time=None, duration=None,
             self.drop(n, inplace=True, errors='ignore')
             six.reraise(SchemaError, SchemaError(str(exc)), sys.exc_info()[2])
 
+    @deprecated('0.2.3', '0.3.0')
     def to_interval_values(self):
         '''Extract observation data in a `mir_eval`-friendly format.
 
@@ -1168,6 +1202,34 @@ def slice(self, start_time, end_time, strict=False):
 
         return sliced_ann
 
+    def to_interval_values(self):
+        '''Extract observation data in a `mir_eval`-friendly format.
+
+        Returns
+        -------
+        intervals : np.ndarray [shape=(n, 2), dtype=float]
+            Start- and end-times of all valued intervals
+
+            `intervals[i, :] = [time[i], time[i] + duration[i]]`
+
+        labels : list
+            List view of value field.
+        '''
+
+        times = timedelta_to_float(self.data.time.values)
+        duration = timedelta_to_float(self.data.duration.values)
+
+        return np.vstack([times, times + duration]).T, list(self.data.value)
+
+    def __iter_obs__(self):
+        for _, (t, d, v, c) in self.data.iterrows():
+            yield Observation(time=t.total_seconds(),
+                              duration=d.total_seconds(),
+                              value=v, confidence=c)
+
+    def __iter__(self):
+        return self.__iter_obs__()
+
 
 class Curator(JObject):
     """Curator
@@ -1881,3 +1943,5 @@ def serialize_obj(obj):
         return [serialize_obj(x) for x in obj]
 
     return obj
+
+

jams/display.py

@@ -63,7 +63,7 @@ def pprint_jobject(obj, **kwargs):
 
 def intervals(annotation, **kwargs):
     '''Plotting wrapper for labeled intervals'''
-    times, labels = annotation.data.to_interval_values()
+    times, labels = annotation.to_interval_values()
 
     return mir_eval.display.labeled_intervals(times, labels, **kwargs)
 
@@ -83,7 +83,7 @@ def pitch_contour(annotation, **kwargs):
     # If the annotation is empty, we need to construct a new axes
     ax = mir_eval.display.__get_axes(ax=ax)[0]
 
-    times, values = annotation.data.to_interval_values()
+    times, values = annotation.to_interval_values()
 
     indices = np.unique([v['index'] for v in values])
 
@@ -102,7 +102,7 @@ def pitch_contour(annotation, **kwargs):
 def event(annotation, **kwargs):
     '''Plotting wrapper for events'''
 
-    times, values = annotation.data.to_interval_values()
+    times, values = annotation.to_interval_values()
 
     if any(values):
         labels = values
@@ -115,7 +115,7 @@ def event(annotation, **kwargs):
 def beat_position(annotation, **kwargs):
     '''Plotting wrapper for beat-position data'''
 
-    times, values = annotation.data.to_interval_values()
+    times, values = annotation.to_interval_values()
 
     labels = [_['position'] for _ in values]
 
@@ -125,7 +125,7 @@ def beat_position(annotation, **kwargs):
 
 def piano_roll(annotation, **kwargs):
     '''Plotting wrapper for piano rolls'''
-    times, midi = annotation.data.to_interval_values()
+    times, midi = annotation.to_interval_values()
 
     return mir_eval.display.piano_roll(times, midi=midi, **kwargs)
 

jams/eval.py

@@ -104,8 +104,8 @@ def beat(ref, est, **kwargs):
     namespace = 'beat'
     ref = coerce_annotation(ref, namespace)
     est = coerce_annotation(est, namespace)
-    ref_interval, _ = ref.data.to_interval_values()
-    est_interval, _ = est.data.to_interval_values()
+    ref_interval, _ = ref.to_interval_values()
+    est_interval, _ = est.to_interval_values()
 
     return mir_eval.beat.evaluate(ref_interval[:, 0], est_interval[:, 0], **kwargs)
 
@@ -145,8 +145,8 @@ def onset(ref, est, **kwargs):
     namespace = 'onset'
     ref = coerce_annotation(ref, namespace)
     est = coerce_annotation(est, namespace)
-    ref_interval, _ = ref.data.to_interval_values()
-    est_interval, _ = est.data.to_interval_values()
+    ref_interval, _ = ref.to_interval_values()
+    est_interval, _ = est.to_interval_values()
 
     return mir_eval.onset.evaluate(ref_interval[:, 0], est_interval[:, 0], **kwargs)
 
@@ -187,8 +187,8 @@ def chord(ref, est, **kwargs):
     namespace = 'chord'
     ref = coerce_annotation(ref, namespace)
     est = coerce_annotation(est, namespace)
-    ref_interval, ref_value = ref.data.to_interval_values()
-    est_interval, est_value = est.data.to_interval_values()
+    ref_interval, ref_value = ref.to_interval_values()
+    est_interval, est_value = est.to_interval_values()
 
     return mir_eval.chord.evaluate(ref_interval, ref_value,
                                    est_interval, est_value, **kwargs)
@@ -229,8 +229,8 @@ def segment(ref, est, **kwargs):
     namespace = 'segment_open'
     ref = coerce_annotation(ref, namespace)
     est = coerce_annotation(est, namespace)
-    ref_interval, ref_value = ref.data.to_interval_values()
-    est_interval, est_value = est.data.to_interval_values()
+    ref_interval, ref_value = ref.to_interval_values()
+    est_interval, est_value = est.to_interval_values()
 
     return mir_eval.segment.evaluate(ref_interval, ref_value,
                                      est_interval, est_value, **kwargs)
@@ -253,7 +253,7 @@ def hierarchy_flatten(annotation):
         A list of lists of labels, ordered by increasing specificity.
     '''
 
-    intervals, values = annotation.data.to_interval_values()
+    intervals, values = annotation.to_interval_values()
 
     ordering = dict()
 
@@ -394,8 +394,8 @@ def melody(ref, est, **kwargs):
     namespace = 'pitch_contour'
     ref = coerce_annotation(ref, namespace)
     est = coerce_annotation(est, namespace)
-    ref_interval, ref_p = ref.data.to_interval_values()
-    est_interval, est_p = est.data.to_interval_values()
+    ref_interval, ref_p = ref.to_interval_values()
+    est_interval, est_p = est.to_interval_values()
 
     ref_freq = np.asarray([p['frequency'] * (-1)**(~p['voiced']) for p in ref_p])
     est_freq = np.asarray([p['frequency'] * (-1)**(~p['voiced']) for p in est_p])
@@ -432,7 +432,7 @@ def pattern_to_mireval(ann):
     patterns = defaultdict(lambda: defaultdict(list))
 
     # Iterate over the data in interval-value format
-    for interval, observation in zip(*ann.data.to_interval_values()):
+    for interval, observation in zip(*ann.to_interval_values()):
 
         pattern_id = observation['pattern_id']
         occurrence_id = observation['occurrence_id']
@@ -525,8 +525,8 @@ def transcription(ref, est, **kwargs):
     namespace = 'pitch_contour'
     ref = coerce_annotation(ref, namespace)
     est = coerce_annotation(est, namespace)
-    ref_intervals, ref_p = ref.data.to_interval_values()
-    est_intervals, est_p = est.data.to_interval_values()
+    ref_intervals, ref_p = ref.to_interval_values()
+    est_intervals, est_p = est.to_interval_values()
 
     ref_pitches = np.asarray([p['frequency'] * (-1)**(~p['voiced']) for p in ref_p])
     est_pitches = np.asarray([p['frequency'] * (-1)**(~p['voiced']) for p in est_p])

jams/sonify.py

@@ -43,7 +43,7 @@ def clicks(annotation, sr=22050, length=None, **kwargs):
     events such as beats or segment boundaries.
     '''
 
-    interval, _ = annotation.data.to_interval_values()
+    interval, _ = annotation.to_interval_values()
 
     return filter_kwargs(mir_eval.sonify.clicks, interval[:, 0],
                          fs=sr, length=length, **kwargs)
@@ -56,7 +56,7 @@ def downbeat(annotation, sr=22050, length=None, **kwargs):
     beat_click = mkclick(440 * 2, sr=sr)
     downbeat_click = mkclick(440 * 3, sr=sr)
 
-    intervals, values = annotation.data.to_interval_values()
+    intervals, values = annotation.to_interval_values()
 
     beats, downbeats = [], []
 
@@ -109,7 +109,7 @@ def chord(annotation, sr=22050, length=None, **kwargs):
     This uses mir_eval.sonify.chords.
     '''
 
-    intervals, chords = annotation.data.to_interval_values()
+    intervals, chords = annotation.to_interval_values()
 
     return filter_kwargs(mir_eval.sonify.chords,
                          chords, intervals,
@@ -127,7 +127,7 @@ def pitch_contour(annotation, sr=22050, length=None, **kwargs):
     are summed together.
     '''
 
-    times, values = annotation.data.to_interval_values()
+    times, values = annotation.to_interval_values()
 
     indices = np.unique([v['index'] for v in values])
 
@@ -159,7 +159,7 @@ def piano_roll(annotation, sr=22050, length=None, **kwargs):
     namespace.
     '''
 
-    intervals, pitches = annotation.data.to_interval_values()
+    intervals, pitches = annotation.to_interval_values()
 
     # Construct the pitchogram
     pitch_map = {f: idx for idx, f in enumerate(np.unique(pitches))}

jams/util.py

@@ -12,6 +12,7 @@
     smkdirs
     filebase
     find_with_extension
+    _deprecated
 """
 
 import os

scripts/jams_to_lab.py

@@ -6,7 +6,6 @@
 import sys
 import os
 import json
-import six
 import pandas as pd
 
 import jams
@@ -56,6 +55,7 @@ def get_comments(jam, ann):
                        'annotation metadata': ann_comments},
                       indent=2)
 
+
 def lab_dump(ann, comment, filename, sep, comment_char):
     '''Save an annotation as a lab/csv.
 
@@ -77,11 +77,11 @@ def lab_dump(ann, comment, filename, sep, comment_char):
         The character used to denote comments
     '''
 
-    intervals, values = ann.data.to_interval_values()
+    intervals, values = ann.to_interval_values()
 
     frame = pd.DataFrame(columns=['Time', 'End Time', 'Label'],
                          data={'Time': intervals[:, 0],
-                               'End Time': intervals[:, 1], 
+                               'End Time': intervals[:, 1],
                                'Label': values})
 
     with open(filename, 'w') as fdesc:

tests/jams_test.py

@@ -211,10 +211,16 @@ def test_jamsframe_interval_values():
 
     jf = jams.JamsFrame.from_dataframe(df)
 
-    intervals, values = jf.to_interval_values()
+    warnings.resetwarnings()
+    warnings.simplefilter('always')
+    with warnings.catch_warnings(record=True) as out:
+        intervals, values = jf.to_interval_values()
+        assert len(out) > 0
+        assert out[0].category is DeprecationWarning
+        assert 'deprecated' in str(out[0].message).lower()
 
-    assert np.allclose(intervals, np.array([[0.0, 1.0], [1.0, 3.0]]))
-    eq_(values, ['a', 'b'])
+        assert np.allclose(intervals, np.array([[0.0, 1.0], [1.0, 3.0]]))
+        eq_(values, ['a', 'b'])
 
 
 def test_jamsframe_serialize():
@@ -369,6 +375,35 @@ def test_annotation_eq():
 
     assert not (ann1 == ann2)
 
+
+def test_annotation_iterator():
+
+    data = [dict(time=0, duration=0.5, value='one', confidence=0.2),
+            dict(time=1, duration=1, value='two', confidence=0.5)]
+
+    namespace = 'tag_open'
+
+    ann = jams.Annotation(namespace, data=data)
+
+    for obs, obs_raw in zip(ann, data):
+        assert isinstance(obs, jams.Observation)
+        assert obs._asdict() == obs_raw, (obs, obs_raw)
+
+
+def test_annotation_interval_values():
+
+    data = dict(time=[0.0, 1.0],
+                duration=[1., 2.0],
+                value=['a', 'b'],
+                confidence=[0.9, 0.9])
+
+    ann = jams.Annotation(namespace='tag_open', data=data)
+
+    intervals, values = ann.to_interval_values()
+
+    assert np.allclose(intervals, np.array([[0.0, 1.0], [1.0, 3.0]]))
+    eq_(values, ['a', 'b'])
+
 # FileMetadata
 
 def test_filemetadata():