.. _section-Annotation using the english property:

Annotation using the english property
-------------------------------------

The **english** property can also be used to do user-level annotation for a property. One advantage of using the **english** property for annotation is that it allows grammatical structure of query results to be changed. For example:

.. code-block:: flora

   motherInLaw [ english -> 'mother-in-law' ].
   firstCousinTwiceRemoved [ english -> 'first cousin twice removed' ].
   @!{FirstCousinTwiceRemovedOneDirectionRule}
     ?Person [firstCousinTwiceRemoved -> ?FirstCousinTwiceRemoved] :-
     ?Person [firstCousin -> ? [grandchild -> ?FirstCousinTwiceRemoved]].

Since **motherInLaw** and **firstCousinTwiceRemoved** are both asserted as properties, the **english** property can be used to annotate them for query result explanations. The following shows an example of how the **english** property helps in query results explanation.

After executing the query ’Who are first cousins twice removed?’, click the question mark next to the first result returned. This brings up the explanation for why **Darryn** and **Peter** are first cousins twice removed. For the **Tree** default show option in **Query Results**, explanations are displayed in conventional predicate relationship format, as shown in :numref:`figure-NL-first-cousin-twice-removed-no-english.png`.

.. _figure-NL-first-cousin-twice-removed-no-english.png:

.. figure:: ../figs/NL-first-cousin-twice-removed-no-english.png
   :alt: The **Tree** option displays explanations using predicate relationships

   The default **Tree** option displays explanations using predicate relationships

Now select show option **English** and expand the explanation tree again. This time the explanations are done using the annotation in the **english** property of **firstCousinTwiceRemoved**.

.. figure:: ../figs/NL-first-cousin-twice-removed-in-english.png
   :alt: The **English** option displays explanations using the annotation defined in **firstCousinTwiceRemoved**’s **english** property

   The **English** option displays explanations using the annotation defined in **firstCousinTwiceRemoved**’s **english** property

Most properties have two arguments, but more is possible.  For example, the following property **monthlyBalance** has 4 arguments.

.. code-block:: flora

   Account1 [ monthlyBalance(2014,1) -> 10000 ].

The 4 arguments, numbered from left to right, are:

.. code-block:: flora

   %1 = Account1
   %2 = 2014
   %3 = 1
   %4 = 10000

The annotation of a property such as **monthlyBalance** must contain symbols (%1, %2, %3 and %4) for each of the 4 arguments.  During a query output, the **Sunflower** natural language module (**NL**) will replace result value with the corresponding argument in the annotation.

So suppose we have saved the following for Account1 in the **Text Editor**:

.. code-block:: flora

   monthlyBalance [ english -> 'In %3 of %2, the balance is %1 of %4' ].
   Account1 [ monthlyBalance(2014,Jan) -> 1000 ].
   @!{'List all balances for Account1'(?X, ?Y, ?Z)} !- Account1 [ monthlyBalance(?X, ?Y) -> ?Z].

Execute the query ’List all balances for Account1’, and click the question mark to see the result explanation.  The **Tree** view shows the explanation in predicate relationships, as in :numref:`figure-NL-account1-tree.png`, while the **English** view shows the explanation using the **english** annotation, as in :numref:`figure-NL-account1-english.png`.


.. _figure-NL-account1-tree.png:

.. figure:: ../figs/NL-account1-tree.png
   :alt: Default show option **Tree** explains using predicate relationships

   Default show option **Tree** explains using predicate relationships


.. _figure-NL-account1-english.png:

.. figure:: ../figs/NL-account1-english.png
   :alt: Show option **English** explains using **monthlyBalance**’s **english** annotation

   Show option **English** explains using **monthlyBalance**’s **english** annotation

The **english** property can also be used to paraphrase nested functional terms. For example, suppose we have terms such as:

.. code-block:: flora

   quantity(10,meter).

and we want to see it output as 10 meters. This can be achieved with the following annotation:

.. code-block:: flora

   quantity[ english -> '%1 %2s'].

Suppose we have the following saved in the **Text Editor**:

.. code-block:: flora

   quantity(10,meter).
   quantity[ english -> '%1 %2s'].
   @!{'List all quantities'(?X, ?Y)} !- quantity(?X, ?Y).

Execute the query ’List all quantities’. The result explanation will look like the following in **Tree** and **English** views, as shown in :numref:`figure-NL-quantity-tree.png` and :numref:`figure-NL-quantity-english.png` respectively.


.. _figure-NL-quantity-tree.png:

.. figure:: ../figs/NL-quantity-tree.png
   :alt: Show option **Tree** explains using predicate relationships

   Show option **Tree** explains using predicate relationships

.. _figure-NL-quantity-english.png:

.. figure:: ../figs/NL-quantity-english.png
   :alt: Show option **English** explains using **quantity**’s **english** annotation

   Show option **English** explains using **quantity**’s **english** annotation