.. _moduleRomanText.clercqTemperley:

music21.romanText.clercqTemperley
=================================

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

.. module:: music21.romanText.clercqTemperley


Parses the de Clercq-Temperley popular music flavor of RomanText.
The Clercq-Temperley file format and additional rock corpus analysis
information may be located at http://theory.esm.rochester.edu/rock_corpus/





CTSong
------



.. class:: CTSong(textFile, **keywords)


    This parser is an object-oriented approach to parsing clercqTemperley text files into music.

    Create a CTSong object one of two ways:
    1) by passing in the string, with newline characters (\n) at the end of each line
    2) by passing in the text file as a string, and have python open the file and read the text

        | exampleClercqTemperley = '''
        | % Brown-Eyed Girl
        | VP: I \| IV \| I \| V \|
        | In: $VP\*2
        | Vr: $VP\*4 IV \| V \| I \| vi \| IV \| V \| I \| V \|       % Second part of verse could be called chorus
        | Ch: V \| \| $VP\*2 I \|\*4
        | Ch2: V \| \| $VP\*3     % Fadeout
        | S: [G] $In $Vr $Vr $Ch $VP $Vr $Ch2'''



    >>> from music21 import *
    >>> s = romanText.clercqTemperley.CTSong(exampleClercqTemperley)
    >>> s = romanText.clercqTemperley.CTSong('C:/Brown-Eyed_Girl.txt')

    When you call the .toScore() method on the newly created CTSong object,
    the code extracts meaningful properties (such as title, text, comments,
    year, rules, home time Signature, and home Key Signature) from the textfile
    and makes these accessible as below.

    The toScore() method has two optional labeling parameters, labelRomanNumerals and
    labelSubsectionsOnScore. Both are set to True by default. Thus, the created score
    will have labels (on the chord's lyric) for each roman numeral as well as for each
    section in the song (LHS). In case of a recursive definition (a rule contains a reference
    to another rule), both labels are printed, with the deepest reference on the smallest lyric line.



    >>> s.toScore().show()




        .. image:: images/ClercqTemperleyExbrown-eyed_girl.png
            :width: 500




    >>> s.title
    'Brown-Eyed Girl'
    >>> s.homeTimeSig
    <music21.meter.TimeSignature 4/4>
    >>> s.homeKeySig
    <music21.key.Key of G major>
    >>> s.comments
    [['Vr:', 'Second part of verse could be called chorus'], ['Ch2:', 'Fadeout']]

    Year is not defined as part of the clercq-temperley format, but it will be helpful
    to have it as a property. So let's assign a year to this song:



    >>> s.year = 1967
    >>> s.year
    1967

    Upon calling toScore(), CTRule objects are also created. CTRule objects are
    the individual rules that make up the song object. For example,



    >>> s.rules
    [<music21.CTRule.CTRule text = VP: I | IV | I | V | , <music21.CTRule.CTRule text = In: $VP*2 , <music21.CTRule.CTRule text = Vr: $VP*4 IV | V | I | vi | IV | V | I | V |       % Second part of verse could be called chorus , <music21.CTRule.CTRule text = Ch: V | | $VP*2 I |*4  , <music21.CTRule.CTRule text = Ch2: V | | $VP*3     % Fadeout ]

    The parser extracts meaningful properties to each rule, such as sectionName,
    home time signature of that rule, home key of that rule, and of course the individual
    stream from the song corresponding to the rule.

    The following examples display the instantiated properties of the second rule (list indexes
    start at one) as created above.


    >>> rule = s.rules[1]
    >>> rule.text
    'In: $VP*2'
    >>> rule.sectionName
    'Introduction'
    >>> rule.homeTimeSig
    <music21.meter.TimeSignature 4/4>
    >>> rule.homeKeySig
    <music21.key.Key of G major>
    >>> rule.streamFromCTSong().show()




        .. image:: images/ClercqTemperleyIntroduction.png
            :width: 500


    With this object-oriented approach to parsing the clercq-temperley text file format,
    we now have the ability to analyze a large corpus (200 files) of popular music
    using the full suite of harmonic tools of music21. We can not only analyze each
    song as a whole, as presented in Clercq and Temperley's research, but we can also analyze each
    individual section (or rule) of a song. This may provide interesting insight
    into popular music beyond our current understanding.

    Examples used throughout this class utilize the following Clercq-Temperley text file

        | BlitzkriegBopCT = '''
        | % Blitzkrieg Bop
        | BP: I \| IV V \| %THIS IS A COMMENT
        | In: $BP\*3 I IV \| I \| $BP\*3 I IV \| I \| R \|\*4 I \|\*4
        | Vr: $BP\*3 I IV \| I \|
        | Br: IV \| \| I \| IV I \| IV \| \| ii \| IV V \|
        | Co: R \|\*4 I \|\*4
        | S: [A] $In $Vr $Vr $Br $Vr $Vr $Br $Vr $Vr $Co'''



    **CTSong** **properties**

        .. attribute:: text


            Get the text of the CTSong. This is the full text of the Clercq-Temperley file. This
            attribute is typically instantiated when the CTSong object is created, either by passing
            in the full string, with newline characters (
            ) at the end of each line or by passing
            in the text file as a string, and have python do the parsing



            >>> from music21 import *
            >>> s = romanText.clercqTemperley.CTSong(BlitzkriegBopCT)
            >>> s = romanText.clercqTemperley.CTSong('C:/BlitzkriegBop.txt')



        .. attribute:: title


            Get or set the title of the CTSong. If not specified explicitly but the clercq-Temperley text exists,
            this attribute searches first few lines of text file for title (a string preceded by a '%')
            if found, sets title attribute to this string and returns this title)



            >>> from music21 import *
            >>> s = romanText.clercqTemperley.CTSong(BlitzkriegBopCT)
            >>> s.title
            'Blitzkrieg Bop'



        .. attribute:: homeTimeSig


            gets the initial, or 'home', time signature in a song by looking at the 'S' substring
            and returning the provided time signature. If not present, returns a default music21
            time signature of 4/4


            >>> from music21 import *
            >>> s = romanText.clercqTemperley.CTSong(BlitzkriegBopCT)
            >>> s.homeTimeSig
            <music21.meter.TimeSignature 4/4>




        .. attribute:: homeKeySig


            gets the initial, or 'home', key signature by looking at the musictext and locating
            the key signature in the first few characters in the song rule. A key signature in the song
            rule might look like this: S: [A] $In $Vr



            >>> from music21 import *
            >>> s = romanText.clercqTemperley.CTSong(BlitzkriegBopCT)
            >>> s.homeKeySig
            <music21.key.Key of A major>



        .. attribute:: comments


            Get or set the comments list of a CTRule object. setting comments does not alter self.text

            comments are stored as a list of comments, each comment on a line as a list. If the
            comment is on a rule line, the list contains both the line's LHS (like In:) and the comment
            if the comment is on a line of its own, only the comment is appended as a list of length one.

            The title is not a comment. The title is stored under self.title

                | textString = '''
                | %Simple Gifts
                | % A wonderful shaker melody
                | Vr: I \| I \| %incomplete verse
                | S: [A] $Vr % Not quite finished!'''


            >>> from music21 import *
            >>> s = romanText.clercqTemperley.CTSong(textString)
            >>> s.comments
            [['A wonderful shaker melody'], ['Vr:', 'incomplete verse'], ['S:', 'Not quite finished!']]
            ⁠ 
            >>> s.comments = ['a new list of comments']
            >>> s.comments
            ['a new list of comments']
            >>> s.appendComment('please append this comment to list')
            >>> s.comments
            ['a new list of comments', 'please append this comment to list']




        .. attribute:: rules


            Get the rules of a CTSong. the Rules is a list of objects of type CTRule. If only a textfile
            provided, this goes through text file and creates the rule object out of each line containing
            a LHS...NOT including the Song line



            >>> from music21 import *
            >>> s = romanText.clercqTemperley.CTSong(BlitzkriegBopCT)
            >>> len(s.rules)
            5
            >>> for rule in s.rules:
            ...   print rule.LHS
            BP
            In
            Vr
            Br
            Co




    **CTSong** **methods**

        .. method:: toScore(labelRomanNumerals=True, labelSubsectionsOnScore=True)


            creates Score object out of a from CTSong...also creates CTRule objects in the process,
            filling their .streamFromCTSong attribute with the corresponding smaller inner stream.
            Individual attributes of a rule are defined by the entire CTSong, such as
            meter and time signature, so creation of CTRule objects typically occurs
            only from this method and directly from the clercqTemperly text.



            >>> from music21 import *
            >>> s = romanText.clercqTemperley.CTSong(BlitzkriegBopCT)
            >>> scoreObj = s.toScore()
            >>> scoreObj.highestOffset
            380.0




        .. method:: appendComment(value)


            append a comment to self.text at the end of the text file. Only strings or lists of strings are
            acceptible to append to the text file. this list of comments (self.comments) is also appended

                | textString = '''
                | %Simple Gifts
                | % A wonderful shaker melody
                | Vr: I \| I \| %incomplete verse
                | S: [A] $Vr % Not quite finished!'''



            >>> from music21 import *
            >>> s = romanText.clercqTemperley.CTSong(textString)
            >>> s.comments
            [['A wonderful shaker melody'], ['Vr:', 'incomplete verse'], ['S:', 'Not quite finished!']]
            >>> s.appendComment('please append this comment to list')
            >>> s.comments
            [['A wonderful shaker melody'], ['Vr:', 'incomplete verse'], ['S:', 'Not quite finished!'], 'please append this comment to list']



        .. method:: labelRomanNumerals(scoreObj)


            provided a scoreObject, labels the roman numerals on each chord.
            The CTSong.toScore() method calls this function by default unless
            labelRomanNumerals=False is passed as a parameter. Method labeling
            doesn't relabel tied roman numeral chords.




