=head1 NAME

Emotion - discrete emotion annotation processing

=head1 SYNOPSIS

  empathize <script>
  empathize --index <script> [<script> ...]

=head1 DESCRIPTION

The most difficult part of this module is learning how to annotate
free-form text with information about what competition is taking
place.  If you haven't studied http://ghost-wheel.net then go do that
first.

The first part of this document describes the XML representation of
3rd person annotations and validation rules.  The second part
describes the perl API.

=head1 XML TUTORIAL

The minimum situation consists of the type of competition and two
opponents.

  abbreviation  type of competition (situation)
  ------------  -------------------------------
  destroys      [-] destroys [-]
  steals        [-] steals from [+]
  uneasy        [-] is made uneasy by [0]
  exposes       [+] exposes [-]
  impasse       [+] and [+] are at an impasse
  admires       [+] admires [0]
  observes      [0] observes [-]
  accepts       [0] accepts [+]
  ready         [0] and [0] are at readiness

Each opponent is labelled either C<left> or C<right>, indicating on
which side of the situation he or she participates.  For example:

  <observes left="student" right="teacher">
    A student watches the teacher make a presentation.
  </observes>

  <observes right="student" left="teacher">
    The teacher watches a student make a presentation.
  </observes>

Of course a teacher is probably more accustomed to lecturing in front
of a class than a student.  This information can be captured with the
C<intensity> attribute:

  <observes left="student" right="teacher" intensity="gentle">
    A student watches the teacher make a presentation.
  </observes>

  <observes right="student" left="teacher" intensity="forceful">
    The teacher watches a student make a presentation.
  </observes>

Now it is clear that the teacher's presentation involves some gentle
excitement, but a student presentation is an exciting test of
self-control.  Since no spin is involved, the emotion is roughly the
same regardless of whether we empathize with the presenter or the
audience.  To contrast, situations involving spin require some
additional structure.  For example:

  <steals left="thief" right="child">
    The thief steals the teddy bear from the child.
  </steals>

Here it is not clear which emotion is intended.  Opponents experience
the situation very differently.  Perhaps the thief is drunk with
accomplishment, but the child is probably quite angry.  To avoid this
ambiguity, situations involving spin follow a transactional structure:

  initiator:   (1) before ---+---> (3) after
                             |
                             v
  victim:             (2) tension

Here is a hypothetical trace of a C<steals> situation decomposed into
the three transaction phases:

  <steals left="thief" right="child" before="focused">
    The thief eyes the teddy bear maliciously and wrenches it
    from the child's passionate grip.
  </steals>

  <steals left="thief" right="child" tension="focused">
    The child becomes furious and starts crying.
  </steals>

  <steals left="thief" right="child" after="focused">
    The thief triumphantly stows the teddy bear in his backpack.
  </steals>

Perhaps this sequence of events is ghastly, but here the goal is
merely to model emotions accurately.  In this example, the three
phases unambiguously correspond to "anxiety," "anger," and "drunk with
accomplishment."

The attributes C<before>, C<tension>, and C<after> describe the
emotional tension.  Tension modifies a general emotion to fit the
precise situation.  For example:

  <steals left="thief" right="child" before="relaxed">
    The thief grabs the teddy bear with abandon.
  </steals>

  <steals left="thief" right="child" before="stifled">
    The thief studies whether the teddy bear can be stolen.
  </steals>

A tension modifier is either C<focused>, C<relaxed>, or C<stifled>.
Emotion correspondance charts can assist in fitting the most accurate
modifier to the situation.  Of course a thief is not always
successful:

  <steals left="thief" right="child" before="stifled">
    The thief studies whether the teddy bear can be stolen.
  </steals>

  <impasse left="child" right="thief" tension="focused">
    The child grips the teddy bear even more tightly.
  </impasse>

The four situations involving spin (C<steals>, C<exposes>, C<admires>,
and C<accepts>) mostly follow the three phase transaction structure.
However, flexibility offered by C<accepts> shows the need to
explicitly indicate an initiator.  For example:

  <accepts left="chef" right="child" before="focused">
    I am hungry.  Is dinner ready?
  </accepts>

  <accepts left="chef" right="child" before="focused">
    You are hungry!
  </accepts>

Looking just at the annotation, a reader cannot determine whether the
child is making a demand, or the chef is voicing the child's
expression of hunger.  An C<initiator> attribute eliminates the
ambiguity:

  <accepts left="chef" right="child" before="focused" initiator="right">
    I am hungry.  Is dinner ready?
  </accepts>

  <accepts left="chef" right="child" before="focused" initiator="left">
    You are hungry!
  </accepts>

Now the situations can be distinguish.  While the annotation is
precise, it is also quite a lot of typing.  To reduce the burden on
the analyst, the parser is capable of guessing reasonable defaults by
consideration of who is talking.  For example:

  <accepts left="chef" initiator="child" before="focused">
    I am hungry.  Is dinner ready?
  </accepts>

