sequence

---

Functions

filter	Filters sequence by callable predicate.
flatten	Flattens sequence.
group_by	Groups sequence items by value of items.
has_duplicates	Is true when sequence has duplicates.
is_decreasing	Is true when sequence is decreasing.
is_increasing	Is true when sequence is increasing.
is_permutation	Is true when sequence is a permutation.
is_repetition_free	Is true when sequence is repetition-free.
join	Join subsequences in sequence.
nwise	Iterates sequence n items at a time.
partition_by_counts	Partitions sequence by counts.
partition_by_ratio_of_lengths	Partitions sequence by ratio of lengths.
partition_by_ratio_of_weights	Partitions sequence by ratio of weights.
partition_by_weights	Partitions sequence by weights exactly.
permute	Permutes sequence by permutation.
remove	Removes sequence items at indices specified by pattern.
remove_repeats	Removes repeats from sequence.
repeat	Repeats sequence, to a total of n copies.
repeat_to_length	Repeats sequence to length.
repeat_to_weight	Repeats sequence to weight.
replace	Replaces every old-valued item in sequence with new.
replace_at	Replaces items at indices with new_material.
retain_pattern	Retains sequence items at indices matching pattern.
reverse	Reverses sequence.
rotate	Rotates sequence by index n.
split	Splits sequence by weights.
sum_by_sign	Sums consecutive sequence items by sign.
truncate	Truncates sequence.
weight	Gets weight of sequence.
zip	Zips sequences.

abjad.sequence.filter(sequence, predicate=None)

Filters sequence by callable predicate.

By length:

>>> sequence = [[1], [2, 3, [4]], [5], [6, 7, [8]]]

>>> abjad.sequence.filter(sequence, lambda _: len(_) == 1)
[[1], [5]]

By duration:

>>> staff = abjad.Staff("c'4. d'8 e'4. f'8 g'2")
>>> sequence = list(staff)

>>> abjad.sequence.filter(
...     sequence, lambda _: _.written_duration == abjad.Duration(1, 8)
... )
[Note("d'8"), Note("f'8")]

Returns sequence type.

abjad.sequence.flatten(sequence, *, classes=None, depth=1)

Flattens sequence.

Flattens sequence:

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

Flattens sequence to depth 2:

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

Flattens sequence to depth -1:

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

Flattens tuples in sequence only:

>>> sequence = ["ab", "cd", ("ef", "gh"), ("ij", "kl")]
>>> abjad.sequence.flatten(sequence, classes=(tuple, list))
['ab', 'cd', 'ef', 'gh', 'ij', 'kl']

Returns sequence type.

abjad.sequence.group_by(sequence, predicate=None)

Groups sequence items by value of items.

>>> items = [0, 0, -1, -1, 2, 3, -5, 1, 1, 5, -5]
>>> sequence = list(items)
>>> for item in abjad.sequence.group_by(sequence):
...     item
... 
[0, 0]
[-1, -1]
[2]
[3]
[-5]
[1, 1]
[5]
[-5]

>>> staff = abjad.Staff("c'8 d' d' e' e' e'")
>>> predicate = lambda _: abjad.PitchSet([_])
>>> sequence = list(staff)
>>> for item in abjad.sequence.group_by(sequence, predicate):
...     item
... 
[Note("c'8")]
[Note("d'8"), Note("d'8")]
[Note("e'8"), Note("e'8"), Note("e'8")]

Returns list of sequence types.

Return type:

list

abjad.sequence.has_duplicates(sequence)

Is true when sequence has duplicates.

>>> abjad.sequence.has_duplicates([0, 1, 2, 3, 4])
False

>>> abjad.sequence.has_duplicates([0, 1, 2, 3, 3])
True

>>> abjad.sequence.has_duplicates([0, 1, 0, 1, 0])
True

abjad.sequence.is_decreasing(sequence, *, strict=True)

Is true when sequence is decreasing.

Is true when sequence is strictly decreasing:

>>> abjad.sequence.is_decreasing([5, 4, 3, 2, 1, 0], strict=True)
True

>>> abjad.sequence.is_decreasing([3, 3, 3, 2, 1, 0], strict=True)
False

>>> abjad.sequence.is_decreasing([3, 3, 3, 3, 3, 3], strict=True)
False

>>> abjad.sequence.is_decreasing([], strict=True)
True

Is true when sequence decreases monotonically:

>>> abjad.sequence.is_decreasing([5, 4, 3, 2, 1, 0], strict=False)
True

>>> abjad.sequence.is_decreasing([3, 3, 3, 2, 1, 0], strict=False)
True

>>> abjad.sequence.is_decreasing([3, 3, 3, 3, 3, 3], strict=False)
True

>>> abjad.sequence.is_decreasing([], strict=False)
True

Return type:

bool

abjad.sequence.is_increasing(sequence, *, strict=True)

Is true when sequence is increasing.

Is true when sequence is strictly increasing:

>>> abjad.sequence.is_increasing([0, 1, 2, 3, 4, 5], strict=True)
True

>>> abjad.sequence.is_increasing([0, 1, 2, 3, 3, 3], strict=True)
False

>>> abjad.sequence.is_increasing([3, 3, 3, 3, 3, 3], strict=True)
False

>>> abjad.sequence.is_increasing([], strict=True)
True

Is true when sequence increases monotonically:

>>> abjad.sequence.is_increasing([0, 1, 2, 3, 4, 5], strict=False)
True

