.. _usersGuide_07_chords:

.. WARNING: DO NOT EDIT THIS FILE:
   AUTOMATICALLY GENERATED.
   PLEASE EDIT THE .py FILE DIRECTLY.


User's Guide, Chapter 7: Chords
===============================


Chords, as the name might suggest, are objects that combine multiple
:class:`~music21.pitch.Pitch` objects on a single stem. They can be
found in the :ref:`moduleChord` module. The most general way to create
a :class:`~music21.chord.Chord` object is by passing in a list of
pitch names you want in the chord:

.. code:: python

    from music21 import *
    cMinor = chord.Chord(["C4","G4","E-5"]) 

``Note`` and ``Chord`` objects, since both are subclasses of the
:class:`~music21.note.GeneralNote` object share many features in
common:

.. code:: python

    cMinor.duration.type = 'half'
    cMinor.quarterLength




.. parsed-literal::
   :class: ipython-result

    2.0



But since a ``Chord`` contains many pitches, it does not have a
``.pitch`` attribute:

.. code:: python

    cMinor.pitch


::


    ---------------------------------------------------------------------------

    AttributeError                            Traceback (most recent call last)

    <ipython-input-4-682233136f94> in <module>()
    ----> 1 cMinor.pitch
    

    AttributeError: 'Chord' object has no attribute 'pitch'


Instead it has a :meth:`.pitches <music21.chord.Chord.pitches>`
attribute which returns a Tuple of pitches in the Chord.

.. code:: python

    cMinor.pitches




.. parsed-literal::
   :class: ipython-result

    (<music21.pitch.Pitch C4>, <music21.pitch.Pitch G4>, <music21.pitch.Pitch E-5>)



Okay, but you already knew what pitches were in the ``Chord`` since you
just created it! What else can you do with it?

How about determining if it is a
:meth:`major <music21.chord.Chord.isMajorTriad>` or a
:meth:`minor <music21.chord.Chord.isMinorTriad>` triad?

.. code:: python

    cMinor.isMajorTriad()




.. parsed-literal::
   :class: ipython-result

    False



.. code:: python

    cMinor.isMinorTriad()




.. parsed-literal::
   :class: ipython-result

    True



You can also figure out if it is in inversion or not:

.. code:: python

    cMinor.inversion()




.. parsed-literal::
   :class: ipython-result

    0



Chords in root position have inversion of 0. But consider this other
chord:

.. code:: python

    cMajor = chord.Chord(["E3","C4","G4"])
    cMajor.inversion()




.. parsed-literal::
   :class: ipython-result

    1



With this chord, two other methods become important:

.. code:: python

    cMajor.root()




.. parsed-literal::
   :class: ipython-result

    <music21.pitch.Pitch C4>



.. code:: python

    cMajor.bass()




.. parsed-literal::
   :class: ipython-result

    <music21.pitch.Pitch E3>



You can find the third and fifth of the ``Chord`` with .third and
.fifth. Note that these properties do not have ``()`` after them. This
was a mistake in how we created ``music21`` and hopefully this will all
be fixed and consistent soon:

.. code:: python

    cMajor.third




.. parsed-literal::
   :class: ipython-result

    <music21.pitch.Pitch E3>



.. code:: python

    cMajor.fifth




.. parsed-literal::
   :class: ipython-result

    <music21.pitch.Pitch G4>



There is also a .seventh property, but it won't do anything here:

.. code:: python

    cMajor.seventh

The result of that is ``None`` which we can test like so...

.. code:: python

    cMajor.seventh is None




.. parsed-literal::
   :class: ipython-result

    True



Displaying Chords
-----------------