Or alternately:

  <talk who="child">
    <accepts left="chef" before="focused">
      I am hungry.  Is dinner ready?
    </accepts>
  </talk>

We covered most of the simple variations.  Here is a summary:

  situation  variations
  ---------- ---------------------------------
  steals     before|tension|after, initiator
  exposes    before|tension|after, initiator
  admires    before|tension|after, initiator
  accepts    before|tension|after, initiator
  impasse    tension
  observes   intensity, [initiator]
  uneasy     intensity, [initiator]
  ready      intensity
  destroys   -

The square brackets denote optional attributes.  More will be said
about this later.

=head2 Question and Answer

Given that a child is holding a teddy by with brown fur, please
consider a sample dialog:

  (adult) Does your teddy bear have brown fur?
  (child) Yes.

How can the quality of a question and answer pair be modelled with the
competition framework?

  <accepts right="child" initiator="adult" before="focused">
    Does your teddy bear have brown fur?
  </accepts>

  <accepts left="parent" initiator="child" before="focused">
    Yes.
  </accepts>

Here the "question" is more like a demand that the child acknowledge
understanding the statement, "teddy bear has brown fur."  And the
child could easily responded differently.  For example:

  <accepts right="child" initiator="adult" before="focused">
    Does your teddy bear have brown fur?
  </accepts>

  <observes initiator="child" right="parent" intensity="forceful">
    (silence)
  </observes>

In this case, the child (in effect) declined to accept the adult's
question.  Notice that there is no indication of the question-answer
connection between these two scenarios.

To encode a question-answer relationship, we need some standard to
recognize them.  Our constraint is that the participants must be
unchanging but the initiator must flip-flop.  These rules were found
by surveying many question-answer exchanges and the rules seem to work
well in practice.  The C<id> and C<answer> attributes encode this
information as follows:

  <accepts id="q1" right="child" initiator="adult" before="focused">
    Does your teddy bear have brown fur?
  </accepts>

  <accepts answer="q1" left="parent" initiator="child" before="focused">
    Yes.
  </accepts>

=head2 Context

Here is a prior example updated with new markup:

  <steals id="p1" initiator="thief" right="child" before="focused">
    The thief eyes the teddy bear maliciously and wrenches it
    from the child's passionate grip.
  </steals>

  <steals answer="p1" left="thief" initiator="child" tension="focused">
    The child becomes furious and starts crying.
  </steals>

  <steals context="p1" initiator="thief" right="child" after="focused">
    The thief triumphantly stows the teddy bear in his backpack.
  </steals>

This last situation describing the thief gloating over his
accomplishment is not really an C<answer> to "p1", but there is
certainly some kind of direct contextual connection.  The C<context>
attribute is available for such cases.  C<context> is a catch-all.  It
is appropriate for any kind of generic relationship for which a more
specific classification is not available.

=head2 Resolution

The parser tries to keep track of situations which remain unresolved
(or pending).  For example:

  <accepts id="o1" initiator="clerk" left="Joey" before="focused">
    What toppings do you want on your pizza?
  </accepts>

  <impasse id="o2" answer="o1" left="Joey" right="cleck" tension="stifled">
    Joey puts the phone on hold.
  </impasse>

In general, stories don't stop abruptly leaving unresolved
cliffhangers.  Here is a clue that can be used to debug annotations.
After processing a transcript, C<empathize> outputs all the situations
which do not find closure.  For example, until Joey picks up the phone
or the clerk gives up in disgust, the pizza situation will be flagged
as unresolved.

Another way to manage resolution is to declare that one side of the
situation is absent.  Here is an example:

  <talk who="teacher">
    <accepts left="students" before="focused" absent="left">
      The students listen to the teacher's tedious monologue.
    </accepts>
  </talk>

In fact, the teacher may never know whether the situation was
truly C<accepts>, C<observes>, or even merely:

  <ready intensity="gentle" left="students" right="teacher">
    The students are intermittently aware that the
    teacher continues to talk.
  </ready>

Notice that the C<absent> attribute is unnecessary in this case.  A
variety of situations do not trigger the need for any resolution, and
C<ready> is one of them.

=head1 EMOTION LIBRARY API

=over 4

=item * Emotion::set_transcript($xml_file)

=item * my $dialog_id = Emotion::set_speaker($who)

=item * my @pending = Emotion::unresolved()

=back

=head2 Emotion::Atom Methods

=over 4

=item * my $situation = Emotion::Atom->new($expat, $attr)

=item * my $emotion = $atom->emotion;

=back

=cut

C<absent> is not avaiable to the initiator, and is not permitted for
C<ready>, C<observes>, C<uneasy>, C<impasse>, or C<destroys>.
