Pattern

class patterntools.Pattern(indices=None, inverted=None, payload=None, period=None)

Pattern.

Example 1. Matches three indices out of every eight:

>>> pattern = patterntools.Pattern(
...     indices=[0, 1, 7],
...     period=8,
...     )
>>> total_length = 16
>>> for index in range(16):
...     match = pattern.matches_index(index, total_length)
...     match = match or ''
...     print(index, match)
0 True
1 True
2
3
4
5
6
7 True
8 True
9 True
10
11
12
13
14
15 True

Example 2. Matches three indices out of every sixteen:

>>> pattern = patterntools.Pattern(
...     indices=[0, 1, 7],
...     period=16,
...     )
>>> total_length = 16
>>> for index in range(16):
...     match = pattern.matches_index(index, total_length)
...     match = match or ''
...     print(index, match)
0 True
1 True
2
3
4
5
6
7 True
8
9
10
11
12
13
14
15

Example 3. Works with improper indices:

>>> pattern = patterntools.Pattern(
...     indices=[16, 17, 23],
...     period=16,
...     )
>>> total_length = 16
>>> for index in range(16):
...     match = pattern.matches_index(index, total_length)
...     match = match or ''
...     print(index, match)
0 True
1 True
2
3
4
5
6
7 True
8
9
10
11
12
13
14
15

Lineage

digraph InheritanceGraph { graph [background=transparent, bgcolor=transparent, color=lightslategrey, fontname=Arial, outputorder=edgesfirst, overlap=prism, penwidth=2, rankdir=LR, root="__builtin__.object", splines=spline, style="dotted, rounded", truecolor=true]; node [colorscheme=pastel19, fontname=Arial, fontsize=12, penwidth=2, style="filled, rounded"]; edge [color=lightsteelblue2, penwidth=2]; subgraph cluster_abctools { graph [label=abctools]; "abjad.tools.abctools.AbjadObject.AbjadObject" [color=1, group=0, label=AbjadObject, shape=box]; "abjad.tools.abctools.AbjadObject.AbstractBase" [color=1, group=0, label=AbstractBase, shape=box]; "abjad.tools.abctools.AbjadValueObject.AbjadValueObject" [color=1, group=0, label=AbjadValueObject, shape=box]; "abjad.tools.abctools.AbjadObject.AbjadObject" -> "abjad.tools.abctools.AbjadValueObject.AbjadValueObject"; "abjad.tools.abctools.AbjadObject.AbstractBase" -> "abjad.tools.abctools.AbjadObject.AbjadObject"; } subgraph cluster_patterntools { graph [label=patterntools]; "abjad.tools.patterntools.Pattern.Pattern" [color=black, fontcolor=white, group=2, label=<<B>Pattern</B>>, shape=box, style="filled, rounded"]; } subgraph cluster_builtins { graph [label=builtins]; "builtins.object" [color=2, group=1, label=object, shape=box]; } "abjad.tools.abctools.AbjadValueObject.AbjadValueObject" -> "abjad.tools.patterntools.Pattern.Pattern"; "builtins.object" -> "abjad.tools.abctools.AbjadObject.AbstractBase"; }

Bases

Attribute summary

from_vector(class_, vector) Makes pattern from boolean vector.
get_boolean_vector([total_length]) Gets boolean vector of pattern applied to input sequence with total_length.
indices Gets indices of pattern.
inverted Is true when pattern is inverted.
matches_index(index, total_length[, rotation]) Is true when pattern matches index taken under total_length.
payload Gets payload of pattern.
period Gets period of pattern.
reverse() Reverses pattern.
rotate([n]) Rotates pattern.
weight Gets weight of pattern.
__and__(other) Logical AND of two patterns.
__copy__(\*args) Copies Abjad value object.
__eq__(expr) Is true when all initialization values of Abjad value object equal the initialization values of expr.
__format__([format_specification]) Formats Abjad object.
__hash__() Hashes Abjad value object.
__invert__() Inverts pattern.
__len__() Gets length of pattern.
__ne__(expr) Is true when Abjad object does not equal expr.
__or__(other) Logical OR of two patterns.
__repr__() Gets interpreter representation of Abjad object.
__xor__(other) Logical XOR of two patterns.

