Sequence

class sequencetools.Sequence(items=None)

A sequence.

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.AbjadObject.AbstractBase" -> "abjad.tools.abctools.AbjadObject.AbjadObject"; } subgraph cluster_sequencetools { graph [label=sequencetools]; "abjad.tools.sequencetools.Sequence.Sequence" [color=black, fontcolor=white, group=2, label=<<B>Sequence</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.AbjadObject.AbjadObject" -> "abjad.tools.sequencetools.Sequence.Sequence"; "builtins.object" -> "abjad.tools.abctools.AbjadObject.AbstractBase"; }

Bases

Attribute summary

degree_of_rotational_symmetry Gets degree of rotational symmetry.
flatten([classes, depth, indices]) Flattens sequence.
is_decreasing([strict]) Is true when sequence decreases.
is_increasing([strict]) Is true when sequence increases.
is_permutation([length]) Is true when sequence is a permutation.
is_repetition_free() Is true when sequence is repetition-free.
is_restricted_growth_function() Is true when sequence is a restricted growth function.
items Gets sequence items.
partition_by_counts(counts[, cyclic, ...]) Partitions sequence by counts.
partition_by_ratio_of_lengths(ratio) Partitions sequence by ratio of lengths.
period_of_rotation Gets period of rotation.
reverse() Reverses sequence.
rotate([index]) Rotates sequence by index.
split(weights[, cyclic, overhang]) Splits sequence by weights.
sum() Sums sequence.
__add__(expr) Adds expr to sequence.
__eq__(expr) Is true when expr is a sequence with items equal to those of this sequence.
__format__([format_specification]) Formats sequence.
__getitem__(i) Gets item i from sequence.
__hash__() Hashes sequence.
__len__() Gets length of sequence.
__ne__(expr) Is true when sequence is not equal to expr.
__radd__(expr) Adds sequence to expr.
__repr__() Gets interpreter representation of sequence.

Read-only properties

Sequence.degree_of_rotational_symmetry

Gets degree of rotational symmetry.

>>> Sequence((1, 1, 1, 1, 1, 1)).degree_of_rotational_symmetry
6
>>> Sequence((1, 2, 1, 2, 1, 2)).degree_of_rotational_symmetry
3
>>> Sequence((1, 2, 3, 1, 2, 3)).degree_of_rotational_symmetry
2
>>> Sequence((1, 2, 3, 4, 5, 6)).degree_of_rotational_symmetry
1
>>> Sequence().degree_of_rotational_symmetry
1

Returns positive integer.

Sequence.items

Gets sequence items.

Returns tuple.

Sequence.period_of_rotation

Gets period of rotation.

>>> Sequence((1, 2, 3, 4, 5, 6)).period_of_rotation
6
>>> Sequence((1, 2, 3, 1, 2, 3)).period_of_rotation
3
>>> Sequence((1, 2, 1, 2, 1, 2)).period_of_rotation
2
>>> Sequence((1, 1, 1, 1, 1, 1)).period_of_rotation
1
>>> Sequence().period_of_rotation
0

Defined equal to length of sequence divided by degree of rotational symmetry of sequence.

Returns positive integer.

Methods

Sequence.flatten(classes=None, depth=-1, indices=None)

Flattens sequence.

Example 1. Flattens sequence completely:

>>> sequence = Sequence((1, [2, 3, [4]], 5, [6, 7, [8]]))
>>> sequence.flatten()
Sequence((1, 2, 3, 4, 5, 6, 7, 8))

Example 2. Flattens sequence to depth 1:

>>> sequence = Sequence((1, [2, 3, [4]], 5, [6, 7, [8]]))
>>> sequence.flatten(depth=1)
Sequence((1, 2, 3, [4], 5, 6, 7, [8]))

Example 3. Flattens sequence to depth 2:

>>> sequence = Sequence((1, [2, 3, [4]], 5, [6, 7, [8]]))
>>> sequence.flatten(depth=2)
Sequence((1, 2, 3, 4, 5, 6, 7, 8))

Example 4. Flattens sequence at indices:

>>> sequence = Sequence((1, [2, 3, [4]], 5, [6, 7, [8]]))
>>> sequence.flatten(indices=[3])
Sequence((1, [2, 3, [4]], 5, 6, 7, 8))

Example 5. Flattens sequence at negative indices:

>>> sequence = Sequence((1, [2, 3, [4]], 5, [6, 7, [8]]))
>>> sequence.flatten(indices=[-1])
Sequence((1, [2, 3, [4]], 5, 6, 7, 8))

Example 6. Flattens only tuples in sequence:

>>> sequence = Sequence(('ab', 'cd', ('ef', 'gh'), ('ij', 'kl')))
>>> sequence.flatten(classes=(tuple,))
Sequence(('ab', 'cd', 'ef', 'gh', 'ij', 'kl'))

Returns new sequence.

Sequence.is_decreasing(strict=True)

Is true when sequence decreases.

With strict=True:

>>> Sequence((5, 4, 3, 2, 1, 0)).is_decreasing(strict=True)
True
>>> Sequence((3, 3, 3, 2, 1, 0)).is_decreasing(strict=True)
False
>>> Sequence((3, 3, 3, 3, 3, 3)).is_decreasing(strict=True)
False
>>> Sequence().is_decreasing(strict=True)
True

With strict=False:

>>> Sequence((5, 4, 3, 2, 1, 0)).is_decreasing(strict=False)
True
>>> Sequence((3, 3, 3, 2, 1, 0)).is_decreasing(strict=False)
True
>>> Sequence((3, 3, 3, 3, 3, 3)).is_decreasing(strict=False)
True
>>> Sequence().is_decreasing(strict=False)
True

Returns true or false.

Sequence.is_increasing(strict=True)

Is true when sequence increases.

With strict=True:

>>> Sequence((0, 1, 2, 3, 4, 5)).is_increasing(strict=True)
True
>>> Sequence((0, 1, 2, 3, 3, 3)).is_increasing(strict=True)
False
>>> Sequence((3, 3, 3, 3, 3, 3)).is_increasing(strict=True)
False
>>> Sequence().is_increasing(strict=True)
True

With strict=False:

>>> Sequence((0, 1, 2, 3, 4, 5)).is_increasing(strict=False)
True
>>> Sequence((0, 1, 2, 3, 3, 3)).is_increasing(strict=False)
True
>>> Sequence((3, 3, 3, 3, 3, 3)).is_increasing(strict=False)
True
>>> Sequence().is_increasing(strict=False)
True

Returns true or false.

Sequence.is_permutation(length=None)

Is true when sequence is a permutation.

Is true when sequence is a permutation:

>>> Sequence((4, 5, 0, 3, 2, 1)).is_permutation()
True

Is false when sequence is not a permutation:

>>> Sequence((1, 1, 5, 3, 2, 1)).is_permutation()
False

Returns true or false.

Sequence.is_repetition_free()

Is true when sequence is repetition-free.

Is true when sequence contains no repetitions:

>>> Sequence((0, 1, 2, 6, 7, 8)).is_repetition_free()
True

Is true when sequence is empty:

>>> Sequence().is_repetition_free()
True

Is false when sequence contains repetitions:

>>> Sequence((0, 1, 2, 2, 7, 8)).is_repetition_free()
False

Returns true or false.

Sequence.is_restricted_growth_function()

Is true when sequence is a restricted growth function.

Is true when sequence is a restricted growth function:

>>> Sequence((1, 1, 1, 1)).is_restricted_growth_function()
True
>>> Sequence((1, 1, 1, 2)).is_restricted_growth_function()
True
>>> Sequence((1, 1, 2, 1)).is_restricted_growth_function()
True
>>> Sequence((1, 1, 2, 2)).is_restricted_growth_function()
True

Is false when sequence is not a restricted growth function:

>>> Sequence((1, 1, 1, 3)).is_restricted_growth_function()
False
>>> Sequence((17,)).is_restricted_growth_function()
False

A restricted growth function is a sequence l such that l[0] == 1 and such that l[i] <= max(l[:i]) + 1 for 1 <= i <= len(l).

Returns true or false.

Sequence.partition_by_counts(counts, cyclic=False, overhang=False, reversed_=False)

Partitions sequence by counts.

Example 1. Partitions sequence once by counts without overhang:

>>> sequence_ = Sequence(range(16))
>>> parts = sequence_.partition_by_counts(
...     [3],
...     cyclic=False,
...     overhang=False,
...     )
>>> for part in parts:
...     part
Sequence((0, 1, 2))

Example 2. Partitions sequence once by counts without overhang:

>>> sequence_ = Sequence(range(16))
>>> parts = sequence_.partition_by_counts(
...     [4, 3],
...     cyclic=False,
...     overhang=False,
...     )
>>> for part in parts:
...     part
Sequence((0, 1, 2, 3))
Sequence((4, 5, 6))

Example 3. Partitions sequence cyclically by counts without overhang:

>>> sequence_ = Sequence(range(16))
>>> parts = sequence_.partition_by_counts(
...     [3],
...     cyclic=True,
...     overhang=False,
...     )
>>> for part in parts:
...     part
Sequence((0, 1, 2))
Sequence((3, 4, 5))
Sequence((6, 7, 8))
Sequence((9, 10, 11))
Sequence((12, 13, 14))

Example 4. Partitions sequence cyclically by counts without overhang:

>>> sequence_ = Sequence(range(16))
>>> parts = sequence_.partition_by_counts(
...     [4, 3],
...     cyclic=True,
...     overhang=False,
...     )
>>> for part in parts:
...     part
Sequence((0, 1, 2, 3))
Sequence((4, 5, 6))
Sequence((7, 8, 9, 10))
Sequence((11, 12, 13))

Example 5. Partitions sequence once by counts with overhang:

>>> sequence_ = Sequence(range(16))
>>> parts = sequence_.partition_by_counts(
...     [3],
...     cyclic=False,
...     overhang=True,
...     )
>>> for part in parts:
...     part
Sequence((0, 1, 2))
Sequence((3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15))

Example 6. Partitions sequence once by counts with overhang:

>>> sequence_ = Sequence(range(16))
>>> parts = sequence_.partition_by_counts(
...     [4, 3],
...     cyclic=False,
...     overhang=True,
...     )
>>> for part in parts:
...     part
Sequence((0, 1, 2, 3))
Sequence((4, 5, 6))
Sequence((7, 8, 9, 10, 11, 12, 13, 14, 15))

Example 7. Partitions sequence cyclically by counts with overhang:

>>> sequence_ = Sequence(range(16))
>>> parts = sequence_.partition_by_counts(
...     [3],
...     cyclic=True,
...     overhang=True,
...     )
>>> for part in parts:
...     part
Sequence((0, 1, 2))
Sequence((3, 4, 5))
Sequence((6, 7, 8))
Sequence((9, 10, 11))
Sequence((12, 13, 14))
Sequence((15,))

Example 8. Partitions sequence cyclically by counts with overhang:

>>> sequence_ = Sequence(range(16))
>>> parts = sequence_.partition_by_counts(
...     [4, 3],
...     cyclic=True,
...     overhang=True,
...     )
>>> for part in parts:
...     part
Sequence((0, 1, 2, 3))
Sequence((4, 5, 6))
Sequence((7, 8, 9, 10))
Sequence((11, 12, 13))
Sequence((14, 15))

Example 9. Reversed-partitions sequence once by counts without overhang:

>>> sequence_ = Sequence(range(16))
>>> parts = sequence_.partition_by_counts(
...     [3],
...     cyclic=False,
...     overhang=False,
...     reversed_=True,
...     )
>>> for part in parts:
...     part
Sequence((13, 14, 15))

Example 10. Reverse-partitions sequence once by counts without overhang:

>>> sequence_ = Sequence(range(16))
>>> parts = sequence_.partition_by_counts(
...     [4, 3],
...     cyclic=False,
...     overhang=False,
...     reversed_=True,
...     )
>>> for part in parts:
...     part
Sequence((9, 10, 11))
Sequence((12, 13, 14, 15))

Example 11. Reverse-partitions sequence cyclically by counts without overhang:

>>> sequence_ = Sequence(range(16))
>>> parts = sequence_.partition_by_counts(
...     [3],
...     cyclic=True,
...     overhang=False,
...     reversed_=True,
...     )
>>> for part in parts:
...     part
Sequence((1, 2, 3))
Sequence((4, 5, 6))
Sequence((7, 8, 9))
Sequence((10, 11, 12))
Sequence((13, 14, 15))

Example 12. Reverse-partitions sequence cyclically by counts without overhang:

>>> sequence_ = Sequence(range(16))
>>> parts = sequence_.partition_by_counts(
...     [4, 3],
...     cyclic=True,
...     overhang=False,
...     reversed_=True,
...     )
>>> for part in parts:
...     part
Sequence((2, 3, 4))
Sequence((5, 6, 7, 8))
Sequence((9, 10, 11))
Sequence((12, 13, 14, 15))

Example 13. Reverse-partitions sequence once by counts with overhang:

>>> sequence_ = Sequence(range(16))
>>> parts = sequence_.partition_by_counts(
...     [3],
...     cyclic=False,
...     overhang=True,
...     reversed_=True,
...     )
>>> for part in parts:
...     part
Sequence((0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12))
Sequence((13, 14, 15))

Example 14. Reverse-partitions sequence once by counts with overhang:

>>> sequence_ = Sequence(range(16))
>>> parts = sequence_.partition_by_counts(
...     [4, 3],
...     cyclic=False,
...     overhang=True,
...     reversed_=True,
...     )
>>> for part in parts:
...     part
Sequence((0, 1, 2, 3, 4, 5, 6, 7, 8))
Sequence((9, 10, 11))
Sequence((12, 13, 14, 15))

Example 15. Reverse-partitions sequence cyclically by counts with overhang:

>>> sequence_ = Sequence(range(16))
>>> parts = sequence_.partition_by_counts(
...     [3],
...     cyclic=True,
...     overhang=True,
...     reversed_=True,
...     )
>>> for part in parts:
...     part
Sequence((0,))
Sequence((1, 2, 3))
Sequence((4, 5, 6))
Sequence((7, 8, 9))
Sequence((10, 11, 12))
Sequence((13, 14, 15))

Example 16. Reverse-partitions sequence cyclically by counts with overhang:

>>> sequence_ = Sequence(range(16))
>>> parts = sequence_.partition_by_counts(
...     [4, 3],
...     cyclic=True,
...     overhang=True,
...     reversed_=True,
...     )
>>> for part in parts:
...     part
Sequence((0, 1))
Sequence((2, 3, 4))
Sequence((5, 6, 7, 8))
Sequence((9, 10, 11))
Sequence((12, 13, 14, 15))

Example 17. Partitions sequence once by counts and asserts that sequence partitions exactly (with no overhang):

>>> sequence_ = Sequence(range(10))
>>> parts = sequence_.partition_by_counts(
...     [2, 3, 5],
...     cyclic=False,
...     overhang=Exact,
...     )
>>> for part in parts:
...     part
Sequence((0, 1))
Sequence((2, 3, 4))
Sequence((5, 6, 7, 8, 9))

Example 18. Partitions sequence cyclically by counts and asserts that sequence partitions exactly:

>>> sequence_ = Sequence(range(10))
>>> parts = sequence_.partition_by_counts(
...     [2],
...     cyclic=True,
...     overhang=Exact,
...     )
>>> for part in parts:
...     part
Sequence((0, 1))
Sequence((2, 3))
Sequence((4, 5))
Sequence((6, 7))
Sequence((8, 9))

Exact partitioning means partitioning with no overhang.

Example 19. Partitions string:

>>> sequence_ = Sequence('some text')
>>> parts = sequence_.partition_by_counts(
...     [3],
...     cyclic=False,
...     overhang=True,
...     )
>>> for part in parts:
...     part
Sequence(('s', 'o', 'm'))
Sequence(('e', ' ', 't', 'e', 'x', 't'))

Returns nested sequence.

Sequence.partition_by_ratio_of_lengths(ratio)

Partitions sequence by ratio of lengths.

Example 1. Partitions sequence by 1:1:1 ratio:

>>> numbers = Sequence(range(10))
>>> ratio = mathtools.Ratio((1, 1, 1))
>>> numbers.partition_by_ratio_of_lengths(ratio)
Sequence((Sequence((0, 1, 2)), Sequence((3, 4, 5, 6)), Sequence((7, 8, 9))))

Example 2. Partitions sequence by 1:1:2 ratio:

>>> numbers = Sequence(range(10))
>>> ratio = mathtools.Ratio((1, 1, 2))
>>> numbers.partition_by_ratio_of_lengths(ratio)
Sequence((Sequence((0, 1, 2)), Sequence((3, 4)), Sequence((5, 6, 7, 8, 9))))

Returns a sequence of sequences.

Sequence.reverse()

Reverses sequence.

Example.

>>> Sequence((1, 2, 3, 4, 5)).reverse()
Sequence((5, 4, 3, 2, 1))

Returns new sequence.

Sequence.rotate(index=None)

Rotates sequence by index.

Example 1. Rotates sequence to the right:

>>> Sequence(tuple(range(10))).rotate(4)
Sequence((6, 7, 8, 9, 0, 1, 2, 3, 4, 5))

Example 2. Rotates sequence to the left:

>>> Sequence(tuple(range(10))).rotate(-3)
Sequence((3, 4, 5, 6, 7, 8, 9, 0, 1, 2))

Example 3. Rotates sequence neither to the right nor the left:

>>> Sequence(tuple(range(10))).rotate(0)
Sequence((0, 1, 2, 3, 4, 5, 6, 7, 8, 9))

Returns new sequence.

Sequence.split(weights, cyclic=False, overhang=False)

Splits sequence by weights.

Todo

Port remaining examples from sequencetools.split_sequence().

Example 1. Splits sequence cyclically by weights with overhang:

>>> sequence_ = Sequence((10, -10, 10, -10))
>>> sequence_.split(
...     (3, 15, 3),
...     cyclic=True,
...     overhang=True,
...     )
Sequence((Sequence((3,)), Sequence((7, -8)), Sequence((-2, 1)), Sequence((3,)), Sequence((6, -9)), Sequence((-1,))))

Returns new sequence.

Sequence.sum()

Sums sequence.

Example 1. Sums sequence of positive numbers:

>>> Sequence([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]).sum()
55

Example 2. Sum sequence of numbers with mixed signs:

>>> Sequence([-1, 2, -3, 4, -5, 6, -7, 8, -9, 10]).sum()
5

Returns new sequence.

Special methods

Sequence.__add__(expr)

Adds expr to sequence.

Adds sequence to sequence:

>>> Sequence((1, 2, 3)) + Sequence((4, 5, 6))
Sequence((1, 2, 3, 4, 5, 6))

Adds tuple to sequence:

>>> Sequence((1, 2, 3)) + (4, 5, 6)
Sequence((1, 2, 3, 4, 5, 6))

Adds list to sequence:

>>> Sequence((1, 2, 3)) + [4, 5, 6]
Sequence((1, 2, 3, 4, 5, 6))

Returns new sequence.

Sequence.__eq__(expr)

Is true when expr is a sequence with items equal to those of this sequence. Otherwise false.

>>> Sequence((1, 2, 3, 4, 5, 6)) == Sequence((1, 2, 3, 4, 5, 6))
True
>>> Sequence((1, 2, 3, 4, 5, 6)) == ((1, 2, 3, 4, 5, 6))
False

Returns true or false.

Sequence.__format__(format_specification='')

Formats sequence.

Example. Prints format:

>>> print(format(Sequence((1, 2, 3, 4, 5, 6))))
sequencetools.Sequence(
    items=(1, 2, 3, 4, 5, 6),
    )

Returns string.

Sequence.__getitem__(i)

Gets item i from sequence.

Example. Gets last item in sequence:

>>> Sequence((1, 2, 3, 4, 5, 6))[-1]
6

Returns item.

Sequence.__hash__()

Hashes sequence.

Required to be explicitly redefined on Python 3 if __eq__ changes.

Returns integer.

Sequence.__len__()

Gets length of sequence.

Gets length of six-item sequence:

>>> len(Sequence((1, 2, 3, 4, 5, 6)))
6

Returns nonnegative integer.

Sequence.__ne__(expr)

Is true when sequence is not equal to expr. Otherwise false.

>>> Sequence((1, 2, 3, 4, 5, 6)) != (1, 2, 3, 4, 5, 6)
True
>>> Sequence((1, 2, 3, 4, 5, 6)) != Sequence((1, 2, 3, 4, 5, 6))
False
Sequence.__radd__(expr)

Adds sequence to expr.

Example 1. Adds sequence to sequence:

>>> Sequence((1, 2, 3)) + Sequence((4, 5, 6))
Sequence((1, 2, 3, 4, 5, 6))

Example 2. Adds sequence to tuple:

>>> (1, 2, 3) + Sequence((4, 5, 6))
Sequence((1, 2, 3, 4, 5, 6))

Example 3. Adds sequence to list:

>>> [1, 2, 3] + Sequence((4, 5, 6))
Sequence((1, 2, 3, 4, 5, 6))

Returns new sequence.

Sequence.__repr__()

Gets interpreter representation of sequence.

Example 1. Gets interpreter representation of sequence with length equal to one:

>>> Sequence((99,))
Sequence((99,))

Example 2. Gets interpreter representation of sequence with length greater than one:

>>> Sequence((1, 2, 3, 4, 5, 6))
Sequence((1, 2, 3, 4, 5, 6))

Returns string.