.. _moduleCorpus.chorales:

music21.corpus.chorales
=======================

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

.. module:: music21.corpus.chorales


This file makes it easier to access Bach's chorales through various
numbering schemes and filters and includes the Iterator()
class for easily iterating through the chorale collection.




ChoraleList
-----------



.. class:: ChoraleList()


    A searchable list of BachChorales by various numbering systems:

    Note that multiple chorales share the same title, so it's best to
    iterate over one of the other lists to get them all.

    The list of chorales comes from http://en.wikipedia.org/wiki/List_of_chorale_harmonisations_by_Johann_Sebastian_Bach
    which does not have all chorales in the Bärenreitter-Kirnbergger or Riemenschneider
    numberings since it only includes BWV 250-438.




    >>> from music21 import *
    >>> bcl = corpus.chorales.ChoraleList()
    >>> info358 = bcl.byBudapest[358]
    >>> for key in info358.keys():
    ...   print key, info358[key]
    budapest 358
    bwv 431
    title Wenn wir in höchsten Nöten sein
    notes None
    baerenreiter 68
    riemenschneider 68
    kalmus 358
    >>> c = corpus.parse('bach/bwv' + str(info358['bwv']))
    >>> c.show() # shows Bach BWV431

    More fully:



    >>> b = corpus.parse('bwv' + str(corpus.chorales.ChoraleList().byRiemenschneider[2]['bwv']))
    >>> b
    <music21.stream.Score ...>




    **ChoraleList** **attributes**

        Attributes without Documentation: `byKalmus`, `byBaerenreiter`, `byBWV`, `byBudapest`, `byTitle`, `byRiemenschneider`

    **ChoraleList** **methods**

        .. method:: prepareList()


            puts a list of Bach Chorales into dicts of dicts called

            self.byBudapest
            self.byBWV
            self.byRiemenschneider

            etc.




ChoraleListRKBWV
----------------



.. class:: ChoraleListRKBWV()


    A searchable list of BachChorales by various numbering systems:

    Note that multiple chorales share the same title, so it's best to
    iterate over one of the other lists to get them all.

    The list of chorales comes from http://www.jsbchorales.net/ which contains
    all chorales in the corpus, but which only has numbers for the kalmus,
    riemenschneider, and bwv numbering systems.




    >>> from music21 import *
    >>> bcl = corpus.chorales.ChoraleListRKBWV()
    >>> info155 = bcl.byRiemenschneider[155]
    >>> for key in info155.keys():
    ...   print key, info155[key]
    kalmus 173
    riemenschneider 155
    bwv 344
    title Hilf, Herr Jesu, laß gelingen 1
    >>> c = corpus.parse('bach/bwv' + str(info155['bwv']))
    >>> c.show() # shows Bach BWV344

    More fully:



    >>> b = corpus.parse('bwv' + str(corpus.chorales.ChoraleListRKBWV().byRiemenschneider[2]['bwv']))
    >>> b
    <music21.stream.Score ...>




    **ChoraleListRKBWV** **attributes**

        Attributes without Documentation: `byKalmus`, `byTitle`, `byBWV`, `byRiemenschneider`

    **ChoraleListRKBWV** **methods**

        .. method:: prepareList()


            puts a list of Bach Chorales into dicts of dicts called

            self.byKalmus
            self.byBWV
            self.byRiemenschneider
            self.byTitle





Iterator
--------