Read-only properties

Pattern.indices

Gets indices of pattern.

Example 1. Matches three indices out of every eight:

>>> pattern = patterntools.Pattern(
...     indices=[0, 1, 7],
...     period=8,
...     )
>>> pattern.indices
(0, 1, 7)

Example 2. Matches three indices out of every sixteen:

>>> pattern = patterntools.Pattern(
...     indices=[0, 1, 7],
...     period=16,
...     )
>>> pattern.indices
(0, 1, 7)

Defaults to none.

Set to integers or none.

Returns integers or none.

Pattern.inverted

Is true when pattern is inverted. Otherwise false.

Example 1. Matches three indices out of every eight:

>>> pattern = patterntools.Pattern(
...     indices=[0, 1, 7],
...     period=8,
...     )
>>> pattern.inverted is None
True
>>> total_length = 16
>>> for index in range(16):
...     match = pattern.matches_index(index, total_length)
...     match = match or ''
...     print(index, match)
0 True
1 True
2
3
4
5
6
7 True
8 True
9 True
10
11
12
13
14
15 True

Example 2. Pattern that rejects three indices from every eight; equivalently, pattern matches 8-3=5 indices out of every eight:

>>> pattern = patterntools.Pattern(
...     indices=[0, 1, 7],
...     period=8,
...     inverted=True
...     )
>>> pattern.inverted
True
>>> total_length = 16
>>> for index in range(16):
...     match = pattern.matches_index(index, total_length)
...     match = match or ''
...     print(index, match)
0
1
2 True
3 True
4 True
5 True
6 True
7
8
9
10 True
11 True
12 True
13 True
14 True
15

Defaults to none.

Set to true, false or none.

Returns true, false or none.

Pattern.payload

Gets payload of pattern.

Example 1. Pattern with rhythm-maker payload assigned to three of every eight indices:

>>> maker = rhythmmakertools.NoteRhythmMaker()
>>> pattern = patterntools.Pattern(
...     indices=[0, 1, 7],
...     payload=maker,
...     period=8,
...     )
>>> total_length = 10
>>> for index in range(10):
...     match = pattern.matches_index(index, total_length)
...     if match:
...         payload = pattern.payload
...     else:
...         payload = ''
...     print(index, payload)
0 NoteRhythmMaker()
1 NoteRhythmMaker()
2
3
4
5
6
7 NoteRhythmMaker()
8 NoteRhythmMaker()
9 NoteRhythmMaker()

Defaults to none.

Set to any object.

Returns arbitrary object.

Pattern.period

Gets period of pattern.

Example 1. Pattern with a period of eight:

>>> pattern = patterntools.Pattern(
...     indices=[0, 1, 7],
...     period=8,
...     )
>>> pattern.period
8
>>> total_length = 16
>>> for index in range(16):
...     match = pattern.matches_index(index, total_length)
...     match = match or ''
...     print(index, match)
0 True
1 True
2
3
4
5
6
7 True
8 True
9 True
10
11
12
13
14
15 True

Example 2. Same pattern with a period of sixteen:

>>> pattern = patterntools.Pattern(
...     indices=[0, 1, 7],
...     period=16,
...     )
>>> pattern.period
16
>>> total_length = 16
>>> for index in range(16):
...     match = pattern.matches_index(index, total_length)
...     match = match or ''
...     print(index, match)
0 True
1 True
2
3
4
5
6
7 True
8
9
10
11
12
13
14
15

Defaults to none.

Set to positive integer or none.

Returns positive integer or none.

Pattern.weight

Gets weight of pattern.

Example 1. Gets weight of cyclic pattern:

>>> pattern = patterntools.Pattern(
...     indices=[0, 1, 7],
...     period=8,
...     )
>>> pattern.weight
3

Example 2. Gets weight of acyclic pattern:

>>> pattern = patterntools.Pattern(
...     indices=[0, 2, 3],
...     )
>>> pattern.weight
3

Weight defined equal to number of indices in pattern.

Returns nonnegative integer.

Methods

Pattern.get_boolean_vector(total_length=None)

Gets boolean vector of pattern applied to input sequence with total_length.

Example 1. Gets boolean vector of acyclic pattern:

>>> pattern = patterntools.Pattern(
...     indices=[4, 5, 6, 7],
...     )
>>> pattern.get_boolean_vector(4)
[0, 0, 0, 0]
>>> pattern.get_boolean_vector(8)
[0, 0, 0, 0, 1, 1, 1, 1]
>>> pattern.get_boolean_vector(16)
[0, 0, 0, 0, 1, 1, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0]

Sets total length to length of pattern when total_length is none:

>>> pattern.get_boolean_vector()
[0, 0, 0, 0, 1, 1, 1, 1]

Example 2. Gets vector of cyclic pattern:

>>> pattern = patterntools.Pattern(
...     indices=[4, 5, 6, 7],
...     period=20,
...     )
>>> pattern.get_boolean_vector(4)
[0, 0, 0, 0]
>>> pattern.get_boolean_vector(8)
[0, 0, 0, 0, 1, 1, 1, 1]
>>> pattern.get_boolean_vector(16)
[0, 0, 0, 0, 1, 1, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0]

Sets total length to length of pattern when total_length is none:

>>> pattern.get_boolean_vector()
[0, 0, 0, 0, 1, 1, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]

Example 3. Gets vector of inverted pattern:

>>> pattern = patterntools.Pattern(
...     indices=[4, 5, 6, 7],
...     period=20,
...     )
>>> pattern.get_boolean_vector(4)
[0, 0, 0, 0]
>>> pattern.get_boolean_vector(8)
[0, 0, 0, 0, 1, 1, 1, 1]
>>> pattern.get_boolean_vector(16)
[0, 0, 0, 0, 1, 1, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0]

Sets total length to length of pattern when total_length is none:

>>> pattern.get_boolean_vector()
[0, 0, 0, 0, 1, 1, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]

Returns list of ones and zeroes.

Pattern.matches_index(index, total_length, rotation=None)

Is true when pattern matches index taken under total_length. Otherwise false.

Example 1a. Matches three indices out of every eight:

>>> pattern = patterntools.Pattern(
...     indices=[0, 1, 7],
...     period=8,
...     )
>>> total_length = 16
>>> for index in range(16):
...     match = pattern.matches_index(index, total_length)
...     match = match or ''
...     print(index, match)
0 True
1 True
2
3
4
5
6
7 True
8 True
9 True
10
11
12
13
14
15 True

Example 1b. Matches three indices out of every eight, offset 1 to the left:

>>> pattern = patterntools.Pattern(
...     indices=[0, 1, 7],
...     period=8,
...     )
>>> total_length = 16
>>> for index in range(16):
...     match = pattern.matches_index(
...         index,
...         total_length,
...         rotation=1,
...         )
...     match = match or ''
...     print(index, match)
0 True
1
2
3
4
5
6 True
7 True
8 True
9
10
11
12
13
14 True
15 True

Example 1c. Matches three indices out of every eight, offset 2 to the left:

>>> pattern = patterntools.Pattern(
...     indices=[0, 1, 7],
...     period=8,
...     )
>>> total_length = 16
>>> for index in range(16):
...     match = pattern.matches_index(
...         index,
...         total_length,
...         rotation=2,
...         )
...     match = match or ''
...     print(index, match)
0
1
2
3
4
5 True
6 True
7 True
8
9
10
11
12
13 True
14 True
15 True

Example 2a. Matches three indices out of every sixteen:

>>> pattern = patterntools.Pattern(
...     indices=[0, 1, 7],
...     period=16,
...     )
>>> total_length = 16
>>> for index in range(16):
...     match = pattern.matches_index(index, total_length)
...     match = match or ''
...     print(index, match)
0 True
1 True
2
3
4
5
6
7 True
8
9
10
11
12
13
14
15

Example 2b. Matches three indices out of every sixteen, offset 1 to the left:

>>> pattern = patterntools.Pattern(
...     indices=[0, 1, 7],
...     period=16,
...     )
>>> total_length = 16
>>> for index in range(16):
...     match = pattern.matches_index(
...         index,
...         total_length,
...         rotation=1,
...         )
...     match = match or ''
...     print(index, match)
0 True
1
2
3
4
5
6 True
7
8
9
10
11
12
13
14
15 True

Example 2c. Matches three indices out of every sixteen, offset 2 to the left:

>>> pattern = patterntools.Pattern(
...     indices=[0, 1, 7],
...     period=16,
...     )
>>> total_length = 16
>>> for index in range(16):
...     match = pattern.matches_index(
...         index,
...         total_length,
...         rotation=2,
...         )
...     match = match or ''
...     print(index, match)
0
1
2
3
4
5 True
6
7
8
9
10
11
12
13
14 True
15 True

Returns true or false.

Pattern.reverse()

Reverses pattern.

Example 1. Matches three indices out of every eight:

>>> pattern = patterntools.Pattern(
...     indices=[0, 1, 7],
...     period=8,
...     )
>>> total_length = 16
>>> for index in range(16):
...     match = pattern.matches_index(index, total_length)
...     match = match or ''
...     print(index, match)
0 True
1 True
2
3
4
5
6
7 True
8 True
9 True
10
11
12
13
14
15 True

Example 2. Reverses pattern:

>>> pattern = patterntools.Pattern(
...     indices=[0, 1, 7],
...     period=8,
...     )
>>> pattern = pattern.reverse()
>>> print(format(pattern))
patterntools.Pattern(
    indices=(-1, -2, -8),
    period=8,
    )
>>> total_length = 16
>>> for index in range(16):
...     match = pattern.matches_index(index, total_length)
...     match = match or ''
...     print(index, match)
0 True
1
2
3
4
5
6 True
7 True
8 True
9
10
11
12
13
14 True
15 True

Returns new pattern.

Pattern.rotate(n=0)

Rotates pattern.

Example 1. Matches three indices out of every eight:

>>> pattern = patterntools.Pattern(
...     indices=[0, 1, 7],
...     period=8,
...     )
>>> total_length = 16
>>> for index in range(16):
...     match = pattern.matches_index(index, total_length)
...     match = match or ''
...     print(index, match)
0 True
1 True
2
3
4
5
6
7 True
8 True
9 True
10
11
12
13
14
15 True

Rotates pattern two elements to the right:

>>> pattern = patterntools.Pattern(
...     indices=[0, 1, 7],
...     period=8,
...     )
>>> pattern = pattern.rotate(n=2)
>>> print(format(pattern))
patterntools.Pattern(
    indices=(2, 3, 9),
    period=8,
    )
>>> total_length = 16
>>> for index in range(16):
...     match = pattern.matches_index(index, total_length)
...     match = match or ''
...     print(index, match)
0
1 True
2 True
3 True
4
5
6
7
8
9 True
10 True
11 True
12
13
14
15

Example 2. Matches three indices out of every eight with negative indices:

>>> pattern = patterntools.Pattern(
...     indices=[-3, -2, -1],
...     period=8,
...     )
>>> total_length = 16
>>> for index in range(16):
...     match = pattern.matches_index(index, total_length)
...     match = match or ''
...     print(index, match)
0
1
2
3
4
5 True
6 True
7 True
8
9
10
11
12
13 True
14 True
15 True

Rotates pattern two elements to the right:

>>> pattern = patterntools.Pattern(
...     indices=[-3, -2, -1],
...     period=8,
...     )
>>> pattern = pattern.rotate(n=2)
>>> print(format(pattern))
patterntools.Pattern(
    indices=(-1, 0, 1),
    period=8,
    )
>>> total_length = 16
>>> for index in range(16):
...     match = pattern.matches_index(index, total_length)
...     match = match or ''
...     print(index, match)
0 True
1 True
2
3
4
5
6
7 True
8 True
9 True
10
11
12
13
14
15 True

Returns new pattern.

Class & static methods

classmethod Pattern.from_vector(class_, vector)

Makes pattern from boolean vector.

Example 1. Matches three indices out of every five:

>>> pattern = [1, 0, 0, 1, 1]
>>> pattern = patterntools.Pattern.from_vector(pattern)
>>> print(format(pattern))
patterntools.Pattern(
    indices=(0, 3, 4),
    period=5,
    )
>>> total_length = 10
>>> for index in range(10):
...     match = pattern.matches_index(index, total_length)
...     match = match or ''
...     print(index, match)
0 True
1
2
3 True
4 True
5 True
6
7
8 True
9 True

Example 2. Matches three indices out of every six:

>>> pattern = [1, 0, 0, 1, 1, 0]
>>> pattern = patterntools.Pattern.from_vector(pattern)
>>> print(format(pattern))
patterntools.Pattern(
    indices=(0, 3, 4),
    period=6,
    )
>>> total_length = 12
>>> for index in range(12):
...     match = pattern.matches_index(index, total_length)
...     match = match or ''
...     print(index, match)
0 True
1
2
3 True
4 True
5
6 True
7
8
9 True
10 True
11

Returns pattern.

Special methods

Pattern.__and__(other)

Logical AND of two patterns.

Example.

>>> pattern_1 = patterntools.select_first(3)
>>> pattern_2 = patterntools.select_last(3)
>>> pattern = pattern_1 & pattern_2
>>> print(format(pattern))
patterntools.CompoundPattern(
    (
        patterntools.Pattern(
            indices=(0, 1, 2),
            ),
        patterntools.Pattern(
            indices=(-3, -2, -1),
            ),
        ),
    operator='and',
    )

Returns compound pattern.

(AbjadValueObject).__copy__(*args)

Copies Abjad value object.

Returns new Abjad value object.

(AbjadValueObject).__eq__(expr)

Is true when all initialization values of Abjad value object equal the initialization values of expr.

Returns true or false.

(AbjadObject).__format__(format_specification='')

Formats Abjad object.

Set format_specification to ‘’ or ‘storage’. Interprets ‘’ equal to ‘storage’.

Returns string.

(AbjadValueObject).__hash__()

Hashes Abjad value object.

Returns integer.

Pattern.__invert__()

Inverts pattern.

Example.

>>> pattern = patterntools.select_first(3)
>>> print(format(pattern))
patterntools.Pattern(
    indices=(0, 1, 2),
    )
>>> pattern = ~pattern
>>> print(format(pattern))
patterntools.Pattern(
    indices=(0, 1, 2),
    inverted=True,
    )
>>> pattern = ~pattern
>>> print(format(pattern))
patterntools.Pattern(
    indices=(0, 1, 2),
    inverted=False,
    )

Negation defined equal to inversion.

Returns new pattern.

Pattern.__len__()

Gets length of pattern.

Example 1. Gets length of cyclic pattern:

>>> pattern = patterntools.Pattern(
...     indices=[0, 1, 7],
...     period=8,
...     )
>>> len(pattern)
8

Length of cyclic pattern defined equal to period of the pattern.

Example 2. Gets length of acyclic pattern:

>>> pattern = patterntools.Pattern(
...     indices=[0, 2, 3],
...     )
>>> len(pattern)
4

Length of acyclic pattern defined equal to greatest index in pattern, plus 1.

Example 3. Gets length of pattern with negative indices:

>>> pattern = patterntools.Pattern(
...     indices=[-3],
...     )
>>> len(pattern)
3

Length of pattern with negative indices defined equal to absolute value of least index.

Returns nonnegative integer.

(AbjadObject).__ne__(expr)

Is true when Abjad object does not equal expr. Otherwise false.

Returns true or false.

Pattern.__or__(other)

Logical OR of two patterns.

Example.

>>> pattern_1 = patterntools.select_first(3)
>>> pattern_2 = patterntools.select_last(3)
>>> pattern = pattern_1 | pattern_2
>>> print(format(pattern))
patterntools.CompoundPattern(
    (
        patterntools.Pattern(
            indices=(0, 1, 2),
            ),
        patterntools.Pattern(
            indices=(-3, -2, -1),
            ),
        ),
    operator='or',
    )

Returns compound pattern.

(AbjadObject).__repr__()

Gets interpreter representation of Abjad object.

Returns string.

Pattern.__xor__(other)

Logical XOR of two patterns.

Example.

>>> pattern_1 = patterntools.select_first(3)
>>> pattern_2 = patterntools.select_last(3)
>>> pattern = pattern_1 ^ pattern_2
>>> print(format(pattern))
patterntools.CompoundPattern(
    (
        patterntools.Pattern(
            indices=(0, 1, 2),
            ),
        patterntools.Pattern(
            indices=(-3, -2, -1),
            ),
        ),
    operator='xor',
    )

Returns compound pattern.