>>> abjad.sequence.is_increasing([0, 1, 2, 3, 3, 3], strict=False)
True

>>> abjad.sequence.is_increasing([3, 3, 3, 3, 3, 3], strict=False)
True

>>> abjad.sequence.is_increasing([], strict=False)
True

Return type:

bool

abjad.sequence.is_permutation(sequence)

Is true when sequence is a permutation.

>>> abjad.sequence.is_permutation([4, 5, 0, 3, 2, 1])
True

>>> abjad.sequence.is_permutation([1, 1, 5, 3, 2, 1])
False

Return type:

bool

abjad.sequence.is_repetition_free(sequence)

Is true when sequence is repetition-free.

>>> abjad.sequence.is_repetition_free([0, 1, 2, 6, 7, 8])
True

>>> abjad.sequence.is_repetition_free([])
True

>>> abjad.sequence.is_repetition_free([0, 1, 2, 2, 7, 8])
False

Return type:

bool

abjad.sequence.join(sequence)

Join subsequences in sequence.

>>> items = [(1, 2, 3), (), (4, 5), (), (6,)]
>>> sequence = list(items)
>>> sequence
[(1, 2, 3), (), (4, 5), (), (6,)]

>>> abjad.sequence.join(sequence)
[(1, 2, 3, 4, 5, 6)]

Returns sequence type.

abjad.sequence.nwise(sequence, n=2, *, cyclic=False, wrapped=False)

Iterates sequence n items at a time.

Iterates items 2 at a time:

>>> sequence = list(range(10))
>>> for item in abjad.sequence.nwise(sequence):
...     item
... 
[0, 1]
[1, 2]
[2, 3]
[3, 4]
[4, 5]
[5, 6]
[6, 7]
[7, 8]
[8, 9]

Iterates items 3 at a time:

>>> sequence = list(range(10))
>>> for item in abjad.sequence.nwise(sequence, n=3):
...     item
... 
[0, 1, 2]
[1, 2, 3]
[2, 3, 4]
[3, 4, 5]
[4, 5, 6]
[5, 6, 7]
[6, 7, 8]
[7, 8, 9]

Iterates items 2 at a time. Wraps around at end:

>>> sequence = list(range(10))
>>> for item in abjad.sequence.nwise(sequence, n=2, wrapped=True):
...     item
... 
[0, 1]
[1, 2]
[2, 3]
[3, 4]
[4, 5]
[5, 6]
[6, 7]
[7, 8]
[8, 9]
[9, 0]

Iterates items 3 at a time. Wraps around at end:

>>> sequence = list(range(10))
>>> for item in abjad.sequence.nwise(sequence, n=3, wrapped=True):
...     item
... 
[0, 1, 2]
[1, 2, 3]
[2, 3, 4]
[3, 4, 5]
[4, 5, 6]
[5, 6, 7]
[6, 7, 8]
[7, 8, 9]
[8, 9, 0]
[9, 0, 1]

Iterates items 2 at a time. Cycles indefinitely:

>>> sequence = list(range(10))
>>> pairs = abjad.sequence.nwise(sequence, n=2, cyclic=True)
>>> for _ in range(15):
...     next(pairs)
... 
[0, 1]
[1, 2]
[2, 3]
[3, 4]
[4, 5]
[5, 6]
[6, 7]
[7, 8]
[8, 9]
[9, 0]
[0, 1]
[1, 2]
[2, 3]
[3, 4]
[4, 5]

Returns infinite generator.

Iterates items 3 at a time. Cycles indefinitely:

>>> sequence = list(range(10))
>>> triples = abjad.sequence.nwise(sequence, n=3, cyclic=True)
>>> for _ in range(15):
...     next(triples)
... 
[0, 1, 2]
[1, 2, 3]
[2, 3, 4]
[3, 4, 5]
[4, 5, 6]
[5, 6, 7]
[6, 7, 8]
[7, 8, 9]
[8, 9, 0]
[9, 0, 1]
[0, 1, 2]
[1, 2, 3]
[2, 3, 4]
[3, 4, 5]
[4, 5, 6]

Returns infinite generator.

Iterates items 1 at a time:

>>> sequence = list(range(10))
>>> for item in abjad.sequence.nwise(sequence, n=1):
...     item
... 
[0]
[1]
[2]
[3]
[4]
[5]
[6]
[7]
[8]
[9]

Ignores wrapped when cyclic=True.

Return type:

Iterator

abjad.sequence.partition_by_counts(sequence, counts, *, cyclic=False, enchain=False, overhang=False, reversed_=False)

Partitions sequence by counts.

Partitions sequence once by counts without overhang:

>>> sequence = list(range(16))
>>> sequence = abjad.sequence.partition_by_counts(
...     sequence,
...     [3],
...     cyclic=False,
...     overhang=False,
... )

>>> sequence
[[0, 1, 2]]

>>> for part in sequence:
...     part
... 
[0, 1, 2]

Partitions sequence once by counts without overhang:

>>> sequence = list(range(16))
>>> parts = abjad.sequence.partition_by_counts(
...     sequence,
...     [4, 3],
...     cyclic=False,
...     overhang=False,
... )

>>> for part in parts:
...     part
... 
[0, 1, 2, 3]
[4, 5, 6]

Partitions sequence cyclically by counts without overhang:

>>> sequence = list(range(16))
>>> parts = abjad.sequence.partition_by_counts(
...     sequence,
...     [3],
...     cyclic=True,
...     overhang=False,
... )

