music21.corpus.corpora¶

Corpus¶

class music21.corpus.corpora.Corpus¶: Abstract base class of all corpora subclasses.

Corpus bases

ProtoM21Object

Corpus read-only properties

Corpus.cacheFilePath¶

Corpus.directoryInformation¶

Returns a tuple of DirectoryInformation objects for each directory in self._directoryInformation.

>>> core = corpus.corpora.CoreCorpus()
>>> diBrief = core.directoryInformation[0:5]
>>> diBrief
(<music21.corpus.work.DirectoryInformation airdsAirs>,
 <music21.corpus.work.DirectoryInformation bach>,
 <music21.corpus.work.DirectoryInformation beach>,
 <music21.corpus.work.DirectoryInformation beethoven>,
 <music21.corpus.work.DirectoryInformation chopin>)
>>> diBrief[2].directoryTitle
'Amy Beach'

Corpus.metadataBundle¶

The metadata bundle for a corpus:

>>> corpus.corpora.CoreCorpus().metadataBundle
<music21.metadata.bundles.MetadataBundle 'core': {151... entries}>

As a technical aside, the metadata bundle for a corpus is actually stored in corpus.manager, in order to cache most effectively over multiple calls. There might be good reasons to eventually move them to each Corpus object, so long as its cached across instances of the class.

Corpus.name¶: The name of a given corpus.

Read-only properties inherited from ProtoM21Object:

classSet

classes

Corpus methods

Corpus.all() → bundles.MetadataBundle¶

This is a synonym for the metadataBundle property, but easier to understand what it does.

>>> corpus.corpora.CoreCorpus().all()
<music21.metadata.bundles.MetadataBundle 'core': {151... entries}>

Corpus.cacheMetadata(useMultiprocessing=True, verbose=True, timer=None)¶: Cache the metadata for a single corpus.

Corpus.getComposer(composerName, *, fileExtensions: Iterable[str] = ())¶

Return all filenames in the corpus that match a composer’s or a collection’s name. A fileExtensions, if provided, defines which extensions are returned. A fileExtensions of (), (default) returns all extensions.

Note that xml and mxl are treated equivalently.

>>> coreCorpus = corpus.corpora.CoreCorpus()
>>> a = coreCorpus.getComposer('bach')
>>> len(a) > 100
True

>>> a = coreCorpus.getComposer('bach', fileExtensions=['krn'])
>>> len(a) < 10
True

>>> a = coreCorpus.getComposer('bach', fileExtensions=('xml',))
>>> len(a) > 10
True

abstract Corpus.getPaths(*, fileExtensions: Iterable[str] = (), expandExtensions: bool = True) → list[pathlib.Path]¶: The paths of the files in a given corpus.

Corpus.getWorkList(workName: str | Path, movementNumber: int | Collection[int] | None = None, *, fileExtensions: Iterable[str] = ())¶

Search the corpus and return a list of filenames of works, always in a list.

If no matches are found, an empty list is returned.

>>> coreCorpus = corpus.corpora.CoreCorpus()

This returns 1 even though there is a ‘.mus’ file, which cannot be read:

>>> len(coreCorpus.getWorkList('cpebach/h186'))
1
>>> len(coreCorpus.getWorkList('cpebach/h186', None, fileExtensions=['.xml']))
1

>>> len(coreCorpus.getWorkList('schumann_clara/opus17', 3))
1
>>> len(coreCorpus.getWorkList('schumann_clara/opus17', 2))
0

Note that ‘verdi’ just gets the single Verdi piece and not the Monteverdi pieces:

>>> len(coreCorpus.getWorkList('verdi'))
1

Corpus.getWorkReferences()¶

Return a data dictionary for all works in this corpus Returns a list of corpus.work.DirectoryInformation objects, one for each directory. A ‘works’ dictionary for each composer provides references to dictionaries for all associated works.

This is used in the generation of corpus documentation

