.. _moduleTrecento.cadencebook:

music21.trecento.cadencebook
============================

.. WARNING: DO NOT EDIT THIS FILE: AUTOMATICALLY GENERATED. Edit the .py file directly

.. module:: music21.trecento.cadencebook


The file trecento/cadences.xls contains (in a modified TinyNotation format) incipits
and cadences for hundreds of trecento ballatas (in a sheet called "fischer_ballata")
and several other works (sanctus, etc.).  This module contains methods and classes
for working with this encoding, including transforming it into music21 Streams.





AgnusDeiSheet
-------------

Inherits from: :class:`~music21.trecento.cadencebook.TrecentoSheet`

.. class:: AgnusDeiSheet(**keywords)



Ballata
-------

Inherits from: :class:`~music21.trecento.cadencebook.TrecentoCadenceWork`

.. class:: Ballata(rowvalues=None, rowDescriptions=None)


    Class representing a fourteenth-century Ballata.

    Overrides the locations of the column numbers in which one finds the cadences.




BallataSheet
------------

Inherits from: :class:`~music21.trecento.cadencebook.TrecentoSheet`

.. class:: BallataSheet(**keywords)


    shortcut to a worksheet containing all the ballata cadences encoded.


    2011-May: over 400 of 460 encoded; unencoded pieces are mostly fragmentary.





CacciaSheet
-----------

Inherits from: :class:`~music21.trecento.cadencebook.TrecentoSheet`

.. class:: CacciaSheet(**keywords)


    shortcut to a worksheet containing all the caccia cadences encoded


    2011-May: none encoded.




    >>> from music21 import *
    >>> cacciaSheet = trecento.cadencebook.CacciaSheet()




CredoSheet
----------

Inherits from: :class:`~music21.trecento.cadencebook.TrecentoSheet`

.. class:: CredoSheet(**keywords)



Gloria
------

Inherits from: :class:`~music21.trecento.cadencebook.TrecentoCadenceWork`

.. class:: Gloria(rowvalues=None, rowDescriptions=None)


    Class representing a fourteenth-century Gloria.

    Overrides the locations of the column numbers in which one finds the cadences.




GloriaSheet
-----------

Inherits from: :class:`~music21.trecento.cadencebook.TrecentoSheet`

.. class:: GloriaSheet(**keywords)


    shortcut to a worksheet containing all the known 14th and early 15th c.
    French, Spanish, and Italian Gloria's openings of the Et in Terra, Dominus Deus,
    Qui Tollis, encoded along with the ends of the Cum Sancto and Amen.


    2011-August: all encoded except some very fragmentary pieces.




    >>> from music21 import *
    >>> cadenceSpreadSheet = trecento.cadencebook.GloriaSheet()
    >>> gloriaNo20 = cadenceSpreadSheet.makeWork(20)
    >>> incipit = gloriaNo20.incipit
    >>> incipit.show('text')
    {0.0} <music21.metadata.Metadata object at 0x...>
    {0.0} <music21.stream.Part C>
        {0.0} <music21.stream.Measure 1 offset=0.0>
            {0.0} <music21.meter.TimeSignature 2/4>
            {0.0} <music21.clef.TrebleClef>
            {0.0} <music21.note.Note D>
        {2.0} <music21.stream.Measure 2 offset=2.0>
            {0.0} <music21.note.Note D>
        ...
            {2.0} <music21.bar.Barline style=final>
    {0.0} <music21.stream.Part Ct>
        {0.0} <music21.stream.Measure 1 offset=0.0>
            {0.0} <music21.meter.TimeSignature 2/4>
            {0.0} <music21.clef.BassClef>
            {0.0} <music21.note.Note D>
        {2.0} <music21.stream.Measure 2 offset=2.0>
            {0.0} <music21.note.Note F#>
        ...
        {16.0} <music21.stream.Measure 9 offset=16.0>
            {0.0} <music21.note.Note B>
            {2.0} <music21.bar.Barline style=final>
    {0.0} <music21.stream.Part T>
        {0.0} <music21.stream.Measure 1 offset=0.0>
            {0.0} <music21.meter.TimeSignature 2/4>
            {0.0} <music21.clef.BassClef>
            {0.0} <music21.note.Note D>
        {2.0} <music21.stream.Measure 2 offset=2.0>
            {0.0} <music21.note.Note D>
        ...
        {16.0} <music21.stream.Measure 9 offset=16.0>
            {0.0} <music21.note.Note E>
            {2.0} <music21.bar.Barline style=final>





KyrieSheet
----------

Inherits from: :class:`~music21.trecento.cadencebook.TrecentoSheet`

.. class:: KyrieSheet(**keywords)



MadrigalSheet
-------------

Inherits from: :class:`~music21.trecento.cadencebook.TrecentoSheet`

.. class:: MadrigalSheet(**keywords)


    shortcut to a worksheet containing all the madrigal cadences encoded


    2011-May: none encoded.






SanctusSheet
------------

Inherits from: :class:`~music21.trecento.cadencebook.TrecentoSheet`

.. class:: SanctusSheet(**keywords)



TrecentoCadenceWork
-------------------



.. class:: TrecentoCadenceWork(rowvalues=None, rowDescriptions=None)


    A class representing a work that takes one line in the Trecento Cadence excel workbook


    Takes in two lists: one containing a value for each column in the excel spreadsheet
    and another containing a description for each column (generally, the excel header row)


    contains the following attributes::

        fisherNum     -- the work number assigned by Kurt von Fischer (only applies to pieces discovered before 1956)
        title         -- may contain unicode characters
        composer      -- "." = anonymous
        encodedVoices -- a string representing the number of voices, a period, then the number of texted voices
        pmfcVol       -- the volume of Polyphonic Music of the Fourteenth Century where the piece might be found (if any)
        pmfcPageStart -- the initial page number in that PMFC volume
        pmfcPageEnd   -- the final page number
        timeSignBegin -- the starting time signature (as a string) for the piece
        entryNotes    -- comments

    attributes shared with all members of the class::

        beginSnippetPositions -- a list of the excel spreadsheet columns in which an incipit of some section can be found. (default = [8])
        endSnippetPositions   -- a list of the excel spreadsheet columns in which an cadence of some section can be found. (default = [])



    **TrecentoCadenceWork** **attributes**

        Attributes without Documentation: `beginSnippetPositions`, `endSnippetPositions`, `fischerNum`, `rowDescriptions`, `totalVoices`, `totalPmfcPage`, `title`, `isAnonymous`, `rowvalues`, `encodedVoices`, `pmfcPageStart`, `pmfcPageEnd`, `timeSigBegin`, `composer`, `entryNotes`, `pmfcVol`, `snippets`

    **TrecentoCadenceWork** **properties**

        .. attribute:: cadenceA


            returns the snippet which represents the cadence at the end of
            the A section of the piece.



        .. attribute:: cadenceB


            returns the snippet that represents the open cadence of the B section
            or the only cadence if there are no open and close endings.



        .. attribute:: cadenceBClos


            Returns the second B cadence -- that is, the 2nd or clos ending.



        .. attribute:: incipit


            Gets the Incipit PolyphonicSnippet of the piece.


            The incipit keeps its time signature
            in a different location from all the other snippets.
            hence, it's a little different


            Returns None if the piece or timeSignature is
            undefined




            >>> from music21 import *
            >>> bs = trecento.cadencebook.BallataSheet()
            >>> accur = bs.makeWork(2)
            >>> accurIncipit = accur.incipit
            >>> print(accurIncipit)
            <music21.trecento.polyphonicSnippet.Incipit ...>



    **TrecentoCadenceWork** **methods**

        .. method:: allCadences()


            returns a list of all the PolyphonicSnippet
            objects which are actually cadences (and not incipits)



        .. method:: asOpus()


            returns all snippets as a music21 opus object



            >>> from music21 import *
            >>> deduto = trecento.cadencebook.BallataSheet().workByTitle('deduto')
            >>> deduto.title
            u'Deduto sey a quel'
            >>> dedutoScore = deduto.asOpus()
            >>> dedutoScore
            <music21.stream.Opus ...>
            >>> dedutoScore.show('lily.png')




        .. method:: asScore()


            returns all snippets as a score chunk




            >>> from music21 import *
            >>> deduto = trecento.cadencebook.BallataSheet().workByTitle('deduto')
            >>> deduto.title
            u'Deduto sey a quel'
            >>> dedutoScore = deduto.asScore()
            >>> dedutoScore
            <music21.stream.Score ...>




        .. method:: convertBlockToStreams(thisBlock)


            Takes a block of music information (in :class:`~music21.trecento.trecentoCadence.TrecentoCadenceStream` notation)
            and returns a list of Streams and other information




            >>> from music21 import *
            >>> block1 = ['e4 f g a', 'g4 a b cc', '', 'no-cadence', '2/4']
            >>> bs = trecento.cadencebook.BallataSheet()
            >>> dummyPiece = bs.makeWork(2)
            >>> blockStreams = dummyPiece.convertBlockToStreams(block1)
            >>> for x in blockStreams:
            ...     print(x)
            <music21.trecento.trecentoCadence.TrecentoCadenceStream ...>
            <music21.trecento.trecentoCadence.TrecentoCadenceStream ...>
            None
            no-cadence
            2/4
            >>> blockStreams[0].show('text')
            {0.0} <music21.meter.TimeSignature 2/4>
            {0.0} <music21.note.Note E>
            {1.0} <music21.note.Note F>
            {2.0} <music21.note.Note G>
            {3.0} <music21.note.Note A>



        .. method:: getAllStreams()


            Get all streams in the work as a List, losing association with
            the other polyphonic units.



            >>> from music21 import *
            >>> b = trecento.cadencebook.BallataSheet().makeWork(20)
            >>> sList = b.getAllStreams()
            >>> sList
            [<music21.stream.Part ...>, <music21.stream.Part ...>, ...]




        .. method:: getOtherSnippets()


            returns a list of bits of music notation that are not the actual
            incipits of the piece.




            >>> from music21 import *
            >>> bs = trecento.cadencebook.BallataSheet()
            >>> accur = bs.makeWork(2)
            >>> accurSnippets = accur.getOtherSnippets()
            >>> for thisSnip in accurSnippets:
            ...     print(thisSnip)
            <music21.trecento.polyphonicSnippet.FrontPaddedSnippet ...>
            <music21.trecento.polyphonicSnippet.FrontPaddedSnippet ...>




        .. method:: getSnippetAtPosition(snippetPosition, type='end')


            gets a "snippet" which is a collection of up to 3 lines of music, a timeSignature
            and a description of the cadence.



            >>> from music21 import *
            >>> bs = trecento.cadencebook.BallataSheet()
            >>> accur = bs.makeWork(2)
            >>> print(accur.getSnippetAtPosition(12))
            <music21.trecento.polyphonicSnippet.FrontPaddedSnippet ...>



        .. method:: pmfcPageRange()


            returns a nicely formatted string giving the page numbers in PMFC where the piece
            can be found



            >>> bs = BallataSheet()
            >>> altroCheSospirar = bs.makeWork(4)
            >>> altroCheSospirar.title
            u'Altro che sospirar'
            >>> altroCheSospirar.pmfcVol
            11
            >>> altroCheSospirar.pmfcPageRange()
            'pp. 2-4'




