Core¶

Introduction¶

This module provides the base class _Set for manipulating musical numeric sequences, integrating vectorial operations through NumPy. It serves as the foundation for more specialized classes in the library, enabling efficient and readable data transformation pipelines for musical data.

_Set Class¶

The core module provides the base class _Set for manipulating musical numeric sequences, integrating vectorial operations through NumPy. The class accepts NumPy arrays, Python lists, or other _Set objects as input. Operations can be chained to create efficient and readable data transformation pipelines for musical data. The class supports arithmetic operations, mathematical transformations, structural manipulations, and logical filters, all optimized for music processing. Most of these operations return new _Set objects, allowing the original objects to remain unchanged and facilitating work with complex musical sequences. In some cases, as documented, operations can be performed in-place to improve performance.

from musicnpy import _Set

s = _Set([0, 2, 4, 5, 7, 9, 11], 60)

print(s.values)

Lifecycle & Setup¶

Initialization and basic methods for resetting, copying, and representing the _Set object.

_Set.__init__(values: Sequence[Real], offset: Real = 0) → None¶

Initialize a _Set with a list of numeric values.

Creates a new _Set instance containing numeric values with an optional offset applied to all elements.

Parameters:

values (ArrayLike) – List of numeric values to initialize the set with.
offset (Numeric) – Value to add to all elements. Defaults to 0.

Example:

>>> s = _Set([1, 2, 3], offset=10)
>>> s.values
[11.0, 12.0, 13.0]

_Set.reset¶

Reset values to their original state.

Restores the working values to match the original values stored at initialization.

Returns:: This set instance with values reset.
Return type:: Self
Example:

>>> s = _Set([1, 2, 3])
>>> s += 10
>>> s.reset.values
[1.0, 2.0, 3.0]

_Set.copy¶

Create a deep copy of this set.

Returns a new _Set instance with copies of all internal arrays, ensuring modifications to the copy do not affect the original.

Returns:: A new independent copy of this set.
Return type:: _Set
Example:

>>> s = _Set([1, 2, 3])
>>> s_copy = s.copy
>>> s_copy += 10
>>> s.values
[1.0, 2.0, 3.0]

_Set.__repr__() → str¶

Return a string representation of the set.

Returns:: String in the format ClassName = [values].
Return type:: str
Example:

>>> s = _Set([1, 2, 3])
>>> repr(s)
'_Set = [1.0, 2.0, 3.0]'

Getters & Properties¶

These properties and methods allow access to various attributes of the _Set object, such as its values, original input, deltas between values, median, odd and even indexed values, and more.

_Set.values¶

Retrieve the current values as a list.

Returns the working copy of values, which may have been modified since initialization.

Returns:: List of current values in the set.
Return type:: list[Numeric]
Example:

>>> s = _Set([1, 2, 3])
>>> s.values
[1.0, 2.0, 3.0]

_Set.original¶

Retrieve the original unmodified values.

Returns the values as they were at initialization (with offset applied), regardless of any subsequent modifications.

Returns:: List of original values.
Return type:: list[Numeric]
Example:

>>> s = _Set([1, 2, 3])
>>> s += 10
>>> s.original
[1.0, 2.0, 3.0]

_Set.deltas¶

Compute the differences between consecutive elements.

Returns:: List of differences between each pair of consecutive elements.
Return type:: list[Numeric]
Example:

>>> s = _Set([1, 3, 6, 10])
>>> s.deltas
[2.0, 3.0, 4.0]

_Set.mean¶

Compute the mean value of the set.

For sets with an even number of elements, returns the average of the two middle values.

Returns:: The median value.
Return type:: Numeric
Example:

>>> s = _Set([1, 3, 5, 7, 9])
>>> s.mean
5.0

_Set.odd¶

Retrieve all odd-valued elements from the set.

Returns:: List containing only elements with odd values.
Return type:: list[Numeric]
Example:

>>> s = _Set([1, 2, 3, 4, 5])
>>> s.odd
[1.0, 3.0, 5.0]

_Set.even¶

Retrieve all even-valued elements from the set.

Returns:: List containing only elements with even values.
Return type:: list[Numeric]
Example:

>>> s = _Set([1, 2, 3, 4, 5])
>>> s.even
[2.0, 4.0]

_Set.profile¶

Get the profile of the set as sign changes of consecutive differences.

Returns a list of signs (+1, 0, -1) indicating whether each consecutive pair of values is ascending, flat, or descending.

Returns:: List of signs representing the contour shape.
Return type:: list
Example:

>>> s = _Set([1, 3, 2, 5, 4])
>>> s.profile
[1.0, -1.0, 1.0, -1.0]

_Set.__len__() → int¶

Return the number of elements in the set.

Returns:: Number of elements.
Return type:: int
Example:

>>> s = _Set([1, 2, 3, 4, 5])
>>> len(s)
5

_Set.getitems(idx: Sequence[Real] = None) → list¶

Retrieve items from the set by their indices.

Supports nested lists of indices for flexible retrieval.

Parameters:: idx (ArrayLike) – List of indices (may contain nested lists).
Returns:: List of values at the specified indices.
Return type:: list
Raises:: TypeError – If idx is not a list or contains invalid types.
Example:

>>> s = _Set([10, 20, 30, 40, 50])
>>> s.getitems([0, 2, 4])
[10.0, 30.0, 50.0]

_Set.getids(items: list = None) → list¶

Find indices of specified values in the set.

Parameters:: items (list) – List of values to search for.
Returns:: List of lists, each containing indices where the corresponding item was found.
Return type:: list[list[int]]
Raises:: ValueError – If items is not a list.
Example:

>>> s = _Set([10, 20, 30, 20, 40])
>>> s.getids([20, 40])
[[1, 3], [4]]

_Set.__getitem__(key: int | slice | Sequence[int]) → Real¶

Retrieve element(s) by index using bracket notation.

Parameters:: key (Index) – Index, slice, or sequence of indices.
Returns:: The element or list of elements at the specified position(s).
Return type:: Numeric | list[Numeric]
Raises:: TypeError – If key type is not supported.
Example:

>>> s = _Set([10, 20, 30, 40, 50])
>>> s[0]
10.0

_Set.__setitem__(key: int | slice | Sequence[int], value: Sequence[Real] | Real) → Self¶

Set element(s) by index using bracket notation.

Parameters:

key (Index) – Index or slice to modify.
value (ArrayLike | Numeric) – New value(s) to assign.

Returns:

This set with updated values.

Return type:

Self

Raises:

TypeError – If key type is not supported.

Example:

>>> s = _Set([1, 2, 3, 4, 5])
>>> s[0] = 10
>>> s.values
[10.0, 2.0, 3.0, 4.0, 5.0]

Arithmetic Operations¶

All arithmetic operations support scalars (single numbers) or sequences (lists, arrays or other _Set).

Operations can be performed between _Set of different lengths; in this case, internally the sets are aligned to the length of the larger one. Additional elements are filled with zeros for addition and subtraction, and with one for multiplication, division, power and modulo.

_Set.__add__(other: Sequence[Real] | Real) → Self¶

Add values element-wise using the + operator.

Parameters:: other (ArrayLike | Numeric) – Values to add (set, sequence, or scalar).
Returns:: A new set with the sum of values.
Return type:: Self
Example:

>>> s = _Set([1, 2, 3])
>>> (s + 10).values
[11.0, 12.0, 13.0]

_Set.__iadd__(other: Sequence[Real] | Real) → Self¶

Add values in-place using the += operator.

Parameters:: other (ArrayLike | Numeric) – Values to add (set, sequence, or scalar).
Returns:: This set with updated values.
Return type:: Self
Example:

>>> s = _Set([1, 2, 3])
>>> s += 5
>>> s.values
[6.0, 7.0, 8.0]

_Set.__radd__(other: Sequence[Real] | Real) → Self¶

Add values with reversed operand order using the + operator.

Parameters:: other (ArrayLike | Numeric) – Values to add (set, sequence, or scalar).
Returns:: A new set with the sum of values.
Return type:: _Set
Example:

>>> s = _Set([1, 2, 3])
>>> (10 + s).values
[11.0, 12.0, 13.0]

_Set.__sub__(other: Sequence[Real] | Real) → Self¶

Subtract values element-wise using the - operator.

Parameters:: other (ArrayLike | Numeric) – Values to subtract (set, sequence, or scalar).
Returns:: A new set with the difference of values.
Return type:: _Set
Example:

>>> s = _Set([10, 20, 30])
>>> (s - 5).values
[5.0, 15.0, 25.0]

_Set.__isub__(other: Sequence[Real] | Real) → Self¶

Subtract values in-place using the -= operator.

Parameters:: other (ArrayLike | Numeric) – Values to subtract (set, sequence, or scalar).
Returns:: This set with updated values.
Return type:: Self
Example:

>>> s = _Set([10, 20, 30])
>>> s -= 5
>>> s.values
[5.0, 15.0, 25.0]

_Set.__rsub__(other: Sequence[Real] | Real) → Self¶

Subtract with reversed operand order using the - operator.

Parameters:: other (ArrayLike | Numeric) – Value to subtract from (set, sequence, or scalar).
Returns:: A new set with the difference of values.
Return type:: _Set
Example:

>>> s = _Set([1, 2, 3])
>>> (10 - s).values
[9.0, 8.0, 7.0]

_Set.__mul__(other: Sequence[Real] | Real) → Self¶

Multiply values element-wise using the * operator.

Parameters:: other (ArrayLike | Numeric) – Values to multiply by (set, sequence, or scalar).
Returns:: A new set with the product of values.
Return type:: _Set
Example:

>>> s = _Set([1, 2, 3])
>>> (s * 10).values
[10.0, 20.0, 30.0]

_Set.__imul__(other: Sequence[Real] | Real) → Self¶

Multiply values in-place using the *= operator.

Parameters:: other (ArrayLike | Numeric) – Values to multiply by (set, sequence, or scalar).
Returns:: This set with updated values.
Return type:: Self
Example:

>>> s = _Set([1, 2, 3])
>>> s *= 5
>>> s.values
[5.0, 10.0, 15.0]

_Set.__rmul__(other: Sequence[Real] | Real) → Self¶

Multiply with reversed operand order using the * operator.

Parameters:: other (ArrayLike | Numeric) – Values to multiply by (set, sequence, or scalar).
Returns:: A new set with the product of values.
Return type:: _Set
Example:

>>> s = _Set([1, 2, 3])
>>> (10 * s).values
[10.0, 20.0, 30.0]

_Set.__truediv__(other: Sequence[Real] | Real) → Self¶

Divide values element-wise using the / operator.

Parameters:: other (ArrayLike | Numeric) – Values to divide by (set, sequence, or scalar).
Returns:: A new set with the quotient of values.
Return type:: _Set
Example:

>>> s = _Set([10, 20, 30])
>>> (s / 2).values
[5.0, 10.0, 15.0]

_Set.__itruediv__(other: Sequence[Real] | Real) → Self¶

Divide values in-place using the /= operator.

Parameters:: other (ArrayLike | Numeric) – Values to divide by (set, sequence, or scalar).
Returns:: This set with updated values.
Return type:: Self
Example:

>>> s = _Set([10, 20, 30])
>>> s /= 2
>>> s.values
[5.0, 10.0, 15.0]

_Set.__rtruediv__(other: Sequence[Real] | Real) → Self¶

Divide with reversed operand order using the / operator.

Parameters:: other (ArrayLike | Numeric) – Value to be divided (set, sequence, or scalar).
Returns:: A new set with the quotient of values.
Return type:: _Set
Example:

>>> s = _Set([2, 4, 5])
>>> (20 / s).values
[10.0, 5.0, 4.0]

_Set.__floordiv__(other: Sequence[Real] | Real) → Self¶

Perform floor division element-wise using the // operator.

Parameters:: other (ArrayLike | Numeric) – Values to divide by (set, sequence, or scalar).
Returns:: A new set with the floor-divided values.
Return type:: _Set
Example:

>>> s = _Set([10, 20, 30])
>>> (s // 3).values
[3.0, 6.0, 10.0]

_Set.__ifloordiv__(other: Sequence[Real] | Real) → Self¶

Perform floor division in-place using the //= operator.

Parameters:: other (ArrayLike | Numeric) – Values to divide by (set, sequence, or scalar).
Returns:: This set with updated values.
Return type:: Self
Example:

>>> s = _Set([10, 20, 30])
>>> s //= 3
>>> s.values
[3.0, 6.0, 10.0]

_Set.__rfloordiv__(other: Sequence[Real] | Real) → Self¶

Perform floor division with reversed operand order using the // operator.

Parameters:: other (ArrayLike | Numeric) – Value to be divided (set, sequence, or scalar).
Returns:: A new set with the floor-divided values.
Return type:: _Set
Example:

>>> s = _Set([3, 4, 5])
>>> (20 // s).values
[6.0, 5.0, 4.0]

_Set.__pow__(other: Sequence[Real] | Real) → Self¶

Raise values to a power element-wise using the ** operator.

Parameters:: other (ArrayLike | Numeric) – Exponent values (set, sequence, or scalar).
Returns:: A new set with exponentiated values.
Return type:: _Set
Example:

>>> s = _Set([2, 3, 4])
>>> (s ** 2).values
[4.0, 9.0, 16.0]

_Set.__ipow__(other: Sequence[Real] | Real) → Self¶

Raise values to a power in-place using the **= operator.

Parameters:: other (ArrayLike | Numeric) – Exponent values (set, sequence, or scalar).
Returns:: This set with updated values.
Return type:: Self
Example:

>>> s = _Set([2, 3, 4])
>>> s **= 2
>>> s.values
[4.0, 9.0, 16.0]

_Set.__rpow__(other: Sequence[Real] | Real) → Self¶

Raise to a power with reversed operand order using the ** operator.

Parameters:: other (ArrayLike | Numeric) – Base value (set, sequence, or scalar).
Returns:: A new set with exponentiated values.
Return type:: _Set
Example:

>>> s = _Set([2, 3, 4])
>>> (2 ** s).values
[4.0, 8.0, 16.0]

_Set.__mod__(other: Sequence[Real] | Real) → Self¶

Compute modulo element-wise using the % operator.

Parameters:: other (ArrayLike | Numeric) – Divisor values (set, sequence, or scalar).
Returns:: A new set with remainder values.
Return type:: _Set
Example:

>>> s = _Set([10, 15, 20])
>>> (s % 3).values
[1.0, 0.0, 2.0]

_Set.__imod__(other: Sequence[Real] | Real) → Self¶

Compute modulo in-place using the %= operator.

Parameters:: other (ArrayLike | Numeric) – Divisor values (set, sequence, or scalar).
Returns:: This set with updated values.
Return type:: Self
Example:

>>> s = _Set([10, 15, 20])
>>> s %= 3
>>> s.values
[1.0, 0.0, 2.0]

_Set.__rmod__(other: Sequence[Real] | Real) → Self¶

Compute modulo with reversed operand order using the % operator.

Parameters:: other (ArrayLike | Numeric) – Dividend value (set, sequence, or scalar).
Returns:: A new set with remainder values.
Return type:: _Set
Example:

>>> s = _Set([3, 4, 6])
>>> (20 % s).values
[2.0, 0.0, 2.0]

_Set.__abs__() → Self¶

Compute absolute values using the built-in abs() function.

Returns:: A new set with absolute values.
Return type:: _Set
Example:

>>> s = _Set([-1, -2, 3, -4])
>>> abs(s).values
[1.0, 2.0, 3.0, 4.0]

_Set._abs() → Self¶

Compute absolute values in-place.

Returns:: This set with absolute values applied.
Return type:: Self
Example:

>>> s = _Set([-1, -2, 3, -4])
>>> s._abs().values
[1.0, 2.0, 3.0, 4.0]

_Set.__neg__() → Self¶

Negate values using the unary - operator.

Returns:: A new set with negated values.
Return type:: _Set
Example:

>>> s = _Set([1, 2, 3])
>>> (-s).values
[-1.0, -2.0, -3.0]

_Set._neg() → Self¶

Negate values in-place.

Returns:: This set with negated values.
Return type:: Self
Example:

>>> s = _Set([1, 2, 3])
>>> s._neg().values
[-1.0, -2.0, -3.0]

Mathematical Transformations¶

These methods apply various mathematical transformations to the sequence, such as transposition, shifting, scaling, limiting values, inverting, rounding, and more.

_Set.shift(other: Real) → Self¶

Shift all values by adding a constant offset.

Updates both the values and the offset attribute.

Parameters:: other (Numeric) – The amount to shift by.
Returns:: This set with shifted values.
Return type:: Self
Example:

>>> s = _Set([1, 2, 3])
>>> s.shift(10).values
[11.0, 12.0, 13.0]

_Set.scaled(min: Real = 0, max: Real = 1) → Self¶

Scale values to a specified range.

Linearly maps all values to fit within the new range [min, max].

Parameters:

min (Numeric) – The minimum of the target range. Defaults to 0.
max (Numeric) – The maximum of the target range. Defaults to 1.

Returns:

This set with scaled values.

Return type:

Self

Example:

>>> s = _Set([0, 50, 100])
>>> s.scaled(0, 10).values
[0.0, 5.0, 10.0]

_Set.limit(min: Real = 0, max: Real = 1) → Self¶

Clip values to a specified range.

Values below min become min; values above max become max.

Parameters:

min (Numeric) – The minimum allowed value. Defaults to 0.
max (Numeric) – The maximum allowed value. Defaults to 1.

Returns:

This set with clipped values.

Return type:

Self

Example:

>>> s = _Set([1, 5, 10, 15, 20])
>>> s.limit(5, 15).values
[5.0, 5.0, 10.0, 15.0, 15.0]

_Set.invert(pivot: Real = None) → Self¶

Invert values around a pivot point.

If no pivot is provided, uses the midpoint between the minimum and maximum values.

Parameters:: pivot (Numeric) – The pivot point for inversion. Defaults to None (midpoint).
Returns:: A new set with inverted values.
Return type:: _Set
Example:

>>> s = _Set([1, 2, 3, 4, 5])
>>> s.invert().values
[5.0, 4.0, 3.0, 2.0, 1.0]

_Set.__invert__() → Self¶

Invert values in-place using the ~ operator.

Inverts values around their midpoint (average of min and max).

Returns:: This set with inverted values.
Return type:: Self
Example:

>>> s = _Set([1, 2, 3, 4, 5])
>>> (~s).values
[5.0, 4.0, 3.0, 2.0, 1.0]

_Set.round(decimals: int = 1) → Self¶

Round values to a specified number of decimal places.

Uses standard rounding (round half to even).

Parameters:: decimals (int) – Number of decimal places. Defaults to 1.
Returns:: This set with rounded values.
Return type:: Self
Example:

>>> s = _Set([1.234, 2.567, 3.891])
>>> s.round(1).values
[1.2, 2.6, 3.9]

_Set.ceil() → Self¶

Round values up to the nearest integer.

Returns:: This set with ceiling values.
Return type:: Self
Example:

>>> s = _Set([1.1, 2.5, 3.9])
>>> s.ceil().values
[2.0, 3.0, 4.0]

_Set.floor() → Self¶

Round values down to the nearest integer.

Returns:: This set with floor values.
Return type:: Self
Example:

>>> s = _Set([1.1, 2.5, 3.9])
>>> s.floor().values
[1.0, 2.0, 3.0]

_Set.interpolation(other: Self = None, step: int = 0, curve: float = 1, decimals: int = 0) → tuple¶

Interpolate between this set and another set over a number of steps.

Generates intermediate values using linear interpolation with optional curve control. The curve parameter controls the interpolation curve shape.

Parameters:

other (_Set) – The target set to interpolate towards.
step (int) – Number of interpolation steps (must be > 0).
curve (float) – Exponent for curve control. Defaults to 1 (linear). Values > 1 create ease-out curves, values < 1 create ease-in curves.

Returns:

List of interpolated _Set instances.

Return type:

list[_Set]

Example:

>>> s1 = _Set([0, 5, 10])
>>> s2 = _Set([10, 15, 20])
>>> result = s1.interpolation(s2, step=3, curve=1)
>>> len(result)
3

_Set.morphing(other: _Set, mode: Literal['up', 'down', 'rand', 'chiasm']) → list[_Set]¶

Generate a sequence of sets morphing from this set to another set. Creates a list of intermediate sets by progressively replacing elements from this set with corresponding elements from the other set based on the specified mode.

Parameters:

other (_Set) – The target set to morph towards.
mode (Literal['up', 'down', 'rand', 'chiasm']) –
Morphing mode. Options are:
- 'up': Replace elements from the start to the end.
- 'down': Replace elements from the end to the start.
- 'rand': Replace elements in random order.
- 'chiasm': Replace elements from the outside towards the center.

Returns:

List of _Set instances representing the morphing sequence.

Return type:

list[_Set]

Raises:

ValueError – If the sets have different lengths or if mode is invalid.

Example:

>>> s1 = _Set([1, 2, 3])
>>> s2 = _Set([4, 5, 6])
>>> morph_sequence = s1.morphing(s2, mode='up')
>>> for i in morph_sequence: print(i.values)
[[1, 2, 3], [4, 2, 3], [4, 5, 3], [4, 5, 6]]

_Set.normalize(mix: Real = 0, max: Real = 1) → Self¶

Normalize values to a specified range.

Linearly scales all values to fit within the specified range [mix, max]. This is an in-place operation that modifies the set’s current values.

Parameters:

mix (Numeric) – The minimum of the target range. Defaults to 0.
max (Numeric) – The maximum of the target range. Defaults to 1.

Returns:

This set with normalized values.

Return type:

Self

Example:

>>> s = _Set([10, 20, 30, 40, 50])
>>> s.normalize(mix=0, max=100).values
[0.0, 25.0, 50.0, 75.0, 100.0]

Structural Manipulation¶

These methods allow for structural changes to the sequence, such as splitting, sorting, reversing, rotating, inserting, removing elements, and more.

_Set.split(*, idx: int | list[int] = None, items: float | list[float] = None, keep_separator: bool = True, split: Literal['before', 'after'] = 'after') → list[Self]¶

Split the set into multiple sets at specified positions or values.

Provide either idx or items, not both.

Parameters:

idx (int | list[int]) – Index or indices at which to split.
items (float | list[float]) – Value or values at which to split.
keep_separator (bool) – If True, keep the separator element in the resulting parts. Defaults to True.
split (Literal['before', 'after']) – Whether to split 'before' or 'after' the separator. Defaults to 'after'.

Returns:

List of _Set instances representing the split parts.

Return type:

list[_Set]

Raises:

ValueError – If neither or both idx and items are provided, or if split mode is invalid.

Example:

>>> s = _Set([1, 2, 3, 4, 5])
>>> parts = s.split(idx=2)
>>> [p.values for p in parts]
[[1.0, 2.0, 3.0], [4.0, 5.0]]

_Set.interleave(other: Sequence[Real] = [0], step: int = 1) → Self¶

Interleave elements from this set and another sequence.

Alternates chunks of step elements from each sequence.

Parameters:

other (ArrayLike) – The sequence to interleave with.
step (int) – Number of elements per chunk. Defaults to 1.

Returns:

A new set with interleaved elements.

Return type:

_Set

Raises:

ValueError – If step is not positive.

Example:

>>> s = _Set([1, 2, 3, 4])
>>> s.interleave(_Set([10, 20, 30]), step=1).values
[1.0, 10.0, 2.0, 20.0, 3.0, 30.0, 4.0]

_Set.sort(type: Literal['<', '>', 'r'] = '<') → Self¶

Sort elements in the specified order.

Parameters:

type (str) –

Sort order. Options are:

'<': Ascending order.
'>': Descending order.
'r': Random shuffle.

Defaults to '<'.

Returns:

This set with sorted elements.

Return type:

Self

Raises:

ValueError – If type is not '<', '>', or 'r'.

Example:

>>> s = _Set([3, 1, 4, 1, 5])
>>> s.sort('<').values
[1.0, 1.0, 3.0, 4.0, 5.0]

_Set.reverse() → Self¶

Reverse the order of elements in-place.

Returns:: This set with elements in reversed order.
Return type:: Self
Example:

>>> s = _Set([1, 2, 3, 4, 5])
>>> s.reverse().values
[5.0, 4.0, 3.0, 2.0, 1.0]

_Set.rotate(n: int = 0) → Self¶

Rotate elements by n positions.

Positive values rotate right; negative values rotate left. Elements that overflow wrap around.

Parameters:: n (int) – Number of positions to rotate.
Returns:: This set with rotated elements.
Return type:: Self
Example:

>>> s = _Set([1, 2, 3, 4, 5])
>>> s.rotate(2).values
[4.0, 5.0, 1.0, 2.0, 3.0]

_Set.insert(pos: int = 0, other: Sequence[Real] | Real = 0) → Self¶

Insert element(s) at a specific position.

Parameters:

pos (int) – Index position for insertion. Defaults to 0.
other (ArrayLike | Numeric) – Element(s) to insert.

Returns:

This set with inserted elements.

Return type:

Self

Example:

>>> s = _Set([1, 2, 3])
>>> s.insert(1, 10).values
[1.0, 10.0, 2.0, 3.0]

_Set.remove(idx: int | Sequence[Real] = None, item: Real | Sequence[Real] = None) → Self¶

Remove elements by index or by value.

Provide either idx or item, not both.

Parameters:

idx (int | ArrayLike) – Index or indices of elements to remove. Defaults to None.
item (Numeric | ArrayLike) – Value or values of elements to remove. Defaults to None.

Returns:

This set with elements removed.

Return type:

Self

Example:

>>> s = _Set([1, 2, 3, 4, 5])
>>> s.remove(idx=2).values
[1.0, 2.0, 4.0, 5.0]

_Set.unique(mode: Literal['normal', 'unique', 'consecutive'] = 'normal') → Self¶

Remove duplicate elements based on the specified mode.

Parameters:

mode (Literal['normal', 'unique', 'consecutive']) –

Deduplication mode. Options are:

'normal': Keep first occurrence of each value.
'unique': Keep only values that appear exactly once.
'consecutive': Remove consecutive duplicates only.

Defaults to 'normal'.

Returns:

This set with duplicates removed.

Return type:

Self

Example:

>>> s = _Set([1, 2, 2, 3, 3, 3, 4])
>>> s.unique('normal').values
[1.0, 2.0, 3.0, 4.0]

_Set.append(other: Sequence[Real] | Real = 0) → Self¶

Append element(s) to the end of the set.

Parameters:: other (ArrayLike | Numeric) – Element(s) to append.
Returns:: This set with appended elements.
Return type:: Self
Example:

>>> s = _Set([1, 2, 3])
>>> s.append(4).values
[1.0, 2.0, 3.0, 4.0]

_Set.repeat(n: int = 0) → Self¶

Repeat the set n times in-place.

Parameters:: n (int) – Number of repetitions.
Returns:: This set with repeated elements.
Return type:: Self
Raises:: ValueError – If n is negative.
Example:

>>> s = _Set([1, 2])
>>> s.repeat(3).values
[1.0, 2.0, 1.0, 2.0, 1.0, 2.0]

_Set.__lshift__(n: int = 0) → Self¶

Repeat the set n times using the << operator.

Parameters:: n (int) – Number of repetitions.
Returns:: A new set with repeated elements.
Return type:: _Set
Raises:: ValueError – If n is negative.
Example:

>>> s = _Set([1, 2, 3])
>>> (s << 2).values
[1.0, 2.0, 3.0, 1.0, 2.0, 3.0]

_Set.__ilshift__(n: int = 0) → Self¶

Repeat the set n times in-place using the <<= operator.

Parameters:

n (int) – Number of repetitions.

Returns:

This set with repeated elements.

Return type:

Self

Raises:

ValueError – If n is negative.
TypeError – If n is not an integer.

Example:

>>> s = _Set([1, 2])
>>> s <<= 2
>>> s.values
[1.0, 2.0, 1.0, 2.0]

_Set.concat(other: Sequence[Real] | Real = 0) → Self¶

Concatenate this set with another sequence or value in-place.

Parameters:: other (ArrayLike | Numeric) – Sequence or value to append.
Returns:: This set with concatenated elements.
Return type:: Self
Example:

>>> s = _Set([1, 2, 3])
>>> s.concat([4, 5]).values
[1.0, 2.0, 3.0, 4.0, 5.0]

_Set.__or__(other: Sequence[Real] | Real = 0) → Self¶

Concatenate with another sequence using the | operator.

Parameters:: other (ArrayLike | Numeric) – Sequence or value to concatenate.
Returns:: A new set with concatenated elements.
Return type:: _Set
Example:

>>> s = _Set([1, 2, 3])
>>> (s | [4, 5]).values
[1.0, 2.0, 3.0, 4.0, 5.0]

_Set.__ior__(other: Sequence[Real] | Real = 0) → Self¶

Concatenate in-place using the |= operator.

Parameters:: other (ArrayLike | Numeric) – Sequence or value to concatenate.
Returns:: This set with concatenated elements.
Return type:: Self
Example:

>>> s = _Set([1, 2, 3])
>>> s |= [4, 5]
>>> s.values
[1.0, 2.0, 3.0, 4.0, 5.0]

Logic, Filters and Sequences¶

These methods allow for logical operations, filtering based on conditions, and retrieving sequences of values.

_Set.filter(condition: list | str, fill=None) → Self¶

Filter elements based on a condition.

Parameters:

condition (np.ndarray | list | str | callable) –
The filtering condition. Can be:
- A boolean array or list.
- A string expression using x for values.
- A callable returning a boolean array.
fill (Numeric) – Value to replace non-matching elements. If None, non-matching elements are removed. Defaults to None.

Returns:

This set with filtered elements.

Return type:

Self

Example:

>>> s = _Set([1, 2, 3, 4, 5, 6])
>>> s.filter('x > 3').values
[4.0, 5.0, 6.0]

_Set.getseq(*, length: int = 2, type: Literal[None, 'wrap', 'fold', 'clip', 'rand', 'randnd'] = None, idx: tuple = None) → Self¶

Generate a sequence of values using various indexing modes.

Parameters:

length (int) – Length of the sequence to generate. Defaults to 2.
type (str) –
Generation mode. Options are:
- None: Random selection with replacement.
- 'wrap': Cycle through indices.
- 'fold': Bounce back and forth.
- 'clip': Clamp indices to range.
- 'rand': Random with replacement.
- 'randnd': Random without replacement.
Defaults to None.
idx (tuple) – Index range [start, end]. Defaults to None (full range).

Returns:

List of generated values.

Return type:

list

Example:

>>> s = _Set([10, 20, 30, 40, 50])
>>> s.getseq(length=6, type='wrap', idx=[0, 2])
[10.0, 20.0, 30.0, 10.0, 20.0, 30.0]

_Set.__iter__() → Iterator[Real]¶

Return an iterator over the set’s elements.

Returns:: Iterator yielding each element in order.
Return type:: Iterator[Numeric]
Example:

>>> s = _Set([1, 2, 3])
>>> list(s)
[1.0, 2.0, 3.0]

Generators¶

These class methods allow for generating _Set objects with random or specific values.

classmethod _Set.rand_int(size: int = 1, min: int = 0, max: int = 12, unique: bool = True) → Self¶

Create a set with random integer values.

Generates random integers within the specified range with optional uniqueness constraint.

Parameters:

size (int) – Number of random integers to generate. Defaults to 1.
min (int) – Minimum value (inclusive). Defaults to 0.
max (int) – Maximum value (exclusive). Defaults to 12.
unique (bool) – If True, all values are unique. Defaults to True.

Returns:

A new set with random integer values.

Return type:

_Set

Example:

>>> s = _Set.rand_int(size=5, min=1, max=10, unique=True)
>>> len(s)
5

classmethod _Set.rand_flt(size: int = 1, min: float = 0, max: float = 12, decimals: int = 2) → Self¶

Create a set with random floating-point values.

Generates random floats within the specified range with a specified decimal precision.

Parameters:

size (int) – Number of random floats to generate. Defaults to 1.
min (float) – Minimum value. Defaults to 0.
max (float) – Maximum value. Defaults to 12.
decimals (int) – Number of decimal places. Defaults to 2.

Returns:

A new set with random float values.

Return type:

_Set

Example:

>>> s = _Set.rand_flt(size=3, min=0, max=10, decimals=2)
>>> len(s)
3

classmethod _Set.n_time(item: Real | list[Real] = 0, size: int = 1) → Self¶

Create a set by repeating an item multiple times.

Tiles (repeats) a numeric value or sequence of values a specified number of times to create a new set.

Parameters:

item (Numeric | list[Numeric]) – A numeric value or list of numeric values to repeat. Defaults to 0.
size (int) – Number of times to repeat the item. Defaults to 1.

Returns:

A new set with repeated values.

Return type:

_Set

Example:

>>> s = _Set.n_time([1, 2], size=3)
>>> s.values
[1.0, 2.0, 1.0, 2.0, 1.0, 2.0]

Internal Methods¶

These methods are used internally by the class and are not typically called directly.

_Set._align(other: Sequence[Real] | Real, fill: Real) → tuple[ndarray, ndarray]¶

Align two arrays to the same length by padding the shorter one.

Parameters:

other (ArrayLike | Numeric) – The array or set to align with.
fill (Numeric) – Value used to pad the shorter array.

Returns:

Tuple of two aligned numpy arrays of equal length.

Return type:

tuple[np.ndarray, np.ndarray]

NB use this methods only in the class!!

Example:

>>> s = _Set([1, 2, 3])
>>> a, b = s._align([4, 5], fill=0)
>>> b.tolist()
[4.0, 5.0, 0.0]

_Set._binary_op(other: Sequence[Real] | Real, op: Callable[[Any, Any], ndarray], fill: Real, reversed: bool = False) → ndarray¶

Perform a binary operation between this set and another operand.

Parameters:

other (ArrayLike | Numeric) – The right-hand operand (set, sequence, or scalar).
op (Callable[[Any, Any], np.ndarray]) – The binary operator function to apply.
fill (Numeric) – Value used to pad shorter arrays during alignment. Defaults to 0.
reversed (bool) – If True, swap operand order. Defaults to False.

Returns:

Result of the operation as a numpy array.

Return type:

np.ndarray

Raises:

TypeError – If the operand type is not supported.

NB use this methods only in the class!!

Example:

>>> s = _Set([1, 2, 3])
>>> result = s._binary_op(10, operator.add)
>>> result.tolist()
[11.0, 12.0, 13.0]

Functions¶

The core module also provides standalone functions for common operations on _Set objects.

musicnpy.core.pad(list: Sequence[Real] = None, n_pad: int = 1, item: Real = 0) → Self¶

Pad the set by adding elements at the end. :param list: The list to pad :type list: ArrayLike :param n_pad: Number of elements to add. Defaults to 1. :type n_pad: int :param item: Value to pad with. Defaults to 0. :type item: Numeric :return: This set with padded elements. :rtype: Self

Example:

>>> s = _Set([1, 2, 3])
>>> pad(s.values, 2, 0)
[1.0, 2.0, 3.0, 0.0, 0.0]