music21.stream.filters¶
The filter module contains StreamFilter objects
which are used by StreamIterator objects to
decide whether or not a given element matches the list of elements that are being
filtered. Filters are used by methods on streams such as
getElementsByClass() to filter elements by classes.
ClassFilter¶
-
class
music21.stream.filters.ClassFilter(classList=())¶ ClassFilter is used by .getElementsByClass() to find elements belonging to a class or a list of classes.
>>> s = stream.Stream() >>> s.append(note.Note('C')) >>> s.append(note.Rest()) >>> s.append(note.Note('D')) >>> sI = iter(s) >>> sI <music21.stream.iterator.StreamIterator for Stream:0x104843828 @:0> >>> for x in sI: ... print(x) <music21.note.Note C> <music21.note.Rest rest> <music21.note.Note D>
>>> sI.filters.append(stream.filters.ClassFilter('Note')) >>> sI.filters [<music21.stream.filters.ClassFilter Note>]
>>> for x in sI: ... print(x) <music21.note.Note C> <music21.note.Note D>
ClassFilter bases
ClassFilter read-only properties
Read-only properties inherited from StreamFilter:
ClassNotFilter¶
-
class
music21.stream.filters.ClassNotFilter(classList=())¶ Returns elements not of the class.
>>> s = stream.Stream() >>> s.append(note.Note('C')) >>> s.append(note.Rest()) >>> s.append(note.Note('D')) >>> sI = iter(s)
>>> sI.filters.append(stream.filters.ClassNotFilter('Note')) >>> sI.filters [<music21.stream.filters.ClassNotFilter Note>]
>>> for x in sI: ... print(x) <music21.note.Rest rest>
ClassNotFilter bases
ClassNotFilter read-only properties
Read-only properties inherited from StreamFilter:
GroupFilter¶
-
class
music21.stream.filters.GroupFilter(groupFilterList=())¶ Returns elements with a certain group.
>>> n1 = note.Note("C") >>> n1.groups.append('trombone') >>> n2 = note.Note("D") >>> n2.groups.append('trombone') >>> n2.groups.append('tuba') >>> n3 = note.Note("E") >>> n3.groups.append('tuba') >>> s1 = stream.Stream() >>> s1.append(n1) >>> s1.append(n2) >>> s1.append(n3) >>> GF = stream.filters.GroupFilter
>>> for thisNote in iter(s1).addFilter(GF("trombone")): ... print(thisNote.name) C D >>> for thisNote in iter(s1).addFilter(GF("tuba")): ... print(thisNote.name) D E
GroupFilter bases
GroupFilter read-only properties
Read-only properties inherited from StreamFilter:
IdFilter¶
-
class
music21.stream.filters.IdFilter(searchId=None)¶ filters on ids. used by stream.getElementById. No corresponding iterator call.
Only a single Id can be passed in. Always returns a single item.
IdFilter bases
IdFilter read-only properties
Read-only properties inherited from StreamFilter:
IsFilter¶
-
class
music21.stream.filters.IsFilter(target=())¶ filter on items where x IS y
>>> s = stream.Stream() >>> s.insert(0, key.KeySignature(-3)) >>> n = note.Note('C#') >>> s.append(n) >>> s.append(note.Rest()) >>> isFilter = stream.filters.IsFilter(n) >>> isFilter.derivationStr 'is' >>> isFilter.target (<music21.note.Note C#>,) >>> isFilter.numToFind 1
.numToFind is used so that once all elements are found, the iterator can short circuit.
>>> for el in s.iter.addFilter(isFilter): ... print(el is n) True
Multiple elements can also be passed into the isFilter:
>>> s = stream.Stream() >>> s.insert(0, key.KeySignature(-3)) >>> n = note.Note('C#') >>> s.append(n) >>> r = note.Rest() >>> s.append(r) >>> isFilter2 = stream.filters.IsFilter([n, r]) >>> isFilter2.numToFind 2
>>> for el in s.iter.addFilter(isFilter2): ... print(el) <music21.note.Note C#> <music21.note.Rest rest>
IsFilter bases
IsFilter read-only properties
Read-only properties inherited from StreamFilter:
IsFilter methods
-
IsFilter.reset()¶
IsNotFilter¶
-
class
music21.stream.filters.IsNotFilter(target=())¶ Filter out everything but an item or list of items:
>>> s = stream.Stream() >>> s.insert(0, key.KeySignature(-3)) >>> n = note.Note('C#') >>> s.append(n) >>> s.append(note.Rest()) >>> for el in s.iter.addFilter(stream.filters.IsNotFilter(n)): ... el <music21.key.KeySignature of 3 flats> <music21.note.Rest rest>
test that resetting works...
>>> for el in s.iter.addFilter(stream.filters.IsNotFilter(n)): ... el <music21.key.KeySignature of 3 flats> <music21.note.Rest rest>
multiple...
>>> s = stream.Stream() >>> s.insert(0, key.KeySignature(-3)) >>> n = note.Note('C#') >>> s.append(n) >>> r = note.Rest() >>> s.append(r) >>> for el in s.iter.addFilter(stream.filters.IsNotFilter([n, r])): ... print(el) <music21.key.KeySignature of 3 flats>
IsNotFilter bases
IsNotFilter read-only properties
Read-only properties inherited from StreamFilter:
IsNotFilter methods
-
IsNotFilter.reset()¶
OffsetFilter¶
-
class
music21.stream.filters.OffsetFilter(offsetStart=0.0, offsetEnd=None, includeEndBoundary=True, mustFinishInSpan=False, mustBeginInSpan=True, includeElementsThatEndAtStart=True)¶ see iterator.getElementsByOffset()
Finds elements that match a given offset range.
OffsetFilter bases
OffsetFilter read-only properties
Read-only properties inherited from StreamFilter:
StreamFilter¶
-
class
music21.stream.filters.StreamFilter¶ A filter is an object that when called returns True or False about whether an element in the stream matches the filter.
A lambda expression: lambda el, iterator: True if EXP else False can also be used as a very simple filter.
Filters can also raise StopIteration if no other elements in this Stream can possibly fit.
The StreamFilter object does nothing in itself but subclasses are crucial in filtering out elements according to different properties.
Each subclass of StreamFilter should set its .derivationStr which is a string that determines which a derived Stream based on this filter should be called
>>> sf = stream.filters.StreamFilter() >>> sf <music21.stream.filters.StreamFilter object at 0x1051de828> >>> sf.derivationStr 'streamFilter'
StreamFilters also have these two properties which help in certain debug operations
>>> 'StreamFilter' in sf.classSet True >>> sf.classes ('StreamFilter', 'object')
StreamFilter read-only properties
-
StreamFilter.classSet¶ this is not cached – it should be if we end up using it a lot...
-
StreamFilter.classes¶