Spelled Interval and Pitch Arrays

Overview

With large datasets, it is often necessary or convenient to represent and process them in vectorized form, for example in numpy arrays. Putting spelled pitches or intervals directly in a numpy array does not have any performance benefits since numpy has no support for the operations between these types. However, the underlying representation of pitches is numeric and most operations on them directly translate to arithmetics on the underlying numbers.

This module provides vectorized types for spelled interval and pitch arrays. They correspond to the types in the pitchtypes.spelled module and generally share the same interface. Internally, spelled array types use numpy arrays to encode their data and implement all of their arithmetic operations in vectorized form. The main exception to native vectorization is printing and parsing, which means that those should be handled with care on large datasets.

Array Creation

From Numeric Arrays

The most direct way to construct a spelled array is by providing its underlying arrays of fifths and (dependent) octaves as a numpy array or something that supports the same interface such as a pandas series.

>>> from pitchtypes import *
>>> import numpy as np
>>> SpelledIntervalClassArray(np.array([1,2,3]))
asic(['P5', 'M2', 'M6'])
>>> SpelledPitchClassArray(np.arange(3))
aspc(['C', 'G', 'D'])
>>> SpelledIntervalArray(np.arange(1,4), np.array([0,-1,-1]))
asi(['P5:0', 'M2:0', 'M6:0'])
>>> import pandas as pd
>>> df = pd.DataFrame({'fifths': [1,2,3], 'octaves':[4,3,3]})
>>> SpelledPitchArray(df.fifths, df.octaves)
asp(['G4', 'D4', 'A4'])

If the data is given using independent octaves (e.g., derived from the name and octave of a pitch), intervals and pitches can also be constructed from those using the class method from_independent(fifths, octaves). This is usually more natural for pitches than for intervals

>>> SpelledPitchArray.from_independent(np.array([1,2,3]), np.array([4,4,4]))
asp(['G4', 'D4', 'A4'])
>>> SpelledIntervalArray.from_independent(np.array([-2,-1,0,1,2]), np.array([0,0,0,0,0]))
asi(['m7:0', 'P4:0', 'P1:0', 'P5:0', 'M2:0'])

From String Arrays

Spelled arrays can also be created from arrays of strings using the from_strings(strings) class method. Note that the parsing is done entirely in Python and thus can be slow on large datasets.

>>> SpelledIntervalArray.from_strings(["M2:0", "-P4:1"])
asi(['M2:0', '-P4:1'])
>>> SpelledPitchClassArray.from_strings([["Db", "D", "D#"], ["Eb", "E", "E#"]])
aspc([['Db', 'D', 'D#'],
 ['Eb', 'E', 'E#']])

From Arrays of Pitches / Intervals

Arrays (or lists) containing pitches or intervals can be converted to the corresponding spelled arrays using the from_array class method:

>>> intervals = np.array([SpelledInterval("P1:0"), SpelledInterval("P1:1")])
>>> intervals
array([P1:0, P1:1], dtype=object)
>>> SpelledIntervalArray.from_array(intervals)
asi(['P1:0', 'P1:1'])
>>> SpelledPitchArray.from_array([SpelledPitch("C4"), SpelledPitch("C5")])
asp(['C4', 'C5'])

Shorthands

When writing code that uses spelled array types, you should generally use one of the above methods for creating spelled arrays, as they make the intention of the code clear. However, for quickly testing or trying something in an interactive way, there are shortcut functions that accept arrays or nested lists of strings, scalar spelled types, and numeric fifths/octaves values.

>>> asi(["aaa1:1"])
asi(['aaa1:1'])
>>> asi([SpelledInterval("aaa1:1")])
asi(['aaa1:1'])
>>> asi([21], [-11])
asi(['aaa1:1'])

>>> asic([SpelledIntervalClass("aaa1")])
asic(['aaa1'])
>>> asic(["aaa1"])
asic(['aaa1'])
>>> asic([21])
asic(['aaa1'])

>>> asp(["A##4", "C5"])
asp(['A##4', 'C5'])
>>> asp([SpelledPitch("A##4"), SpelledPitch("C5")])
asp(['A##4', 'C5'])
>>> asp([17, 0], [-5, 5])
asp(['A##4', 'C5'])

