trunk/ruta-docbook/src/docbook/tools.ruta.workbench.explain_perspective.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"[
<!ENTITY imgroot "images/tools/ruta/workbench/" >
<!ENTITY % uimaents SYSTEM "../../target/docbook-shared/entities.ent" >  
%uimaents;
]>
<!-- Licensed to the Apache Software Foundation (ASF) under one or more contributor 
  license agreements. See the NOTICE file distributed with this work for additional 
  information regarding copyright ownership. The ASF licenses this file to 
  you under the Apache License, Version 2.0 (the "License"); you may not use 
  this file except in compliance with the License. You may obtain a copy of 
  the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required 
  by applicable law or agreed to in writing, software distributed under the 
  License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 
  OF ANY KIND, either express or implied. See the License for the specific 
  language governing permissions and limitations under the License. -->

<section id="section.ugr.tools.ruta.workbench.explain_perspective">
  <title>UIMA Ruta Explain Perspective</title>
  <para>
    Writing new rules is laborious, especially if the newly written
    rules do not behave as expected. The UIMA Ruta system is able to
    record the application of each single rule and block in order to
    provide an explanation of the rule inference and a
    minimal debugging functionality. The information about the application of the rules
    itself is stored in the resulting xmiCAS output file, if the parameters
    of the executed engine are configured correctly. The simplest way to
    generate these explanation information is to click on the common 'Debug' button (looks like a green bug)
    while having the UIMA Ruta script file you want to debug active in
    your editor. The current UIMA Ruta file will then be executed on the text files in the input
    directory and xmiCAS are created in the output directory containing the
    additional UIMA feature structures describing the
    rule inference. To show the newly created execution information, you can either open the
    Explain perspective or open the necessary views separately and arrange
    them as you like. There are eight views that display information about
    the execution of the rules: Applied Rules, Covering Rules, Created By,
    Failed Rules, Matched Rules, Rule Elements, Rule List
    and Statistics. All of theses views are further explained in detail, using the
    UIMA Ruta example project for examples.
  </para>

  <para>
    To make it possible to reproduce all of the examples used below,
    switch to the UIMA Ruta Explain perspective within your Eclipse
    workbench.
    Import the UIMA Ruta example project and open the main
    Ruta script file 'Main.ruta'. Now press the 'Debug' button
    and wait
    for the end of execution. Open the resulting xmiCAS file
    'Test1.txt.xmi', which you can find in the output folder.
  </para>

  <section
    id="section.ugr.tools.ruta.workbench.explain_perspective.applied_rules">
    <title>Applied Rules</title>
    <para>
      The Applied Rules view displays structured information about all
      rules that tried to apply to the input documents.
    </para>
    <para>
      The structure is as follows: if BLOCK constructs were used in the
      executed Ruta file, the rules contained in that block will be
      represented as child node in the tree of the view. Each Ruta
      file is a BLOCK construct itself and named after the file. The
      root node of the view is, therefore, always a BLOCK containing the rules of the
      executed UIMA Ruta script. Additionally, if a rule calls a different
      Ruta file, then the root block of that file is the child of the
      calling rule.
    </para>
    <para>
      If you double-click on one of the rules, the related script file
      is opened within the editor and the rule itself is selected.
    </para>
    <para>
      <xref linkend='section.ugr.tools.ruta.workbench.explain_perspective' />
      shows the whole rule hierarchy resulting from the UIMA Ruta example
      project. The root of the whole hierarchy is the BLOCK associated to
      the 'Main.ruta' script. On the next level, the rules called by the
      'Main.ruta' script are listed. Since there is a call to each of the
      script files 'Year.ruta',
      'Author.ruta' and 'Title.ruta', these are included
      into the hierarchy, each forming their own block.
    </para>
    <para>
      The following image shows the UIMA Ruta Applied Rules view.
      <figure
        id="figure.ugr.tools.ruta.workbench.explain_perspective.applied_rules">
        <title> Applied Rules view
        </title>
        <mediaobject>
          <imageobject role="html">
            <imagedata width="576px" format="PNG" align="center"
              fileref="&imgroot;explain/applied_rules_view.png" />
          </imageobject>
          <imageobject role="fo">
            <imagedata width="5.5in" format="PNG" align="center"
              fileref="&imgroot;explain/applied_rules_view.png" />
          </imageobject>
          <textobject>
            <phrase>
              Applied Rules view.
            </phrase>
          </textobject>
        </mediaobject>
      </figure>
    </para>
    <para>
      Besides the hierarchy, the view shows how often a rule tried to match
      in total and how often it succeeded. This is shown in brackets at the
      beginning of each rule entry. The Applied Rules view tells us
      that the rule
      <literal>NUM{REGEXP("19..|20..") -> MARK(Year)};</literal>
      within script 'Year.ruta' tried to match twice but only succeeded once.
    </para>
    <para>
      After this information, the rule itself is given. Notice that
      each rule is given with all the parameters it has been executed.
      Have a look at rule entry
      <literal>[1/1]Document{->MARKFAST(FirstName,FirstNameList,false,0,true)}
      </literal> within BLOCK Author. The rule obviously has been executed with five
      parameters. If you double-click on this rule, you will get to the
      rule in the script file 'Author.ruta'. It shows the rule as follows:
      <literal>Document{-> MARKFAST(FirstName, FirstNameList)};</literal>. This means the last three parameters have been default values used
      to execute the rule.
    </para>
    <para>
      Additionally, some profiling information, giving details about
      the absolute time and the percentage of total execution time the rule
      needed, is added at the end of each rule entry.
    </para>
    <para>
      The selection (single-click) of a rule in this view will
      directly change the information visualized in the views Failed Rules
      and Matched Rules.
    </para>
  </section>

  <section
    id="section.ugr.tools.ruta.workbench.explain_perspective.matched_and_failed_rules">
    <title>Matched Rules and Failed Rules</title>
    <para>
      If a rule is selected (single-click) in the Applied Rules view,
      then the Matched Rules view displays all instances (text passages) on
      which the rule matched. On the contrary, the Failed Rules view shows
      the instances on which the rule tried but failed to match.
    </para>
    <para>
      Select rule <literal>[2/3]Name{-PARTOF(NameListPart)} NameLinker[1,2]{->
        MARK(NameListPart,1,2)};</literal> within BLOCK Author.
      <xref
        linkend='figure.ugr.tools.ruta.workbench.explain_perspective.matched_and_failed_rules' />
      shows the text passages this rule tried to match on. One did not
      succeed. It is displayed within the Failed Rules view. Two
      succeeded and are shown in the Matched Rules view.
    </para>
    <para>
      The following image shows the UIMA Ruta Applied Rules view.
      <figure
        id="figure.ugr.tools.ruta.workbench.explain_perspective.matched_and_failed_rules">
        <title> The views Matched Rules and Failed Rules
        </title>
        <mediaobject>
          <imageobject role="html">
            <imagedata width="576px" format="PNG" align="center"
              fileref="&imgroot;explain/matched_and_failed.png" />
          </imageobject>
          <imageobject role="fo">
            <imagedata width="5.5in" format="PNG" align="center"
              fileref="&imgroot;explain/matched_and_failed.png" />
          </imageobject>
          <textobject>
            <phrase>
              The views Matched Rules and Failed Rules.
            </phrase>
          </textobject>
        </mediaobject>
      </figure>
    </para>
    <para>
      The selection (single-click) of one of the text passages in
      either Matched Rules view or Failed Rules view will directly change
      the information visualized in the Rule Elements view.
    </para>
  </section>

  <section
    id="section.ugr.tools.ruta.workbench.explain_perspective.rule_elements">
    <title>Rule Elements</title>
    <para>
      If you select one of the listed instances in the Matched or
      Failed Rules view, then the Rule Elements view contains a listing
      of the rule elements and their conditions belonging to the related rule
      used on the specific text passage. There is detailed
      information available on what text passage each rule element did or
      did not match and which condition did or did not evaluate true.
    </para>
    <para>
      Within the Rule Elements view, each rule element generates its
      own explanation hierarchy. On the root level, the rule element itself
      is given. An apostrophe at the beginning of the rule element
      indicates that this rule was the anchor for the rule execution. On
      the next level, the text passage on which the rule element tried to
      match on is given. The last level explains, why the rule element
      did or did not match. The first entry on this level tells, if the text
      passage is of the requested annotation type. If it is, a green hook
      is shown in front of the requested type. Otherwise, a red cross is
      shown. In the following the rule conditions and their evaluation on
      the given text passage are shown.
    </para>
    <para>
      In the previous example, select the listed instance
      <literal>Bethard, S.</literal>. The Rule Elements view shows the related explanation displayed
      in <xref linkend='figure.ugr.tools.ruta.workbench.explain_perspective.rule_elements' />.
    </para>
    <para>
      The following image shows the UIMA Ruta Rule Elements view.
      <figure
        id="figure.ugr.tools.ruta.workbench.explain_perspective.rule_elements">
        <title> The views Matched Rules and Failed Rules
        </title>
        <mediaobject>
          <imageobject role="html">
            <imagedata width="250px" format="PNG" align="center"
              fileref="&imgroot;explain/rule_elements.png" />
          </imageobject>
          <imageobject role="fo">
            <imagedata width="3.5in" format="PNG" align="center"
              fileref="&imgroot;explain/rule_elements.png" />
          </imageobject>
          <textobject>
            <phrase>
              The Rule Elements view.
            </phrase>
          </textobject>
        </mediaobject>
      </figure>
    </para>
    <para>
      As you can see, the first rule element <literal>Name{-PARTOF(NameListPart)}</literal>
      matched on the text passage <literal>Bethard, S.</literal>
      since it is firstly annotated with a <quote>Name</quote> annotation and secondly it is not part of an annotation
      <quote>NameListPart</quote>. However, as this first text passage is not followed by a
      <quote>NameLinker</quote> annotation the whole rule fails.
    </para>
  </section>

  <section
    id="section.ugr.tools.ruta.workbench.explain_perspective.covering_rules">
    <title>Covering Rules</title>
    <para>
      This views is very similar to the Applied Rules view, but
      displays only rules and blocks under a given selection. If the user
      clicks on any position in the xmiCAS document, a Covering Rules view
      is generated containing only rule elements that affect that position
      in the document. The Matched Rules,
      Failed Rules and Rule Elements
      views only contain match
      information of that position.
    </para>
  </section>

  <section id="section.ugr.tools.ruta.workbench.explain_perspective.rule_list">
    <title>Rule List</title>
    <para>
      This views is very similar to the Applied Rules view and the
      Covering Rules view, but displays only rules and NO blocks under a
      given selection. If the user clicks on any position in the xmiCAS
      document, a list of rules that matched or tried to match on that
      position in the document is generated within the Rule List view. The
      Matched Rules, Failed Rules and Rule Elements views only contain
      match information of that position. Additionally, this view provides
      a text field for filtering the rules. Only those rules remain that
      contain the entered text.
    </para>
  </section>

  <section
    id="section.ugr.tools.ruta.workbench.explain_perspective.created_by">
    <title>Created By</title>
    <para>
      The Created By view tells you which rule created a specific
      annotation. To get this information, select an annotation in the
      Annotation Browser. After doing this, the Created By view shows the
      related information.
    </para>
    <para>
      To see how this works, use the example project and go to the
      Annotation view. Select the
      <quote>d.u.e.Year</quote>
      annotation <quote>(2008)</quote>. The Created By view displays the information, shown in
      <xref linkend='figure.ugr.tools.ruta.workbench.explain_perspective.created_by' />. 
      You can double-click on the shown rule to jump to the related
      document <quote>Year.ruta</quote>.
    </para>
    <para>
      The following image shows the UIMA Ruta Created By view.
      <figure
        id="figure.ugr.tools.ruta.workbench.explain_perspective.created_by">
        <title> The Created By view
        </title>
        <mediaobject>
          <imageobject role="html">
            <imagedata width="560px" format="PNG" align="center"
              fileref="&imgroot;explain/created_by.png" />
          </imageobject>
          <imageobject role="fo">
            <imagedata width="5.5in" format="PNG" align="center"
              fileref="&imgroot;explain/created_by.png" />
          </imageobject>
          <textobject>
            <phrase>
              The Created By view.
            </phrase>
          </textobject>
        </mediaobject>
      </figure>
    </para>
  </section>

  <section
    id="section.ugr.tools.ruta.workbench.explain_perspective.statistics">
    <title>Statistics</title>
    <para>
      The Statistics view displays profiling information for the used
      conditions and actions of the UIMA Ruta language. Three
      numbers are
      given for each element: The total time of execution, the amount of
      executions and the average time per execution.
    </para>
    <para>
      The following image shows the UIMA Ruta Statistics view generated
      form the UIMA Ruta example project.
      <figure
        id="figure.ugr.tools.ruta.workbench.explain_perspective.statistics">
        <title> The Statistics view
        </title>
        <mediaobject>
          <imageobject role="html">
            <imagedata width="300px" format="PNG" align="center"
              fileref="&imgroot;explain/statistics.png" />
          </imageobject>
          <imageobject role="fo">
            <imagedata width="4.0in" format="PNG" align="center"
              fileref="&imgroot;explain/statistics.png" />
          </imageobject>
          <textobject>
            <phrase>
              The Statistics view.
            </phrase>
          </textobject>
        </mediaobject>
      </figure>
    </para>
  </section>

</section>