Package 'musicMCT'

Description

As for other hyperplane arrangements, it is useful to consider the number of entries which equal 0 in an anaglyph signvector. However, such entries can represent three different types of regularity: regularity within the first set, regularity within the second set, or regularity in the comparison between them. This function distinguishes between those three types of hyperplanes.

Usage

anazero_fingerprint(set, edo = 12, rounder = 10)

Arguments

Value

A vector with three entries, representing regularities in the first set, regularities in the second set, and regularities between them.

See Also

make_anaglyph_ineqmat(), svzero_fingerprint()

Examples

maj <- c(0, 4, 7)
sus2 <- c(0, 2, 7)
anazero_fingerprint(c(maj, sus2))

# The first entry shows that the major triad has 0 regularities.
# This is equivalent to:
countsvzeroes(maj)

# The second entry shows that the sus2 trichord has 1 regularity.
# This is equivalent to:
countsvzeroes(sus2)

# The final entry shows that the major triad's perfect fifth
# equals the size of the *two* perfect fifths in the sus2 trichord.
# We can visualize the whole set of relationships using a brightness
# graph:
brightnessgraph(maj, sus2)

Description

Among others, Carey & Clampitt (1989) and Clampitt (1997) have shown that much can be learned about a set by representing it as a word on $m$ "letters" which represent the $m$ distinct steps between adjacent members of the set. This is more or less what is done in theory fundamentals classes when a major scale is represented as TTSTTTS (if we temporarily forget that T and S represent specific interval sizes). In scholarship the algebraic letters are usually represented as letters of the Latin alphabet, but for some computational purposes it is useful for these to be explicitly ordered. That is, the major scale should be represented as integers 2212221, which is distinct from 1121112. (Thus asword makes finer distinctions than you might expect coming from a word-theoretic context.)

Usage

asword(set, edo = 12, rounder = 10)

Arguments

Value

Vector of integers of the same length as set. 1 should always be the lowest value, representing the smallest step size in the set.

Examples

dia_12edo <- c(0, 2, 4, 5, 7, 9, 11)
qcm_fifth <- meantone_fifth()
qcm_dia <- sort(((0:6)*qcm_fifth)%%12)
just_dia <- j(dia)
asword(dia_12edo)
asword(qcm_dia)
asword(just_dia)

#### asword() is less discriminating than colornum(). 
#### See "Modal Color Theory," 16
set1 <- c(0, 1, 4, 7, 8)
set2 <- c(0, 1, 3, 5, 6)
set1_word <- asword(set1)
set2_word <- asword(set2)
isTRUE(all.equal(set1_word, set2_word))
colornum(set1) == colornum(set2) 
# (Last line only works with representative_signvectors loaded.)

Description

The essential step in creating the brightness graph of a scale's modes is to compute the pairwise comparisons between all the modes. Which ones are strictly brighter than others according to "voice-leading brightness" (see "Modal Color Theory," 6-7)? This function makes those pairwise comparisons in a manner that's useful for more computation.

Usage

brightness_comparisons(set, goal = NULL, edo = 12, rounder = 10)

Arguments

Details

Note that the returned value shows all voice-leading brightness comparisons, not just the transitive reduction of those comparisons. (That is, dorian is shown as darker than ionian even though mixolydian intervenes in the brightness graph.)

Value

If goal=NULL, an n-by-n matrix where n is the size of the scale. Row i represents mode i of the scale in comparison to all n modes. If the entry in row i, column j is -1, then mode i is "voice-leading darker" than mode j. If 1, mode i is "voice-leading brighter". If 0, mode i is neither brighter nor darker, either because contrary motion is involved or because mode i is identical to mode j. (Entries on the principal diagonal are always 0.)

If goal is a set, the result is a 2n-by-2n matrix whose first n rows and columns represent the modes of set and whose last n rows and columns represent the modes of goal. (Thus the upper left n-by-n square is the same as if goal were NULL and the lower right n-by-n square is the result of entering goal as set with an empty goal parameter. The upper-right and lower-left quadrants of the matrix make comparisons between the modes of set and goal.) The meaning of entries -1, 0, and 1 are as above.

See Also

brightnessgraph() for a human-readable presentation of the same information.

Examples

# Because the diatonic scale, sc7-35, is non-degenerate well-formed, the only
# 0 entries should be on its diagonal.
brightness_comparisons(sc(7, 35))

mystic_chord <- sc(6,34)
colSums(sim(mystic_chord)) # The sum brightnesses of the mystic chord's 6 modes
brightness_comparisons(mystic_chord) 
# Almost all 0s because very few mode pairs are comparable.
# That's because nearly all modes have the same sum, which means they have sum-brightness
# ties, and voice-leading brightness can't break a sum-brightness tie.
# (See "Modal Color Theory," 7.)

major <- c(0, 4, 7)
minor <- c(0, 3, 7)
brightness_comparisons(major, minor)

Description

Discussed in "Modal Color Theory" (pp. 7-11), the brightness graph of a scale is a Hasse diagram that represents the sum- and voice-leading brightness relationships between the modes of a scale. Each node of the graph represents a mode. With default options, the large Roman numeral of each node indicates which mode of the input scale it represents. (The input scale is roman numeral I.) Small Arabic numerals beneath the Roman numeral indicate the pitch-classes of the mode (relative to scale degree 1 as 0). In parentheses, the sum brightness of the mode is shown. Modes with higher sum brightness are farther up on the graph. Arrows connect modes that can be compared by voice-leading brightness. The arrows only show a transitive reduction of all VL-brightness comparisons, so that if you can travel between two sets by only going "up" or "down" the arrows, the source and destination are indeed related by voice-leading brightness.

If goal=NULL (as it is by default), the brightness graph includes simply the modes of set. However, goal can be any other scale of the same length as set, in which case the brightness graph includes modes of both sets and their interconnections. The modes of goal are represented by lower-case roman numerals, while upper-case numerals represent the modes of set.

Various visual parameters can be configured: numdigits determines how many digits of each pitch-class to display; show_sums toggles on or off the sum brightness values; show_pitches toggles on or off the individual pitch classes of each mode; fixed_do, if set to TRUE switches the graph from showing "parallel" modes (e.g. C ionian vs C aeolian) to showing "relative" modes (e.g. C ionian to A aeolian).

For now, the function doesn't have a smart way to determine the horizontal positioning of modes in the graph. It uses a heuristic that works well for many sets, but sometimes it will create too much visual overlap or won't clarify underlying structure particularly well. Think of these automatically generated graphs as the starting point for manual fine tuning.

Usage

brightnessgraph(
  set,
  goal = NULL,
  numdigits = 2,
  show_sums = TRUE,
  show_pitches = TRUE,
  fixed_do = FALSE,
  edo = 12,
  rounder = 10
)

Arguments

Value

Invisibly, an igraph graph object (the structure of the plotted brightness graph)

Examples

brightnessgraph(c(0,2,4,5,7,9,11))
brightnessgraph(c(0,2,4,5,7,9,11), fixed_do=TRUE)
brightnessgraph(c(0,1,4,9,11),edo=15)

#### A more complicated graph
werck_ratios <- c(1, 256/243, 64*sqrt(2)/81, 32/27, (256/243)*2^(1/4), 4/3, 
  1024/729, (8/9)*2^(3/4), 128/81, (1024/729)*2^(1/4), 16/9, (128/81)*2^(1/4))
werckmeister_3 <- z(werck_ratios)
brightnessgraph(werckmeister_3, show_sums=FALSE, show_pitches=FALSE)


#### Graph for both inversions of the Tristan genus:
dom7 <- c(0, 4, 7, 10)
halfdim <- c(0, 3, 6, 10)
brightnessgraph(dom7, halfdim)

Description

For her album Beauty in the Beast, Wendy Carlos developed several non-octave scales whose step sizes are calculated to optimize approximations of three intervals: the 3:2 fifth, the 5:4 major third, and the 6:5 minor third. The alpha, beta, gamma, and delta scales differ in terms of how strongly they privilege each of those just intervals. The basic step size for each scale is created by calling this function with the appropriate name argument (e.g. "alpha"). You can also choose your own weights for the three approximated just intervals, in which case the name argument is overridden.

Usage

carlos_step(name = "alpha", weights = NULL, edo = 12)

Arguments

Value

Single numeric value containing the step size for the desired scale

Examples

alpha_scale <- (0:31) * carlos_step()
practically_12tet <- (0:24) * carlos_step(weights=c(7, 4, 3))

Description

Clampitt (2007, 467; doi:10.1007/978-3-642-04579-0_46) defines two $n$-note sets to be Q-related if they:

• Have all but one tone in common

• Are related by tni()

• Have a strictly crossing-free voice leading which preserves all $n-1$ common tones This function finds all sets which are Q-related to an input set in this sense. The relation is defined to generalize the smooth voice leadings between consonant triads and diatonic scales to other sets, in particular demonstrating that non-singular pairwise well-formed scales (see isgwf()) demonstrate similarly nice voice leading properties.