>>> aspc(["A##", "C"])
aspc(['A##', 'C'])
>>> aspc([SpelledPitchClass("A##"), SpelledPitchClass("C")])
aspc(['A##', 'C'])
>>> aspc([17, 0])
aspc(['A##', 'C'])

Working with Spelled Arrays

Array Return Values

Most methods on spelled arrays now return either another spelled array or an array or numbers or strings:

>>> asi(["P1:0", "M3:0", "-m2:1"]).direction()
array([ 0,  1, -1])
>>> abs(asi(["P1:0", "M3:0", "-m2:1"]))
asi(['P1:0', 'M3:0', 'm2:1'])
>>> cs = aspc(["C", "C#", "C##", "Cb"])
>>> cs.alteration()
array([ 0,  1,  2, -1])
>>> cs.degree()
array([0, 0, 0, 0])
>>> cs.letter()
array(['C', 'C', 'C', 'C'], dtype='<U1')

Comparison also works element-wise:

>>> asi(["M2:0", "d5:0", "-P5:0"]) > asi(["m2:0", "a4:0", "-P4:0"])
array([ True,  True, False])
>>> asic(["M2", "-m7", "m2"]) == SpelledIntervalClass("M2")
array([ True,  True, False])
>>> asp(["C4", "B###3", "Dbbb4"]).compare(SpelledPitch("C4"))
array([ 0, -1,  1])
>>> aspc(["C", "C#", "D"]).array_equal(aspc(["C", "Db", "D"]))
False

Use array_equal to test the overall equality of two arrays as == will return element-wise equality.

Warning

Note that the ordering of non-class intervals/pitches and interval/pitch classes is different. Non-class pitches and intervals are ordered diatonically while pitch/interval classes are ordered on the line of fifths (see here).

Names and Strings

