music21.stream.filters

The filter module contains StreamFilter objects which are used by StreamIterator objects to decide whether 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 quarter>
<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 ProtoM21Object:

ClassFilter methods

ClassFilter.__eq__(other)

Return self==value.

Methods inherited from StreamFilter:

Methods inherited from ProtoM21Object:

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 quarter>

ClassNotFilter bases

ClassNotFilter read-only properties

Read-only properties inherited from ProtoM21Object:

ClassNotFilter methods

Methods inherited from ClassFilter:

Methods inherited from StreamFilter:

Methods inherited from ProtoM21Object:

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 ProtoM21Object:

GroupFilter methods

Methods inherited from StreamFilter:

Methods inherited from ProtoM21Object:

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 ProtoM21Object:

IdFilter methods

Methods inherited from StreamFilter:

Methods inherited from ProtoM21Object:

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 quarter>

IsFilter bases

IsFilter read-only properties

Read-only properties inherited from ProtoM21Object:

IsFilter methods

IsFilter.reset()

Methods inherited from ProtoM21Object:

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 quarter>

test that resetting works:

>>> for el in s.iter().addFilter(stream.filters.IsNotFilter(n)):
...     el
<music21.key.KeySignature of 3 flats>
<music21.note.Rest quarter>

Using multiple filters:

>>> 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 ProtoM21Object:

IsNotFilter methods

IsNotFilter.reset()

Methods inherited from ProtoM21Object:

OffsetFilter

class music21.stream.filters.OffsetFilter(offsetStart=0.0, offsetEnd=None, *, includeEndBoundary=True, mustFinishInSpan=False, mustBeginInSpan=True, includeElementsThatEndAtStart=True, stopAfterEnd=True)

see getElementsByOffset() for docs on this filter.

Finds elements that match a given offset range.

  • Changed in v5.5: all arguments except offsetStart and offsetEnd are keyword only.

  • Changed in v6.5: stopAfterEnd can be set globally.

OffsetFilter bases

OffsetFilter read-only properties

Read-only properties inherited from ProtoM21Object:

OffsetFilter methods

OffsetFilter.isElementOffsetInRange(e, offset, *, stopAfterEnd=False) → bool

Given an element, offset, and stream, return True, False, or raise StopIteration if the element is in the range, not in the range, or (if stopAfterEnd is True) is not and no future elements will be in the range.

Factored out from __call__ to be used by OffsetHierarchyFilter, and it’s just a beast. :-)

Methods inherited from StreamFilter:

Methods inherited from ProtoM21Object:

OffsetHierarchyFilter

class music21.stream.filters.OffsetHierarchyFilter(offsetStart=0.0, offsetEnd=None, *, includeEndBoundary=True, mustFinishInSpan=False, mustBeginInSpan=True, includeElementsThatEndAtStart=True, stopAfterEnd=True)

see getElementsByOffsetInHierarchy() for docs on this filter.

Finds elements that match a given offset range in the hierarchy.

Do not call .stream() afterwards or unstable results can occur.

OffsetHierarchyFilter bases

OffsetHierarchyFilter read-only properties

Read-only properties inherited from ProtoM21Object:

OffsetHierarchyFilter methods

Methods inherited from OffsetFilter:

Methods inherited from StreamFilter:

Methods inherited from ProtoM21Object:

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, inherited from ProtoM21Object which help in certain debug operations

>>> 'StreamFilter' in sf.classSet
True
>>> sf.classes
('StreamFilter', 'ProtoM21Object', 'object')

StreamFilter bases

StreamFilter read-only properties

Read-only properties inherited from ProtoM21Object:

StreamFilter methods

StreamFilter.reset()

Methods inherited from ProtoM21Object: