scales                package:none                R Documentation

Scales fitting given criteria for a stringed instrument. Position of notes on a stringed instrument.

Description:

scales produces musical scales for a chosen tonic which fit certain criteria (notes to include, notes to exclude and type of scale), creates a matrix indicating the position of notes on the arm of a stringed instrument based on entry values for number of strings, number of frets and tuning, and returns a list of matrices with the positions of the notes on the arm created for each scale fitting the criteria. The resulting matrices represent tablatures for the scales. 
The user may choose to obtain note positions on the fretboard of an instrument with given numbers of strings and frets and a given tuning instead.
The function also produces a .txt file with the results in your working directory. This file is called "scales.txt" if the function is used to obtain tablatures for scales, or "instrument.txt" if the user chooses to obtain note positions on the fretboard of an instrument.

Usage:

scales(tonic=1,notes=tonic,except=F,region=c(0,frets),types="all",strings=6,tune=c(8,3,11,6,1,8),frets=15,grades=T)

Arguments:

tonic	numeric or character.				The tonic (first degree) of the scales to be returned by the function. May be given as a character representing the note in letter notation, using '#' for sharp and 'b' for flat (e.g "A", "F#" or "Gb") or as a number corresponding to a note, as follows: A=1, A# (or Bb)=2, B (or Cb)=3, C (or B#)=4, C# (or Db)=5, D=6, D# (or Eb)=7, E (or Fb)=8, F (or E#)=9, F# (or Gb)=10, G=11, G# (or Ab)=12.
							If you want to obtain note positions on the fretboard of an instrument only, use the (numeric) value 0 for tonic.
							The default value is '1', which returns scales in 'A' ('la').
				
notes	numeric or character.				Notes which MUST be included in the scales to be returned by the function. The tonic is obviously always included in the scales to be returned. May be given as a vector of type character, representing the notes in letter notation using '#' for sharp and 'b' for flat (e.g. c("B","F")) or as a vector of numbers corresponding to the notes, as explained in the argument 'tonic', above.
							The default is to include only the tonic.

except	numeric, character or FALSE			Notes NOT to be included in the scales to be returned by the function. May be given as a vector of type character, representing the notes in letter notation, using '#' for sharp and 'b' for flat (e.g. c("B", "C")) or as a vector of numbers corresponding to the notes, as explained in the argument 'tonic', above.
							If except=FALSE, all scales with the given 'tonic' including the notes given in 'notes' will be returned. This is the default for the function.

region	numeric vector of length=2			The region of the fretboard in which the scales returned are shown, given as a numeric vector with 2 elements corresponding to the first and last frets of the fretboard which should be shown (0 corresponds to open strings). Useful for users who wish to view possible ways to play scales on a particular region of an instrument.
							If the second element in this argument is larger than 'frets', the function will return an error message.

