pitchtypes.spelled_array.SpelledIntervalArray

class pitchtypes.spelled_array.SpelledIntervalArray(fifths, octaves)

Bases: SpelledArray, AbstractSpelledArrayInterval, Interval, Diatonic, Chromatic

Represents an array of spelled intervals.

__init__(fifths, octaves)

Takes two numpy arrays, one for fifths and one for internal/dependent octaves, both as integers.

Parameters:

• fifths – the internal fifths of each interval (numpy array of integers)

• octaves – the internal octaves of each interval (numpy array of integers)

Methods

__init__(fifths, octaves)	Takes two numpy arrays, one for fifths and one for internal/dependent octaves, both as integers.
abs()	For downward intervals, return their upward counterpart, otherwise just return the interval itself.
alteration()	Return the number of semitones by which the interval is altered from its the perfect or major variant.
array_equal(other)	Returns True if self and other are the equal, False otherwise.
chromatic_semitone(shape)	Returns an array of the given shape filled with chromatic semitones (a1:0).
compare(other)	Element-wise comparison between two spelled arrays.
copy()	Returns a shallow copy of the array.
deepcopy()	Returns a deep copy of the array.
degree()	Return the "relative scale degree" (0-6) to which the interval points (unison=0, 2nd=1, octave=0, 2nd down=6, etc.).
diatonic_steps()	Return the diatonic steps of the interval (unison=0, 2nd=1, ..., octave=7, ...).
direction()	Returns the direction of the interval (1=up / 0=neutral / -1=down).
embed()	For interval classes, return an embedding into the interval space in a (type-dependent) default octave.
fifths()	Return the position of the interval on the line of fifths.
from_array(intervals)	Create an interval array from an array of intervals.
from_independent(fifths, octaves)	Create an interval array from fifths (interval class) and independent/external octaves.
from_onehot(onehot, fifth_low, octave_low)	Create a spelled interval array from a one-hot tensor.
from_strings(strings)	Create an interval array from an array of strings (using spelled interval notation).
generic()	Return the generic interval, i.e. the number of diatonic steps modulo octave.
ic()	Return the interval class that corresponds to this interval.
internal_octaves()	Return the internal octave representation of a pitch, which is dependent on the fifths.
is_step()	Return True if the interval is considered a step, False otherwise.
name()	Returns the names of the objects in the array as an array of strings of the same shape.
octave(shape)	Return an array of the given shape filled with perfect octaves (P1:1).
octaves()	For intervals, return the number of octaves the interval spans.
onehot(fifth_range, octave_range[, dtype])	Returns a one-hot encoding of the intervals in fifths and independent octaves as the innermost dimensions.
parse_interval(s)	Parse a string as a spelled interval or spelled interval class.
semitones()	Return the number of semitones corresponding to the interval.
steps()	Return the number of diatonic steps corresponding to the interval.
to_class()	Alias for ic(), but also supported by pitch types.
unison(shape)	Create an array of the given shape filled with perfect unisons (P1:0).

__abs__()

For downward intervals, return their upward counterpart, otherwise just return the interval itself.

__add__(other)

Returns the sum of two intervals.

__contains__(item)

Returns true if the array contains the given interval/pitch.

Parameters:

item – the potential item to test

Returns:

True if the array contains item, otherwise False

__eq__(other)

Element-wise <= between two spelled arrays.

Parameters:

other – the spelled array or scalar to compare to

Returns:

a boolean array that indicates where this array is == other

__ge__(other)

Element-wise >= between two spelled arrays.

Parameters:

other – the spelled array or scalar to compare to

Returns:

a boolean array that indicates where this array is >= other

__getitem__(index)

Returns an item or a subarray of the spelled array. Supports advanced indexing as on numpy arrays.

Parameters:

index – a numpy-compatible index into the array

Returns:

a new array or a scalar value (depending on the index)

__gt__(other)

Element-wise > between two spelled arrays.

Parameters:

other – the spelled array or scalar to compare to

Returns:

a boolean array that indicates where this array is > other

__hash__ = None

__le__(other)

Element-wise <= between two spelled arrays.

Parameters:

other – the spelled array or scalar to compare to

Returns:

a boolean array that indicates where this array is <= other

__len__()

Returns the length of the array (first dimension, as in numpy).

Returns:

the length of the array (1st dimension, integer)

__lt__(other)

Element-wise < between two spelled arrays.

Parameters:

other – the spelled array or scalar to compare to

Returns:

a boolean array that indicates where this array is < other

__mul__(other)

Returns an integer multiple of the interval.

__ne__(other)

Element-wise <= between two spelled arrays.

Parameters:

other – the spelled array or scalar to compare to

Returns:

a boolean array that indicates where this array is != other

__neg__()

Returns the inversion of the interval (same size in the other direction).

__repr__()

Return repr(self).

__rmul__(other)

Returns an integer multiple of the interval.

__setitem__(index, item)

Sets the given indices to the given item(s). Supports advanced indexing as on numpy arrays.

Parameters:

• index – a numpy-compatible index into the array

• item – an array or a scalar to assign to the indicated sub-array

__str__()

Return str(self).

__sub__(other)

Returns the difference of two intervals.

__weakref__

list of weak references to the object (if defined)

abs()

For downward intervals, return their upward counterpart, otherwise just return the interval itself.

Returns:

the absolute interval

alteration()

Return the number of semitones by which the interval is altered from its the perfect or major variant. Positive alteration always indicates augmentation, negative alteration indicates diminution (minor or smaller) of the interval’s magnitude. For interval classes, alteration refers to the upward version of the interval (e.g. for m7/-M2 it is -1). For pitches, return the accidentals (positive=sharps, negative=flats, 0=natural).