TrecentoSheet
-------------



.. class:: TrecentoSheet(**keywords)


    A TrecentoSheet represents a single worksheet of an excel spreadsheet
    that contains data about particular pieces of trecento music.


    Users can iterate over the rows to get TrecentoCadenceWork objects for each row.



    See the specialized subclasses below, esp. BallataSheet for more details.




    >>> from music21 import *
    >>> kyrieSheet = trecento.cadencebook.TrecentoSheet(sheetname = 'kyrie')
    >>> for thisKyrie in kyrieSheet:
    ...     print thisKyrie.title
    Questa Fanc.
    Kyrie Summe Clementissime
    Kyrie rondello



    **TrecentoSheet** **attributes**

        Attributes without Documentation: `filename`, `sheetname`, `totalRows`, `rowDescriptions`, `sheet`

    **TrecentoSheet** **methods**

        .. method:: makeWork(rownumber=2)


            Returns the TrecentoCadenceWork at the given row number
            Same as using getItem above, but without slices...

            We use Excel Row numbers, NOT Python row numbers:
            in other words, makeWork(1) = Excel row 1 (python row 0)

            Row 1 is a header, so makeWork(2) gives the first piece.



            >>> from music21 import *
            >>> ballataSheet = trecento.cadencebook.BallataSheet()
            >>> b = ballataSheet.makeWork(3)
            >>> print(b.title)
            Ad(d)io, amore mio



        .. method:: next()

            No documentation.


        .. method:: workByTitle(title)


            return the first work with TITLE in the work's title.  Case insensitive



            >>> from music21 import *
            >>> ballataSheet = trecento.cadencebook.BallataSheet()
            >>> farina = ballataSheet.workByTitle('farina')
            >>> print(farina.title)
            De mia farina
            >>> farina.incipit.parts[0].show('text')
            {0.0} <music21.stream.Measure 1 offset=0.0>
                {0.0} <music21.meter.TimeSignature 3/4>
                {0.0} <music21.clef.TrebleClef>
                {0.0} <music21.note.Rest rest>
                {1.0} <music21.note.Rest rest>
                {2.0} <music21.note.Note C>
                {2.5} <music21.note.Note D>
            {3.0} <music21.stream.Measure 2 offset=3.0>
                {0.0} <music21.note.Note E>
                {1.0} <music21.note.Note G>
                {2.0} <music21.note.Note G>
            {6.0} <music21.stream.Measure 3 offset=6.0>
                {0.0} <music21.note.Note G>
                {1.0} <music21.note.Note E>
                {2.0} <music21.note.Note D>
                {3.0} <music21.bar.Barline style=final>