(Strictly speaking, Clampitt includes tn() in the second part of the definition. However, the first criterion is only possible under tn() if the set is generated and therefore inversionally symmetrical. Therefore if a set satisfies Clampitt's definition by tn(), it also satisfies the tni() requirement.)

If the third part of the definition is relaxed, allowing the voice leading to involve voice crossing, Clampitt (1997, 121) identifies this as the Q*-relation. The Q*-relation can be computed with this function by setting method="hamming". (All other methods provided by vl_dist() give equivalent results in this context.)

When method is not "hamming", a synonym for "Q relation" is "Cohn flip" (Lewin 1996, doi:10.2307/843888).

Usage

clampitt_q(
  set,
  index = NULL,
  method = c("taxicab", "euclidean", "chebyshev", "hamming"),
  edo = 12,
  rounder = 10
)

Arguments

Value

A list with two entries, "sets" and "vls". The former is a matrix whose columns are the sets which are Q-related to the input set, in OP-normal form. The latter is a matrix whose rows represent the voice-leading motions which transform set into its goals. (This follows the general practice of musicMCT of representing scales as columns and voice leadings as rows.) The rows of "vls" correspond to the columns of "sets", but the columns of "vls" correspond to the order of the input set, which may not match the normal form of the output sets. (See the last example.)

See Also

isgwf(), minimize_vl(), normal_form()

Examples

# The Neo-Riemannian P, L, and R transformations on triads are all Q-relations:
major_triad <- c(0, 4, 7)
clampitt_q(major_triad)

# A well-formed scale like the diatonic has two Q-relations given by its signature transformations:
major_scale <- c(0, 2, 4, 5, 7, 9, 11)
clampitt_q(major_scale)

# A non-singular pairwise well-formed scale also has Q-relations:
clampitt_q(j(dia))

# Set-class 7-31 is pairwise well-formed:
clampitt_q(sc(7, 31))
# It also has two additional Q*-related sets:
clampitt_q(sc(7, 31), method="hamming")

# Most other types of scales have at most one Q-relation:
dominant_seventh <- c(0, 4, 7, 10)
clampitt_q(dominant_seventh)

# The order of "sets" may not match the order of "vls":
clampitt_q(c(0, 1, 4, 7))

Description

No-frills way to plot the elements of a set on the circular "clockface" of pc-set theory pedagogy. (See e.g. Straus 2016, ISBN: 9781324045076.)

Usage

clockface(set, edo = 12)

Arguments

Value

Invisible copy of the input set

Examples

just_diatonic <- j(dia)
clockface(just_diatonic)

double_tresillo <- c(0, 3, 6, 9, 12, 14)
clockface(double_tresillo, edo=16)

Description

As described on p. 28 of "Modal Color Theory," it's convenient to have a systematic labeling system ("color numbers") to refer to the distinct colors in the hyperplane arrangements. This serves a similar function to Forte's set-class numbers in traditional pitch-class set theory. Color numbers are defined with reference to a complete list of the possible sign vectors for each cardinality, so they depend on the extensive prior computation that is stored in the object representative_signvectors. (This is a large file that cannot be included in the package musicMCT itself. It needs to be downloaded separately, saved in your working directory, and loaded by entering representative_signvectors <- readRDS("representative_signvectors.rds"). Color numbers are currently only defined for scales with 7 or fewer notes.

Usage

colornum(set, ineqmat = NULL, signvector_list = NULL, edo = 12, rounder = 10)

Arguments

Details

Note that the perfectly even "white" scale is number 0 for every cardinality by definition.

The function assumes that you don't need to be reminded of the cardinality of the set you've entered. That is, there's a color number 2 for every cardinality, so you can get that value returned by entering a trichord, tetrachord, etc.

Value

Single non-negative integer (the color number) if a signvector_list is specified or representative_signvectors is loaded; otherwise NULL

Examples

colornum(edoo(5))
colornum(c(0, 3, 7))
colornum(c(0, 2, 7))
colornum(c(0, 1, 3, 7))
colornum(c(0, 1, 3, 6, 10, 15, 21), edo=33)
colornum(c(0, 2, 4, 5, 7, 9, 11))

Description

As "Modal Color Theory" (pp. 31ff.) describes, it can be useful to know whether two colors are adjacent to each other in the MCT space. That is, can one scalar color be continuously modified until it becomes the other, without crossing through any third color? For instance, the 5-limit just diatonic scale is a two-dimensional color that is adjacent to the 1-d line of meantone diatonic scales. This means, in some sense, that the meantone structure is a good approximation of the 5-limit just structure.

Usage

comparesignvecs(signvecX, signvecY)

Arguments

Value

Integer: 0 if the sign vectors represent the same color, 1 if they are adjacent, and -1 if they are neither adjacent nor identical.

Examples

meantone_major_sv <- signvector(c(0, 2, 4, 5, 7, 9, 11))
meantone_dorian_sv <- signvector(c(0, 2, 3, 5, 7, 9, 10))
just_major <- j(dia)
just_dorian <- sim(just_major)[,2] 
just_major_sv <- signvector(just_major)
just_dorian_sv <- signvector(just_dorian)

comparesignvecs(meantone_major_sv, just_major_sv)
comparesignvecs(meantone_dorian_sv, just_major_sv)
comparesignvecs(meantone_dorian_sv, just_dorian_sv)

Description

By default the period of a scale (normally the octave) has a size of 12 units (semitones). But it can be useful to convert to a different measurement unit, e.g. to compare a scale defined in 19-tone equal temperament (19edo) to the size of its intervals when measured in normal 12edo semitones, or vice versa.

Usage

convert(x, edo1, edo2)

Arguments

Value

A numeric vector the same length as x representing the input set converted to the desired cardinality (edo2).

Examples

maqam_rast <- c(0, 2, 3.5, 5, 7, 9, 10.5)
convert(maqam_rast, 12, 24)

perfect_fifth <- z(3/2)
lydian_scale <- sort((perfect_fifth * (0:6)) %% 12)
convert(lydian_scale, 12, 53)

Description

Usually, it is most intuitive to music theorists to represent a scale as a vector of the pitch-classes it contains. However, for certain computations in the setting of Modal Color Theory, it is more convenient to use a coordinate system with the "white" perfectly even scale as the origin (because this is the point where all of the hyperplanes in the arrangement defining scalar "colors" intersect). Therefore, these two functions convert between the two coordinate systems: coord_to_edo takes in a scale represented by its pitch classes and returns its displacement vector from "white" and coord_from_edo does the reverse.

Usage

coord_to_edo(set, edo = 12)

coord_from_edo(set, edo = 12)

Arguments

Details

It should be noted that the representative "white" scale used is not necessarily the closest one to the scale in question. Instead, it is the unique transposition of white that has 0 as its first coordinate. This is natural in the context of Modal Color Theory, which essentially always assumes transpositional equivalence with $x_0 = 0$. The closest transposition of "white" to set will be the one that has the same sum class as set, guaranteeing that the voice leading between them is "pure contrary" (Tymoczko 2011, 81ff; explored further in Straus 2018 doi:10.1215/00222909-7127694).

Value

Numeric vector of same length as set. Same scale, new coordinate system.

Examples

dominant_seventh_chord <- c(0, 2, 6, 9)
coord_to_edo(dominant_seventh_chord)

ait1 <- c(0, 1, 4, 6)
ait2 <- c(0, 1, 3, 7)
coord_to_edo(ait1)
coord_to_edo(ait2) # !

weitzmann_pentachord <- coord_from_edo(c(0, -1, 0, 0, 0)) # See note 53 of "Modal Color Theory"
convert(weitzmann_pentachord, 12, 60)
coord_to_edo(weitzmann_pentachord)

Description

Computes the magnitudes and phases of the DFT components for a given (multi)set which can be input as either a vector of elements or as a distribution. (See Amiot (2016, doi:10.1007/978-3-319-45581-5) for an overview of applications of the DFT in this vein.) Entering a distribution takes priority over an entered set.

Usage

dft(set, distro = NULL, edo = 12, rounder = 10)

Arguments

Details

The scaling and orientation of phases corresponds to that used in Yust (2021) https://doi.org/10.1093/mts/mtaa0017: phases are reported as multiples of one kth of an octave (where the set is entered in k-edo), and oriented so that the $\hat{f}_1$ component of a singleton points in the direction of the singleton (i.e. the phase of $\hat{f}_1$ for pitch class 4 is 4). This differs from the phase values use in other publications, such as Yust (2015, doi:10.1215/00222909-2863409). Magnitudes are not squared, following Amiot (2016) rather than Yust (2021).

Value

A 2-by-k real matrix, where k is the number of independent components. The ith column corresponds to the (i-1)th component (so that the first column gives the zeroth component). The first row gives the magnitudes of the components and the second row gives the phases. (See details regarding interpretation of the values: they are scaled by edo/(2*pi) from radians.)

Examples

# Compare to Yust (2021), Example 10
reich_signature <- c(0, 1, 2, 4, 5, 7, 9, 10)
dft(reich_signature)
# Magnitudes differ from Yust by squaring:
round(dft(reich_signature)[1, ]^2, digits=3)

reich_sig_distribution <- c(1, 1, 1, 0, 1, 1, 0, 1, 0, 1, 1, 0)
dft(distro=reich_sig_distribution)

# Z-related AITs differ in phase but not magnitude:
ait1 <- c(0, 1, 4, 6)
ait2 <- c(0, 1, 3, 7)
dft(ait1)
dft(ait2)

Description

Creates a perfectly even scale that divides the octave into n equal steps. Such scales serve as the origin for the hyperplane arrangements of Modal Color Theory, whence the name edoo for "equal division of the octave origin."

Usage

edoo(card, edo = 12)

Arguments

Value

Numeric vector of length card representing a scale of card notes.

Examples

edoo(5)
edoo(5, edo=15)
octatonic_scale <- tc(edoo(4), c(0, 1))
print(octatonic_scale)

Description

David Lewin's EMB and COV functions: see Lewin, Generalized Musical Intervals and Transformations (New Haven, CT: Yale University Press, 1987), 105-120. For EMB, given a group ("CANON") of transformations which are considered to preserve a set's type, find the number of instances of that type in a larger set (scale). Lewin characterizes this generally, but emb() only offers $T_n$ and $T_n / T_nI$ transformation groups as available canonical groups. Conversely, Lewin's COV function asks how many instances of a scale type include subset: this is implemented as cover() (not cov()!).

Usage

emb(subset, scale, canon = c("tni", "tn"), edo = 12, rounder = 10)

cover(subset, scale, canon = c("tni", "tn"), edo = 12, rounder = 10)

Arguments

Value

Integer: count of subset or scale types satisfying the desired relation.

Examples

emb(c(0, 4, 7), sc(7, 35))
emb(c(0, 4, 7), sc(7, 35), canon="tn")

# Works for continuous pc-space too:
emb(j(1, 3, 5), j(dia))
emb(j(1, 2, 3, 5, 6), j(dia))
emb(j(1, 2, 4, 5, 6), j(dia), canon="tn")

emb(c(0, 4, 7), c(0, 1, 3, 7))
emb(c(0, 4, 7), c(0, 1, 3, 7), canon="tn")

emb(c(0, 4), c(0, 4, 8))
cover(c(0, 4), c(0, 4, 8))

harmonic_minor <- c(0, 2, 3, 5, 7, 8, 11)
cover(c(0, 4, 8), harmonic_minor)
cover(c(0, 4, 8), harmonic_minor, canon="tn")

Description

Section 3.3 of "Modal Color Theory" describes a "brightness ratio" which characterizes the modes of a scale in terms of how well "sum brightness" acts as a proxy for "voice-leading brightness." Scales with a brightness ratio less than 1 are pretty well behaved from this perspective, while ones with a brightness ratio greater than 1 are poorly behaved. When the brightness ratio is 0, sum brightness and voice-leading brightness give exactly the same results. (This can happen for sets on two extremes: those like the diatonic scale which are well formed and those like the Weitzmann scales, which differ from "white" in only one scale degree.)

I wish I had come up with a more descriptive name than "brightness ratio" for this property, because it's not really a ratio of brightness in the sense you might expect (i.e. "this scale is 20% bright"). Rather, it's a ratio of two brightness-related properties, delta and eps. "Modal Color Theory" (p. 20) offers definitions of these. Delta is "the largest sum difference between (voice-leading) incomparable modes," with value 0 by definition if all of the modes are comparable. ("This, in a sense, is a measure of how badly voice-leading brightness breaks down from the perspective of sum brightness.") Epsilon "represents the smallest sum difference between non-identical but comparable modes." This is harder to give an intuitive gloss on, but my attempt in "MCT" was "Essentially, epsilon measures the finest distinction that voice-leading brightness is capable of parsing."

The brightness ratio (ratio) itself is simply delta divided by epsilon.

Usage

eps(set, edo = 12, rounder = 10)

delta(set, edo = 12, rounder = 10)

ratio(set, edo = 12, rounder = 10)

Arguments

Value

Single non-negative numeric value

Examples

harmonic_minor <- c(0, 2, 3, 5, 7, 8, 11)
hypersaturated_harmonic_minor <- saturate(2, harmonic_minor)
c(delta(harmonic_minor), eps(harmonic_minor))
c(delta(hypersaturated_harmonic_minor), eps(hypersaturated_harmonic_minor))

# Delta and epsilon depend on the precise scale, but ratio() is constant on a hue
ratio(harmonic_minor)
ratio(hypersaturated_harmonic_minor)

#### Sort all 12tet heptachords by brightness ratio
heptas12 <- unique(apply(combn(12, 7), 2, primeform),MARGIN=2)
hepta_ratios <- apply(heptas12, 2, ratio)
sorted_heptas <- heptas12[, order(hepta_ratios)]
colnames(sorted_heptas) <- apply(sorted_heptas, 2, fortenum)
sorted_heptas

#### Compare evenness to ratio for 12tet hetpachords
plot(apply(heptas12, 2, evenness), hepta_ratios, xlab="Evenness", ylab="Brightness Ratio")

Description

Calculates the distance from a set to the nearest perfectly even division of the octave, which will not be the one with a first entry of 0, unlike almost every other usage in this package. That's because, for most purposes, we do want to distinguish between different modes of a set, but it seems counterintuitive to me to say that one mode of a scale is less even than another. Since this value is a distance from the perfectly even ("white") scale, lower values indicate more evenness.

Usage

evenness(
  set,
  method = c("euclidean", "taxicab", "chebyshev", "hamming"),
  edo = 12,
  rounder = 10
)

Arguments

Details

Note that the values this function returns depend on what measurement unit you're using (i.e. are you in 12edo or 16edo?). Their absolute value isn't terribly significant: you should only make relative comparisons between calculations done with the same value for edo.

Currently, methods other than "Euclidean" are somewhat experimental.

Value

Single non-negative numeric value

Examples

evenness(c(0, 4, 8))
evenness(c(0, 4, 7)) < evenness(c(0, 1, 2))

dim_triad <- c(0, 3, 6)
sus_2 <- c(0, 2, 7)
coord_to_edo(dim_triad)
coord_to_edo(sus_2)
evenness(dim_triad) == evenness(sus_2)

Description

When considering an n-note set's potential voice leadings to transpositions of a goal (along the lines of vl_rolodex() and tndists()), there will always be some transposition in continuous pc-space for which a given modal rotation is the best potential target for voice leading. (That is, there is always some x such that whichmodebest(set, tn(set, x)) == k for any k between 1 and n.) Moreover, there will always be a transposition level at the boundary between two different ideal modes, where both modes require the same amount of voice leading work. flex_points() identifies those inflection points where one mode gives way to another. (Note: flex_points() identifies these points by numerical approximation, so it may not give exact values. For more precision, increase the value of subdivide.)

Usage

flex_points(
  set,
  goal = NULL,
  method = c("taxicab", "euclidean", "chebyshev", "hamming"),
  subdivide = 100,
  edo = 12,
  rounder = 10
)

Arguments

Value

Numeric vector of the transposition indices that are inflection points. Length of result matches size of set, except in the case of some multisets, which can have fewer inflection points.

Examples

major_triad_12tet <- c(0, 4, 7)
major_triad_just <- z(1, 5/4, 3/2)
major_triad_19tet <- c(0, 6, 11)

flex_points(major_triad_12tet, method="euclidean", subdivide=1000)
flex_points(major_triad_just, method="euclidean", subdivide=1000)

# Note that the units of measurement correspond to edo.
# The value 3.16 here corresponds to exactly 1/6 of an octave.
flex_points(major_triad_19tet, edo=19)

Description

Given a pitch-class set (in 12edo only), look up Forte 1973's catalog number for the corresponding set class.

Usage

fortenum(set)

Arguments

Value

Character string in the form "n-x" where n is the number of notes in the set and x is the ordinal position in Forte's list.

Examples

fortenum(c(0, 4, 7))
fortenum(c(0, 3, 7))
fortenum(c(4, 8, 11))

Description

For compatibility with music theory's traditional pitch-class set theory, whose landmark text is Allen Forte's 1973 The Structure of Atonal Music, the data set fortenums hard-codes the ordinal positions of 12-equal pitch-class set classes from Allen Forte's list. This allows us to look up specific set classes from Forte numbers or vice versa. sc() does the former and fortenum() does the latter. There's very little need to ever interact with the file fortenums itself: you should be able to get anything you need from this data through either sc() or fortenum().

Note that primeform() in musicMCT uses Rahn's algorithm rather than Forte's for finding a canonical representative of each set class. Consequently, the entries of fortenums also use Rahn's prime forms rather than Forte's.

Usage

fortenums

Format

A list of length 12. The nth entry of the list corresponds to set classes of cardinality n. Each list entry is a vector of character strings; every element of the vector contains a Rahn prime form as a comma-delimited string. These prime forms are ordered in the same sequence as Forte's list. Thus, for instance, the set class of the minor triad is represented by the string "0, 3, 7", which is the 11th element in fortenums[[3]].

Source

Forte, Allen. 1973. The Structure of Atonal Music. New Haven, CT: Yale University Press. Appendix 1, pp. 179-181.

Description

When working with sets in continuous pitch-class spaces (i.e., where octave equivalence is needed), R's normal operator for modulo division %% does not always give ideal results. Values that are very close to (but below) the octave appear to be far from 0. This function uses rounding to give octave-equivalent results that music theorists expect.

Usage

fpmod(set, edo = 12, rounder = 10)

Arguments

Value

Numeric vector the same length as set

Examples

really_small <- 1e-13
c_major <- c(0, 4, 7, 12-really_small)
c_major %% 12
fpmod(c_major, 12)

Description

Working with scales in continuous pitch space, many pitches and intervals are irrationals represented as floating point numbers. This can cause arithmetic and rounding errors, leading to it looking like there are more distinct pitches/intervals in the set than there really are. Use fpunique rather than base::unique() whenever you handle scales in continuous pitch space.

Usage

fpunique(x, MARGIN = 0, rounder = 10)

Arguments

Details

Sometimes you may need to adjust the tolerance (rounder) to get correct results, especially if you have done several operations in a row which may have introduced rounding errors.

Value

Numeric array of unique elements (vector if MARGIN is 0; matrix otherwise)

Examples

just_dia <- j(dia)
intervals_in_just_dia <- sort(as.vector(sim(just_dia)))
failed_unique_intervals <- unique(intervals_in_just_dia)
fpunique_intervals <- fpunique(intervals_in_just_dia)
length(failed_unique_intervals)
length(fpunique_intervals)

Description

Given an ineqmat (i.e. a matrix representing a hyperplane arrangement), this function tells us which of those hyperplanes affect a specific generic interval size. (One specific application of this is is step_signvector(), which pays attention only to the comparisons between step sizes in a scale.)

Usage

get_relevant_rows(generic_intervals, ineqmat)

Arguments

Value

Vector of integers indicating the relevant hyperplanes from ineqmat

Examples

heptachord_ineqmat <- getineqmat(7)
heptachord_step_comparisons <- get_relevant_rows(1, heptachord_ineqmat)

# Create an ineqmat that attends only to the quality of (024) trichordal
# subsets in a heptachord.
heptachord_triads <- get_relevant_rows(c(0, 2, 4), heptachord_ineqmat)
triads_in_7_ineqmat <- heptachord_ineqmat[heptachord_triads,]

# Now, the following two heptachords have different colors
# but the same pattern of (024) trichordal subsets, so their signvector
# using triads_in_7_ineqmat is identical:
heptachord_1 <- convert(c(0, 1, 3, 6, 8, 12, 13), 17, 12)
heptachord_2 <- convert(c(0, 1, 3, 5, 7, 10, 11), 14, 12)
colornum(heptachord_1) == colornum(heptachord_2)
sv_1 <- signvector(heptachord_1, ineqmat=triads_in_7_ineqmat)
sv_2 <- signvector(heptachord_2, ineqmat=triads_in_7_ineqmat)
isTRUE(all.equal(sv_1, sv_2))
subset_varieties(c(0, 2, 4), heptachord_1, unique=FALSE)
subset_varieties(c(0, 2, 4), heptachord_2, unique=FALSE)
# Both have identical qualities for triads on scale degree 3, 5, and 7,
# which you can see by comparing columns 3, 5, and 7 in the two
# matrices above.

Description

Some scalar structures can vary their specific pitches much more flexibly than others while retaining the same overall "color." For instance, the meantone family of diatonic scales is generated by a line of fifths and can only vary along one dimension: the size of the generating fifth. This literally defines a line in the MCT geometry, and if the scale moves off that line it ceases to have the same structure as the diatonic scale. (Notably, it stops being non-degenerate well-formed.) By contrast, the 5-limit just diatonic scale is defined by two distinct parameters: the size of its major third and the size of its perfect fifth. See "Modal Color Theory," pp. 26-27, for more discussion.

Usage

howfree(set, ineqmat = NULL, edo = 12, rounder = 10)

Arguments

Details

The returned value is "essentialized," i.e. calculated by factoring out degrees of freedom that are universal to the given hyperplane arrangement. For instance, the set ⁠(0, 4, 8)⁠ has absolutely no room for variation in the black arrangement, as none of its pitches can move at all. Unsurprisingly, howfree(c(0, 4, 8), ineqmat="black") returns 0. But if we use the modal color theory arrangement, i.e. howfree(c(0, 4, 8), ineqmat="mct"), the result is still 0 even though for this arrangement we could transpose the augmented triad to start on any pitch without altering its scalar structure. For the MCT arrangement, chromatic transposition offers a degree of freedom that is essentially invisible to the arrangement, so howfree() doesn't report it in the value it returns for that arrangement. Similarly, the anaglyph arrangements (see make_anaglyph_ineqmat()) factor out transposition of each set individually, so howfree(..., inemqat="anaglyph") ignores two degrees of freedom.

Value

Single non-negative integer

Examples

c_natural_minor <- c(0, 2, 3, 5, 7, 8, 10)
c_melodic_minor <- c(0, 2, 3, 5, 7, 9, 11)
just_diatonic <- j(dia)
howfree(c_natural_minor)
howfree(c_melodic_minor)
howfree(just_diatonic)

howfree(c(0, 4, 7))
howfree(c(0, 4, 7), ineqmat="white")

howfree(c(0, 2, 6), ineqmat="mct")
howfree(c(0, 2, 6), ineqmat="roth")

Description

Ian Ring's website The Exciting Universe of Music Theory is a comprehensive and useful compilation of information about pitch-class sets in twelve-tone equal temperament. It tracks many properties that musicMCT is unlikely to duplicate, so this function opens the corresponding page for a pc-set in your browser. This only works for sets in 12-edo which include pitch-class 0.

Usage

ianring(set, is_interactive = NULL)

Arguments

Value

Invisibly, the integer which Ring's site uses to index the input set. The main purpose of the function is its side effect of opening a page of Ring's site in a browser.

Examples

c_major <- c(0, 2, 4, 5, 7, 9, 11)
c_major_value <- ianring(c_major, is_interactive=FALSE)
print(c_major_value)
# And indeed you should find information about the major scale
# at https://ianring.com/musictheory/scales/2741


# Set is_interactive to TRUE below to open the website in a
# browser window.
ianring(c(0, 2, 3, 7, 8), is_interactive=FALSE)

Description

David Lewin's interval function (IFUNC) calculates all the intervals from some source set x to some goal set y. See Lewin, Generalized Musical Intervals and Transformations (New Haven, CT: Yale University Press, 1987), 88. Lewin's definition of the IFUNC depends on the GIS it applies to, but this package's ifunc() is less flexible. It uses only ordered pitch-class intervals as the group of IVLS to be measured. Its intervals can, however, be any continuous value and are not restricted to integers mod edo. The format of the result depends on whether non-integer intervals occur.

Usage

ifunc(
  x,
  y = NULL,
  edo = 12,
  rounder = 10,
  display_digits = 2,
  show_zeroes = TRUE
)

Arguments

Value

Numeric vector counting the number of occurrences of each interval. The names() of the result indicate which interval size is counted by each entry. If x and y both belong to a single mod edo universe (and show_zeroes=TRUE), the result is a vector of length edo and includes explicit 0 results for missing intervals. If x and y must be measured in continuous pitch-class space, no missing intervals are identified (since there would be infinitely many to list).

Examples

ifunc(c(0, 3, 7))
ifunc(c(0, 3, 7), c(0, 4, 7))
ifunc(c(0, 4, 7), c(0, 3, 7))

ifunc(c(0, 2, 4, 7, 9), show_zeroes=FALSE)

just_dia <- j(dia)
ifunc(just_dia)
ifunc(just_dia, display_digits=4)

# See Lewin, GMIT p. 89:
lewin_x <- c(4, 10)
lewin_y1 <- c(9, 1, 5)
lewin_y2 <- c(7, 11, 9)
isTRUE(all.equal(ifunc(lewin_x, lewin_y1), ifunc(lewin_x, lewin_y2)))
apply(cbind(lewin_y1, lewin_y2), 2, fortenum)

Description

The data file ineqmats represents the hyperplane arrangements at the core of Modal Color Theory as matrices containing the hyperplanes' normal vectors. See Appendix 1.2 of Sherrill (2025) for a discussion of the format of these matrices. The matrices can be generated on the fly by makeineqmat(), but for large computations it's faster simply to call on precalculated data rather than to run makeineqmat() many thousands of times. Thus the object ineqmats saves the inequality matrices for scales of cardinality 1-53, to be called upon by getineqmat().

Usage

ineqmats

Format

ineqmats A list with 53 entries. The nth entry of the list gives the inequality matrix for n-note scales. Each inequality matrix itself is an m by (n+1) matrix, where m is an element of OEIS A034828 (see Sherrill 2025, 40-42). The last column of the matrix contains an offset related to whether any of the generic intervals "wrap around the octave," as e.g. the third from 7 to 2 does in a heptachord. This column is linearly dependent on the previous n columns, which contain the coefficients of the hyperplane's normal vectors. That is, the first row of the matrix (dropping its last entry) is the normal vector for the first hyperplane of the arrangement, and so on.

Source

The data in ineqmats can be recreated with the command sapply(2:53, makeineqmat) and then appending integer(0) as the first element of the list (for the case of one-note scales which have no pairwise interval comparisons and therefore need a matrix of size 0).

Description

Produces scales of different colors which have equivalent scalar properties. The hyperplane arrangements of MCT have three types of symmetry, which allows us to find scales at different but equivalent points in the arrangement. Such scales will be nearly structurally identical in most senses although their specific intervals will be rather different. See details for a discussion of the symmetries involved.

Usage

ineqsym(set = NULL, a = 1, b = 0, card = NULL, involution = FALSE, edo = 12)

Arguments

Details

Two symmetries of the MCT hyperplane arrangement are familiar. One is modal "rotation": two modes of the same scale must have equivalent structures, by the defining relations of the theory. The parameter b controls these rotations. The second familiar symmetry is involution (see "Modal Color Theory," 32). Set parameter involution to TRUE to apply this symmetry. The more interesting symmetry of the MCT arrangements is controlled by parameter a. This symmetry allows us to permute the roles of the scale's generic intervals in its scalar makeup. For instance, non-degenerate well-formed scales (see iswellformed() are all generated by a particular generic interval. The familiar diatonic scale is generated by its generic fourths, whereas another well-formed scale like (0, 2, 3, 5, 6, 7, 9) in 10edo (with step-word LSLSSLS) is generated by its generic sixths. We can permute the hyperplanes of the heptachordal MCT arrangement so that the overall structure is preserved but the diatonic scale is mapped onto LSLSSLS. In general, the permutations of ineqsym() allow us to map any non-degenerate well-formed scale onto any other: they form an orbit under the symmetries of the space. This gives another sense in which "well-formedness" is a large family of scale structures. That sense generalizes to all scales, not just ones that are highly regular like well-formed scales.

In short, ineqsym() preserves many scalar properties, including:

• countsvzeroes() and svzero_fingerprint()

• howfree()

• ratio(), delta(), and eps()

• brightnessgraph() structure

• evenness()

• isgwf() and a fortiori iswellformed()

• Number and respective properties of adjacent colors

• spectrumcount() up to permutation of the values

Value

Numeric vector representing a scale of same length as set. Default parameters determine the identity symmetry and will return set itself. If set is left as its default NULL value, the function returns instead the card-by-card permutation matrix that implements the symmetry.

Examples

wt_plus_1 <- sc(7,33)
equiv_scale <- ineqsym(wt_plus_1, 3, 2)
both_scales <- cbind(wt_plus_1, equiv_scale)
freedoms <- apply(both_scales, 2, howfree)
evennesses <- round(apply(both_scales, 2, evenness), 3)
svzeroes <- apply(both_scales, 2, countsvzeroes)
ratios <- round(apply(both_scales, 2, ratio), 3)
spectra <- apply(apply(both_scales, 2, spectrumcount), 2, toString)
cbind(freedoms, evennesses, svzeroes, ratios, spectra)
brightnessgraph(wt_plus_1)
brightnessgraph(equiv_scale)

Description

As defined by Clough and Myerson 1986 (doi:10.1080/00029890.1986.11971924), an "interval spectrum" is a list of all the specific (or "chromatic") intervals that occur as instances of a single generic (or "diatonic") interval within some reference scale. For instance, in the usual diatonic scale, the generic interval 1 (a "step" in the scale) comes in two specific sizes: 1 semitone and 2 semitones. Therefore its interval spectrum $\langle 1 \rangle = \{ 1, 2 \}$. These functions calculates the spectrum for every generic interval within a set and return either a list of specific values in each spectrum or a summary of how many distinct values there are.

Usage

intervalspectrum(set, edo = 12, rounder = 10)

spectrumcount(set, edo = 12, rounder = 10)

Arguments

Value

intervalspectrum returns a list of length one less than length(set). The nth entry of the list represents the specific sizes of generic interval n. spectrumcount returns a vector that reports the length of each entry in that list (i.e. the number of distinct specific intervals for each generic interval).

Examples

intervalspectrum(sc(7,35))
qcm_fifth <- meantone_fifth()
qcm_dia <- sort(((0:6)*qcm_fifth)%%12)
intervalspectrum(qcm_dia)
just_dia <- 12 * log2(c(1, 9/8, 5/4, 4/3, 3/2, 5/3, 15/8))
intervalspectrum(just_dia)

spectrumcount(just_dia) # The just diatonic scale is trivalent.

# Melodic minor nearly has "Myhill's Property" except for its 3 sizes of fourth and fifth
spectrumcount(sc(7,34))

Description

Tests whether a scale has a generalized type of well formedness (pairwise or n-wise well formedness).

Usage

isgwf(set, stepword = NULL, allow_de = FALSE, edo = 12, rounder = 10)

Arguments

Details

David Clampitt's 1997 dissertation ("Pairwise Well-Formed Scales: Structural and Transformational Properties," SUNY Buffalo) offers a generalization of the notion of well-formedness from 1-dimensional structures with a single generator to 2-dimensional structures that mediate between two well-formed scales. Ongoing research suggests that this can be extended further to "n-wise" or "general" well-formedness, though n-wise well-formed scales are increasingly rare as n grows larger.

Value

Boolean: is the set n-wise well formed?

Examples

meantone_diatonic <- c(0, 2, 4, 5, 7, 9, 11)
just_diatonic <- j(dia)
some_weird_thing <- convert(c(0, 1, 3, 6, 8, 12, 14), 17, 12)
example_scales <- cbind(meantone_diatonic, just_diatonic, some_weird_thing)

apply(example_scales, 2, howfree)
apply(example_scales, 2, isgwf)

Description

Rothenberg (1978, doi:10.1007/BF01768477) identifies a potentially desirable trait for scales which he calls "propriety." Loosely speaking, a scale is proper if its specific intervals are well sorted in terms of the generic intervals they belong to. A scale is strictly proper if, given two generic sizes g and h such that g < h, every specific size corresponding to g is smaller than every specific size corresponding to h. A scale if improper if any specific size of g is larger than any specific size of h. An ambiguity occurs if any size of g equals any size of h: scales with ambiguities are weakly but not strictly proper.

Usage

isproper(set, strict = FALSE, edo = 12, rounder = 10)

has_contradiction(set, edo = 12, rounder = 10)

strictly_proper(set, edo = 12, rounder = 10)

Arguments

Value

Boolean which answers whether the input satisfies the property named by the function

See Also

make_roth_ineqmat() creates an ineqmat for a hyperplane arrangement that lets you explore propriety-related issues in finer detail.

Examples

c_major <- c(0, 2, 4, 5, 7, 9, 11)
has_contradiction(c_major)
strictly_proper(c_major)
isproper(c_major)
isproper(c_major, strict=TRUE)

isproper(j(dia), strict=TRUE)

pythagorean_diatonic <- sort(((0:6)*z(3/2))%%12)
isproper(pythagorean_diatonic)
has_contradiction(pythagorean_diatonic)

Description

Tests whether a scale has the property of "well-formedness" or "moment of symmetry."

Usage

iswellformed(set, stepword = NULL, allow_de = FALSE, edo = 12, rounder = 10)

Arguments

Details

The three concepts of "well-formedness," "Myhill's property," and "moment of symmetry" refer to nearly the same scalar property, generalizing one of the most important features of the familiar diatonic scale. See Clough, Engebretsen, and Kochavi (1999, 77; doi:10.2307/745921) for a useful discussion of their relationships. In short, except for a few edge cases, a scale possesses these properties if it is generated by copies of a single interval (as the Pythagorean diatonic is generated by the ratio 3:2) and all copies of the generator belong to the same generic interval (as the 3:2 generator of the diatonic always corresponds to a "fifth" within the scale). Such a structure typically means that all generic intervals come in 2 distinct sizes, which is the definition of "Myhill's property." An exception occurs if the generator manages to produce a perfectly even scale, e.g. when the whole tone scale is generated by 6 copies of 1/6 of the octave. Such a scale lacks Myhill's property and Carey & Clampitt (1989, 200; doi:10.2307/745935) call such cases "degenerate well-formed." Instead of Myhill's property, such scales have only 1 specific value in each intervalspectrum().

Clough, Engebretsen, and Kochavi define a related concept, distributionally even scales, which include the hexatonic and octatonic scales (Forte sc6-20 and sc8-28). Such scales are in some sense halfway between "degenerate" and "non-degenerate well-formed" because some of their interval spectra have 1 element while others have 2. From another perspective, distributionally even scales are non-degenerate well formed with a period smaller than the octave (e.g. as the hexatonic scales 1-3 step pattern repeats every third of an octave).

The term "moment of symmetry" refers to the non-degenerate well-formed scales and was coined by Erv Wilson 1975 (cited in Clough, Engebretsen, and Kochavi). It tends to be more widely used in microtonal music theory.

Scales with this property have considerably interesting voice-leading properties and are some of the most important landmarks in the geometry of MCT. See "Modal Color Theory," pp. 14, 17, 29, 33-34, and 36-37. A substantial portion of MCT amounts to an attempt to generalize ideas developed for MOS/NDWF scales to all scale structures.

Value

Boolean answering "Is the scale MOS (with equivalence interval equal to the period)?" (if allow_de=FALSE) or "Is the scale well-formed in any sense?" (if allow_de=TRUE).

Examples

iswellformed(sc(7, 35))
iswellformed(c(0, 2, 4, 6))
iswellformed(c(0, 1, 6, 7))
iswellformed(c(0, 1, 6, 7), allow_de=TRUE)
iswellformed(NULL, stepword=c(2, 2, 1, 2, 1, 2, 1))

Description

Is the pc-set inversionally symmetrical? That is, does it map onto itself under $T_n I$ for some appropriate $n$? isym() can return either TRUE/FALSE or an index of symmetry but defaults to the former. isym_index() is a simple wrapper for isym() that returns the latter. isym_degree() counts the total number of inversional symmetries (i.e. the number of distinct inversional axes of symmetry).

Usage

isym(set, return_index = FALSE, edo = 12, rounder = 10)

isym_index(set, ...)

isym_degree(set, ...)

Arguments

Details

isym() is evaluated by asking whether, for some appropriate rotation, the step-interval series of the given set is equal to the step-interval series of the set's inversion. This is designed to work for sets in continuous pc-space, not just integers mod k. Note also that this calculates abstract pitch-class symmetry, not potential symmetry in pitch space. (See the second example.)

Value

isym() returns the Boolean value from testing for symmetry, unless return_index=TRUE, in which case isym() and isym_index() return a numeric value for one index of inversion at which the set is symmetrical. If the set is not inversionally symmetrical, they will return NA. isym_degree() gives the degree of inversional symmetry.

Examples

#### Mod 12
isym(c(0, 1, 5, 8))
isym(c(0, 2, 4, 8))

#### Continuous Values
qcm_fifth <- meantone_fifth()
qcm_dia <- sort(((0:6)*qcm_fifth)%%12)
just_dia <- j(dia)
isym(qcm_dia)
isym(just_dia)

#### Rounding matters:
isym(qcm_dia, rounder=15)

### Index and Degree
hexatonic_scale <- c(0, 1, 4, 5, 8, 9)
isym_index(hexatonic_scale) # Only returns one suitable index
isym_degree(hexatonic_scale)

Description

The classic summary of a set's dyadic subset content from pitch-class set theory. The name ivec is short for interval-class vector.

Usage

ivec(set, edo = 12)

Arguments

Value

Numeric vector of length floor(edo/2)

Examples

ivec(c(0, 1, 4, 6))
ivec(c(0, 1, 3, 7))

#### Z-related sextuple in 24edo:
sextuple <- matrix(
  c(0, 1, 2, 6, 8, 10, 13, 16,
  0, 1, 3, 7, 9, 11, 12, 17,
  0, 1, 6, 8, 10, 13, 14, 16,
  0, 1, 7, 9, 11, 12, 15, 17,
  0, 1, 2, 4, 8, 10, 13, 18,
  0, 2, 3, 4, 8, 10, 15, 18), nrow=6, byrow=TRUE)
apply(sextuple, 1, ivec, edo=24) # The ic-vectors are the 6 identical columns of the output matrix

Description

It's not hard to define a just interval from a frequency ratio: it only requires an input like 12*log2(freq_ratio). That gets pretty tiresome if you're doing this a lot, though, so for convenience musicMCT includes a j() function (not related to Clough and Douthett's J function but it wishes it was). j() is designed to behave a lot like base R's c() in the way that you'd use it to define a scale (see the examples below). The inputs that this can take are limited and hard-coded, since there's no systematic way to define short hands for every potential just interval. In general, the logic is that individual digits refer to major intervals up from the tonic in the 5-limit just diatonic scale. The prefix "m" to a number (e.g. "m3") gives the equivalent minor version of the interval. If you just want the entire 5-limit diatonic, you can enter dia.

Usage

j(..., edo = 12)

Arguments

Value

Numeric vector representing the input just intervals converted to edo unit steps per octave

See Also

z() as a shortcut for 12*log2(x) when a just interval you need isn't defined for j().

Examples

major_triad <- j(1,3,5)
isTRUE(all.equal(major_triad, j(u, M3, "5")))

isTRUE(all.equal(j(dia), j(1,2,3,4,5,6,7)))

# How far is the twelve-equal major scale from the 5-limit just diatonic?
dist(rbind(c(0,2,4,5,7,9,11), j(dia)))

# Is 53-equal temperament a good approximation of the 5-limit just diatonic?
j(dia, edo=53)

Description

Voice leadings between members of a single set class are well characterized by the Modal Color Theory arrangements of makeineqmat(). Those arrangements do not tell the whole story for relationships between inequivalent sets. (For instance, under what circumstances are two brightnessgraph() structures equivalent when set and goal belong to different set classes?) Such relationships are described by the "anaglyph" arrangements produced by this function. (The name for the arrangements alludes to those 20th-century 3D movie glasses which produce a stereoscopic effect by using lenses of different colors for each eye. Like those glasses, the anaglyph arrangements "see" two scalar colors at once.)

Usage

make_anaglyph_ineqmat(card)

Arguments

Details

Note that, unlike for most other hyperplane arrangements, for anaglyph arrangements card is only half the size of the data you're working with, since anaglyph arrangements compare two sets of size card. In general, when using anaglyph ineqmats with other functions, such as signvector() or howfree(), you should enter the two sets to be compared as a single vector, i.e. c(set, goal). See the use of howfree() in the example.

Value

A matrix with 2*card+1 columns and k rows, where k is either 4 times an entry of A050509 in the OEIS if card is even, or an entry of A033594 if card is odd.

Examples

min7 <- c(0, 3, 7, 10)
maj7 <- c(0, 4, 7, 11)
just_min7 <- j(1, m3, 5, m7)
just_maj7 <- j(1, 3, 5, 7)

# The 12tet and just pairs have the same anaglyph signvector:
anaglyph_tetrachords <- make_anaglyph_ineqmat(4)
signvector(c(min7, maj7), ineqmat=anaglyph_tetrachords)
signvector(c(just_min7, just_maj7), ineqmat=anaglyph_tetrachords)

# They therefore have equivalent brightness graphs:
brightnessgraph(min7, maj7)
brightnessgraph(just_min7, just_maj7)

# The pair is able to vary along two dimensions in anaglyph space:
howfree(c(min7, maj7), ineqmat="anaglyph")

Description

The "black" hyperplane arrangement compares a set's scale degrees individually to the pitches of edoo(card) (where card is the number of notes in set). This primarily has the purpose of attending to the overall transposition level of a set. Most applications of Modal Color Theory assume transpositional equivalence, but occasionally it is useful to relax that assumption. Sum class (Straus 2018, doi:10.1215/00222909-7127694) is a natural way to track this information, but the "black" arrangements do so qualitatively in the spirit of modal color theory. make_black_ineqmat() returns only the inequality matrix for the "black" arrangement, while make_gray_ineqmat() for convenience combines the results of make_white_ineqmat() and make_black_ineqmat().

Usage

make_black_ineqmat(card)

make_gray_ineqmat(card)

Arguments

Value

A card by card+1 inequality matrix (for make_black_ineqmat()) or the result of combining white and black inequality matrices (in that order) for make_gray_ineqmat().

See Also

make_white_ineqmat()

Examples

# The set (1, 4, 7)'s elements are respectively below, equal to, and
# above the pitches of edoo(3).
test_set <- c(1, 4, 7)
signvector(test_set, ineqmat=make_black_ineqmat(3))

# The result changes if you transpose test_set down a semitone:
signvector(test_set - 1, ineqmat=make_black_ineqmat(3))

# The results from signvector(..., ineqmat=make_black_ineqmat) can
# also be calculated with coord_to_edo():
sign(coord_to_edo(test_set))
sign(coord_to_edo(test_set - 1))

Description

The "infrared" hyperplane arrangements are in some sense an extension of the "pastel" arrangements to be more like the Rothenberg arrangements. (This is the sense of the color-conceit name for the arrangements: they contain red-like colors that we don't see in ordinary use of modal color theory.) That is, the infrared arrangement for a given color contains all the pastel hyperplanes (except those filtered out when include_wraparound=FALSE), plus additional ones that make comparisons between generic intervals of different sizes (as the Rothenberg arrangements do). Unlike the Rothenberg arrangements, however, the infrared arrangments are central: every hyperplane passes through the "origin" generated by edoo(). It should be the case that every infrared hyperplane either belongs to the pastel arrangement or is parallel to one in a Rothenberg arrangement. This family of arrangements is conceived primarily for the study of voice leadings rather than scales themselves.

Usage

make_infrared_ineqmat(card, include_wraparound = TRUE)

Arguments

Details

These arrangements are still somewhat experimental and may change. In particular, the ordering of hyperplanes currently is inconsistent between settings for include_wraparound.

Value

A matrix with card+1 columns and k rows (where k is the number of hyperplanes in the arrangement). When include_wraparound=TRUE, k is the cardth doubly triangular number.

See Also

make_pastel_ineqmat() and make_roth_ineqmat()

Examples

# To see the effect of "include_wraparound" param, compare to
# pastel arrangements:
make_pastel_ineqmat(3)
make_infrared_ineqmat(3)
make_infrared_ineqmat(3, include_wraparound=FALSE)

# In general, infrared arrangements are more complicated than pastel:
make_pastel_ineqmat(4)
make_infrared_ineqmat(4, include_wraparound=TRUE)

Description

By default, the various hyperplane arrangements of musicMCT treat the "white" perfectly even scale as their center. (It is the point where all the hyperplanes of the MCT, white, and black arrangements intersect, and although the Rothenberg arrangements do not pass through the scale by definition, it is still a center of symmetry for them.) This function let you construct hyperplane arrangements that have been shifted to treat any other set as their center. (Details on why you might want this to come.)

Usage

make_offset_ineqmat(set, ineqmat = NULL, edo = 12)

Arguments

Value

A matrix with the same shape as the ones that define the standard arrangement of type ineqmat

See Also

makeineqmat() for modal color theory arrangements; make_white_ineqmat(), make_black_ineqmat(), and make_roth_ineqmat() for other relevant arrangements.

Examples

# When used for the sign vector with any central arrangement, the
# input `set` will have a sign vector of all 0s:
viennese_trichord <- c(0, 1, 6)
signvector(viennese_trichord, ineqmat=make_offset_ineqmat(viennese_trichord))

# Where does melodic minor lie in relation to major?
major <- c(0, 2, 4, 5, 7, 9, 11)
melmin <- c(0, 2, 3, 5, 7, 9, 11)
signvector(melmin, ineqmat=make_offset_ineqmat(major, ineqmat="white"))

Description

Although the Rothenberg propriety of a single scale can be computed directly with isproper(), propriety is a scalar feature (like modal "color") which is defined by a scale's position in the geometry of continuous pc-set space. That is, propriety, contradictions, and ambiguities are all determined by a scale's relationship to a hyperplane arrangement, but the arrangements which define these properties are different from the ones of Modal Color Theory. make_roth_ineqmat() creates the ineqmats needed to study those arrangements, similar to what makeineqmat() does for MCT arrangements. make_rosy_ineqmat() creates the combination of Rothenberg and MCT arrangements. (The name puns on the "Roth" of Rothenberg meaning "red," lending a reddish or rosy tint to the "colors" of the MCT arrangement.)

Each row of a Rothenberg ineqmat represents a hyperplane, just like the rows produced by makeineqmat(). The rows are normalized so that their first non-zero entry is either 1 or -1, and their orientations are assigned so that a strictly proper set will return only -1s for its sign vector relative to the Rothenberg arrangement. A 0 in a Rothenberg sign vector represents an ambiguity. Note that the Rothenberg arrangements are never "central," which means that the hyperplanes do not all intersect at the perfectly even scale. (It is clear that they must not, because perfectly even scales have no ambiguities.) These arrangements also grow in complexity much faster than the MCT arrangements do: for tetrachords, MCT arrangements have 8 hyperplanes while Rothenberg arrangements have 22. For heptachords, those numbers increase to 42 and 259, respectively. Thus, this function runs slowly when called on cardinalities of only modest size (e.g. 12-24). Matrices for cardinalities up through 24 have been precomputed and are stored in roth_ineqmats; get_roth_ineqmat() attempts to access them from that file rather than generating them from scratch.

Usage

make_roth_ineqmat(card)

get_roth_ineqmat(card)

make_rosy_ineqmat(card)

Arguments

Value

A matrix with card+1 columns and k rows, where k is the number of hyperplanes in the arrangement.

Examples

c_major <- c(0, 2, 4, 5, 7, 9, 11)
hepta_roth_ineqmat <- make_roth_ineqmat(7)
isproper(c_major)
cmaj_roth_sv <- signvector(c_major, ineqmat=hepta_roth_ineqmat)
table(cmaj_roth_sv)
hepta_roth_ineqmat[which(cmaj_roth_sv==0),] 
# This reveals that c_major has one ambiguity, which results from
# the interval from 4 to 7 being exactly half an octave.

Description

Although the hyperplane arrangements of Modal Color Theory determine most scalar properties, there are some potentially interesting questions which require different arrangements. This function makes "white" arrangements which consider how many of a scale's intervals correspond exactly to the "white" or perfectly even color for their generic size. That is, for an interval x belonging to generic size g in an n note scale, does $x = g \cdot \frac{edo}{n}$? This may be relevant, for instance, because two modes have identical sum brightnesses when the interval that separates their tonics is "white" in this way. Mostly you will want to use these matrices as inputs to functions with an ineqmat parameter.

In many cases, it is desirable to use a combination of the MCT ineqmat from makeineqmat() and the quasi-white ineqmat from make_white_ineqmat(). Generally these are distinct, but they do have some shared hyperplanes in even cardinalities related to formal tritones (intervals that divide the scale exactly in half). Therefore, the function make_pastel_ineqmat() exists to give the result of combining them with duplicates removed. (The moniker "pastel" is meant to suggest combining the colors of MCT arrangements with a white pigment from white arrangements.)

Just as the MCT arrangements are concretized by the files "representative_scales" and "representative_signvectors," the white and pastel arrangements are represented by offwhite_scales, offwhite_signvectors, pastel_scales, and pastel_signvectors. This data has not been as thoroughly vetted as the files for the MCT arrangements, and currently white and pastel arrangements are only represented up through cardinality 6. The files are hosted at the modalcolortheory repo like representative_scales because they are too large to include in musicMCT.

Usage

make_white_ineqmat(card)

make_pastel_ineqmat(card)

Arguments

Value

A matrix with card+1 columns and k rows, where k is the nth triangular number

Examples

major_triad <- c(0, 4, 7)
howfree(major_triad)
howfree(major_triad, ineqmat=make_white_ineqmat(3))
# Because it's now constrained to preserve its step of exactly 1/3 the octave.

just_major_triad <- j(1, 3, 5)
howfree(just_major_triad)
howfree(just_major_triad, ineqmat=make_white_ineqmat(3))
# Because this triad's major third isn't identical to 400 cents which equally
# divide the octave.

ait1 <- c(0, 1, 4, 6)
quantize_color(ait1, reconvert=TRUE)
# quantize_color() doesn't match (0146) exactly because it's only looking for
# any set in the same 3-dimensional color as 0146.

quantize_color(ait1, ineqmat=make_white_ineqmat(4), reconvert=TRUE)
# Now that it's constrained to respect ait1's minor third from 1 to 4, the set 0146
# is now the first satisfactory result that quantize_color() finds.

Description

As described in Appendix 1.2 of "Modal Color Theory," information about the defining hyperplane arrangements is stored as a matrix containing the hyperplanes' normal vectors as rows. (Because these are matrices and they correspond ultimately to the intervallic inequalities that define MCT geometry, this package refers to them as ineqmats, and sometimes to the individual hyperplanes as ineqs.) These have already been computed and are stored as data in this package (ineqmats) for cardinalities up to 53, but they can be recreated from scratch with makeineqmat. This might be useful if for some reason you need to deal with a huge scale and therefore want to use an arrangement whose matrix isn't already saved. Note that a call like makeineqmat(60) may take a dozen or more seconds to run (and at sizes that large, the arrangement is terribly complex, with ~17K distinct hyperplanes).

getineqmat tests whether the matrix already exists for the desired cardinality. If so, it is retrieved; if not, it is created using makeineqmat.

Usage

makeineqmat(card)

getineqmat(card)

Arguments

Value

A matrix with card+1 columns and roughly card^(3)/8 rows

Examples

makeineqmat(2) # Simple: is step 1 > step 2?
makeineqmat(3) # Simple: step 1 > step 2? step 1 > step 3? step 2 > step 3?
makeineqmat(7) # Okay...
ineqmat20 <- makeineqmat(20)
dim(ineqmat20) # Yikes!

Description

Scales which are "maximally even" divisions of some equal-tempered universe have several musically interesting properties. When a maximally even scale has a number of notes (card) that is coprime to the size of the equal-tempered universe, the maximally even scale is called a "non-degenerate well-formed" or "moment of symmetry" scale. When its size divides the equal temperament, it is a perfectly even scale. When it is neither coprime nor a divisor, it produces a scale with a structure like the octatonic (i.e. a union of perfectly even scales, or a well-formed scale with a period smaller than the octave). The scale is generated by quantizing a perfectly even scale to the chosen chromatic cardinality. Two quantization options are offered (rounding down and rounding to the nearest value).

Usage

maxeven(card, edo = 12, floor = TRUE)

Arguments

Value

Numeric vector of length card representing a scale of card notes.

Examples

maxeven(7, 12)
maxeven(6, 15)
maxeven(6, 15, floor=FALSE)

diatonic_in_19 <- maxeven(7, 19)
tresillo <- maxeven(3,8)

Description

Creates an interval that approximates a pure 3:2 fifth which has been tempered smaller by some fraction of a syntonic comma, making it easy to construct diatonic meantone scales. The default is to create a quarter-comma meantone fifth (i.e. about 697 cents).

Usage

meantone_fifth(frac = 1/4)

Arguments

Value

Single numeric value of the tempered fifth measured in 12edo semitones.

Examples

zarlino_fifth <- meantone_fifth(2/7)
zarlino_diatonic <- sort((0:6 * zarlino_fifth) %% 12)
print(zarlino_diatonic)

fifth_in_19edo <- convert(11, 19, 12)
meantone_fifth(1/3) - fifth_in_19edo

Description

Given a source set and a goal to move to, find the voice leading from source to goal with smallest size.

Usage

minimize_vl(
  source,
  goal,
  method = c("taxicab", "euclidean", "chebyshev", "hamming"),
  no_ties = FALSE,
  edo = 12,
  rounder = 10
)

Arguments

Details

Unless method="hamming", it is assumed that the minimal voice leading should be strongly crossing-free, so you might get strange results if your source and goal are not both in ascending order.

Using method="hamming" in principle should only care about preserving common tones, with no other restrictions on how voices move. This gives a profusion of tied voice leadings, which is not generally useful. This function therefore eliminates many of the options by requiring that the voices which aren't common tones make a minimal voice leading by the taxicab metric. Nevertheless, for multisets, method="hamming" can still return many tied possibilities.

Value

Numeric array. In most cases, a vector the same length as source; or a vector of NA the same length as source if goal and source have different lengths. If no_ties=FALSE and multiple voice leadings are equivalent, the array can be a matrix with m rows where m is the number of equally small voice leadings.

Examples

c_major <- c(0, 4, 7)
ab_minor <- c(8, 11, 3)
minimize_vl(c_major, ab_minor)

diatonic_scale <- c(0, 2, 4, 5, 7, 9, 11)
minimize_vl(diatonic_scale, tn(diatonic_scale, 7))

d_major <- c(2, 6, 9)
minimize_vl(c_major, d_major)
minimize_vl(c_major, d_major, no_ties=TRUE)
minimize_vl(c_major, d_major, method="euclidean", no_ties=FALSE)

minimize_vl(c(0, 4, 7, 10), c(7, 7, 11, 2), method="euclidean")
minimize_vl(c(0, 4, 7, 10), c(7, 7, 11, 2), method="euclidean", no_ties=TRUE)

natural_hexachord <- c(0, 2, 4, 5, 7, 9)
hard_hexachord <- c(7, 9, 11, 0, 2, 4)
minimize_vl(natural_hexachord, hard_hexachord, method="hamming")

Description

Often, the elementary voice leadings of a set (given by vlsig()) can be broken into two intermediate voice leadings through a different set (i.e. ones given by inter_vlsig() with some suitable choice of goal). A classic example is the voice leading (0, 1, 2) that takes C major (C, E, G) to F major (C, F, A). This voice leading is elementary for major triads, but it can be decomposed into the succession of Neo-Riemannian voice leadings R-then-L by passing through a minor triad. Such decompositions are not always possible, though: given a choice of set and goal classes, sometimes the elementary path from one mode of set to another does not pass through any mode of goal. Such a voice leading is "monochrome" in the sense that it uses the restricted palette of the modes of a single set.

Usage

monochrome_vl(
  set,
  goal = NULL,
  bool = FALSE,
  display_digits = 2,
  edo = 12,
  rounder = 10
)

Arguments

Value

If bool=FALSE, a voice-leading matrix formatted after inter_vlsig(). If bool=TRUE, a single Boolean value indicating whether any monochrome voice leadings exist for set and goal.

Examples

maj7 <- c(0, 4, 7, 11)
mM7 <- c(0, 3, 7, 11)

# Just a few basic transformations lead between these seventh chords:
inter_vlsig(maj7, mM7)
inter_vlsig(mM7, maj7)

# But we can see from their brightness graph that modes III and I of maj7
# have no intermediate voice leading that involves the minor-major seventh:
brightnessgraph(maj7, mM7)

# monochrome_vl detects this voice leading:
monochrome_vl(maj7, mM7)

# Note that the equivalent does not apply to the minor-major seventh, which always
# has some mode of the major 7th chord decomposing its elementary voice leadings:
monochrome_vl(mM7, maj7)

# Finally, note that the presence of monochrome voice leadings is dependent on 
# the pair of chord types you choose, not simply the "set." For instance, we can 
# define a chord that will decompose the voice leading from mode III to mode I 
# of the major 7th:
dom7 <- c(0, 4, 7, 10)
monochrome_vl(maj7, dom7)
brightnessgraph(maj7, dom7)

Description

Navigate scale space by finding the point where a given line intersects with a given hyperplane. Hyperplanes are specified by the row and ineqmat parameters. That is, the hyperplane is given by the rowth row of the specified ineqmat. An arbitrary hyperplane can be specified by entering row=1 with the desired hyperplane as a 1-row matrix as the input to ineqmat.

For the line, two different use cases are available. In the first, set is specified. In this case, the line in question is the given set's "hue" (i.e., the line which runs from edoo() to set). This is useful when exploring non-central arrangements such as the Rothenberg arrangements (make_roth_ineqmat()); for an arrangement centered on edoo(), it will simply return edoo(). In the second, set is left NULL and both point and direction must be specified. Here, the given line is the one which runs through point parallel to the vector specified by direction.

Usage

move_to_hyperplane(
  row,
  set = NULL,
  point = NULL,
  direction = NULL,
  ineqmat = NULL,
  method = c("taxicab", "euclidean", "chebyshev", "hamming"),
  edo = 12,
  rounder = 10
)

Arguments

Value

A list with three entries: set, dist, and sign. set is a numeric vector with the intersection point of the given line and hyperplane. dist gives the voice-leading distance (as measured using method) from input set or point to the result set. sign indicates whether the intersection point lies along the given direction or opposite it. (For instance, when a hue is specified by input set, a positive sign indicates that the intersection belongs to the same color as input set, whereas a negative sign indicates that the intersection is a scalar involution of the input.)

If the line lies entirely on the given hyperplane, the returned set simply matches the input, while dist and sign are 0. If the line and hyperplane do not intersect, the result set is a vector of NAs the same length as the input set or point; dist is Inf and sign is NA. In both of these cases, a warning is given.

Examples

major_triad <- c(0, 4, 7)
# Let's find where the major triad's hue first intersects a Rothenberg hyperplane:
move_to_hyperplane(3, set=major_triad, ineqmat="roth")
same_hue(major_triad, c(0, 4, 6))
strictly_proper(major_triad)
strictly_proper(c(0, 4, 6))

# But the major triad's hue intersects every MCT hyperplane at the center of the space:
move_to_hyperplane(3, set=major_triad, ineqmat="mct")

# Let's move away from the major triad in other directions than its hue:
lower_third <- c(0, -1, 0)
move_to_hyperplane(1, point=major_triad, direction=lower_third)
move_to_hyperplane(2, point=major_triad, direction=lower_third)
move_to_hyperplane(3, point=major_triad, direction=lower_third)

Description

Following Hook (2023, 416-18, ISBN: 9780190246013), calculates a normal form for the input set using any combination of OPTIC symmetries.

Usage

normal_form(set, optic = "opc", edo = 12, rounder = 10)

Arguments

Details

This function is designed for flexibility in the optic parameter, not speed. In situations where you need to calculate a large number of OPTIC- or OPTC-normal forms, you should use primeform() or tnprime() respectively, which are considerably faster.

Value

Numeric vector with the desired normal form of set

See Also

primeform(), tnprime(), and startzero() for faster functions dedicated to specific symmetry combinations

Examples

# See Exercise 10.4.8 in Hook (2023, 420):
eroica <- c(-25, -13, -6, -3, 0, 3)
normal_form(eroica, optic="pti")
normal_form(eroica, optic="op")

# See Table 10.4.1 in Hook (2023, 417):
alpha <- c(-5, -11, 14, 9, 14, 14, 2)
num_symmetries <- sample(0:5, 1)
random_symmetries <- sample(c("o", "p", "t", "i", "c"), num_symmetries)
random_symmetries <- paste(random_symmetries, collapse="")
print(random_symmetries)
normal_form(alpha, optic=random_symmetries)

Description

Modal Color Theory is capable of describing "scales" (perhaps "melodies" might be more accurate) which do all sorts of non-scalar things, like repeating notes, ascending and descending inconsistently, not observing octave equivalence, and so on. This function tests whether an input has a 'well-behaved' form in that it starts on 0, only ascends, doesn't repeat pitches, and doesn't go above the octave. If you find an interesting scale structure represented by a set that doesn't satisfy these constraints, you can always desaturate it until it does (i.e. call something like saturate(.1, my_scale_with_bad_OPTCs)).

Usage

optc_test(set, edo = 12, rounder = 10, single_answer = TRUE)

Arguments

Value

Either a single Boolean value or a vector of 4 Boolean values, depending on the single_answer argument.

Examples

major_triad_normal_form <- c(0, 4, 7)
major_triad_open_spacing <- c(0, 7, 16)
major_triad_voice_crossing <- c(0, 7, 4)
major_triad_on_des <- c(1, 5, 8)
major_triad_doubled_third_omit_5 <- c(0, 4, 4)
example_triads <- cbind(major_triad_normal_form,
			   major_triad_open_spacing,
			   major_triad_voice_crossing,
			   major_triad_on_des,
			   major_triad_doubled_third_omit_5)

apply(example_triads, 2, optc_test)
optc_test(major_triad_voice_crossing, single_answer=FALSE)

Description

Given a hyperplane arrangement (specified by ineqmat) and a subset of those hyperplanes (specified numerically as the rows of ineqmat), determine some point that lies on the intersection of those hyperplanes. If the chosen hyperplanes do not all intersect in at least one point, returns NAs and throws a warning. This function exists mostly for the sake of calculations about a hyperplane arrangement itself, not for musical applications: its results are often not very scale-like (e.g., they often fail optc_test()).

Usage

point_on_flat(rows, card, ineqmat = NULL, edo = 12, rounder = 10)

Arguments

Value

Numeric vector of length card which lies on the specified hyperplanes. If the intersection of the hyperplanes is empty, throws a warning and returns a vector of NAs with length card.

See Also

match_flat() and populate_flat() are intended for more concretely musical applications, returning a set on the chosen flat which is similar to an input set.

Examples

# Works essentially like an inverse of whichsvzeroes():
test_set <- sc(5, 32)
whichsvzeroes(test_set)
generated_point <- point_on_flat(c(5, 8, 10), card=5)
whichsvzeroes(generated_point)

# But note that the given point might lie on any face of the flat:
signvector(test_set)
signvector(generated_point)

# Works for other hyperplane arrangements:
point_on_flat(c(2, 3, 6), card=3, ineqmat="roth")
point_on_flat(c(2, 4), card=4, ineqmat="black")

# Not all combinations of hyperplanes admit a solution:
try(point_on_flat(c(1, 2, 3), card=3, ineqmat="roth"))

Description

Sometimes it's useful to explore a flat or a color by testing small differences that result from different positions within the flat. This function generates random points on the desired flat to test, similar to surround_set() but constrained to lie on a target flat. Requires a base set that serves as an "origin" around which the random scales are to be generated (before being projected onto the target flat).

Usage

populate_flat(
  set,
  target_scale = NULL,
  target_rows = NULL,
  start_zero = TRUE,
  ineqmat = NULL,
  edo = 12,
  rounder = 10,
  magnitude = 2,
  distance = 1
)

Arguments

Details

The target flat can be specified by naming the target_rows that determine the flat (in the manner of project_onto()) or by naming a target_scale on the desired flat. Both parameters default to NULL, in which case the function populates the flat that set itself lies on.

Value

A matrix whose columns represent scales on the desired flat. The matrix has n rows (where n is the number of notes in set) and n * 10^magnitude columns.

Examples

# Let's sample several scales on the same flat as j(dia):
major <- c(0, 2, 4, 5, 7, 9, 11)
jdia_flat_scales <- populate_flat(major, j(dia))
unique(apply(jdia_flat_scales, 2, whichsvzeroes), MARGIN=2)

# So all the scales do lie on one flat, but they may be different colors.
# Let's plot them using different literal colors to represent the scalar "colors."
jdia_flat_svs <- apply(apply(jdia_flat_scales, 2, signvector), 2, toString)
unique_svs <- sort(unique(jdia_flat_svs))
match_sv <- function(sv) which(unique_svs == sv)
sv_colors <- grDevices::hcl.colors(length(unique_svs), 
                                   palette="Green-Orange")[sapply(jdia_flat_svs, match_sv)]
plot(jdia_flat_scales[2,], jdia_flat_scales[3,], pch=20, col=sv_colors,
  xlab = "Height of scale degree 2", ylab = "Height of scale degree 3",
  asp=1)
abline(0, 2, lty="dashed", lwd=2)
points(j(2), j(3), cex=2, pch="x")
points(2, 4, cex=2, pch="o")

# Most of our sampled sets belong to two colors separated by the dashed
# line on the plot. The dashed line represents the inequality that determines 
# the size of a scale's second step in relation to its first step. This is
# hyperplane #1 in the space, so it corresponds to the first entry in each 
# scale's sign vector. The point labeled "x" represents the just diatonic scale 
# itself, which has a larger first step than second step. The point labeled 
# "o" represents the 12-equal diatonic, whose whole steps are all equal and which 
# therefore lies directly on hyperplane #1. Finally, note that our sampled scales
# also touch on a few other colors at the bottom & left fringes of the scatter plot.

Description

In traditional pitch-class set theory, concepts like normal order and primeform() establish a canonical representative for each equivalence class of pitch-class sets. It's useful to do something similar in MCT as well: given a family of scales, such as the collection of modes or a scale_palette(), we can define the "primary color" of the family as the one that comes first when the scales' sign vectors are ordered lexicographically. primary_hue() uses ineqsym() to return a specific representative of the primary color which belongs to the same palette of hues as the input. Because primary_hue() focuses on hues rather than colors, it may not highlight the fact that two scales have the same primary color. Thus, for information about broader families, primary_colornum() returns the color number of the primary color, primary_signvector() returns the sign vector, and primary_color() itself uses quantize_color() to return a consistent representative of each color.

Usage

primary_hue(
  set,
  type = c("all", "half_palette", "modes"),
  ineqmat = NULL,
  edo = 12,
  rounder = 10
)

primary_colornum(set, type = "all", signvector_list = NULL, ...)

primary_signvector(set, type = "all", ...)

primary_color(set, type = "all", nmax = 12, reconvert = FALSE, ...)

Arguments

Value

A numeric vector representing a scale for primary_hue(); a single integer for primary_colornum(); a signvector() for primary_signvector(); and a list like quantize_color() for primary_color().

Examples

major_64 <- c(0, 5, 9)
primary_hue(major_64)
primary_hue(major_64, type="modes")

viennese_trichord <- c(0, 6, 11)
# Same primary color as major_64:
apply(cbind(major_64, viennese_trichord), 2, primary_signvector)

# But a different primary hue:
primary_hue(viennese_trichord)

# Only works with representative_signvectors loaded:
primary_colornum(major_64) == primary_colornum(viennese_trichord)

primary_color(major_64)
primary_color(viennese_trichord)

Description

Takes a set (in any order, inversion, and transposition) and returns the canonical ("prime") form that represents the $T_n /T_n I$-type to which the set belongs. Uses the algorithm from Rahn 1980 rather than Forte 1973.

Usage

primeform(set, edo = 12, rounder = 10)

Arguments

Details

In principle this should work for sets in continuous pitch-class space, not just those in a mod k universe. But watch out for rounding errors: if you can manage to work with integer values, that's probably safer. Otherwise, try rounding your set to various decimal places to test for consistency of result.

Value

Numeric vector of same length as set

Examples

primeform(c(0, 3, 4, 8))
primeform(c(0, 1, 3, 7, 8))
primeform(c(0, 3, 6, 9, 12, 14), edo=16)

Description

Projects a scale onto the nearest point that lies on a target flat of the hyperplane arrangement. project_onto() determines the target flat from a list of linearly independent rows in ineqmat which define the flat. match_flat() determines the target by extrapolating from a given scale on that flat. Note that while the projection lies on the desired flat (i.e. it will have all of the necessary 0s in its sign vector), it will not necessarily belong to any particular color. (That is, projection doesn't give you control over the 1s and -1s of the sign vector.)

Usage

project_onto(
  set,
  target_rows,
  ineqmat = NULL,
  start_zero = TRUE,
  edo = 12,
  rounder = 10
)

match_flat(
  set,
  target_scale,
  start_zero = TRUE,
  ineqmat = NULL,
  edo = 12,
  rounder = 10
)

Arguments

Value

A numeric vector of same length as set, representing the projection of set onto the flat determined by target_rows or target_scale.

Examples

minor_triad <- c(0, 3, 7)
project_onto(minor_triad, 3)
project_onto(minor_triad, 1)
project_onto(minor_triad, c(1, 3))
# This last projection results in the perfectly even scale
# because that's the only scale on both hyperplanes 1 and 3.

major_scale <- c(0, 2, 4, 5, 7, 9, 11)
projected_just_dia <- match_flat(j(dia), major_scale)
print(projected_just_dia)

# This is very close to fifth-comma meantone:
fifth_comma_meantone <- sim(sort(((0:6) * meantone_fifth(1/5))%%12))[,5]
vl_dist(projected_just_dia, fifth_comma_meantone)

Description

Modal Color Theory is able to analyze scales in continuous pitch-class space, but sometimes irrational values can be inconvenient to work with. Therefore it's often quite useful to find a scale that has the same color as the one you're studying, but which can be represented by integers in some mod k universe. See "Modal Color Theory," 27.

Usage

quantize_color(
  set,
  nmax = 12,
  reconvert = FALSE,
  ineqmat = NULL,
  target_edo = NULL,
  edo = 12,
  rounder = 10
)

Arguments

Value

If reconvert=FALSE, a list of two elements: element 1 is set with a vector of integers representing the quantized scale; element 2 is edo representing the number k of unit steps in the mod k universe. If reconvert=TRUE, returns a single numeric vector measured relative to the unit step size input as edo: these generally will not be integers. Values may be NA if no suitable quantization was found beneath the limit given by nmax or in target_edo (if specified).

Examples

qcm_fifth <- meantone_fifth()
qcm_lydian <- sort(((0:6)*qcm_fifth)%%12)
quantize_color(qcm_lydian)

# Let's approximate the Werckmeister III well-temperament
werck_ratios <- c(1, 256/243, 64*sqrt(2)/81, 32/27, (256/243)*2^(1/4), 4/3, 
  1024/729, (8/9)*2^(3/4), 128/81, (1024/729)*2^(1/4), 16/9, (128/81)*2^(1/4))
werck3 <- z(werck_ratios)
quantize_color(werck3)
quantize_color(werck3, reconvert=TRUE)

quantize_color(j(dia))
quantize_color(j(dia), target_edo=22)

Description

Given any scale, this function attempts to find a scale defined as integers mod k which belongs to the same hue as the input (i.e. would return TRUE when same_hue() is applied). This function thus is similar in spirit to quantize_color() but seeks a more precise structural match between input and quantization. Note, though, that while quantize_color() should always be able to find a suitable quantization (if nmax is set high enough), this is not necessarily true for quantize_hue(). There are lines in $\mathbb{R}^n$ which pass through no rational points but the origin, so some hues (including ones of musical interest like the 5-limit just diatonic scale) may not have any quantization.

Usage

quantize_hue(
  set,
  nmax = 12,
  reconvert = FALSE,
  target_edo = NULL,
  edo = 12,
  rounder = 10
)

Arguments

Value

If reconvert=FALSE, a list of two elements: element 1 is set with a vector of integers representing the quantized scale; element 2 is edo representing the number k of unit steps in the mod k universe. If reconvert=TRUE, returns a single numeric vector measured relative to the unit step size input as edo: these generally will not be integers. Values may be NA if no suitable quantization was found beneath the limit given by nmax or in target_edo (if specified).

Examples

meantone_diatonic <- sort(((0:6)*meantone_fifth())%%12)
quantize_hue(meantone_diatonic) # Succeeds
quantize_hue(j(dia), nmax=15) # Fails no matter how high you set nmax.

quasi_guido <- convert(c(0, 2, 4, 5, 7, 9), 13, 12)
quantize_color(quasi_guido)
quantize_hue(quasi_guido)

quantize_hue(c(0, 1, 4, 6))
quantize_hue(c(0, 1, 4, 6), target_edo=16)