.. _queries_reference:

***************
Query Reference
***************


Getting elements
================

:code:`c.phone`
:code:`c.lexicon_phone`
:code:`c.speaker`
:code:`c.discourse`

Attributes
==========

In addition to any values that get added through enrichment, there are several built in attributes that allow access to
different parts of the database.

+--------------------------------------+-------------------------------------------------+----------------------------------------+
| Attribute type                       |  Code                                           | Notes                                  |
+======================================+=================================================+========================================+
| Label [1]_                           |  :code:`c.phone.label`                          |                                        |
+--------------------------------------+-------------------------------------------------+----------------------------------------+
| Name [2]_                            |  :code:`c.speaker.name`                         |                                        |
+--------------------------------------+-------------------------------------------------+----------------------------------------+
| Begin [3]_                           |  :code:`c.phone.begin`                          |                                        |
+--------------------------------------+-------------------------------------------------+----------------------------------------+
| End [3]_                             |  :code:`c.phone.end`                            |                                        |
+--------------------------------------+-------------------------------------------------+----------------------------------------+
| Duration [3]_                        |  :code:`c.phone.duration`                       |                                        |
+--------------------------------------+-------------------------------------------------+----------------------------------------+
| Previous annotation [3]_             |  :code:`c.phone.previous`                       |                                        |
+--------------------------------------+-------------------------------------------------+----------------------------------------+
| Following annotation [3]_            |  :code:`c.phone.following`                      |                                        |
+--------------------------------------+-------------------------------------------------+----------------------------------------+
| Previous pause [3]_                  |  :code:`c.phone.word.previous_pause`            |  Must be from a `word` annotation      |
+--------------------------------------+-------------------------------------------------+----------------------------------------+
| Following pause [3]_                 |  :code:`c.phone.word.following_pause`           |  Must be from a `word` annotation      |
+--------------------------------------+-------------------------------------------------+----------------------------------------+
| Speaker [3]_                         |  :code:`c.phone.speaker`                        |                                        |
+--------------------------------------+-------------------------------------------------+----------------------------------------+
| Discourse [3]_                       |  :code:`c.phone.discourse`                      |                                        |
+--------------------------------------+-------------------------------------------------+----------------------------------------+
| Pitch attribute [3]_                 |  :code:`c.phone.pitch`                          |                                        |
+--------------------------------------+-------------------------------------------------+----------------------------------------+
| Formants attribute [3]_              |  :code:`c.phone.formants`                       |                                        |
+--------------------------------------+-------------------------------------------------+----------------------------------------+
| Intensity attribute [3]_             |  :code:`c.phone.intensity`                      |                                        |
+--------------------------------------+-------------------------------------------------+----------------------------------------+
| Minimum value [4]_                   |  :code:`c.phone.pitch.min`                      |                                        |
+--------------------------------------+-------------------------------------------------+----------------------------------------+
| Maximum value [4]_                   |  :code:`c.phone.pitch.max`                      |                                        |
+--------------------------------------+-------------------------------------------------+----------------------------------------+
| Mean value [4]_                      |  :code:`c.phone.pitch.mean`                     |                                        |
+--------------------------------------+-------------------------------------------------+----------------------------------------+
| Raw track [4]_                       |  :code:`c.phone.pitch.track`                    |                                        |
+--------------------------------------+-------------------------------------------------+----------------------------------------+
| Sampled track [4]_                   |  :code:`c.phone.pitch.sampled_track`            |                                        |
+--------------------------------------+-------------------------------------------------+----------------------------------------+
| Interpolated track [4]_              |  :code:`c.phone.pitch.interpolated_track`       |                                        |
+--------------------------------------+-------------------------------------------------+----------------------------------------+



.. [1] Only available for graph annotations and lexicon annotations
.. [2] Only available for speakers/discourses
.. [3] Only available for graph annotations
.. [4] Only available for acoustic attributes

Filters
=======

+--------------------------------------+-------------------------------------------------+----------------------------------------+
| Filter type                          |  Code                                           | Notes                                  |
+======================================+=================================================+========================================+
| Equal                                |  :code:`c.phone.label == 'aa'`                  |                                        |
+--------------------------------------+-------------------------------------------------+----------------------------------------+
| Not equal                            |  :code:`c.phone.label != 'aa'`                  |                                        |
+--------------------------------------+-------------------------------------------------+----------------------------------------+
| Greater than                         |  :code:`c.phone.begin > 0`                      |                                        |
+--------------------------------------+-------------------------------------------------+----------------------------------------+
| Greater than or equal                |  :code:`c.phone.begin >= 0`                     |                                        |
+--------------------------------------+-------------------------------------------------+----------------------------------------+
| Less than                            |  :code:`c.phone.end < 10`                       |                                        |
+--------------------------------------+-------------------------------------------------+----------------------------------------+
| Less than or equal                   |  :code:`c.phone.end <= 10`                      |                                        |
+--------------------------------------+-------------------------------------------------+----------------------------------------+
| In                                   |  :code:`c.phone.label.in_(['aa','ae'])`         |  :code:`in_` can also take a query     |
+--------------------------------------+-------------------------------------------------+----------------------------------------+
| Not in                               |:code:`c.phone.label.not_in_(['aa'])`            | :code:`not_in_` can also take a query  |
+--------------------------------------+-------------------------------------------------+----------------------------------------+
| Is null                              |  :code:`c.phone.label == None`                  |                                        |
+--------------------------------------+-------------------------------------------------+----------------------------------------+
| Is not null                          |  :code:`c.phone.label != None`                  |                                        |
+--------------------------------------+-------------------------------------------------+----------------------------------------+
| Regular expression match             |  :code:`c.phone.label.regex('a,')`              |                                        |
+--------------------------------------+-------------------------------------------------+----------------------------------------+
| In subset                            |  :code:`c.phone.subset == 'syllabic'`           |                                        |
+--------------------------------------+-------------------------------------------------+----------------------------------------+
| Not in subset                        |  :code:`c.phone.subset != 'syllabic'`           |                                        |
+--------------------------------------+-------------------------------------------------+----------------------------------------+
| Precedes pause                       |:code:`c.word.precedes_pause == True`            |  Only available for graph annotations  |
+--------------------------------------+-------------------------------------------------+----------------------------------------+
| Does not precede pause               |:code:`c.word.precedes_pause == False`           |  Only available for graph annotations  |
+--------------------------------------+-------------------------------------------------+----------------------------------------+
| Follows pause                        |:code:`c.word.follows_pause == True`             |  Only available for graph annotations  |
+--------------------------------------+-------------------------------------------------+----------------------------------------+
| Does not follow pause                |:code:`c.word.follows_pause == False`            |  Only available for graph annotations  |
+--------------------------------------+-------------------------------------------------+----------------------------------------+
| Right aligned                        |:code:`c.phone.end == c.phone.word.end`          |  Only available for graph annotations  |
+--------------------------------------+-------------------------------------------------+----------------------------------------+
| Not right aligned                    |:code:`c.phone.end != c.phone.word.end``         |  Only available for graph annotations  |
+--------------------------------------+-------------------------------------------------+----------------------------------------+
| Left aligned                         |:code:`c.phone.begin == c.phone.word.begin`      |  Only available for graph annotations  |
+--------------------------------------+-------------------------------------------------+----------------------------------------+
| Not left aligned                     |:code:`c.phone.begin != c.phone.word.begin`      |  Only available for graph annotations  |
+--------------------------------------+-------------------------------------------------+----------------------------------------+