3.13. pctheory.transformations
This file contains classes and functions for working with standard transformations: the ordered tone operators (OTOs) and unordered tone operators (or UTOs).
class OTO
Represents an ordered tone operator (OTO) of the form TnMm or TnRMm. This class can be used with both PitchClass12 and PitchClass24 objects. When used with a twelve-tone row, if m ∈ {1, 5, 7, 11}, operators in this class are row operators (ROs). OTO objects are represented with a tuple of size 3: (t, r, m), where t is the index of transposition, r is 1 if the operator is a retrograde operator and 0 otherwise, and m is the index of multiplication. OTOs can transform only pcsegs, not individual pcs.
OTO constructor
OTO.__init__(T=0, R=0, M=0)
Constructs an OTO. You can provide the indices of transposition and multiplication, as well as whether or not this is a retrograde operator (1 for retrograde or 0 for no retrograde).
OTO properties
OTO.oto(int, int, int)
The OTO, as a tuple (T, R, M).
OTO methods
OTO.transform(pcseg: list)[PitchClass12]or[PitchClass24]
Transforms a pcseg by the OTO operator.
OTO overloaded special functions
Overloaded special functions include __eq__(), __getitem__(), __hash__(), __ne__(), __repr__(), and __str__(). Basically, this means that you can index an OTO object (for example, my_oto[i]), as well as compare OTO objects using the == and != operators. The str() implementation allows OTO objects to be printed.
class UTO
Represents an unordered tone operator (UTO) of the form TnMm. This class can be used with both PitchClass12 and PitchClass24 objects. When used with chromatic pcsets or pcsegs, if m ∈ {1, 5, 7, 11}, operators in this class are twelve-tone operators (TTOs). UTO objects are represented with a tuple of size 2: (t, m), where t is the index of transposition, and m is the index of multiplication. Applying an UTO transformation to a pcseg does not affect the order of the pcseg. UTOs can transform individual pcs, or pcs nested within one or more lists or sets.
UTO constructor
UTO.__init__(T=0, M=0)
Constructs an UTO. You can provide the indices of transposition and multiplication.
UTO properties
UTO.uto(int, int)
The UTO, as a tuple (T, M).
UTO methods
UTO.cycles(num_pcs=12)[[int]]
Gets the cycles of the UTO operator.
UTO.inverse(num_pcs=12)UTO
Gets the inverse of the UTO operator.
UTO.transform(item)whatever was input
Transforms an item by the OTO operator. The item may be a PitchClass12 or PitchClass24, a pcset, a pcseg, or a poset with any amount of nesting. The UTO.transform() function is recursive, so it is possible to use it to transform a very gnarly poset like [0A{3[5B]}5{[9{A6}5]}2].
UTO overloaded special functions
Overloaded special functions include __eq__(), __getitem__(), __hash__(), __ne__(), __repr__(), and __str__(). Basically, this means that you can index an UTO object (for example, my_uto[i]), as well as compare UTO objects using the == and != operators. The str() implementation allows UTO objects to be printed.
find_utos(pcset1: set, pcset2: set){UTO}
Finds all UTOs that can transform pcset1 into pcset2.
get_otos12(){str: OTO}
Gets all of the chromatic OTOs (Tn, TnR, TnMm, and TnRMm) as a dictionary. The keys are string values of the format "T4", "T5R", "T8M7", and "T10RM11", for example.
get_otos24(){str: OTO}
Gets all of the microtonal OTOs (Tn, TnR, TnMm, and TnRMm) as a dictionary. The keys are string values of the format "T15", "T20R", "T8M13", and "T16RM23", for example.
get_utos12(){str: UTO}
Gets all of the chromatic UTOs (Tn and TnMm) as a dictionary. The keys are string values of the format "T4" and "T10M11", for example.
get_utos24(){str: UTO}
Gets all of the microtonal UTOs (Tn, and TnMm) as a dictionary. The keys are string values of the format "T15" and "T16M23", for example.
left_multiply_utos(*args, num_pcs=12)UTO
Left-multiplies a succession of UTOs. They can either be provided as individual arguments or as a single list. The function will begin with the highest index in the list and work its way backwards, returning the final product.
make_uto_list(*args)[UTO]
Makes a list of UTOs from any number of provided tuples or lists.