>>> for part in parts:
...     part
... 
[0, 1, 2]
[3, 4, 5]
[6, 7, 8]
[9, 10, 11]
[12, 13, 14]

Partitions sequence cyclically by counts without overhang:

>>> sequence = list(range(16))
>>> parts = abjad.sequence.partition_by_counts(
...     sequence,
...     [4, 3],
...     cyclic=True,
...     overhang=False,
... )

>>> for part in parts:
...     part
... 
[0, 1, 2, 3]
[4, 5, 6]
[7, 8, 9, 10]
[11, 12, 13]

Partitions sequence once by counts with overhang:

>>> sequence = list(range(16))
>>> parts = abjad.sequence.partition_by_counts(
...     sequence,
...     [3],
...     cyclic=False,
...     overhang=True,
... )

>>> for part in parts:
...     part
... 
[0, 1, 2]
[3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15]

Partitions sequence once by counts with overhang:

>>> sequence = list(range(16))
>>> parts = abjad.sequence.partition_by_counts(
...     sequence,
...     [4, 3],
...     cyclic=False,
...     overhang=True,
... )

>>> for part in parts:
...     part
... 
[0, 1, 2, 3]
[4, 5, 6]
[7, 8, 9, 10, 11, 12, 13, 14, 15]

Partitions sequence cyclically by counts with overhang:

>>> sequence = list(range(16))
>>> parts = abjad.sequence.partition_by_counts(
...     sequence,
...     [3],
...     cyclic=True,
...     overhang=True,
... )

>>> for part in parts:
...     part
... 
[0, 1, 2]
[3, 4, 5]
[6, 7, 8]
[9, 10, 11]
[12, 13, 14]
[15]

Partitions sequence cyclically by counts with overhang:

>>> sequence = list(range(16))
>>> parts = abjad.sequence.partition_by_counts(
...     sequence,
...     [4, 3],
...     cyclic=True,
...     overhang=True,
... )

>>> for part in parts:
...     part
... 
[0, 1, 2, 3]
[4, 5, 6]
[7, 8, 9, 10]
[11, 12, 13]
[14, 15]

Reverse-partitions sequence once by counts without overhang:

>>> sequence = list(range(16))
>>> parts = abjad.sequence.partition_by_counts(
...     sequence,
...     [3],
...     cyclic=False,
...     overhang=False,
...     reversed_=True,
... )

>>> for part in parts:
...     part
... 
[13, 14, 15]

Reverse-partitions sequence once by counts without overhang:

>>> sequence = list(range(16))
>>> parts = abjad.sequence.partition_by_counts(
...     sequence,
...     [4, 3],
...     cyclic=False,
...     overhang=False,
...     reversed_=True,
... )

>>> for part in parts:
...     part
... 
[9, 10, 11]
[12, 13, 14, 15]

Reverse-partitions sequence cyclically by counts without overhang:

>>> sequence = list(range(16))
>>> parts = abjad.sequence.partition_by_counts(
...     sequence,
...     [3],
...     cyclic=True,
...     overhang=False,
...     reversed_=True,
... )

>>> for part in parts:
...     part
... 
[1, 2, 3]
[4, 5, 6]
[7, 8, 9]
[10, 11, 12]
[13, 14, 15]

Reverse-partitions sequence cyclically by counts without overhang:

>>> sequence = list(range(16))
>>> parts = abjad.sequence.partition_by_counts(
...     sequence,
...     [4, 3],
...     cyclic=True,
...     overhang=False,
...     reversed_=True,
... )

>>> for part in parts:
...     part
... 
[2, 3, 4]
[5, 6, 7, 8]
[9, 10, 11]
[12, 13, 14, 15]

Reverse-partitions sequence once by counts with overhang:

>>> sequence = list(range(16))
>>> parts = abjad.sequence.partition_by_counts(
...     sequence,
...     [3],
...     cyclic=False,
...     overhang=True,
...     reversed_=True,
... )

>>> for part in parts:
...     part
... 
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12]
[13, 14, 15]

Reverse-partitions sequence once by counts with overhang:

>>> sequence = list(range(16))
>>> parts = abjad.sequence.partition_by_counts(
...     sequence,
...     [4, 3],
...     cyclic=False,
...     overhang=True,
...     reversed_=True,
... )

>>> for part in parts:
...     part
... 
[0, 1, 2, 3, 4, 5, 6, 7, 8]
[9, 10, 11]
[12, 13, 14, 15]

Reverse-partitions sequence cyclically by counts with overhang:

>>> sequence = list(range(16))
>>> parts = abjad.sequence.partition_by_counts(
...     sequence,
...     [3],
...     cyclic=True,
...     overhang=True,
...     reversed_=True,
... )

>>> for part in parts:
...     part
... 
[0]
[1, 2, 3]
[4, 5, 6]
[7, 8, 9]
[10, 11, 12]
[13, 14, 15]

Reverse-partitions sequence cyclically by counts with overhang:

>>> sequence = list(range(16))
>>> parts = abjad.sequence.partition_by_counts(
...     sequence,
...     [4, 3],
...     cyclic=True,
...     overhang=True,
...     reversed_=True,
... )

>>> for part in parts:
...     part
... 
[0, 1]
[2, 3, 4]
[5, 6, 7, 8]
[9, 10, 11]
[12, 13, 14, 15]

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

>>> sequence = list(range(10))
>>> parts = abjad.sequence.partition_by_counts(
...     sequence,
...     [2, 3, 5],
...     cyclic=False,
...     overhang=abjad.EXACT,
... )