types	character					Specific scales ("scale types") to be returned by the function. Given as a character vector with the names of all types of scales to be returned. The scales currently included in the function (and which can therefore be included in vectors for this argument) and their names for entry in this argument are:
							Greek modes: "ionian" (=major tonal scale), "dorian", "phrygian", "lydian", "mixolydian", "eolian" (=natural minor tonal scale), "locrian";
							Other tonal scales: "harmonic", "melodic" (corresponds to ascending melodic minor scale, as the descending melodic minor is equivalent to the eolian mode);
							Pentatonic scales: "minorpentatonic", "majorpentatonic";
							Other heptatonic scales: "altered", "flamenco", "doubleharmonic"
							Hexatonic scales: "augmented", "blues" (corresponds to minor pentatonic with a 'blue note' on the #4th degree), "wholetone"
							Chromatic scale: "chromatic"
							If types="all", all scales with the given 'tonic' fitting the conditions in the 'notes' and 'exclude' arguments are returned. This is the default for this argument.

strings	numeric						The number of strings on the instrument for which the result should be shown. The default is 6 strings, as in a guitar (which is used as the 'default instrument' by this function).

tune	numeric or character vector of length=strings	The tuning to be used for each of the strings on the instrument for which the result should be shown, in order from the first string (i.e. highest pitched or thinnest) to the last string (i.e. lowest pitched or thickest). The tuning may be given as a vector of type character, representing the notes in letter notation using '#' for sharp and 'b' for flat (e.g. c("E","B","G","D","A","E")) or as a vector of numbers corresponding to the notes, as explained in the argument 'tonic', above.

frets	numeric						The number of frets on the instrument for which the result should be shown, or the maximum number of frets to be shown in the results. The default value is 15 frets. 
							Pay attention to the fact that too large a number of frets will cause the resulting matrices not to be shown in a single line (both in the output window and in the .txt files written), which may hamper in reading the results.

degrees	logical						If TRUE, the scales returned will show the corresponding Scale Degree ("I"=tonic, "II"=supertonic, "III"=mediant, "IV"=subdominant, "V"=dominant, "VI"=submediant, "VII"=leading tone/subtonic) at the positions corresponding to each note in the scale. This is the default for the function.
							If FALSE, the scales returned will simply show an "X" in all positions for notes included in the scale.


Details:

The numerical form of entry for the arguments 'tonic', 'notes', 'except' and 'tune' exist mostly as a result of the inner workings of the function. It is recommended (and much more intuitive) to use the character form to input these arguments.
For the matrices showing the scales to be clearly arranged and easily visible (both in the output panel and in the .txt files produced), it is recommended that the R console be expanded to an adequate width prior to running this function.
The "scales.txt" (for scale tablatures) or "instrument.txt" (for note positions on the fretboard of an instrument) files which are produced when running this function are always created with these names, so if you run the function a second time without moving or renaming the file created on the first run, the file produced during the second run will overwrite the file from the first run.

Value:

If 'tonic' is different from 0, scales returns a list with a number of components of class=matrix which corresponds to the number of scales which fit the criteria entered in the arguments 'notes', 'except' and 'types', to a maximum of 18 (the total number of scales currently included in the function).
The name of each component corresponds to the name of the scale it represents, as explained in the argument 'types', above.
If 'tonic'=0, scales returns a single matrix, corresponding to the positions of each note in the fretboard of an instrument with number of strings and frets and tuning as given in the arguments 'strings', 'frets' and 'tune'.
Each matrix in the list (for 'tonic' different from 0) or the single returned matrix (for 'tonic'=0) has nrow=strings, ncol=frets+1 (with open strings shown as "fret 0"). Row names correspond to the notes for each string (i.e. argument 'tune'), and column names correspond to the number of each fret ("fr 0", "fr 1", "fr n").

Warning:

Remember to use 'tonic=0' if you want to obtain just note positions in the fretboard.
If the user enters 'tonic=0', the function ignores all arguments other than 'strings', 'tune' and 'frets'.
Do not run this function while keeping console width too small. This will cause the matrices for scales in both the output window and the produced .txt file to be broken and shown in two or more rows, which hampers reading.
Remember to rename or move the .txt file produced after each run from the working directory before running this function again, as the function will overwrite files with the names "scales.txt" or "instrument.txt" after each run.
The function will return error messages if the user tries to input values not identified by the function in the arguments 'tonic', 'notes', 'except' or 'tune'. 
An error message will also be returned if no scales currently included in the function fit the conditions set by the user in the arguments 'notes', 'except' and/or 'types'.


Author(s):

Thiago Macek Gonçalves Zahn

thimacek@gmail.com


References:

Yamaguchi, Masaya. 2006. The Complete Thesaurus of Musical Scales, revised edition. New York: Masaya Music Services. ISBN 0-9676353-0-6.
http://en.wikipedia.org/wiki/List_of_musical_scales_and_modes


Examples:

scales(tonic="C",types=c("majorpentatonic","minorpentatonic")) ## Returns tablatures for major and minor pentatonic scales in C ('do') on a guitar (default instrument), indicating scale degrees.

scales(tonic="D#",except="C",strings=4,tune=c("G","D","A","E")) ## Returns tablatures for all D# ('re#') scales NOT including C ('do') on a bass guitar (4 stringed instrument with 'EADG' tuning).

scales(tonic="G",notes=c("C","D"),tune=c("D","B","G","D","G","G")) ## Returns tablatures for all G ('sol') scales including C ('do') and D ('re', dominant) on a guitar with an open G overtones tuning.

scales(tonic=0,strings=4,tune=c("E","A","D","G")) ## Returns position of notes on the fretboard of a violin (4 stringed instrument with tuning GDAE).