fragment¶

exception decitala.fragment.FragmentException[source]¶: Bases: Exception

exception decitala.fragment.DecitalaException[source]¶: Bases: decitala.fragment.FragmentException

exception decitala.fragment.GreekFootException[source]¶: Bases: decitala.fragment.FragmentException

exception decitala.fragment.ProsodicException[source]¶: Bases: decitala.fragment.FragmentException

class decitala.fragment.GeneralFragment(data, name=None, **kwargs)[source]¶

Bases: object

Class representing a generic rhythmic fragment. The user must provide either a path to a music21 readable file or an array of quarter length values.

Parameters

data – Either an array of quarter length values or a path to a music21 readable file.
name (str) – Optional name.

Raises

FragmentException – If an array and file are provided or if neither are provided.

>>> random_fragment_path = "./corpora/Decitalas/63_Nandi.xml"
>>> g1 = GeneralFragment(data=random_fragment_path, name='MyNandi')
>>> g1
<fragment.GeneralFragment MyNandi: [0.5  0.25 0.25 0.5  0.5  1.   1.  ]>
>>> g1.filename
'63_Nandi.xml'
>>> g1.num_onsets
7
>>> g1.ql_array()
array([0.5 , 0.25, 0.25, 0.5 , 0.5 , 1.  , 1.  ])
>>> g1.successive_ratio_array()
array([1. , 0.5, 1. , 2. , 1. , 2. , 1. ])
>>> g1.dseg(as_str=True)
'<1 0 0 1 1 2 2>'
>>> g1.std()
0.2901442287369986
>>> for this_cycle in g1.cyclic_permutations():
...     print(this_cycle)
...
[0.5  0.25 0.25 0.5  0.5  1.   1.  ]
[0.25 0.25 0.5  0.5  1.   1.   0.5 ]
[0.25 0.5  0.5  1.   1.   0.5  0.25]
[0.5  0.5  1.   1.   0.5  0.25 0.25]
[0.5  1.   1.   0.5  0.25 0.25 0.5 ]
[1.   1.   0.5  0.25 0.25 0.5  0.5 ]
[1.   0.5  0.25 0.25 0.5  0.5  1.  ]
>>> # We can also initialize with an array.
>>> GeneralFragment(data=np.array([0.75, 0.75, 0.5, 0.25]))
<fragment.GeneralFragment: [0.75 0.75 0.5  0.25]>
>>> # We can also set keyword arguments
>>> g1.coolness_level = 'pretty cool'
>>> g1.coolness_level
'pretty cool'

ql_array(retrograde=False)[source]¶

Parameters: retrograde (bool) – Whether to return the fragment in its original form or in retrograde.
Returns: The quarter length array of the fragment.
Return type: numpy.array

ql_tuple(retrograde=False)[source]¶

Parameters: retrograde (bool) – Whether to return the fragment in retrograde.
Returns: The quarter length array of the fragment as a tuple.
Return type: tuple

property carnatic_string¶: See docstring of decitala.utils.ql_array_to_carnatic_string.

property greek_string¶: See docstring of decitala.utils.ql_array_to_greek_diacritics.

property num_onsets¶

Returns: The number of onsets in the fragment.
Return type: int

property num_anga_classes¶

Returns: The number of anga classes in the fragment (the number of unique rhythmic values).
Return type: int

>>> GeneralFragment(data=np.array([0.75, 0.75, 0.5, 0.25])).num_anga_classes
3

property ql_duration¶

Returns: The overall duration of the fragment (expressed in quarter lengths).
Return type: float

dseg(reduced=False, as_str=False)[source]¶: See docstring of decitala.utils.dseg.

successive_ratio_array(retrograde=False)[source]¶: See docstring of decitala.utils.successive_ratio_array.

successive_difference_array(retrograde=False)[source]¶: See docstring of decitala.utils.successive_difference_array.

cyclic_permutations()[source]¶

Returns: All cyclic permutations of ql_array, as in Morris (1998).
Return type: numpy.array

property is_non_retrogradable¶

Returns: Whether or not the given fragment is palindromic (i.e. non-retrogradable.)
Return type: bool

anga_class_counter()[source]¶