>>> for part in parts:
...     part
... 
[0, 1]
[2, 3, 4]
[5, 6, 7, 8, 9]

Partitions sequence cyclically by counts and asserts that sequence partitions exactly. Exact partitioning means partitioning with no overhang:

>>> sequence = list(range(10))
>>> parts = abjad.sequence.partition_by_counts(
...     sequence,
...     [2],
...     cyclic=True,
...     overhang=abjad.EXACT,
... )

>>> for part in parts:
...     part
... 
[0, 1]
[2, 3]
[4, 5]
[6, 7]
[8, 9]

Partitions string:

>>> sequence = list("some text")
>>> parts = abjad.sequence.partition_by_counts(
...     sequence,
...     [3],
...     cyclic=False,
...     overhang=True,
... )

>>> for part in parts:
...     part
... 
['s', 'o', 'm']
['e', ' ', 't', 'e', 'x', 't']

Partitions sequence cyclically into enchained parts by counts; truncates overhang:

>>> sequence = list(range(16))
>>> parts = abjad.sequence.partition_by_counts(
...     sequence,
...     [2, 6],
...     cyclic=True,
...     enchain=True,
...     overhang=False,
... )

>>> for part in parts:
...     part
... 
[0, 1]
[1, 2, 3, 4, 5, 6]
[6, 7]
[7, 8, 9, 10, 11, 12]
[12, 13]

Partitions sequence cyclically into enchained parts by counts; returns overhang at end:

>>> sequence = list(range(16))
>>> parts = abjad.sequence.partition_by_counts(
...     sequence,
...     [2, 6],
...     cyclic=True,
...     enchain=True,
...     overhang=True,
... )

>>> for part in parts:
...     part
... 
[0, 1]
[1, 2, 3, 4, 5, 6]
[6, 7]
[7, 8, 9, 10, 11, 12]
[12, 13]
[13, 14, 15]

REGRESSION: partitions sequence cyclically into enchained parts by counts; does not return false 1-element part at end:

>>> sequence = list(range(16))
>>> parts = abjad.sequence.partition_by_counts(
...     sequence,
...     [5],
...     cyclic=True,
...     enchain=True,
...     overhang=True,
... )

>>> for part in parts:
...     part
... 
[0, 1, 2, 3, 4]
[4, 5, 6, 7, 8]
[8, 9, 10, 11, 12]
[12, 13, 14, 15]

Edge case: empty counts nests sequence and ignores keywords:

>>> sequence = list(range(16))
>>> parts = abjad.sequence.partition_by_counts(sequence, [])

>>> for part in parts:
...     part
... 
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15]

Returns list of sequence types.

Return type:

list

abjad.sequence.partition_by_ratio_of_lengths(sequence, ratio)

Partitions sequence by ratio of lengths.

Partitions sequence by 1:1:1 ratio:

>>> numbers = list(range(10))
>>> ratio = (1, 1, 1)

>>> for part in abjad.sequence.partition_by_ratio_of_lengths(numbers, ratio):
...     part
... 
[0, 1, 2]
[3, 4, 5, 6]
[7, 8, 9]

Partitions sequence by 1:1:2 ratio:

>>> numbers = list(range(10))
>>> ratio = (1, 1, 2)

>>> for part in abjad.sequence.partition_by_ratio_of_lengths(numbers, ratio):
...     part
... 
[0, 1, 2]
[3, 4]
[5, 6, 7, 8, 9]

Returns list of sequence types.

Return type:

list

abjad.sequence.partition_by_ratio_of_weights(sequence, weights)

Partitions sequence by ratio of weights.

>>> ratio = (1, 1, 1)
>>> sequence = list(10 * [1])
>>> sequence = abjad.sequence.partition_by_ratio_of_weights(sequence, ratio)
>>> for item in sequence:
...     item
... 
[1, 1, 1]
[1, 1, 1, 1]
[1, 1, 1]

>>> ratio = (1, 1, 1, 1)
>>> sequence = list(10 * [1])
>>> sequence = abjad.sequence.partition_by_ratio_of_weights(sequence, ratio)
>>> for item in sequence:
...     item
... 
[1, 1, 1]
[1, 1]
[1, 1, 1]
[1, 1]

>>> ratio = (2, 2, 3)
>>> sequence = list(10 * [1])
>>> sequence = abjad.sequence.partition_by_ratio_of_weights(sequence, ratio)
>>> for item in sequence:
...     item
... 
[1, 1, 1]
[1, 1, 1]
[1, 1, 1, 1]

>>> ratio = (3, 2, 2)
>>> sequence = list(10 * [1])
>>> sequence = abjad.sequence.partition_by_ratio_of_weights(sequence, ratio)
>>> for item in sequence:
...     item
... 
[1, 1, 1, 1]
[1, 1, 1]
[1, 1, 1]

>>> ratio = (1, 1)
>>> items = [1, 1, 1, 1, 1, 1, 2, 2, 2, 2, 2, 2]
>>> sequence = list(items)
>>> sequence = abjad.sequence.partition_by_ratio_of_weights(sequence, ratio)
>>> for item in sequence:
...     item
... 
[1, 1, 1, 1, 1, 1, 2, 2]
[2, 2, 2, 2]

>>> ratio = (1, 1, 1)
>>> items = [1, 1, 1, 1, 1, 1, 2, 2, 2, 2, 2, 2]
>>> sequence = list(items)
>>> sequence = abjad.sequence.partition_by_ratio_of_weights(sequence, ratio)
>>> for item in sequence:
...     item
... 
[1, 1, 1, 1, 1, 1]
[2, 2, 2]
[2, 2, 2]

