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.

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

OffsetFilter bases

OffsetFilter read-only properties

Read-only properties inherited from StreamFilter:

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. :-)

OffsetHierarchyFilter

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

see iterator.getElementsByOffsetInHierarchy()

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

OffsetHierarchyFilter methods

Methods inherited from OffsetFilter:

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