>>> workRefs = corpus.corpora.CoreCorpus().getWorkReferences()
>>> workRefs[1:3]
[<music21.corpus.work.DirectoryInformation bach>,
 <music21.corpus.work.DirectoryInformation beach>]

Corpus.rebuildMetadataCache(useMultiprocessing=True, verbose=True)¶

Rebuild a named bundle from scratch.

If a bundle is associated with one of music21’s corpora, delete any metadata cache on disk, clear the bundle’s contents and reload in all files from that associated corpus.

Return the rebuilt metadata bundle.

Corpus.search(query: str, field: str | None = None, *, fileExtensions: Iterable[str] = (), **keywords)¶

Search this corpus for metadata entries, returning a metadataBundle

>>> corpus.corpora.CoreCorpus().search('3/4')
<music21.metadata.bundles.MetadataBundle {1875 entries}>

>>> corpus.corpora.CoreCorpus().search(
...      'bach',
...      field='composer',
...      )
<music21.metadata.bundles.MetadataBundle {363 entries}>

>>> predicate = lambda noteCount: noteCount < 20
>>> corpus.corpora.CoreCorpus().search(
...     predicate,
...     field='noteCount',
...     )
<music21.metadata.bundles.MetadataBundle {134 entries}>

static Corpus.translateExtensions(fileExtensions: Iterable[str] = (), *, expandExtensions: bool = True) → tuple[str, ...]¶

Utility to get default extensions, or, optionally, expand extensions to all known formats.

>>> coreCorpus = corpus.corpora.CoreCorpus()
>>> for extension in coreCorpus.translateExtensions():
...     extension
...
'.abc'
'.capx'
'.mid'
'.midi'
'.xml'
'.mxl'
'.musicxml'
'.md'
'.musedata'
'.zip'
'.krn'
'.rntxt'
'.rntext'
'.romantext'
'.rtxt'
'.nwctxt'
'.nwc'

>>> coreCorpus.translateExtensions(('.mid',), expandExtensions=False)
('.mid',)

>>> coreCorpus.translateExtensions(('.mid',), expandExtensions=True)
('.mid', '.midi')

It does not matter if you choose a canonical name or not, the output is the same:

>>> coreCorpus.translateExtensions(('.musicxml',), expandExtensions=True)
('.xml', '.mxl', '.musicxml')

>>> coreCorpus.translateExtensions(('.xml',), expandExtensions=True)
('.xml', '.mxl', '.musicxml')

Leading dots don’t matter:

>>> coreCorpus.translateExtensions(('xml',))
('.xml', '.mxl', '.musicxml')

# With multiple extensions:

>>> coreCorpus.translateExtensions(('.mid', '.musicxml'), expandExtensions=False)
('.mid', '.musicxml')
>>> coreCorpus.translateExtensions(('.mid', '.musicxml'))
('.mid', '.midi', '.xml', '.mxl', '.musicxml')

Changed in v9: returns a tuple, not a list. first element must be an Iterable of strings

TODO: unify with tools in common.formats

Methods inherited from ProtoM21Object:

isClassOrSubclass()

CoreCorpus¶

class music21.corpus.corpora.CoreCorpus¶

A model of the core corpus.

>>> coreCorpus = corpus.corpora.CoreCorpus()

CoreCorpus bases

CoreCorpus read-only properties

CoreCorpus.cacheFilePath¶

CoreCorpus.noCorpus¶

Return True or False if this is a corpus or noCorpus distribution.

>>> corpus.corpora.CoreCorpus().noCorpus
False

Read-only properties inherited from Corpus:

directoryInformation

metadataBundle

Read-only properties inherited from ProtoM21Object:

classSet

classes

CoreCorpus read/write properties

CoreCorpus.manualCoreCorpusPath¶

Set music21’s core corpus to a directory, and save that information in the user settings.

This is specifically for use with “no corpus” music21 packages, where the core corpus was not included with the rest of the package functionality, and had to be installed separately.

Set it to a directory:

>>> coreCorpus = corpus.corpora.CoreCorpus()
>>> coreCorpus.manualCoreCorpusPath = '~/Desktop'

Unset it:

>>> coreCorpus.manualCoreCorpusPath = None
>>> coreCorpus.manualCoreCorpusPath is None
True

CoreCorpus methods

CoreCorpus.getPaths(fileExtensions: Iterable[str] = (), *, expandExtensions=True) → list[pathlib.Path]¶

Get all paths in the core corpus that match a known extension, or an extension provided by an argument.

If expandExtensions is True, a format for an extension, and related extensions, will be replaced by all known input extensions.

This is convenient when an input format might match for multiple extensions.

>>> coreCorpus = corpus.corpora.CoreCorpus()
>>> corpusFilePaths = coreCorpus.getPaths()
>>> 3000 < len(corpusFilePaths) < 4000
True

>>> kernFilePaths = coreCorpus.getPaths(['krn'])
>>> len(kernFilePaths) >= 500
True

>>> abcFilePaths = coreCorpus.getPaths(['abc'])
>>> len(abcFilePaths) >= 100
True

Methods inherited from Corpus:

all()
cacheMetadata()
getComposer()

getWorkList()
getWorkReferences()
rebuildMetadataCache()

search()
translateExtensions()

Methods inherited from ProtoM21Object:

isClassOrSubclass()

LocalCorpus¶

class music21.corpus.corpora.LocalCorpus(name: str | None = None)¶

A model of a local corpus.

>>> localCorpus = corpus.corpora.LocalCorpus()

The default local corpus is unnamed (or called “local” or None), but an arbitrary number of independent, named local corpora can be defined and persisted:

>>> namedLocalCorpus = corpus.corpora.LocalCorpus('funk')

Illegal local corpus name (‘core’ or ‘virtual’)

>>> corpus.corpora.LocalCorpus('core')
Traceback (most recent call last):
music21.exceptions21.CorpusException: The name 'core' is reserved.

LocalCorpus bases

LocalCorpus read-only properties

LocalCorpus.directoryPaths¶: The directory paths in use by a given local corpus.

LocalCorpus.existsInSettings¶: True if this local corpus has a corresponding entry in music21’s user settings, otherwise false.

LocalCorpus.name¶

The name of a given local corpus. Either ‘local’ for the unnamed corpus or a name for a named corpus

>>> corpus.corpora.LocalCorpus().name
'local'

>>> corpus.corpora.LocalCorpus('funkCorpus').name
'funkCorpus'

Read-only properties inherited from Corpus:

directoryInformation

metadataBundle

Read-only properties inherited from ProtoM21Object:

classSet

classes

LocalCorpus read/write properties

LocalCorpus.cacheFilePath¶

Get the path to the file path that stores the .json file.

returns a pathlib.Path

LocalCorpus methods

LocalCorpus.addPath(directoryPath)¶

Add a directory path to a local corpus:

>>> localCorpus = corpus.corpora.LocalCorpus('a new corpus')
>>> localCorpus.addPath('~/Desktop')

Paths added in this way will not be persisted from session to session unless explicitly saved by a call to LocalCorpus.save().

LocalCorpus.delete()¶: Delete a non-default local corpus from the user settings.

LocalCorpus.getPaths(*, fileExtensions: Iterable[str] = (), expandExtensions=True) → list[pathlib.Path]¶

Access files in additional directories supplied by the user and defined in environment settings in the ‘localCorpusSettings’ list.

If additional paths are added on a per-session basis with the addPath() function, these paths are also returned with this method.

LocalCorpus.removePath(directoryPath: str | Path) → None¶

Remove a directory path from a local corpus.

If that path is included in the list of persisted paths for the given corpus, it will be removed permanently.

>>> testCorpus = corpus.corpora.LocalCorpus(name='test')
>>> testCorpus.addPath('~/Desktop')
>>> len(testCorpus.directoryPaths)
1
>>> testCorpus.removePath('~/Desktop')
>>> testCorpus.directoryPaths
()