Returns: A counter of the elements from :meth:decitala.fragment.ql_array.
Return type: collections.Counter

is_sub_fragment(other, try_retrograde=True)[source]¶

Parameters

other – A GeneralFragment, Decitala, or GreekFoot object.
try_retrograde (bool) – Whether to allow searching in retrograde.

Returns

Whether or not self is a sub-fragment of other.

Return type

bool

morris_symmetry_class()[source]¶

Returns: The fragment’s form of rhythmic symmetry, as defined by Morris in Sets, Scales and Rhythmic Cycles. A Classification of Talas in Indian Music (1999).
Return type: int

1. Maximally Trivial: of the form \(X\) (one onset, one anga class)
1. Trivial Dual Symmetry: of the form \(XY\)
1. Trivial Symmetry: of the form \(XXXXXX\)
1. Maximally Trivial Palindrome: of the form \(XXX...XYX...XXX\)
1. Trivial Dual Palindromic: of the form \(XXX...XYYYX...XXX\)
1. Palindromic: of the form \(XY...Z...YX\)
1. Stream: of the form \(XYZ...abc...\)

std()[source]¶

Returns: The standard deviation of ql_array().
Return type: float

c_score()[source]¶

Returns: The c-score of the fragment, as defined in Povel and Essens (1985).
Return type: float
Raises: NotImplementedError

nPVI()[source]¶

Returns: The nPVI of the fragment (Low, Grabe, & Nolan, 2000).
Return type: float

augment(factor=1.0, difference=0.0)[source]¶

This method returns a new GeneralFragment object with a ql_array corresponding to the original fragment augmented by a given ratio and difference.

Parameters

factor (float) – The factor by which the GeneralFragment will be augmented.
difference (float) – The difference by which the GeneralFragment will be augmented.

Return type

GeneralFragment object.

>>> pre_augmentation = GeneralFragment([2.0, 2.0], name="Spondee")
>>> pre_augmentation
<fragment.GeneralFragment Spondee: [2. 2.]>
>>> pre_augmentation.augment(factor=2.0, difference=0.75)
<fragment.GeneralFragment Spondee/r:2.0/d:0.75: [4.75 4.75]>

class decitala.fragment.Decitala(name, **kwargs)[source]¶

Bases: decitala.fragment.GeneralFragment

Class defining a Decitala object. The class reads from the fragments_db file in the databases directory (see the Decitalas table).

Parameters: name (str) – Name of the decitala, as is transliterated in the Lavignac (1921).
Raises: DecitalaException – when there is an issue with the name.

>>> ragavardhana = Decitala('Ragavardhana')
>>> ragavardhana
<fragment.Decitala 93_Ragavardhana>
>>> ragavardhana.filename
'93_Ragavardhana.xml'
>>> ragavardhana.name
'93_Ragavardhana'
>>> ragavardhana.id_num
'93'
>>> ragavardhana.num_onsets
4
>>> ragavardhana.ql_array()
array([0.25 , 0.375, 0.25 , 1.5  ])
>>> ragavardhana.successive_ratio_array()
array([1.        , 1.5       , 0.66666667, 6.        ])
>>> ragavardhana.successive_difference_array()
array([ 0.   ,  0.125, -0.125,  1.25 ])
>>> ragavardhana.carnatic_string
'o oc o Sc'
>>> ragavardhana.is_non_retrogradable
False
>>> ragavardhana.dseg(as_str = True)
'<0 1 0 2>'
>>> ragavardhana.std()
0.5257063700393976
>>> ragavardhana.nPVI()
74.28571428571429
>>> ragavardhana.morris_symmetry_class()
7
>>> Decitala('Jaya').ql_array()
array([0.5 , 1.  , 0.5 , 0.5 , 0.25, 0.25, 1.5 ])
>>> for this_cycle in Decitala('Jaya').cyclic_permutations():
...     print(this_cycle)
...
[0.5  1.   0.5  0.5  0.25 0.25 1.5 ]
[1.   0.5  0.5  0.25 0.25 1.5  0.5 ]
[0.5  0.5  0.25 0.25 1.5  0.5  1.  ]
[0.5  0.25 0.25 1.5  0.5  1.   0.5 ]
[0.25 0.25 1.5  0.5  1.   0.5  0.5 ]
[0.25 1.5  0.5  1.   0.5  0.5  0.25]
[1.5  0.5  1.   0.5  0.5  0.25 0.25]
>>> # We can check if a fragment is a sub-fragment of another (meaning its
>>> # successive_ratio_array appears inorder in another with the is_sub_fragment method.
>>> Decitala("75_Pratapacekhara").is_sub_fragment(Decitala("Ragavardhana"), try_retrograde=True)
True