>>> ratio = (1, 1, 1)
>>> sequence = list([5, 5])
>>> sequence = abjad.sequence.partition_by_ratio_of_weights(sequence, ratio)
>>> for item in sequence:
...     item
... 
[5]
[5]
[]

>>> ratio = (1, 1, 1, 1)
>>> sequence = list([5, 5])
>>> sequence = abjad.sequence.partition_by_ratio_of_weights(sequence, ratio)
>>> for item in sequence:
...     item
... 
[5]
[]
[5]
[]

>>> ratio = (2, 2, 3)
>>> sequence = list([5, 5])
>>> sequence = abjad.sequence.partition_by_ratio_of_weights(sequence, ratio)
>>> for item in sequence:
...     item
... 
[5]
[5]
[]

>>> ratio = (3, 2, 2)
>>> sequence = list([5, 5])
>>> sequence = abjad.sequence.partition_by_ratio_of_weights(sequence, ratio)
>>> for item in sequence:
...     item
... 
[5]
[5]
[]

Rounded weight-proportions of sequences returned equal to rounded weights.

Returns list of sequence types.

Return type:

list

abjad.sequence.partition_by_weights(sequence, weights, *, cyclic=False, overhang=False, allow_part_weights=Comparison.EXACT)

Partitions sequence by weights exactly. :rtype: list

>>> sequence = [3, 3, 3, 3, 4, 4, 4, 4, 5]

Partitions sequence once by weights with overhang:

>>> for item in abjad.sequence.partition_by_weights(
...     sequence,
...     [3, 9],
...     cyclic=False,
...     overhang=False,
... ):
...     item
... 
[3]
[3, 3, 3]

Partitions sequence once by weights. Allows overhang:

>>> for item in abjad.sequence.partition_by_weights(
...     sequence,
...     [3, 9],
...     cyclic=False,
...     overhang=True,
... ):
...     item
... 
[3]
[3, 3, 3]
[4, 4, 4, 4, 5]

Partitions sequence cyclically by weights:

>>> for item in abjad.sequence.partition_by_weights(
...     sequence,
...     [12],
...     cyclic=True,
...     overhang=False,
... ):
...     item
... 
[3, 3, 3, 3]
[4, 4, 4]

Partitions sequence cyclically by weights. Allows overhang:

>>> for item in abjad.sequence.partition_by_weights(
...     sequence,
...     [12],
...     cyclic=True,
...     overhang=True,
... ):
...     item
... 
[3, 3, 3, 3]
[4, 4, 4]
[4, 5]

>>> sequence = list([3, 3, 3, 3, 4, 4, 4, 4, 5, 5])

Partitions sequence once by weights. Allows part weights to be just less than specified:

>>> for item in abjad.sequence.partition_by_weights(
...     sequence,
...     [10, 4],
...     cyclic=False,
...     overhang=False,
...     allow_part_weights=abjad.LESS,
... ):
...     item
... 
[3, 3, 3]
[3]

Partitions sequence once by weights. Allows part weights to be just less than specified. Allows overhang:

>>> for item in abjad.sequence.partition_by_weights(
...     sequence,
...     [10, 4],
...     cyclic=False,
...     overhang=True,
...     allow_part_weights=abjad.LESS,
... ):
...     item
... 
[3, 3, 3]
[3]
[4, 4, 4, 4, 5, 5]

Partitions sequence cyclically by weights. Allows part weights to be just less than specified:

>>> for item in abjad.sequence.partition_by_weights(
...     sequence,
...     [10, 5],
...     cyclic=True,
...     overhang=False,
...     allow_part_weights=abjad.LESS,
... ):
...     item
... 
[3, 3, 3]
[3]
[4, 4]
[4]
[4, 5]
[5]

Partitions sequence cyclically by weights. Allows part weights to be just less than specified. Allows overhang:

>>> for item in abjad.sequence.partition_by_weights(
...     sequence,
...     [10, 5],
...     cyclic=True,
...     overhang=True,
...     allow_part_weights=abjad.LESS,
... ):
...     item
... 
[3, 3, 3]
[3]
[4, 4]
[4]
[4, 5]
[5]

>>> sequence = list([3, 3, 3, 3, 4, 4, 4, 4, 5, 5])

Partitions sequence once by weights. Allow part weights to be just more than specified:

>>> for item in abjad.sequence.partition_by_weights(
...     sequence,
...     [10, 4],
...     cyclic=False,
...     overhang=False,
...     allow_part_weights=abjad.MORE,
... ):
...     item
... 
[3, 3, 3, 3]
[4]

Partitions sequence once by weights. Allows part weights to be just more than specified. Allows overhang:

>>> for item in abjad.sequence.partition_by_weights(
...     sequence,
...     [10, 4],
...     cyclic=False,
...     overhang=True,
...     allow_part_weights=abjad.MORE,
... ):
...     item
... 
[3, 3, 3, 3]
[4]
[4, 4, 4, 5, 5]

Partitions sequence cyclically by weights. Allows part weights to be just more than specified:

>>> for item in abjad.sequence.partition_by_weights(
...     sequence,
...     [10, 4],
...     cyclic=True,
...     overhang=False,
...     allow_part_weights=abjad.MORE,
... ):
...     item
... 
[3, 3, 3, 3]
[4]
[4, 4, 4]
[5]