.. class:: Iterator(currentNumber=None, highestNumber=None, numberingSystem='riemenschneider', **kwargs)


    This is a class for iterating over many Bach Chorales. It is designed to make it easier to use
    one of music21's most accessible datasets. It will parse each chorale in the selected
    range in a lazy fashion so that a list of chorales need not be parsed up front. To select a
    range of chorales, first select a .numberingSystem ('riemenschneider', 'bwv', 'kalmus', 'budapest',
    'baerenreiter', or 'title'). Then, set .currentNumber to the lowest number in the range and
    .highestNumber to the highest in the range. This can either be done by catalogue number
    (iterationType = 'number') or by index (iterationType = 'index').

    Changing the numberingSystem will reset the iterator and change the range values to span the entire numberList.
    The iterator can be initialized with three parameters (currentNumber, highestNumber, numberingSystem). For example
    BachChoraleIterator(1,26,'riemenschneider') iterates through the riemenschneider numbered chorales from 1 to 26.
    Additionally, the following kwargs can be set:

    returnType = either 'stream' (default) or 'filename'

    iterationType = either 'number' or 'index'

    titleList = [list, of, titles]

    numberList = [list, of, numbers]



    >>> from music21 import *
    >>> for chorale in corpus.chorales.Iterator(1,4, returnType = 'filename'):
    ...    print chorale
    bach/bwv269
    bach/bwv347
    bach/bwv153.1
    bach/bwv86.6




    >>> BCI = corpus.chorales.Iterator()
    >>> BCI.numberingSystem
    'riemenschneider'
    ⁠ 
    >>> BCI.currentNumber
    1



    >>> BCI.highestNumber
    371

    An exception will be raised if the number set is not in the numbering system selected, or if the
    numbering system selected is not valid.



    >>> BCI.currentNumber = 25
    Traceback (most recent call last):
    ...
    BachException: 25 does not correspond to a chorale in the riemenschneider numbering system
    ⁠ 
    >>> BCI.numberingSystem = 'not a numbering system'
    Traceback (most recent call last):
    ...
    BachException: not a numbering system is not a valid numbering system for Bach Chorales.

    If the numberingSystem 'title' is selected, the iterator must be initialized with a list of titles.
    It will iterate through the titles in the order of the list.



    >>> BCI.numberingSystem = 'title'
    >>> BCI.returnType = 'filename'
    >>> BCI.titleList = ['Jesu, meine Freude', 'Mit Fried und Freud ich fahr dahin', 'Not a Chorale']
    Not a Chorale will be skipped because it is not a recognized title
    ⁠ 
    >>> for chorale in BCI:
    ...    print chorale
    bach/bwv358
    bach/bwv83.5

    The numberList, which by default includes all chorales in the chosen numberingSystem,
    can be set like the titleList. In the following example, note that the first chorale in the given
    numberList will not be part of the iteration because the first currentNumber is set to 2 at the
    start by the first argument. (If iterationType = 'index' setting the currentNumber to 1 and the
    highestNumber to 7 would have the same effect as the given example.



    >>> BCI = corpus.chorales.Iterator(2, 371, numberingSystem = 'riemenschneider', numberList = [1,2,3,4,6,25,190,371], returnType = 'filename')
    25 will be skipped because it is not in the numberingSystem riemenschneider
    ⁠ 
    >>> for chorale in BCI:
    ...    print chorale
    bach/bwv347
    bach/bwv153.1
    bach/bwv86.6
    bach/bwv281
    bach/bwv337
    bach/bwv278

    Elements in the iterator can be accessed by index as well as slice.



    >>> for chorale in corpus.chorales.Iterator(returnType = 'filename')[4:10]:
    ...    print chorale
    bach/bwv86.6
    bach/bwv267
    bach/bwv281
    bach/bwv17.7
    bach/bwv40.8
    bach/bwv248.12-2
    bach/bwv38.6
    ⁠ 
    >>> print corpus.chorales.Iterator(returnType = 'filename')[55]
    bach/bwv159.5


    For the first 20 chorales in the Riemenschneider numbering system, there are professionally
    annotated roman numeral analyses in romanText format, courtesy of Dmitri Tymoczko of Princeton
    University.  To get them as an additional part to the score set returnType to "stream", and
    add a keyword "analysis = True":

    If chorales are accessed through the Iterator(), the metadata.title attribute will have the
    correct German title. This is different from the metadata returned by the parser which does
    not give the German title but rather the BWV number.



    >>> corpus.chorales.Iterator(returnType = 'stream')[1].metadata.title
    'Ich dank dir, lieber Herre'






    By default: numberingSystem = 'riemenschneider', currentNumber = 1, highestNumber = 371, iterationType = 'number',
    and returnType = 'stream'



    **Iterator** **attributes**

        Attributes without Documentation: `analysis`

    **Iterator** **properties**

        .. attribute:: numberingSystem

            This property determines which numbering system to iterate through chorales with.
            It can be set to 'bwv', 'kalmus', 'baerenreiter', 'budapest', or 'riemenschneider'.
            It can also be set to 'title' in which case the iterator needs to be given a list
            of chorale titles in .titleList. At this time, the titles need to be exactly as they
            appear in the dictionary it queries.


        .. attribute:: currentNumber

            The currentNumber is the number of the chorale (in the set numberingSystem) for the
            next chorale to be parsed by the iterator. It is initially the first chorale in whatever
            numberingSystem is set, but it can be changed to any other number in the numberingSystem
            as desired as long as it does not go above the highestNumber which is the boundary
            of the iteration.


        .. attribute:: highestNumber

            The highestNumber is the number of the chorale (in the set numberingSystem) for the
            last chorale to be parsed by the iterator. It is initially the highest numbered chorale in whatever
            numberingSystem is set, but it can be changed to any other number in the numberingSystem
            as desired as long as it does not go below the currentNumber of the iteration.


        .. attribute:: titleList

            This is to store the list of titles to iterate over if .numberingSystem is set to 'title'.


        .. attribute:: numberList

            Allows access to the catalogue numbers (or indices if iterationType is 'index')
            that will be iterated over. This can be set to a specific list of numbers.
            They will be sorted.


        .. attribute:: returnType

            This property determins what the iterator returns; 'stream' is the default and causes the iterator to parse
            each chorale. If this is set to 'filename', the iterator will return the filename of each chorale but not
            parse it.


        .. attribute:: iterationType

            This property determines how boundary numbers are interpreted, as indices or as catalogue numbers.


    **Iterator** **methods**

        .. method:: next()


            At each iteration, the _currentIndex is incremented, and the next chorale is parsed based upon its bwv number which is queried via
            whatever the current numberingSystem is set to. If the _currentIndex becomes higher than the _highestIndex, the iteration stops.