CTRule
------



.. class:: CTRule(text='', **keywords)


    CTRule objects correspond to the individual lines defined in a
    :class:`~music21.romanText.clercqTemperley.CTSong` object. They are typically
    created by the parser after a CTSong object has been created and the .toScore() method
    has been called on that object. The usefullness of each CTRule object is that each
    has a :meth:`~music21.romanText.clercqTemperley.CTRUle.streamFromCTSong` attribute,
    which is the stream from the entire score that the rule corresponds to.



    **CTRule** **attributes**

        .. attribute:: text

            the full text of the CTRule, including the LHS, chords, and comments


    **CTRule** **properties**

        .. attribute:: LHS


            Get the LHS (Left Hand Side) of the CTRule. If not specified explicitly but CTtext present, searches
            first characters up until ':' for rule and returns string)



            >>> from music21 import *
            >>> s = romanText.clercqTemperley.CTRule('In: $BP*3 I IV | I | $BP*3 I IV | I | R |*4 I |*4 % This is a comment')
            >>> s.LHS
            'In'



        .. attribute:: sectionName


            stores the expanded version of the Left hand side (LHS) such as Introduction, Verse, etc. if
            text present uses LHS to expand)

            Currently supported abbreviations: In: Introduction, Br: Bridge, Vr: Verse, S: Song, Fadeout: Fadeout



            >>> from music21 import *
            >>> s = romanText.clercqTemperley.CTRule('Vr2: $BP*3 I IV | I |')
            >>> s.sectionName
            'Verse2'



        .. attribute:: musicText


            Gets just the music text of the CTRule, excluding the the left hand side and comments



            >>> from music21 import *
            >>> s = romanText.clercqTemperley.CTRule('In: $BP*3 I IV | I | $BP*3 I IV | I | R |*4 I |*4 % This is a comment')
            >>> s.text
            'In: $BP*3 I IV | I | $BP*3 I IV | I | R |*4 I |*4 % This is a comment'
            >>> s.musicText
            '$BP*3 I IV | I | $BP*3 I IV | I | R |*4 I |*4'



        .. attribute:: homeTimeSig


            Get the beginning of the line's time signature. If not specified explicitly but CTtextfile present,
            searches first characters of text file for a time signature (of the form [4/4] )
            if not found, returns default of 4/4



            >>> from music21 import *
            >>> s = romanText.clercqTemperley.CTRule('In: $BP*3 I IV | I | ')
            >>> s.homeTimeSig
            <music21.meter.TimeSignature 4/4>
            >>> s = romanText.clercqTemperley.CTRule('In: [C] [12/8] $BP*3 I IV | I | ')
            >>> s.homeTimeSig
            <music21.meter.TimeSignature 12/8>



        .. attribute:: homeKeySig


            Get or set the beginning of the line's key signature. If not specified explicitly but
            CTtextfile present, searches first characters of text file for a key signature
            (of the form [D#] or [Cb] or [a] uppercase for major, lowercase for minor) if not found, returns default of C Major



            >>> from music21 import *
            >>> s = romanText.clercqTemperley.CTRule('In: $BP*3 I IV | I | ')
            >>> s.homeKeySig
            <music21.key.Key of C major>
            >>> s = romanText.clercqTemperley.CTRule('In: [Db] [12/8] $BP*3 I IV | I | ')
            >>> s.homeKeySig
            <music21.key.Key of D- major>



        .. attribute:: comments


            Get or set the comments of a CTRule object. Functionality is identical to CTRule comments



            >>> from music21 import *
            >>> s = romanText.clercqTemperley.CTRule('In: $BP*3 I IV | I | $BP*3 I IV | I | R |*4 I |*4 % This is a comment')
            >>> s.comments
            [['In:', 'This is a comment']]



    **CTRule** **methods**

        .. method:: appendComment(value)


            append a comment to self.text at the end of the text file. Only strings or lists of strings are
            acceptible to append to the text file. Identical to
            :meth:`~music21.romanText.clercqTemperley.CTSong.appendComment`



        .. method:: streamFromCTSong()


            returns the stream associated with this CTRule only if present; would be generated
            by the :meth:`~music21.romanText.clercqTemperley.CTSong.toScore` method on a
            :class:`~music21.romanText.clercqTemperley.CTSong` object