property id_num¶

Returns: The ID of the fragment, as given by Lavignac (1921).
Return type: int

classmethod get_by_id(input_id)[source]¶

A class method which retrieves a Decitala object based on a given ID number. These numbers are listed in the Lavignac Encyclopédie (1921) and Messiaen Traité. Some talas have “sub-talas,” meaning that their id is not unique.

Returns: A Decitala object
Parameters: input_id (str) – The ID number of the tala (in range 1-120).
Return type: Decitala
Raises: DecitalaException – when there is an issue with the input_id.

>>> Decitala.get_by_id("89")
<fragment.Decitala 89_Lalitapriya>

property num_matras¶

Returns: Returns the number of matras in the tala (here, the number of eighth notes).
Return type: int

class decitala.fragment.GreekFoot(name, **kwargs)[source]¶

Bases: decitala.fragment.GeneralFragment

Class that stores greek foot data. The class reads from the fragments_db file in the databases directory (see the Greek_Metrics table).

>>> bacchius = GreekFoot('Bacchius')
>>> bacchius
<fragment.GreekFoot Bacchius>
>>> bacchius.filename
'Bacchius.xml'
>>> bacchius.name
'Bacchius'
>>> bacchius.num_onsets
3
>>> bacchius.ql_array()
array([1., 2., 2.])
>>> bacchius.successive_ratio_array()
array([1., 2., 1.])
>>> bacchius.greek_string
'⏑ –– ––'
>>> bacchius.dseg(as_str = True)
'<0 1 1>'
>>> bacchius.std()
0.4714045207910317
>>> for this_cycle in bacchius.cyclic_permutations():
...     print(this_cycle)
...
[1. 2. 2.]
[2. 2. 1.]
[2. 1. 2.]

class decitala.fragment.Breve(**kwargs)[source]¶

Bases: decitala.fragment.GeneralFragment

A fragment.GeneralFragment object representing a Breve.

class decitala.fragment.Macron(**kwargs)[source]¶

Bases: decitala.fragment.GeneralFragment

A fragment.GeneralFragment object representing a Macron.

class decitala.fragment.ProsodicMeter(name, origin=None, **kwargs)[source]¶

Bases: decitala.fragment.GeneralFragment

>>> ct = ProsodicMeter("Cretic_Tetrameter", origin="greek")
>>> ct
<fragment.ProsodicMeter Cretic_Tetrameter Greek>
>>> ct.ql_array()
array([2., 1., 2., 1., 1., 1., 2., 2., 1., 1., 1., 2., 1., 2.])
>>> for f in ct.components:
...     print(f)
<fragment.GreekFoot Amphimacer>
<fragment.GreekFoot Peon_IV>
<fragment.GreekFoot Peon_I>
<fragment.GreekFoot Amphimacer>
>>> ct.origin
'greek'

class decitala.fragment.ProsodicFragment(name, **kwargs)[source]¶

Bases: decitala.fragment.GeneralFragment

Class that stores prosodic data. The class reads from the fragments_db file in the databases directory (see the ProsodicFragments table).

NOTE: This class be deprecated eventually. Currently wraps ProsodicMeter.

decitala.fragment.get_all_greek_feet()[source]¶: Function for returning all Greek Feet in a list.

decitala.fragment.get_all_decitalas()[source]¶: Function for returning all Decitalas in a list.

decitala.fragment.get_all_prosodic_fragments()[source]¶: WILL BE DEPRECTATED! USE get_all_prosodic_meters.

decitala.fragment.prosodic_meter_query(collection)[source]¶

Function for returning all Prosodic Meters that contain the queried collection of fragment.GreekFoot objects.

Parameters: collection – an iterable collection of fragment.GreekFoot objects.