.. _usersGuide_17_derivations:

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



User's Guide: Chapter 17: Derivations
=====================================

Suppose you have a ``music21`` score that was organized something like
this:

.. figure:: graphicalRepresentation/music21_hierarchy.jpg
   :alt: Figure 17.1: Score hierarchy

   Figure 17.1: Score hierarchy

What we've seen already is that iterating over the score via,
``for n in score: print n`` will only get you the highest level of
objects, namely the ``Metadata`` object and the two ``Part`` objects.
The inner objects, measures, clefs, notes, etc. Will not be available.
The simplest way of getting at all these objects is with the
``Stream.flat`` property. Calling it on this score will change the
representation so that only the non-stream elements (the pink ovals)
remain in the score:

.. figure:: graphicalRepresentation/music21_flat.jpg
   :alt: Figure 17.2: Flat Score

   Figure 17.2: Flat Score

This should be a review from previous chapters in the User's Guide. This
section explains the relationship between the original ``stream.Score``
object, which we will call ``s``, and the ``flat`` representation, which
we will call ``s.flat`` or ``sf``. The relationship between the two is
called a ``Derivation``. Symbolically, this representation can be
visualized as follows:

.. figure:: graphicalRepresentation/music21_derivation.jpg
   :alt: Figure 17.3: Derivation representation

   Figure 17.3: Derivation representation

Let's parse a Mozart string quartet, K. 80, give it an ID and look where
it came from:

.. code:: python

    s = corpus.parse('mozart/k80', 1)
    s.id = 'mozartK80'
    s.derivation




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

    <Derivation of <music21.stream.Score mozartK80> from None via "None">



This Score is the first Stream representing this piece in music21 so it
has no derivation origin. However, let's look at the first couple of
measures of the piece using ``.measures``:

.. code:: python

    sExcerpt = s.measures(1, 4)
    sExcerpt.id = 'excerpt'
    sExcerpt.show()




.. image:: usersGuide_17_derivations_11_0.png



This excerpt has a more interesting ``.derivation``:

.. code:: python

    sExcerpt.derivation




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

    <Derivation of <music21.stream.Score excerpt> from <music21.stream.Score mozartK80> via "measures">



There are three things that are reported by the ``__repr__`` of the
:class:`~music21.derivation.Derivation` object: the client (that is
the element housing the Derivation object), the origin (that is the
Stream that the client was derived from), and the method that derived
the new Stream:

.. code:: python

    sExcerpt.derivation.client




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

    <music21.stream.Score excerpt>



.. code:: python

    sExcerpt.derivation.origin




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

    <music21.stream.Score mozartK80>



.. code:: python

    sExcerpt.derivation.method




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

    'measures'



Let's create another Stream from the Excerpt, this time, via
transposition:

.. code:: python

    sTransposed = sExcerpt.transpose('P4')
    sTransposed.show()




.. image:: usersGuide_17_derivations_19_0.png



.. code:: python

    sTransposed.id = 'transposed'
    sTransposed.derivation




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

    <Derivation of <music21.stream.Score transposed> from <music21.stream.Score excerpt> via "transpose">



.. code:: python

    sTransposed.derivation.method




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

    'transpose'



Now this Stream has an origin, and that Stream has an origin. If we
wanted to know where everything came from, we can use the
``.rootDerivation`` property:

.. code:: python

    sTransposed.derivation.origin




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

    <music21.stream.Score excerpt>



.. code:: python

    sTransposed.derivation.origin.derivation.origin




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

    <music21.stream.Score mozartK80>



.. code:: python

    sTransposed.derivation.rootDerivation




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

    <music21.stream.Score mozartK80>



If we wnat to know the whole history of where this Stream comes from, we
can use the ``.chain()`` method on the Derivation object:

.. code:: python

    for previousScore in sTransposed.derivation.chain():
        print(previousScore)


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

    <music21.stream.Score excerpt>
    <music21.stream.Score mozartK80>


Note that derived Streams retain information about where they came from,
but not vice-versa: there's no way to go from the original "mozartK80"
Stream back to the "transposed" Stream.

There are good uses for the derivation chain. For instance, what if we
want to change every ``piano`` mark to a ``forte``, we might define a
function to do that on a Stream and then call it on ``sTransposed``:

.. code:: python

    def makeLouder(s):
        for dyn in s.recurse().getElementsByClass('Dynamic'):
            dyn.value = 'f'
    
    makeLouder(sTransposed)
    sTransposed.show()




.. image:: usersGuide_17_derivations_29_0.png



That's pretty cool, but our original score is unchanged:

.. code:: python

    sExcerpt.show()




.. image:: usersGuide_17_derivations_31_0.png



So, if we want to backtrack up the history of the score, let's call
``makeLouder`` on each Score in the ``.derivation.chain()`` (and now you
might see why we make ``makeLouder`` a function to begin with:)

.. code:: python

    for s in sTransposed.derivation.chain():
        makeLouder(s)
    
    sExcerpt.show()




.. image:: usersGuide_17_derivations_33_0.png



I hope that this gave a sense not only what Derviations are, but also
why you might use them. Let's move on to ...[topic to be written]...