Returns:

an array of alterations (integers)

array_equal(other)

Returns True if self and other are the equal, False otherwise.

Parameters:

other – another spelled array of the same type

Returns:

True if the two arrays are equal, False otherwise

classmethod chromatic_semitone(shape)

Returns an array of the given shape filled with chromatic semitones (a1:0).

Parameters:

shape – the shape of the resulting array (tuple of integers)

Returns:

a SpelledIntervalArray of shape shape filled with a1:0

compare(other)

Element-wise comparison between two spelled arrays.

Returns 0 where the elements are equal, 1 where the first element is greater, and -1 where the second element is greater.

Spelled intervals use diatonic ordering, for example P4:0 < a4:0 < aaaa4:0 < d5:0 < P5:0.

This method can be indirectly used through binary comparison operators (including ==, < etc.). To test the overall equality of two spelled arrays, use array_equal

Parameters:

other – another SpelledIntervalArray or SpelledInterval

Returns:

an array of -1 / 0 / 1 (integer)

copy()

Returns a shallow copy of the array. This also creates copies of the underlying numpy arrays.

Returns:

a copy of the array

deepcopy()

Returns a deep copy of the array.

Returns:

a deepcopy of the array

degree()

Return the “relative scale degree” (0-6) to which the interval points (unison=0, 2nd=1, octave=0, 2nd down=6, etc.). For pitches, return the integer that corresponds to the letter (C=0, D=1, …).

Returns:

an array of degrees (integers)

diatonic_steps()

Return the diatonic steps of the interval (unison=0, 2nd=1, …, octave=7, …). Respects both direction and octaves.

Returns:

an array of diatonic steps (integers)

direction()

Returns the direction of the interval (1=up / 0=neutral / -1=down). The perfect unisons (P1:0) is considered neutral.

Returns:

an array of -1 / 0 / 1 (integer)

embed()

For interval classes, return an embedding into the interval space in a (type-dependent) default octave. For non-class intervals, return the interval itself.

Returns:

a non-class version of this interval

fifths()

Return the position of the interval on the line of fifths.

Returns:

an array of fifths (integers)

static from_array(intervals)

Create an interval array from an array of intervals.

Parameters:

intervals – an array-like of SpelledInterval

Returns:

the corresponding interval array

static from_independent(fifths, octaves)

Create an interval array from fifths (interval class) and independent/external octaves.

Parameters:

• fifths – the internal fifths of each interval (numpy array of integers)

• octaves – the external/independent octaves of each interval (numpy array of integers)

Returns:

the corresponding interval array

static from_onehot(onehot, fifth_low, octave_low)

Create a spelled interval array from a one-hot tensor. fifth_low denotes the lower bound of the fifth range used in the vector, octave_low the lower bound of the octave range. The shape of the resulting array will be equivalent to the first n-2 dimensions of the input tensor.

Parameters:

• onehot – a one-hot tensor representing the intervals (numpy array)

• fifth_low – the lowest fifth expressible in the one-hot tensor (integer)

• octave_low – the lowest octave expressible in the one-hot tensor (integer)

Returns:

the corresponding interval array

static from_strings(strings)

Create an interval array from an array of strings (using spelled interval notation).

Parameters:

strings – an array-like of interval notation strings

Returns:

the corresponding interval array

generic()

Return the generic interval, i.e. the number of diatonic steps modulo octave. Unlike degree(), the result respects the sign of the interval (unison=0, 2nd up=1, 2nd down=-1).

Returns:

an array of generic intervals (integers)

ic()

Return the interval class that corresponds to this interval. If the interval is already an interval class, it is returned itself.

Returns:

the interval’s corresponding interval class

internal_octaves()

Return the internal octave representation of a pitch, which is dependent on the fifths.

Only use this if you know what you are doing.

Returns:

an array of internal/dependent octaves (integers)

is_step()

Return True if the interval is considered a step, False otherwise.

Returns:

the stepness of the interval (boolean)

name()

Returns the names of the objects in the array as an array of strings of the same shape.

Returns:

an array of notation strings

classmethod octave(shape)

Return an array of the given shape filled with perfect octaves (P1:1).

Parameters:

shape – the shape of the resulting array (tuple of integers)

Returns:

a SpelledIntervalArray of shape shape filled with P1:0

octaves()

For intervals, return the number of octaves the interval spans. Negative intervals start with -1, decreasing. For pitches, return the absolute octave of the pitch.

Returns:

an array of external/independent octaves (integers)

onehot(fifth_range, octave_range, dtype=<class 'int'>)

Returns a one-hot encoding of the intervals in fifths and independent octaves as the innermost dimensions. The range of fifths and octaves is given by fifth_range and octave_range respectively, where each is a tuple (lower, upper). The outer shape of the output tensor is identical to the shape of the original array, so the resulting shape is original_shape + (n_fifths, n_octaves).

Parameters:

• fifth_range – the (inclusive) range of fifths (pair of integers)

• octave_range – the (inclusive) range of octaves (pair of integers)

• dtype – dtype of the resulting array (default: int)

Returns:

a one-hot tensor (numpy array)

semitones()

Return the number of semitones corresponding to the interval.

steps()

Return the number of diatonic steps corresponding to the interval.

to_class()

Alias for ic(), but also supported by pitch types.

Returns:

the interval’s corresponding interval class

classmethod unison(shape)

Create an array of the given shape filled with perfect unisons (P1:0).

Parameters:

shape – the shape of the resulting array (tuple of integers)

Returns:

a SpelledIntervalArray of shape shape filled with P1:0