Regular spelled types can be converted to a string representation using str(). Calling str() or py:func:`repr on spelled arrays also works but returns one string for the full array. If you want instead to get an array of strings (one for each pitch or interval in the original array), you can use the method name().

>>> unisons = asi([0, 7, 14, 21], [0, -4, -8, -12])
>>> unisons
asi(['P1:0', 'a1:0', 'aa1:0', 'aaa1:0'])
>>> str(unisons)
'[P1:0 a1:0 aa1:0 aaa1:0]'
>>> print(unisons)
[P1:0 a1:0 aa1:0 aaa1:0]
>>> unisons.name()
array(['P1:0', 'a1:0', 'aa1:0', 'aaa1:0'], dtype='<U6')

Special Intervals

For special intervals such as unison(), octave(), and chromatic_semitone(), you now have to provide a shape:

>>> print(SpelledIntervalArray.unison(12))
[P1:0 P1:0 P1:0 P1:0 P1:0 P1:0 P1:0 P1:0 P1:0 P1:0 P1:0 P1:0]
>>> print(SpelledIntervalClassArray.chromatic_semitone((3,5)))
[[a1 a1 a1 a1 a1]
 [a1 a1 a1 a1 a1]
 [a1 a1 a1 a1 a1]]

Array Interface

Spelled arrays support indexing as in numpy.

>>> intervals = asi(["m6:0", "m7:8", "dd1:3"])
>>> intervals[0]
m6:0
>>> intervals[[1,2]]
asi(['m7:8', 'dd1:3'])
>>> intervals[[1,2,1,2]]
asi(['m7:8', 'dd1:3', 'm7:8', 'dd1:3'])
>>> intervals[[True, False, True]]
asi(['m6:0', 'dd1:3'])

Besides indexing, spelled arrays also support common collection methods such as len(), in, or iteration:

>>> len(intervals)
3
>>> SpelledInterval("m7:8") in intervals
True
>>> for i in intervals:
...     print(f"Interval {i} corresponds to interval class {i.ic()}.")
...
Interval m6:0 corresponds to interval class m6.
Interval m7:8 corresponds to interval class m7.
Interval dd1:3 corresponds to interval class dd1.
>>> list(intervals)
[m6:0, m7:8, dd1:3]

One-hot Encoding

Spelled arrays support the same one-hot encoding style as their scalar counterparts. That means that non-class intervals/pitches are encoded using fifths and (independent) octaves while interval/pitch classes are encoded only in fifths. Each dimension covers a certain range of fifths/octaves that needs to be known when converting to/from one-hot tensors. You can create a one-hot tensor using onehot() and convert it back to a spelled array using from_onehot().

In addition to the fifth and octave dimensions, one-hot tensors of spelled arrays have additional dimensions that reflect the original shape of the array. The fifth (and octave) dimension(s) are the last (two) dimensions in the tensor’s shape, so for non-class arrays, the shape of the one-hot tensor is original_shape + (n_fifths, n_octaves) while for class arrays, the shape is original_shape + (n_fifths,).

Simple example (pitch class array, one array dimension):

>>> pc_onehot = aspc(["C", "G", "F", "D", "Bb", "A", "Eb"]).onehot((-4,4))
>>> pc_onehot.shape # 7 pitches x 9 fifths (-4 to 4)
(7, 9)
>>> pc_onehot
array([[0, 0, 0, 0, 1, 0, 0, 0, 0],
       [0, 0, 0, 0, 0, 1, 0, 0, 0],
       [0, 0, 0, 1, 0, 0, 0, 0, 0],
       [0, 0, 0, 0, 0, 0, 1, 0, 0],
       [0, 0, 1, 0, 0, 0, 0, 0, 0],
       [0, 0, 0, 0, 0, 0, 0, 1, 0],
       [0, 1, 0, 0, 0, 0, 0, 0, 0]])
>>> SpelledPitchClassArray.from_onehot(pc_onehot, -4)
aspc(['C', 'G', 'F', 'D', 'Bb', 'A', 'Eb'])

Complex example (interval array, two array dimensions):

>>> intervals = asi([["M6:0", "m3:0", "M2:1"],
...                  ["-M6:0", "-m3:0", "P1:0"]])
>>> print(intervals)
[[M6:0 m3:0 M2:1]
 [-M6:0 -m3:0 P1:0]]
>>> i_onehot = intervals.onehot((-4,4), (-1,1))
>>> i_onehot.shape # 2 rows, 3 columns, 9 fifths (-4 to 4), 3 octaves (-1 to 1)
(2, 3, 9, 3)
>>> i_onehot[0,2] # M2:1: fifth=2 (out of -4 to 4), octave=1 (out of -1 to 1)
array([[0, 0, 0],
       [0, 0, 0],
       [0, 0, 0],
       [0, 0, 0],
       [0, 0, 0],
       [0, 0, 0],
       [0, 0, 1],
       [0, 0, 0],
       [0, 0, 0]])
>>> SpelledInterval("M2:1").onehot((-4,4), (-1,1))
array([[0, 0, 0],
       [0, 0, 0],
       [0, 0, 0],
       [0, 0, 0],
       [0, 0, 0],
       [0, 0, 0],
       [0, 0, 1],
       [0, 0, 0],
       [0, 0, 0]])

Reference

pitchtypes.asi(things, things2=None)

A quick way to construct a spelled-interval array. Takes an array-like of strings or spelled intervals, or two array-likes of integers (fifths and internal/dependent octaves).

Parameters:

things – an array-like of strings / fifths (integers) / SpelledInterval
things2 – an array-like of dependent octaves (integers), when providing fifths in the first parameter

Returns:

a spelled-interval array of the same shape as the input

pitchtypes.asic(things)

A quick way to construct a spelled-interval-class array. Takes either an array-like of strings or spelled interval classes, or an array-like of integers (fifths).

Parameters:: things – an array-like of strings / fifths (integers) / SpelledIntervalClass
Returns:: a spelled-interval-class array of the same shape as the input

pitchtypes.asp(things, things2=None)

A quick way to construct a spelled-pitch array. Takes either an array-like of strings or spelled pitches, or two array-likes of integers (fifths and internal/dependent octaves).

Parameters:

things – an array-like of strings / fifths (integers) / SpelledPitch
things2 – an array-like of dependent octaves (integers), when providing fifths in the first parameter

Returns:

a spelled-pitch array of the same shape as the input

pitchtypes.aspc(things)

A quick way to construct a spelled-pitch-class array. Takes either an array-like of strings or spelled pitch classes, or an array-like of integers (fifths).

Parameters:: things – an array-like of strings / fifths (integers) / SpelledPitchClass
Returns:: a spelled-pitch-class array of the same shape as the input

General Interface

class pitchtypes.SpelledArray

A common base class for vectorized spelled pitch and interval types. Uses the same interface as the Spelled types.

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

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

abstract 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.

The respective ordering differs between types. Non-class pitches and intervals use diatonic ordering, interval/pitch classes use line-of-fifths ordering.

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 spelled array or scalar
Returns:: an array of -1 / 0 / 1 (integer)

abstract 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

abstract fifths()

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

Returns:: an array of fifths (integers)

abstract 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)

abstract 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)

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)

abstract 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)

abstract onehot()

Return a one-hot encoded tensor representing the elements of the array. Specialized versions of this method take ranges for their respective dimensions.

Returns:: a one-hot tensor for the array

Spelled Interval and Pitch

class pitchtypes.SpelledIntervalArray(fifths, octaves)

Represents an array of spelled intervals.

semitones(): Return the number of semitones corresponding to the interval.

steps(): Return the number of diatonic steps corresponding to the interval.

__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)

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_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

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_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

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

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

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

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)

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

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

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

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)

fifths()

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

Returns:: an array of fifths (integers)

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)

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)

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)

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)

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)

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)

abs()

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

Returns:: the absolute interval

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

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)

to_class()

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

Returns:: the interval’s corresponding interval class

class pitchtypes.SpelledPitchArray(fifths, octaves)

Represents an array of spelled pitches.

steps(): Return the number of diatonic steps corresponding to the pitch.

semitones(): Return the number of chromatic semitones corresponding to the pitch.

midi(): Return the MIDI number corresponding to the pitch.

__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 pitch (numpy array of integers)
octaves – the internal octaves of each pitch (numpy array of integers)

static from_independent(fifths, octaves)

Create a pitch array from fifths and indenpendent octaves. The fifths indicate the names of the pitches while the octaves indicate their octave numbers.

Parameters:

fifths – the internal fifths of each pitch (numpy array of integers)
octaves – the external/independent octaves of each pitch (numpy array of integers)

Returns:

the corresponding pitch array

static from_strings(strings)

Create a pitch array from an array of strings.

Parameters:: strings – an array-like of pitch notation strings
Returns:: the corresponding pitch array

static from_array(pitches)

Create a pitch array from an array of pitches.

Parameters:: intervals – an array-like of SpelledPitch
Returns:: the corresponding pitch array

static from_onehot(onehot, fifth_low, octave_low)

Create a spelled pitch 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 pitches (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 pitch array

interval_from(other)

Computes the interval from another pitch to this pitch.

Parameters:: other – another pitch
Returns:: the interval from other to self

pc()

Returns the pitch class corresponding to the pitch. For pitch classes, it returns the pitch class itself.

Returns:: the pitch class that corresponds to this pitch

embed()

For a pitch class, returns the corresponding pitch in a (type-dependent) default octave. For non-class pitches, returns the pitch itself.

Returns:: a non-class version of this pitch

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 pitches use diatonic ordering, for example F4 < F#4 < F####4 < Gb4 < G4.

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 SpelledPitchArray or SpelledPitch
Returns:: an array of -1 / 0 / 1 (integer)

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

fifths()

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

Returns:: an array of fifths (integers)

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)

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)

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)

letter()

Returns the letter associated with the pitch (without accidentals).

Returns:: an array of pitch letters (single-character strings)

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

Returns a one-hot encoding of the pitches 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)

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

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)

interval_to(other)

Computes the interval from this pitch to another pitch.

Parameters:: other – another pitch
Returns:: the interval from self to other

to_class()

Alias for pc(), but also supported by interval types.

Returns:: the pitch class that corresponds to this pitch

Spelled Interval and Pitch Class

class pitchtypes.SpelledIntervalClassArray(fifths)

Represents an array of spelled interval classes, i.e. intervals without octave information.

semitones(): Return the number of semitones corresponding to the interval.

steps(): Return the number of diatonic steps corresponding to the interval.

__init__(fifths)

Takes a numpy array of fifths as integers.

Parameters:: fifths – the internal fifths of each interval class (numpy array of integers)

static from_strings(strings)

Create an interval-class array from an array of strings.

Parameters:: strings – an array-like of interval-class notation strings
Returns:: the corresponding interval-class array

static from_array(intervals)

Create an interval class array from an array of interval classes.

Parameters:: intervals – an array-like of SpelledIntervalClass
Returns:: the corresponding interval-class array

static from_onehot(onehot, fifth_low)

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

Parameters:

onehot – a one-hot tensor representing the interval classes (numpy array)
fifth_low – the lowest fifth expressible in the one-hot tensor (integer)

Returns:

the corresponding interval-class array

classmethod unison(shape)

Return an array of the given shape filled with perfect unisons (P1).

Parameters:: shape – the shape of the resulting array (tuple of integers)
Returns:: a SpelledIntervalClassArray of shape shape filled with P1

classmethod octave(shape)

Same as unison() since octaves are equivalent to unisons in interval-class space.

Parameters:: shape – the shape of the resulting array (tuple of integers)
Returns:: a SpelledIntervalClassArray of shape shape filled with P1

classmethod chromatic_semitone(shape)

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

Parameters:: shape – the shape of the resulting array (tuple of integers)
Returns:: a SpelledIntervalClassArray of shape shape filled with a1

direction()

Returns the (element-wise) directions of the intervals. The direction of each interval is determined by its shortest realization: m2/-M7 is upward (1) while M7/-m2 is downward (-1). Perfect unisons (P1) are neutral (0).

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

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

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

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

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 interval classes use line-of-fifth ordering, for example P4 < P1 < P5 < M2.

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 SpelledIntervalClassArray or SpelledIntervalClass
Returns:: an array of -1 / 0 / 1 (integer)

fifths()

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

Returns:: an array of fifths (integers)

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)

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)

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)

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)

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)

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

Returns a one-hot encoding of the interval classes in fifths as the innermost dimension. The range of fifths is given by fifth_range as 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,).

Parameters:

fifth_range – the (inclusive) range of fifths (pair of integers)
dtype – dtype of the resulting array (default: int)

Returns:

a one-hot tensor (numpy array)

abs()

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

Returns:: the absolute interval

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

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)

to_class()

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

Returns:: the interval’s corresponding interval class

class pitchtypes.SpelledPitchClassArray(fifths)

Represents a spelled pitch class, i.e. a pitch without octave information.

steps(): Return the number of diatonic steps corresponding to the pitch.

semitones(): Return the number of chromatic semitones corresponding to the pitch.

midi(): Return the MIDI number corresponding to the pitch.

__init__(fifths)

Takes a numpy array of fifths as integers.

Parameters:: fifths – the internal fifths of each pitch class (numpy array of integers)

static from_strings(strings)

Create a pitch-class array from an array of strings.

Parameters:: strings – an array-like of pitch-class notation strings
Returns:: the corresponding pitch-class array

static from_array(pitches)

Create an pitch class array from an array of pitch classes.

Parameters:: intervals – an array-like of SpelledPitchClass
Returns:: the corresponding pitch-class array

static from_onehot(onehot, fifth_low)

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

Parameters:

onehot – a one-hot tensor representing the pitch classes (numpy array)
fifth_low – the lowest fifth expressible in the one-hot tensor (integer)

Returns:

the corresponding pitch-class array

interval_from(other)

Computes the interval from another pitch to this pitch.

Parameters:: other – another pitch
Returns:: the interval from other to self

pc()

Returns the pitch class corresponding to the pitch. For pitch classes, it returns the pitch class itself.

Returns:: the pitch class that corresponds to this pitch

embed()

For a pitch class, returns the corresponding pitch in a (type-dependent) default octave. For non-class pitches, returns the pitch itself.

Returns:: a non-class version of this pitch

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

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 pitch classes use line-of-fifth ordering, for example Bb < F < C < G < D.

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 SpelledPitchClassArray or SpelledPitchClass
Returns:: an array of -1 / 0 / 1 (integer)

fifths()

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

Returns:: an array of fifths (integers)

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)

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)

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)

letter()

Returns the letter associated with the pitch (without accidentals).

Returns:: an array of pitch letters (single-character strings)

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

Returns a one-hot encoding of the pitch classes in fifths as the innermost dimension. The range of fifths is given by fifth_range as 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,).

Parameters:

fifth_range – the (inclusive) range of fifths (pair of integers)
dtype – dtype of the resulting array (default: int)

Returns:

a one-hot tensor (numpy array)

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

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)

interval_to(other)

Computes the interval from this pitch to another pitch.

Parameters:: other – another pitch
Returns:: the interval from self to other

to_class()

Alias for pc(), but also supported by interval types.

Returns:: the pitch class that corresponds to this pitch