Partitions sequence cyclically by weights. Allows part weights to be just more than specified. Allows overhang:

>>> for item in abjad.sequence.partition_by_weights(
...     sequence,
...     [10, 4],
...     cyclic=True,
...     overhang=True,
...     allow_part_weights=abjad.MORE,
... ):
...     item
... 
[3, 3, 3, 3]
[4]
[4, 4, 4]
[5]
[5]

Returns list of sequence types.

abjad.sequence.permute(sequence, permutation)

Permutes sequence by permutation.

>>> abjad.sequence.permute([10, 11, 12, 13, 14, 15], [5, 4, 0, 1, 2, 3])
[15, 14, 10, 11, 12, 13]

>>> abjad.sequence.permute([11, 12, 13, 14], [1, 0, 3, 2])
[12, 11, 14, 13]

Raises exception when lengths do not match:

>>> abjad.sequence.permute([1, 2, 3, 4, 5, 6], [3, 0, 1, 2])
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/Users/trevor/abjad/abjad/sequence.py", line 1775, in permute
    raise ValueError(message)
ValueError: permutation [3, 0, 1, 2] must match length of [1, 2, 3, 4, 5, 6].

Returns sequence type.

abjad.sequence.remove(sequence, pattern)

Removes sequence items at indices specified by pattern.

>>> sequence = list(range(15))

>>> abjad.sequence.remove(sequence, abjad.index([2, 3]))
[0, 1, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14]

Removes elements and indices -2 and -3:

>>> abjad.sequence.remove(sequence, abjad.index([-2, -3]))
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 14]

>>> abjad.sequence.remove(sequence, abjad.index([2, 3], 4))
[0, 1, 4, 5, 8, 9, 12, 13]

>>> abjad.sequence.remove(sequence, abjad.index([-2, -3], 4))
[2, 3, 6, 7, 10, 11, 14]

>>> abjad.sequence.remove(sequence, abjad.index([]))
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14]

>>> abjad.sequence.remove(sequence, abjad.index([97, 98, 99]))
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14]

Removes no elements:

>>> abjad.sequence.remove(sequence, abjad.index([-97, -98, -99]))
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14]

Returns sequence type.

abjad.sequence.remove_repeats(sequence)

Removes repeats from sequence.

>>> abjad.sequence.remove_repeats([31, 31, 35, 35, 31, 31, 31, 31, 35])
[31, 35, 31, 35]

Returns sequence type.

abjad.sequence.repeat(sequence, n=1)

Repeats sequence, to a total of n copies.

>>> abjad.sequence.repeat([1, 2, 3], n=0)
[]

>>> abjad.sequence.repeat([1, 2, 3], n=1)
[[1, 2, 3]]

>>> abjad.sequence.repeat([1, 2, 3], n=2)
[[1, 2, 3], [1, 2, 3]]

Returns list of sequence types.

Return type:

list

abjad.sequence.repeat_to_length(sequence, length=0, *, start=0)

Repeats sequence to length.

Repeats list to length 11:

>>> abjad.sequence.repeat_to_length([0, 1, 2, 3, 4], 11)
[0, 1, 2, 3, 4, 0, 1, 2, 3, 4, 0]

>>> abjad.sequence.repeat_to_length([0, 1, 2, 3, 4], 11, start=2)
[2, 3, 4, 0, 1, 2, 3, 4, 0, 1, 2]

>>> abjad.sequence.repeat_to_length([0, -1, -2, -3, -4], 11)
[0, -1, -2, -3, -4, 0, -1, -2, -3, -4, 0]

>>> abjad.sequence.repeat_to_length([0, -1, -2, -3, -4], 0)
[]

>>> abjad.sequence.repeat_to_length([1, 2, 3], 10, start=100)
[2, 3, 1, 2, 3, 1, 2, 3, 1, 2]

Returns sequence type.

abjad.sequence.repeat_to_weight(sequence, weight, *, allow_total=Comparison.EXACT)

Repeats sequence to weight.

Repeats sequence to weight of 23 exactly:

>>> abjad.sequence.repeat_to_weight([5, -5, -5], 23)
[5, -5, -5, 5, -3]

Repeats sequence to weight of 23 more:

>>> abjad.sequence.repeat_to_weight([5, -5, -5], 23, allow_total=abjad.MORE)
[5, -5, -5, 5, -5]

Repeats sequence to weight of 23 or less:

>>> abjad.sequence.repeat_to_weight([5, -5, -5], 23, allow_total=abjad.LESS)
[5, -5, -5, 5]

>>> sequence = [abjad.Duration(3, 16)]
>>> weight = abjad.Duration(5, 4)
>>> sequence = abjad.sequence.repeat_to_weight(sequence, weight)
>>> sum(sequence)
Duration(5, 4)

>>> [abjad.duration.with_denominator(_, 16) for _ in sequence]
[(3, 16), (3, 16), (3, 16), (3, 16), (3, 16), (3, 16), (2, 16)]

Returns sequence type.

abjad.sequence.replace(sequence, old, new)

Replaces every old-valued item in sequence with new.

>>> sequence = [0, 2, 3, 0, 2, 3, 0, 2, 3]
>>> abjad.sequence.replace(sequence, 0, 1)
[1, 2, 3, 1, 2, 3, 1, 2, 3]

Returns sequence type.

abjad.sequence.replace_at(sequence, indices, new_material)

Replaces items at indices with new_material.

Replaces items at indices 0, 2, 4, 6:

>>> sequence = list(range(16))
>>> abjad.sequence.replace_at(
...     sequence,
...     ([0], 2),
...     (["A", "B", "C", "D"], None),
... )
['A', 1, 'B', 3, 'C', 5, 'D', 7, 8, 9, 10, 11, 12, 13, 14, 15]

Replaces elements at indices 0, 1, 8, 13:

>>> sequence = list(range(16))
>>> abjad.sequence.replace_at(
...     sequence,
...     ([0, 1, 8, 13], None),
...     (["A", "B", "C", "D"], None),
... )
['A', 'B', 2, 3, 4, 5, 6, 7, 'C', 9, 10, 11, 12, 'D', 14, 15]

Replaces every item at even index:

>>> sequence = list(range(16))
>>> abjad.sequence.replace_at(
...     sequence,
...     ([0], 2),
...     (["*"], 1),
... )
['*', 1, '*', 3, '*', 5, '*', 7, '*', 9, '*', 11, '*', 13, '*', 15]

Replaces every element at an index congruent to 0 (mod 6) with 'A'; replaces every element at an index congruent to 2 (mod 6) with 'B':

>>> sequence = list(range(16))
>>> abjad.sequence.replace_at(
...     sequence,
...     ([0], 2),
...     (["A", "B"], 3),
... )
['A', 1, 'B', 3, 4, 5, 'A', 7, 'B', 9, 10, 11, 'A', 13, 'B', 15]

Returns sequence type.

abjad.sequence.retain_pattern(sequence, pattern)

Retains sequence items at indices matching pattern.

>>> sequence = list(range(10))

>>> abjad.sequence.retain_pattern(sequence, abjad.index_all())
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]

>>> abjad.sequence.retain_pattern(sequence, abjad.index([2, 3]))
[2, 3]

>>> abjad.sequence.retain_pattern(sequence, abjad.index([-2, -3]))
[7, 8]

>>> abjad.sequence.retain_pattern(sequence, abjad.index([2, 3], 4))
[2, 3, 6, 7]

>>> abjad.sequence.retain_pattern(sequence, abjad.index([-2, -3], 4))
[0, 3, 4, 7, 8]

>>> abjad.sequence.retain_pattern(sequence, abjad.index([97, 98, 99]))
[]

>>> abjad.sequence.retain_pattern(sequence, abjad.index([-97, -98, -99]))
[]

Returns sequence type.

abjad.sequence.reverse(sequence, *, recurse=False)

Reverses sequence.

Reverses sequence:

>>> sequence = [[1, 2], 3, [4, 5]]

>>> abjad.sequence.reverse(sequence)
[[4, 5], 3, [1, 2]]

Reverses recursively:

>>> segment_1 = abjad.PitchClassSegment([1, 2])
>>> pitch = abjad.NumberedPitch(3)
>>> segment_2 = abjad.PitchClassSegment([4, 5])
>>> sequence = list([segment_1, pitch, segment_2])

>>> for item in abjad.sequence.reverse(sequence, recurse=True):
...     item
... 
PitchClassSegment([5, 4])
NumberedPitch(3)
PitchClassSegment([2, 1])

Returns sequence type.

abjad.sequence.rotate(sequence, n=0)

Rotates sequence by index n.

Rotates sequence to the right:

>>> sequence = list(range(10))

>>> abjad.sequence.rotate(sequence, n=4)
[6, 7, 8, 9, 0, 1, 2, 3, 4, 5]

Rotates sequence to the left:

>>> sequence = list(range(10))

>>> abjad.sequence.rotate(sequence, n=-3)
[3, 4, 5, 6, 7, 8, 9, 0, 1, 2]

Rotates sequence to neither the right nor the left:

>>> sequence = list(range(10))

>>> abjad.sequence.rotate(sequence, n=0)
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]

Returns sequence type.

abjad.sequence.split(sequence, weights, *, cyclic=False, overhang=False)

Splits sequence by weights.

Splits sequence cyclically by weights with overhang:

>>> sequence = list([10, -10, 10, -10])

>>> for part in abjad.sequence.split(
...     sequence,
...     (3, 15, 3),
...     cyclic=True,
...     overhang=True,
... ):
...     part
... 
[3]
[7, -8]
[-2, 1]
[3]
[6, -9]
[-1]

Splits sequence once by weights with overhang:

>>> for part in abjad.sequence.split(
...     sequence,
...     (3, 15, 3),
...     cyclic=False,
...     overhang=True,
... ):
...     part
... 
[3]
[7, -8]
[-2, 1]
[9, -10]

Splits sequence once by weights without overhang:

>>> for part in abjad.sequence.split(
...     sequence,
...     (3, 15, 3),
...     cyclic=False,
...     overhang=False,
... ):
...     part
... 
[3]
[7, -8]
[-2, 1]

REGRESSION. Splits sequence of durations cyclically by weights with overhang; then expresses durations as pairs with denominator:

>>> sequence = list(
...     [
...         abjad.Duration(20, 2),
...         abjad.Duration(-20, 2),
...         abjad.Duration(20, 2),
...         abjad.Duration(-20, 2),
...     ]
... )

>>> for part in abjad.sequence.split(
...     sequence,
...     (3, 15, 3),
...     cyclic=True,
...     overhang=True,
... ):
...     [abjad.duration.with_denominator(_, 2) for _ in part]
... 
[(6, 2)]
[(14, 2), (-16, 2)]
[(-4, 2), (2, 2)]
[(6, 2)]
[(12, 2), (-18, 2)]
[(-2, 2)]