We can display the ``Chord`` object just like any
:class:`~music21.note.Note` (Don't worry if this isn't working for you
yet...we'll get this set up in Chapter 8)

.. code:: python

    cMinor.show()




.. image:: usersGuide_07_chords_29_0.png



.. code:: python

    cMajor.show()




.. image:: usersGuide_07_chords_30_0.png



These chords are a bit "spacey", so let's get ``c`` in
:meth:`~music21.chord.Chord.closedPosition`:

.. code:: python

    cClosed = cMinor.closedPosition()
    cClosed.show()




.. image:: usersGuide_07_chords_32_0.png



Notice that ``cMinor`` is unchanged. The closed position chord is only
``cClosed``:

.. code:: python

    cMinor.show()




.. image:: usersGuide_07_chords_34_0.png



If we wanted to change the Chord object itself, we call
``.closedPosition(inPlace = True)`` which alters the original. Since the
original is altered, we don't need to put ``x = ...`` in front of it

.. code:: python

    cMajor.closedPosition(inPlace = True)
    cMajor.show()




.. image:: usersGuide_07_chords_36_0.png



There is also a method,
:meth:`~music21.chord.Chord.semiClosedPosition` which acts like
``.closedPosition`` except that if there is already a pitch at that step
(i.e., D-flat and D-sharp are both step "D"), then the note is moved up
an octave. This is useful for displaying complex, post tonal chords in
the most compact form possible:

.. code:: python

    c1 = chord.Chord(['C4','E5','C#6','E-7', 'G8','C9','E#9'])
    c2 = c1.semiClosedPosition()
    c2.show()




.. image:: usersGuide_07_chords_38_0.png



We can get the :meth:`common name <music21.chord.Chord.commonName>` of
each of these Chords:

.. code:: python

    cn1 = cMinor.commonName
    print(cn1)


.. parsed-literal::
   :class: ipython-result

    minor triad


.. code:: python

    print(cMajor.commonName)


.. parsed-literal::
   :class: ipython-result

    major triad


More complex chords have less common "commonNames". Here's one that the
American composer Elliott Carter liked a lot.

.. code:: python

    elliottCarterChord = chord.Chord(['C4','D-4','E4','F#4'])
    elliottCarterChord.commonName




.. parsed-literal::
   :class: ipython-result

    'all-interval tetrachord'



.. code:: python

    elliottCarterChord.show()




.. image:: usersGuide_07_chords_44_0.png



More ways of creating chords; Chords and Streams
------------------------------------------------

There are other ways of creating a Chord if you'd like. One way is from
a bunch of already created ``Note`` objects:

.. code:: python

    d = note.Note('D4')
    fSharp = note.Note('F#4')
    a = note.Note('A5')
    dMajor = chord.Chord([d, fSharp, a])
    
    dMajor.show()




.. image:: usersGuide_07_chords_47_0.png



Or we can pass a string with note names separated by spaces:

.. code:: python

    e7 = chord.Chord("E4 G#4 B4 D5")
    e7.show()




.. image:: usersGuide_07_chords_49_0.png



The octaves are optional, especially if everything is within an octave:

.. code:: python

    es = chord.Chord("E- G B-")
    es.show()




.. image:: usersGuide_07_chords_51_0.png



But you will definitely want them if a chord crosses the boundary of an
octave (between B and C). Unless you love 6-4 chords, this is probably
not what you want:

.. code:: python

    fMajor = chord.Chord("F A C")
    fMajor.show()




.. image:: usersGuide_07_chords_53_0.png



Notice that because C sorts before F and A that the chord is in second
inversion, or 64. We can figure out the inversion of a ``Chord`` like
so:

.. code:: python

    print(fMajor.inversion(), fMajor.inversionName())


.. parsed-literal::
   :class: ipython-result

    2 64


In addition to .commonName, there are a few other "name" properties that
might be interesting:

.. code:: python

    fMajor.fullName




.. parsed-literal::
   :class: ipython-result

    'Chord {F | A | C} Quarter'



.. code:: python

    fMajor.pitchedCommonName




.. parsed-literal::
   :class: ipython-result

    'F-major triad'



Like ``Note`` objects, we can put ``Chord`` objects inside a
:class:`~music21.strea.Stream`:

.. code:: python

    stream1 = stream.Stream()
    stream1.append(cMinor)
    stream1.append(fMajor)
    stream1.append(es)
    stream1.show()




.. image:: usersGuide_07_chords_60_0.png



We can mix and match ``Notes``, :class:`Rests <music21.note.Rest>`,
and ``Chords``:

.. code:: python

    rest1 = note.Rest()
    rest1.quarterLength = 0.5
    noteASharp = note.Note('A#5')
    noteASharp.quarterLength = 1.5
    
    stream2 = stream.Stream()
    stream2.append(cMinor)
    stream2.append(rest1)
    stream2.append(noteASharp)
    stream2.show()




.. image:: usersGuide_07_chords_62_0.png



Post-tonal chords (in brief)
----------------------------

There are a lot of methods for dealing with post-tonal aspects of
chords. If you're not interested in twentieth century music, go ahead
and skip to the next chapter, but, here are some fun things.

The ``intervalVector`` of a chord is a list of the number of
``[semitones, whole-tones, minor-thirds/augmented-seconds, major-thirds, perfect fourths, and tritones]``
in the chord or inversion. A minor triad, for instance, has one minor
third (C to E-flat), one major third (E-flat to G), and one perfect
fourth (G to C above, since octave does not matter):

.. code:: python

    cMinor.intervalVector




.. parsed-literal::
   :class: ipython-result

    [0, 0, 1, 1, 1, 0]



A major triad has the same interval vector:

.. code:: python

    cMajor.intervalVector




.. parsed-literal::
   :class: ipython-result

    [0, 0, 1, 1, 1, 0]



The elliottCarterChord is unique in that it has an ``.intervalVector``
of all 1's:

.. code:: python

    elliottCarterChord.intervalVector




.. parsed-literal::
   :class: ipython-result

    [1, 1, 1, 1, 1, 1]



Well, it's almost unique: there is another chord with the same
``.intervalVector``. That Chord is called its Z-relation or Z-pair.

.. code:: python

    elliottCarterChord.hasZRelation




.. parsed-literal::
   :class: ipython-result

    True



.. code:: python

    otherECChord = elliottCarterChord.getZRelation()
    otherECChord




.. parsed-literal::
   :class: ipython-result

    <music21.chord.Chord C C# E- G>



We can see it though there's a little problem with accidentals still on
output (we should put a natural on the C or, better, flip the enharmonic
C# to Db).

.. code:: python

    otherECChord.pitches[1].getHigherEnharmonic(inPlace=True)
    otherECChord.show()




.. image:: usersGuide_07_chords_74_0.png



.. code:: python

    otherECChord.intervalVector




.. parsed-literal::
   :class: ipython-result

    [1, 1, 1, 1, 1, 1]



The other post-tonal tools you might be interested in are given below.
We'll return to them in a later chapter, but here are three important
ones:

.. code:: python

    print(elliottCarterChord.primeForm)


.. parsed-literal::
   :class: ipython-result

    [0, 1, 4, 6]


.. code:: python

    print(elliottCarterChord.normalForm)


.. parsed-literal::
   :class: ipython-result

    [0, 1, 4, 6]


.. code:: python

    print(elliottCarterChord.forteClass)


.. parsed-literal::
   :class: ipython-result

    4-15A


If you really only care about semitones, you can create a chord just
with the pitchClasses:

.. code:: python

    oddChord = chord.Chord([1, 3, 7, 9, 10])
    oddChord.show()




.. image:: usersGuide_07_chords_81_0.png



Though if you use pitchClasses above 11, then they are treated as MIDI
numbers, where 60 = MiddleC, 72 = C5, etc. Enharmonic spelling is chosen
automatically.

.. code:: python

    midiChordType = chord.Chord([60, 65, 70, 75])
    midiChordType.show()




.. image:: usersGuide_07_chords_83_0.png



Okay, so now you've learned the basics (and more!) of Notes and Chords.
If you haven't been able to see them on your own,
:ref:`Chapter 8: Installing MusicXML Readers <usersGuide_08_installingMusicXML>`
will fix it. It's also going to cover the basic file formats of
``music21``.