jams.AnnotationArray

class jams.AnnotationArray(annotations=None)

Bases: list

This list subclass provides serialization and search/filtering for annotation collections.

Fancy-indexing can be used to directly search for annotations belonging to a particular namespace. Three types of indexing are supported:

• integer or slice : acts just as in list, e.g., arr[0] or arr[1:3]
• string : acts like a search, e.g., arr[‘beat’] == arr.search(namespace=’beat’)
• (string, integer or slice) acts like a search followed by index/slice

Examples

>>> # Retrieve the first annotation with simple indexing
>>> ann = jam.annotations[0]

>>> # Retrieve the first three annotations
>>> anns = jam.annotations[:3]

>>> # Retrieve a list of beat annotations
>>> # equivalent to jam.search(namespace='beat')
>>> beat_anns = jam.annotations['beat']

>>> # Retrieve the second beat annotation
>>> # equivalent to jam.search(namespace='beat')[1]
>>> beat2 = jam.annotations['beat', 1]

>>> # Retrieve everything after the second salami annotation
>>> seg_anns = jam.annotations['segment_salami_.*', 2:]

__init__(self, annotations=None)

Create an AnnotationArray.

Parameters:

annotations: list

List of Annotations, or appropriately formated dicts is consistent with Annotation.

Methods

__init__(self[, annotations])	Create an AnnotationArray.
append(self, object, /)	Append object to the end of the list.
clear(self, /)	Remove all items from list.
copy(self, /)	Return a shallow copy of the list.
count(self, value, /)	Return number of occurrences of value.
extend(self, iterable, /)	Extend list by appending elements from the iterable.
index(self, value[, start, stop])	Return first index of value.
insert(self, index, object, /)	Insert object before index.
pop(self[, index])	Remove and return item at index (default last).
remove(self, value, /)	Remove first occurrence of value.
reverse(self, /)	Reverse IN PLACE.
search(self, \*\*kwargs)	Filter the annotation array down to only those Annotation objects matching the query.
slice(self, start_time, end_time[, strict])	Slice every annotation contained in the annotation array using Annotation.slice and return as a new AnnotationArray
sort(self, /, \*[, key, reverse])	Stable sort IN PLACE.
trim(self, start_time, end_time[, strict])	Trim every annotation contained in the annotation array using Annotation.trim and return as a new AnnotationArray.

search(self, **kwargs)

Filter the annotation array down to only those Annotation objects matching the query.

Parameters:

kwargs : search parameters

See JObject.search

Returns:

results : AnnotationArray

An annotation array of the objects matching the query

See also

JObject.search

slice(self, start_time, end_time, strict=False)

Slice every annotation contained in the annotation array using Annotation.slice and return as a new AnnotationArray

See Annotation.slice for details about slicing. This function does not modify the annotations in the original annotation array.

Parameters:

start_time : float

The desired start time for slicing in seconds.

end_time

The desired end time for slicing in seconds. Must be greater than start_time.

strict : bool

When False (default) observations that lie at the boundaries of the slicing range (see Annotation.slice for details) will have their time and/or duration adjusted such that only the part of the observation that lies within the trim range is kept. When True such observations are discarded and not included in the sliced annotation.

Returns:

sliced_array : AnnotationArray

An annotation array where every annotation has been sliced.

trim(self, start_time, end_time, strict=False)

Trim every annotation contained in the annotation array using Annotation.trim and return as a new AnnotationArray.

See Annotation.trim for details about trimming. This function does not modify the annotations in the original annotation array.

Parameters:

start_time : float

The desired start time for the trimmed annotations in seconds.

end_time

The desired end time for trimmed annotations in seconds. Must be greater than start_time.

strict : bool

When False (default) observations that lie at the boundaries of the trimming range (see Annotation.trim for details) will have their time and/or duration adjusted such that only the part of the observation that lies within the trim range is kept. When True such observations are discarded and not included in the trimmed annotation.

Returns:

trimmed_array : AnnotationArray

An annotation array where every annotation has been trimmed.