Returns list of sequence types.

Return type:

list

abjad.sequence.sum_by_sign(sequence, *, sign=(-1, 0, 1))

Sums consecutive sequence items by sign.

>>> sequence = [0, 0, -1, -1, 2, 3, -5, 1, 2, 5, -5, -6]

>>> abjad.sequence.sum_by_sign(sequence)
[0, -2, 5, -5, 8, -11]

>>> abjad.sequence.sum_by_sign(sequence, sign=[-1])
[0, 0, -2, 2, 3, -5, 1, 2, 5, -11]

>>> abjad.sequence.sum_by_sign(sequence, sign=[0])
[0, -1, -1, 2, 3, -5, 1, 2, 5, -5, -6]

>>> abjad.sequence.sum_by_sign(sequence, sign=[1])
[0, 0, -1, -1, 5, -5, 8, -5, -6]

>>> abjad.sequence.sum_by_sign(sequence, sign=[-1, 0])
[0, -2, 2, 3, -5, 1, 2, 5, -11]

>>> abjad.sequence.sum_by_sign(sequence, sign=[-1, 1])
[0, 0, -2, 5, -5, 8, -11]

>>> abjad.sequence.sum_by_sign(sequence, sign=[0, 1])
[0, -1, -1, 5, -5, 8, -5, -6]

>>> abjad.sequence.sum_by_sign(sequence, sign=[-1, 0, 1])
[0, -2, 5, -5, 8, -11]

Sums consecutive negative elements when -1 in sign.

Sums consecutive zero-valued elements when 0 in sign.

Sums consecutive positive elements when 1 in sign.

Returns sequence type.

abjad.sequence.truncate(sequence, *, sum_=None, weight=None)

Truncates sequence.

>>> sequence = [-1, 2, -3, 4, -5, 6, -7, 8, -9, 10]

Truncates sequence to weights ranging from 1 to 10:

>>> for weight in range(1, 11):
...     result = abjad.sequence.truncate(sequence, weight=weight)
...     print(weight, result)
... 
1 [-1]
2 [-1, 1]
3 [-1, 2]
4 [-1, 2, -1]
5 [-1, 2, -2]
6 [-1, 2, -3]
7 [-1, 2, -3, 1]
8 [-1, 2, -3, 2]
9 [-1, 2, -3, 3]
10 [-1, 2, -3, 4]

Truncates sequence to sums ranging from 1 to 10:

>>> for sum_ in range(1, 11):
...     result = abjad.sequence.truncate(sequence, sum_=sum_)
...     print(sum_, result)
... 
1 [-1, 2]
2 [-1, 2, -3, 4]
3 [-1, 2, -3, 4, -5, 6]
4 [-1, 2, -3, 4, -5, 6, -7, 8]
5 [-1, 2, -3, 4, -5, 6, -7, 8, -9, 10]
6 [-1, 2, -3, 4, -5, 6, -7, 8, -9, 10]
7 [-1, 2, -3, 4, -5, 6, -7, 8, -9, 10]
8 [-1, 2, -3, 4, -5, 6, -7, 8, -9, 10]
9 [-1, 2, -3, 4, -5, 6, -7, 8, -9, 10]
10 [-1, 2, -3, 4, -5, 6, -7, 8, -9, 10]

Truncates sequence to zero weight:

>>> abjad.sequence.truncate(sequence, weight=0)
[]

Truncates sequence to zero sum:

>>> abjad.sequence.truncate(sequence, sum_=0)
[]

Ignores sum when weight and sum are both set.

Raises value error on negative sum.

Returns sequence type.

abjad.sequence.weight(sequence)

Gets weight of sequence.

>>> abjad.sequence.weight([])
0

>>> abjad.sequence.weight([1])
1

>>> abjad.sequence.weight([1, 2, 3])
6

>>> abjad.sequence.weight([1, 2, -3])
6

>>> abjad.sequence.weight([-1, -2, -3])
6

>>> abjad.sequence.weight([-1, 2, -3, 4, -5, 6, -7, 8, -9, 10])
55

>>> abjad.sequence.weight([[1, -7, -7], [1, -8 - 8]])
32

Return type:

Any

abjad.sequence.zip(sequences, *, cyclic=False, truncate=True)

Zips sequences.

Zips cyclically:

>>> sequence = [[1, 2, 3], ["a", "b"]]
>>> for item in abjad.sequence.zip(sequence, cyclic=True):
...     item
... 
(1, 'a')
(2, 'b')
(3, 'a')

>>> sequence = [[10, 11, 12], [20, 21], [30, 31, 32, 33]]
>>> for item in abjad.sequence.zip(sequence, cyclic=True):
...     item
... 
(10, 20, 30)
(11, 21, 31)
(12, 20, 32)
(10, 21, 33)

Zips without truncation:

>>> sequence = [[1, 2, 3, 4], [11, 12, 13], [21, 22, 23]]
>>> for item in abjad.sequence.zip(sequence, truncate=False):
...     item
... 
(1, 11, 21)
(2, 12, 22)
(3, 13, 23)
(4,)

Zips strictly:

>>> sequences = [[1, 2, 3, 4], [11, 12, 13], [21, 22, 23]]
>>> for triple in abjad.sequence.zip(sequences):
...     triple
... 
(1, 11, 21)
(2, 12, 22)
(3, 13, 23)

Returns list of tuples.

Return type:

list[tuple]